Commands

Every client → server message uses the same envelope on both gateways:

{ "id": <client_correlation_id>, "cmd": "<verb>", "params": { ... } }

id — client-side correlation id; echoed in the response.
cmd — one of subscribe / update_subscription / unsubscribe / list_subscriptions / get_book_snapshot / ping.
params — command-specific payload (omitted for ping and list_subscriptions).

Every accepted subscription gets a connection-local sid (numeric). Use sid for subsequent updates / unsubscribes and to route incoming events. sids are not stable across reconnects. On /ws/user:

{
  "id": 1,
  "cmd": "subscribe",
  "params": {
    "subscriptions": [
      { "channel": "user_orders" },
      { "channel": "user_fills" },
      { "channel": "vault_positions", "ids": ["0x1234...abcd"] }
    ]
  }
}

On /ws/market:

{
  "id": 1,
  "cmd": "subscribe",
  "params": {
    "subscriptions": [
      { "channel": "token_trade_matches",     "ids": ["12345...", "67890..."] },
      { "channel": "token_trade_settlements", "ids": ["12345..."] },
      { "channel": "token_book",              "ids": ["12345..."] },
      { "channel": "token_ohlc",              "ids": ["12345..."] },
      { "channel": "condition_lifecycle",     "ids": ["0xabc..."] },
      { "channel": "system",                  "ids": ["platform_status"] },
      { "channel": "token_trade_matches",     "ids": ["not-a-token-id"] }
    ]
  }
}

Response (market gateway, with a bad tokenId rejected):

{
  "id": 1,
  "type": "subscribed",
  "accepted": [
    { "sid": 12, "channel": "token_trade_matches",     "ids": ["12345...", "67890..."] },
    { "sid": 13, "channel": "token_trade_settlements", "ids": ["12345..."] },
    { "sid": 14, "channel": "token_book",              "ids": ["12345..."] },
    { "sid": 15, "channel": "token_ohlc",              "ids": ["12345..."] },
    { "sid": 16, "channel": "condition_lifecycle",     "ids": ["0xabc..."] },
    { "sid": 17, "channel": "system",                  "ids": ["platform_status"] }
  ],
  "rejected": [
    {
      "channel": "token_trade_matches",
      "ids":     ["not-a-token-id"],
      "code":    "invalid_params",
      "message": "invalid token id: not-a-token-id"
    }
  ]
}

Normalization rules

All addresses lowercased.
tokenId is decimal-string with no leading zeroes.
conditionId is lowercased 32-byte hex.
Duplicate ids removed.

Rejection codes

`code`	When
`invalid_params`	unknown channel, malformed id, missing required `ids` (including the socket’s wallet on `dispute_intent` / `bond_payout_credited` / `me_limits_invalidated` with an API key), or `ids` sent to a channel that takes none (`user_orders`, `user_fills`, `user_activity`, `notifications`, `all_trade_matches`, `all_trade_settlements`, `all_books`, `global_activity`)
`forbidden`	wrong gateway (public channel on `/ws/user` or private channel on `/ws/market`); also raised when a `vault_positions` / `vault_activity` id is not the vault bound to this socket (your key’s vault, or the vault of the `X-User-Wallet` wallet on a multi-wallet key), or when the socket was opened before that wallet had a vault, and when a `dispute_intent` / `bond_payout_credited` / `me_limits_invalidated` id is not the socket’s wallet
`api_key_scope_missing`	key is missing a scope required by the channel (private channels need `portfolio:read`)
`subscription_cap_exceeded`	this connection already holds the maximum number of subscriptions (200 by default); existing subscriptions are not evicted
`subscription_too_many_ids`	the subscription would hold more than 100 ids. Message: `"subscription accepts at most 100 ids"`. Split your ids across multiple subscriptions on the same connection.

`update_subscription`

Modify the id list of an existing id-based subscription instead of opening a new one. Not allowed on channels whose subscription has no id list (user_orders, user_fills, user_activity, notifications, dispute_intent, bond_payout_credited, me_limits_invalidated, the all_* channels and global_activity): the command is answered with invalid_params ("<channel> does not support id updates").

Add ids

{
  "id": 2,
  "cmd": "update_subscription",
  "params": { "sid": 12, "action": "add_ids", "ids": ["789"] }
}

