Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.adipredictstreet.com/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
subscribe

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"] }
    ]
  }
}
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 tokenId"
    }
  ]
}

​
Normalization rules

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

​
Rejection codes

codeWhen
invalid_paramsunknown channel, malformed id, missing required ids, or wallet-scoped channel (user_orders / user_fills) sent with ids
forbiddenwrong gateway (public channel on /ws/user or private channel on /ws/market); also raised when vault_positions ids aren’t covered by the API key’s associated_vault row
api_key_scope_missingkey is missing a scope required by the channel (private channels need portfolio:read)
subscription_cap_exceededthis connection already holds the maximum subscriptions (256); existing subscriptions are not evicted
subscription_too_many_idsa single subscription / add_ids call exceeded the per-channel id cap (100). 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 subscription-less channels (user_orders, user_fills).

​
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"]
}
update_subscription on a subscription-less channel is rejected with invalid_params.

​
get_book_snapshot

Force a fresh full-depth book_snapshot on a token_book subscription without unsubscribing / resubscribing. Use on a sequence gap (book_delta.prevSeq != lastSeq) or after a long pause. By sid: 
{
  "id": 7,
  "cmd": "get_book_snapshot",
  "params": { "sid": 14 }
}
By token ids (server resolves to the matching subscription): 
{
  "id": 7,
  "cmd": "get_book_snapshot",
  "params": { "tokenIds": ["12345...", "67890..."] }
}
Response is one book_snapshot per resolved subscription, OR one book_snapshot_failed per token if the snapshot fetch couldn’t complete: 
{
  "type":    "book_snapshot_failed",
  "sid":     14,
  "channel": "token_book",
  "id":      "12345...",
  "data":    { "tokenId": "12345...", "reason": "upstream_unavailable", "tsMs": 1776949200000 }
}

​
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. There is no application-level idle timeout, but production clients should still send a ping every 20–30 s to defeat intermediate proxies / load balancers that close idle TCP connections.