Skip to content
First Access Exchange

Indexer WebSocket API

URL: wss://indexer.testnet.firstaccess.exchange/v4/ws. Messages are JSON.

The channels and messages are dYdX's indexer's at the chain's upstream commit, unchanged; the fork adds chainMarket to every chain market in v4_markets.

Connecting and subscribing

On connect the server sends {"type": "connected", "connection_id": "...", "message_id": 0}. Then subscribe:

{ "type": "subscribe", "channel": "v4_orderbook", "id": "TESTCOPERP-USD", "batched": true }

and unsubscribe with {"type": "unsubscribe", "channel": "...", "id": "..."}. The server answers with subscribed (carrying an initial snapshot in contents), then sends channel_data messages (contents one update, with a version), or channel_batch_data when subscribed with "batched": true (contents an array, flushed every 250 ms), and unsubscribed. Errors are {"type": "error", "message": "..."}.

Keep-alive is protocol-level: the server pings every 30 s and closes a connection that hasn't answered within 10 s (code 1011). A JSON {"type": "ping"} is accepted and ignored.

Channels

ChannelidSnapshot (subscribed)Updates (channel_data)
v4_marketsnone/v4/perpetualMarkets: {markets}{trading: {[ticker]: changed fields}, oraclePrices: {[ticker]: {oraclePrice, effectiveAt, effectiveAtHeight, marketId}}}
v4_orderbooka ticker{bids: [{price, size}], asks: [...]}{bids: [[price, size]], asks: [[price, size]]}: levels whose size changed, size "0" removed
v4_tradesa ticker{trades: [...]}{trades: [{id, size, price, side, createdAt, type}]}
v4_candles{ticker}/{resolution}, e.g. TESTCOPERP-USD/1MIN{candles: [...]}One candle
v4_subaccounts{address}/{subaccountNumber}{subaccount, orders, blockHeight}{perpetualPositions, assetPositions, orders, fills, transfers, tradingReward, blockHeight} (whichever changed)
v4_parent_subaccounts{address}/{parentSubaccountNumber}As above, for a parent and its childrenAs above, with subaccountNumber naming the child
v4_block_heightnone{height, time}{blockHeight, time}

On v4_markets a chain market's entries carry chainMarket as the HTTP API's do, and its oraclePrices updates are the chain's own prices (the index I for a company perpetual). An event's S has no perpetual, so it isn't listed: read it from the node (overview).

Order updates on v4_subaccounts carry status and, when an order leaves the book, removalReason (ORDER_REMOVAL_REASON_*, including First Access's ORDER_REMOVAL_REASON_OUTSIDE_CALL_PRICE_BAND).

Example

// Node 22 or later has a global WebSocket; browsers do too.
const ws = new WebSocket('wss://indexer.testnet.firstaccess.exchange/v4/ws');
ws.onopen = () => {
  ws.send(JSON.stringify({ type: 'subscribe', channel: 'v4_orderbook', id: 'TESTCOPERP-USD', batched: true }));
  ws.send(JSON.stringify({ type: 'subscribe', channel: 'v4_subaccounts', id: 'dydx1.../1' }));
};
ws.onmessage = (e) => {
  const m = JSON.parse(e.data);
  if (m.type === 'subscribed') console.log('snapshot', m.channel, m.id, m.contents);
  else if (m.type === 'channel_data' || m.type === 'channel_batch_data') console.log(m.channel, m.id, m.contents);
  else if (m.type === 'error') console.error(m.message);
};

Limits

Per connection: 2 subscribe messages a second for each channel and id, 2 invalid messages a second, messages of at most 64 KiB, and at most 256 v4_subaccounts and v4_parent_subaccounts subscriptions and 32 each of v4_markets, v4_orderbook, v4_trades and v4_candles (one v4_block_height). Going over closes the connection with code 1008. A subscription's first message (the subscribed contents) is fetched from the HTTP API by the server, not counted against your HTTP limit (Known gaps).