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
| Channel | id | Snapshot (subscribed) | Updates (channel_data) |
|---|---|---|---|
v4_markets | none | /v4/perpetualMarkets: {markets} | {trading: {[ticker]: changed fields}, oraclePrices: {[ticker]: {oraclePrice, effectiveAt, effectiveAtHeight, marketId}}} |
v4_orderbook | a ticker | {bids: [{price, size}], asks: [...]} | {bids: [[price, size]], asks: [[price, size]]}: levels whose size changed, size "0" removed |
v4_trades | a 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 children | As above, with subaccountNumber naming the child |
v4_block_height | none | {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);
};# pip install websocket-client (a dydx-v4-client dependency)
import json
import websocket
def on_open(ws):
ws.send(json.dumps({"type": "subscribe", "channel": "v4_orderbook", "id": "TESTCOPERP-USD", "batched": True}))
def on_message(ws, message):
m = json.loads(message)
print(m["type"], m.get("channel"), m.get("contents"))
websocket.WebSocketApp(
"wss://indexer.testnet.firstaccess.exchange/v4/ws", on_open=on_open, on_message=on_message
).run_forever()# websocat: https://github.com/vi/websocat
echo '{"type":"subscribe","channel":"v4_trades","id":"TESTCOPERP-USD"}' |
websocat -n wss://indexer.testnet.firstaccess.exchange/v4/wsLimits
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).