Remove ids

{
  "id": 3,
  "cmd": "update_subscription",
  "params": { "sid": 12, "action": "remove_ids", "ids": ["123"] }
}

Response (server returns the resulting full id set):

{
  "id": 2,
  "type": "ok",
  "sid": 12,
  "channel": "token_trade_matches",
  "ids": ["456", "789"]
}

A failed update_subscription leaves the subscription unchanged and answers with an error frame, not a rejected[] list:

{ "id": 2, "type": "error", "code": "subscription_too_many_ids", "message": "subscription accepts at most 100 ids" }

The codes are invalid_params for a malformed request, a subscription-less channel or a malformed id, forbidden for a vault id that is not this socket’s vault, not_found for an unknown sid, duplicate_subscription when another subscription on the connection already has the resulting shape, and subscription_too_many_ids when the ids already on the sid plus the added ones exceed 100. Error frames also carry a trace_id when one is available.

`get_book_snapshot`

Force a fresh book_snapshot without unsubscribing / resubscribing. Use on a sequence gap (book_delta data.prevSeq differs from the last seq you applied) or after a long pause. By sid (every token on that token_book subscription; add ids to refresh only some of them):

{
  "id": 7,
  "cmd": "get_book_snapshot",
  "params": { "sid": 14 }
}

By token ids, without a sid:

{
  "id": 7,
  "cmd": "get_book_snapshot",
  "params": { "ids": ["12345...", "67890..."] }
}

The server first acknowledges with the resolved token list (sid is echoed only when you passed one):

{ "id": 7, "type": "ok", "channel": "token_book", "sid": 14, "ids": ["12345..."] }

It then pushes one book_snapshot per token id, or a book_snapshot_failed for a token whose snapshot couldn’t be fetched. Snapshots requested by ids alone carry no sid.

{
  "type":    "book_snapshot_failed",
  "sid":     14,
  "channel": "token_book",
  "id":      "12345...",
  "data":    { "tokenId": "12345...", "reason": "snapshot_unavailable", "retryable": true, "subscriptionActive": true }
}

retryable is always true — back off and send the command again. subscriptionActive is true when the request carried a sid (that subscription stays in place and keeps streaming) and false for a request by ids alone. A sid that isn’t a token_book subscription is rejected with invalid_params; an unknown sid with not_found; a request with neither sid nor an ids array with invalid_params ("ids array is required").

`unsubscribe`

{
  "id": 4,
  "cmd": "unsubscribe",
  "params": { "sids": [12, 13] }
}

{ "id": 4, "type": "unsubscribed", "sids": [12, 13] }

Unknown sids are silently ignored (idempotent — the response only lists sids that were actually removed).

`list_subscriptions`

{ "id": 5, "cmd": "list_subscriptions" }

{
  "id": 5,
  "type": "subscriptions",
  "items": [
    { "sid": 10, "channel": "user_orders" },
    { "sid": 11, "channel": "user_fills" }
  ]
}

Useful after a reconnect to confirm what the server thinks you’re subscribed to before rebuilding state.

`ping`

{ "id": 6, "cmd": "ping" }

{ "id": 6, "type": "pong", "ts": 1776949200000 }

ts is the server clock in milliseconds — clients can use it as a clock-skew probe. The server enforces an idle timeout (60 s by default). It sends a WebSocket protocol-level ping every half window (30 s by default) and drops, without a close frame, any connection that has neither answered with a protocol pong nor sent a message since the previous ping. Browsers and the common WebSocket libraries answer protocol pings automatically. Production clients should still send a ping command every 20–30 s: any client message counts as activity, and it also keeps intermediate proxies / load balancers from closing an idle TCP connection.

Introduction

Endpoints

WebSocket

Normalization rules

Rejection codes

`update_subscription`

Add ids

Remove ids

`get_book_snapshot`

`unsubscribe`

`list_subscriptions`

`ping`

​subscribe

​Normalization rules

​Rejection codes

​update_subscription

​Add ids

​Remove ids

​get_book_snapshot

​unsubscribe

​list_subscriptions

​ping

`subscribe`

Normalization rules

Rejection codes

`update_subscription`

Add ids

Remove ids

`get_book_snapshot`

`unsubscribe`

`list_subscriptions`

`ping`