WebSocket

The realtime gateway streams orderbook, ticker, trade, and private user events.

wss://api.foresight.now/v1/ws[?token=<ws_token>]

The token is optional — without it you can still subscribe to public channels.
The token is required for the private user channel. Get one from POST /v1/auth/ws-token (single-use, 60s TTL). See Authentication.

Every message — inbound and outbound — is JSON with a type field. Invalid JSON gets { "type": "error", "message": "Invalid JSON" }.

Inbound messages (client → server)

Ping

{ "type": "ping" }

The server replies { "type": "pong" }. There is no server-initiated heartbeat — send ping yourself periodically. Public channels require condition_id + chain_id:

{ "type": "subscribe", "channel": "book", "condition_id": "0x...", "chain_id": 56 }

The private channel requires only the channel name (events are wallet-scoped):

{ "type": "subscribe", "channel": "user" }

The server acks:

{ "type": "subscribed", "channel": "book", "condition_id": "0x...", "chain_id": 56 }

For the book channel, a book_snapshot is pushed immediately after the ack.

Unsubscribe

Same shape as subscribe; the server acks with type: "unsubscribed".

Channels

Public

Channel	Carries
`book`	Orderbook snapshot (once) + `book_delta_batch` updates
`ticker`	Best bid/ask and last-price updates
`trades`	Public trade prints

Private

Channel	Carries
`user`	Every order-lifecycle, fill, and settlement event for the authenticated wallet

The user channel is a single unified stream — filter client-side on event.type. Subscribing to it without a valid token returns:

{ "type": "error", "code": "AUTH_REQUIRED", "message": "Private channel requires authentication" }

One market (condition_id, chain_id) yields three public subscriptions: book, ticker, and trades. There is no wildcard subscription — subscribe per market.

Outbound messages (server → client)

`book_snapshot`

Sent once after subscribing to book, and again on reconnect.

{
  "type": "book_snapshot",
  "condition_id": "0x...",
  "chain_id": 56,
  "seq": 42,
  "timestamp": 1713619200000,
  "bids": [{ "price": "0.54", "remainingSize": "123.45" }],
  "asks": [{ "price": "0.55", "remainingSize": "80.0" }]
}

Adopt seq as your sequence anchor. Each book level is { price, remainingSize } as decimal strings.

`book_delta_batch`

A batch of price-level updates coalesced from a single matcher commit or cancel. Apply all deltas as a group.

{
  "type": "book_delta_batch",
  "condition_id": "0x...",
  "chain_id": 56,
  "seq": 43,
  "deltas": [
    { "side": "BUY",  "price": "0.62", "size": "450" },
    { "side": "BUY",  "price": "0.61", "size": "0" },
    { "side": "SELL", "price": "0.64", "size": "120" }
  ]
}

Field	Meaning
`seq`	Monotonic per `(condition_id, chain_id)`. Increments by 1 per batch. Use for gap detection.
`deltas[].side`	`BUY` = bids, `SELL` = asks
`deltas[].price`	Price level (decimal string, 2dp)
`deltas[].size`	New total remaining size at that level. `0` means remove the level.

Read levels from deltas[], not from the top-level message. Each entry’s size is the new aggregate size at that price — replace the level, or delete it when size is 0. The same (side, price) never appears twice in one batch.

`ticker` / `trade`

{ "type": "ticker", "condition_id": "0x...", "chain_id": 56, "...": "..." }
{ "type": "trade",  "condition_id": "0x...", "chain_id": 56, "...": "..." }

`user` events

The private user channel carries several event types — filter on type. Order-lifecycle events carry the full order snapshot (same shape as GET /v1/orders/{hash}):

`type`	Trigger
`order_placement`	Order accepted and resting on the book
`order_update`	`remaining_size` changed (partial fill or settlement rollback)
`order_cancellation`	You cancelled the order
`order_expired`	Engine evicted it (no liquidity for MARKET, expired LIMIT, rollback)
`order_filled`	Fully matched — terminal `MATCHED`, then `FILLED` after settle
`order_failed`	Async matcher exhausted retries / hit a permanent error — `MATCH_FAILED` (may include `match_failed_reason`)

{
  "type": "order_update",
  "order": {
    "order_hash": "0x...",
    "condition_id": "0x...",
    "chain_id": 56,
    "side": "BUY",
    "outcome": 1,
    "order_type": "LIMIT",
    "price": "0.55",
    "size": "100",
    "remaining_size": "60",
    "status": "PARTIALLY_FILLED",
    "token_id": "...",
    "fee_rate_bps": 100,
    "expiration": "0",
    "created_at": "...",
    "book_added_at": "...",
    "updated_at": "..."
  },
  "timestamp": 1713619200000
}

Fill events (type: "fill") — one per match per side:

{
  "type": "fill",
  "order": { "...full order snapshot..." },
  "fill": { "batch_id": "...", "price": 0.55, "size": 50 },
  "trade_id": "...",
  "role": "maker",
  "timestamp": 1713619200000
}

Settlement events (type: "settlement_update") — after on-chain settlement:

{
  "type": "settlement_update",
  "settlement_status": "SETTLED",
  "tx_hash": "0x...",
  "trade_ids": ["..."],
  "timestamp": 1713619200000
}

FAILED settlements may include error_code / error_reason.

`error`

{ "type": "error", "code": "AUTH_REQUIRED", "message": "..." }

code is optional.

Applying book deltas

Seed from the snapshot

Build bids and asks maps keyed by price from book_snapshot, using { price, remainingSize }. Record seq.

Apply each batch atomically

For every entry in book_delta_batch.deltas (in array order): pick the side (BUY → bids, SELL → asks). If size is 0, delete the level; otherwise set the level to size.

Detect gaps

Track seq per market. If a batch arrives with seq !== last + 1, you missed an update — resync by re-fetching GET /v1/markets/{id}/book or re-subscribing (which sends a fresh snapshot).

Render

Sort bids high→low, asks low→high, slice to the depth you need.

Reconnect

POST /v1/auth/ws-token → fresh token (single-use).
Open wss://api.foresight.now/v1/ws?token=<token>.
Re-subscribe to every channel you need.
For book, the new book_snapshot resets your baseline — drop any deltas received before it.

A slow consumer is dropped if its send buffer backs up past ~1 MiB (close code 1013). Reconnect, re-subscribe, and pull a fresh snapshot.

CLOB Trading API

CLOB API Reference

AMM Trade API (Legacy)

Inbound messages (client → server)

Ping

Unsubscribe

Channels

Public

Private

Outbound messages (server → client)

`book_snapshot`

`book_delta_batch`

`ticker` / `trade`

`user` events

`error`

Applying book deltas

Reconnect

​Inbound messages (client → server)

​Ping

​Subscribe

​Unsubscribe

​Channels

​Public

​Private

​Outbound messages (server → client)

​book_snapshot

​book_delta_batch

​ticker / trade

​user events

​error

​Applying book deltas

​Reconnect

Inbound messages (client → server)

Ping

Subscribe

Unsubscribe

Channels

Public

Private

Outbound messages (server → client)

`book_snapshot`

`book_delta_batch`

`ticker` / `trade`

`user` events

`error`

Applying book deltas

Reconnect