WebSocket: OHLCV

Messages

{
  "const": "<string>",
  "pair_address": "<string>",
  "token_address": "<string>",
  "timeframe": "<string>",
  "timestamp": "<string>",
  "open": 123,
  "high": 123,
  "low": 123,
  "close": 123,
  "volume_sol": 123,
  "volume_token": 123,
  "trade_count": 123,
  "buy_count": 123,
  "sell_count": 123,
  "unique_traders": 123,
  "is_closed": true
}

WSS

ohlcv

The OHLCV WebSocket emits one frame per bar update for each (pool, timeframe) you subscribe to. You get mid-bar updates while a bar is open (is_closed: false) and a final update on close (is_closed: true). This is the right channel when you want to render a live chart or trigger logic on bar close. For one-shot history, use /api/v1/candles and /api/v1/candles/latest. For raw per-swap data, use WebSocket: swaps.

Endpoint and auth

wss://ws.dexploit.dev/ws/ohlcv

Authenticate either via Bearer header (server) or query string (browser) — /ws/ohlcv accepts both, same as /ws/swaps:

Authorization: Bearer ohlcv_live_sk_<your_key>

# or, for browsers:
wss://ws.dexploit.dev/ws/ohlcv?api_key=ohlcv_live_sk_<your_key>

After the connection is up the server sends a hello frame:

{ "client_id": "8caba129-bdab-…", "data_inception": "2026-05-02T00:03:00Z", "status": "connected" }

Then send a subscribe. Both pair_addresses and timeframes are required — the server will reply with {"error": "invalid subscribe: timeframes empty"} (or similar) if either is missing.

{
  "type": "subscribe",
  "pair_addresses": ["HdqYz5GVuWgNXbE6fBkgCYXUSPGoyco5yYLBaL5ZzKAR"],
  "timeframes": ["1s", "1m"]
}

Server ack:

{ "status": "subscribed", "op": "subscribed", "pairs": 1, "timeframes": ["1s", "1m"], "subjects": 2 }

This first frame is the one-shot, backward-compatible path: a client that only ever sends it sees zero change from before. pairs is the distinct pool count, subjects is the number of live (pool, timeframe) pairs, and op mirrors status.

A subject is one (pair_address, timeframe) pair — the unit the stream actually fans out on. A subscribe of 3 pools × 2 timeframes is 3 pairs but 6 subjects.

Add / remove / unsubscribe (mid-stream)

Once you’re subscribed you can change the watched symbol set without reconnecting by sending more frames on the same socket. This is what lets a chart or watchlist UI swap the active pool, or add/drop timeframes, in place. Every mutating frame carries an op. Each (pair_address, timeframe) pair it expands to is a subject; the ack’s pairs/timeframes/subjects always report the new total live set after the op — not just the delta.

`op`	Effect	Ack `op`
`add`	Union the new `(pair, timeframe)` subjects into the live set. Bars for the added symbols start arriving immediately.	`added`
`remove`	Drop those subjects. Bars for removed symbols stop.	`removed`
`unsubscribe`	Clear all subjects. `pair_addresses` / `timeframes` are optional and ignored. Totals go to `0`.	`unsubscribed`
`subscribe`	Replace the entire live set with the new one (reset). Atomic — see note below.	`subscribed`

Add symbols

{ "op": "add", "pair_addresses": ["38tqb1K…"], "timeframes": ["1m"] }

Ack with the new totals (now 2 pools × the union of timeframes):

{ "status": "added", "op": "added", "pairs": 2, "timeframes": ["1m", "1s"], "subjects": 3 }

Remove symbols

{ "op": "remove", "pair_addresses": ["38tqb1K…"], "timeframes": ["1m"] }

{ "status": "removed", "op": "removed", "pairs": 1, "timeframes": ["1m", "1s"], "subjects": 2 }

Unsubscribe (clear everything)

{ "op": "unsubscribe" }

{ "status": "unsubscribed", "op": "unsubscribed", "pairs": 0, "timeframes": [], "subjects": 0 }

Replace the whole set

A later frame with op: "subscribe" (or with no op — absent defaults to subscribe) replaces the entire live set with the new one:

{ "op": "subscribe", "pair_addresses": ["HdqYz5GVu…"], "timeframes": ["5m"] }

{ "status": "subscribed", "op": "subscribed", "pairs": 1, "timeframes": ["5m"], "subjects": 1 }

This reset behaviour is the opposite of the swaps WebSocket. On /ws/ohlcv, to widen the set you must use op: "add" — sending another subscribe (or an op-absent frame) discards what you had. The frame’s op field is what the server reads; the legacy type field is ignored.

The replace is atomic: if the new set would exceed the per-connection subject cap, the replace is rejected and your prior subscription stays fully intact.

Frame shape

{
  "type": "ohlcv",
  "pair_address": "HdqYz5GVuWgNXbE6fBkgCYXUSPGoyco5yYLBaL5ZzKAR",
  "token_address": "BsZoKtYtP3V2xJnqonEaYXXaQdLv8kPM45aRbt23oPEJ",
  "timeframe": "1m",
  "timestamp": "2026-05-20T12:20:00+00:00",
  "open":  7.553982e-7,
  "high":  7.613724e-7,
  "low":   7.553982e-7,
  "close": 7.613724e-7,
  "volume_sol":   2058053069,
  "volume_token": 2713479778451,
  "trade_count":   5,
  "buy_count":     5,
  "sell_count":    0,
  "unique_traders": 5,
  "is_closed": false
}

Field	Notes
`pair_address`	The on-chain pool/LP account. Note the naming: OHLCV frames key the pool as `pair_address`, but swaps WebSocket frames key the same on-chain pool as `pool_address`. Same account, different field name across the two streams.
`timestamp`	Bar open time, ISO 8601. The bar covers `[timestamp, timestamp + timeframe)`.
`is_closed`	`false` for interim mid-bar pushes; `true` on the bar’s final tick. A given `(pair, timeframe, timestamp)` may emit multiple `is_closed: false` frames followed by one `is_closed: true` — the latter is authoritative.
`volume_sol`	Lamports, despite the name. Divide by `1e9` for SOL.
`volume_token`	Token base units. Divide by `10 ** quote_decimals` for human-readable.
`unique_traders`	Distinct wallets that traded in this bar so far. Grows monotonically across mid-bar frames.

Limits and errors

Two independent limits apply:

Limit	Bounds	Env	Default
`pair_addresses` per frame	The pool count of a single `subscribe` / `add` / `subscribe`-replace frame.	`MAX_PAIRS_PER_SUBSCRIBE`	1000
Live subjects per connection	The cumulative live `(pool × timeframe)` set across all your `add`s.	`MAX_SUBJECTS_PER_CONNECTION`	5000

Mid-stream errors are non-fatal — the socket stays open and a later valid frame still works. (Only an error on the initial subscribe frame closes the connection, as before.)

Bad frame / unknown op → { "error": "invalid subscribe: <detail>" } and the socket stays open. An unknown op comes back as { "error": "invalid subscribe: unknown op: <op>" }.
Per-frame pool cap → { "error": "invalid subscribe: too many pair_addresses; max 1000" }.
Per-connection subject cap → an add or subscribe-replace that would push the live set past the cap is rejected atomically — no partial apply, and your existing subjects keep delivering:

{ "error": "subject cap reached for this connection; cap 5000", "cap": 5000 }

Minimal TypeScript client

import WebSocket from 'ws'; // browser: use the global WebSocket

const URL    = 'wss://ws.dexploit.dev/ws/ohlcv';
const API    = 'ohlcv_live_sk_<your_key>';
const PAIR   = '<pool_address>';
const TFS    = ['1m'];

let backoff = 1000;

function connect() {
  const ws = new WebSocket(URL, { headers: { Authorization: `Bearer ${API}` } });

  ws.on('open', () => {
    backoff = 1000;
    ws.send(JSON.stringify({
      type: 'subscribe',
      pair_addresses: [PAIR],
      timeframes: TFS,
    }));
  });

  ws.on('message', (raw) => {
    const f = JSON.parse(raw.toString());
    if (f.type !== 'ohlcv') return; // skip hello + subscribe ack + errors
    const tag = f.is_closed ? 'CLOSED' : 'open  ';
    const volSol = f.volume_sol / 1e9;
    console.log(
      `${tag} ${f.timeframe}@${f.timestamp}  o=${f.open.toExponential(3)} c=${f.close.toExponential(3)} ` +
      `vol=${volSol.toFixed(3)} SOL (${f.trade_count} trades)`,
    );
  });

  ws.on('close', () => {
    setTimeout(connect, backoff);
    backoff = Math.min(backoff * 2, 60_000);
  });

  ws.on('error', () => { /* close fires next */ });
}

connect();

If you’re rendering a live chart, key your local bar store by (pair_address, timeframe, timestamp) and overwrite the entry on every frame for that key — the latest frame is always the freshest snapshot of that bar. When is_closed: true arrives, that bar is final.

Changing the watched set at runtime

A watchlist or chart UI that switches the active pool sends add / remove on the same open socket — no reconnect. Helpers, and an ack handler that reads back the new live totals:

// `ws` is the open socket from above.

// Start watching another pool (keeps the existing ones):
const addPair = (pair: string, tfs = ['1m']) =>
  ws.send(JSON.stringify({ op: 'add', pair_addresses: [pair], timeframes: tfs }));

// Stop watching a pool:
const removePair = (pair: string, tfs = ['1m']) =>
  ws.send(JSON.stringify({ op: 'remove', pair_addresses: [pair], timeframes: tfs }));

// Drop everything (e.g. on view teardown):
const clearAll = () => ws.send(JSON.stringify({ op: 'unsubscribe' }));

// In your message handler, branch on the ack/error frames:
ws.on('message', (raw) => {
  const f = JSON.parse(raw.toString());
  switch (f.op ?? f.status) {            // 'subscribed' | 'added' | 'removed' | 'unsubscribed'
    case 'added':
    case 'removed':
    case 'unsubscribed':
    case 'subscribed':
      // f.pairs / f.subjects are the NEW live totals after the op.
      console.log(`live set: ${f.pairs} pools, ${f.subjects} subjects`);
      return;
  }
  if (f.error) {                          // non-fatal mid-stream — socket stays open
    console.warn('op rejected:', f.error, f.cap ? `(cap ${f.cap})` : '');
    return;
  }
  // …otherwise it's an `ohlcv` bar frame — handle as above.
});

Use op: 'subscribe' (or an op-absent frame) only when you intend to reset the whole set — it discards the current subscription. To widen, always use op: 'add'. For reconnect strategy, gap-filling against /api/v1/candles, and keepalive guidance, see Reconnect & backpressure.

Programmatic spec

The full message contract for this channel — and the other two WebSocket streams — is published as an AsyncAPI 3.0 document you can feed into client generators, validators, or an LLM.

Messages

{
  "const": "<string>",
  "pair_address": "<string>",
  "token_address": "<string>",
  "timeframe": "<string>",
  "timestamp": "<string>",
  "open": 123,
  "high": 123,
  "low": 123,
  "close": 123,
  "volume_sol": 123,
  "volume_token": 123,
  "trade_count": 123,
  "buy_count": 123,
  "sell_count": 123,
  "unique_traders": 123,
  "is_closed": true
}

api_key

type:httpApiKey

?api_key=ohlcv_live_sk_… appended to the connection URL. Browser-friendly; the only option in environments where you can't set headers.

Subscribe / add / remove / unsubscribe

type:object

Op-tagged frame that mutates the live (pool x timeframe) set. The FIRST frame subscribes; later frames on the same socket can add/remove/unsubscribe or subscribe (reset) without reconnecting. op absent = subscribe = REPLACE.

Candle update

type:object

One bar update for a subscribed (pool, timeframe). NOTE: volume_sol is in lamports despite the name (divide by 1e9 for SOL); volume_token is in base units (divide by 10**quote_decimals).

Connect hello

type:object

Sent once on connect with a UUID client_id and the index inception timestamp.

Subscribe / add / remove ack

type:object

Sent after each successful op. status and op echo the op (subscribed/added/removed/unsubscribed). pairs/subjects are the new LIVE TOTALS after the op (not a delta). A subject = one (pool, timeframe) pair.

Stream error

type:object

Validation failure, auth issue, or server-side error. Connection usually stays open after a recoverable error.

Getting started

Concepts

Streaming

Examples

Endpoint and auth

Add / remove / unsubscribe (mid-stream)

Add symbols

Remove symbols

Unsubscribe (clear everything)

Replace the whole set

Frame shape

Limits and errors

Minimal TypeScript client

Changing the watched set at runtime

Programmatic spec

​Endpoint and auth

​Subscribe

​Add / remove / unsubscribe (mid-stream)

​Add symbols

​Remove symbols

​Unsubscribe (clear everything)

​Replace the whole set

​Frame shape

​Limits and errors

​Minimal TypeScript client

​Changing the watched set at runtime

​Programmatic spec

Endpoint and auth

Subscribe

Add / remove / unsubscribe (mid-stream)

Add symbols

Remove symbols

Unsubscribe (clear everything)

Replace the whole set

Frame shape

Limits and errors

Minimal TypeScript client

Changing the watched set at runtime

Programmatic spec