WebSocket API

Connection

Connect to the WebSocket endpoint:

wss://exchange.jamesxu.dev/ws

Once connected, the server begins sending heartbeat messages every 15 seconds. The connection supports one L3 market subscription at a time. Trading and user-event messages share the same socket once you authenticate.

You can subscribe to market data and trade on the same connection. Authenticate first, then subscribe to a market.

Client messages
Server messages

authenticate

Send your API key to identify yourself. On success the server replies with authenticated.

{"op":"authenticate","api_key":"YOUR_API_KEY"}

string

required

Must be "authenticate".

api_key

string

required

Your trader API key.

Subscribe to the L3 order book for a market. The server replies immediately with a snapshot, then streams delta messages.

{"op":"subscribe","channel":"l3","market":"BTC-USD","last_sequence":null}

string

required

Must be "subscribe".

channel

string

required

Must be "l3". No other channels are currently supported.

market

string

required

Market identifier, e.g. "BTC-USD".

last_sequence

number

Supported by the protocol shape, but the current server flow always returns a full snapshot regardless of this value. Pass null or omit the field.

unsubscribe

Stop receiving updates for a market.

{"op":"unsubscribe","channel":"l3","market":"BTC-USD"}

string

required

Must be "unsubscribe".

channel

string

required

Must be "l3".

market

string

required

Market identifier to unsubscribe from.

submit_order

Place a limit order. Requires authentication. The server replies with ack on success or reject on failure.

{
  "op": "submit_order",
  "request_id": "req-1",
  "market": "BTC-USD",
  "side": "BUY",
  "price": 100,
  "quantity": 2
}

string

required

Must be "submit_order".

request_id

string

Client-assigned identifier echoed back in the ack or reject. Useful for correlating responses to requests.

market

string

required

Market identifier, e.g. "BTC-USD".

side

string

required

"BUY" or "SELL".

price

number

required

Limit price in integer units (subject to the market’s tick size).

quantity

number

required

Order quantity (subject to the market’s minimum order quantity).

cancel_order

Cancel an open order you own. Requires authentication.

{
  "op": "cancel_order",
  "request_id": "req-2",
  "order_id": "66377526-7b98-485a-8c40-7024e68fa3c5"
}

string

required

Must be "cancel_order".

request_id

string

Client-assigned correlation identifier.

order_id

string

required

UUID of the order to cancel.

amend_order

Reduce the remaining quantity of an open order you own. Requires authentication.

{
  "op": "amend_order",
  "request_id": "req-3",
  "order_id": "66377526-7b98-485a-8c40-7024e68fa3c5",
  "remaining": 1
}

string

required

Must be "amend_order".

request_id

string

Client-assigned correlation identifier.

order_id

string

required

UUID of the order to amend.

remaining

number

required

New remaining quantity. Must be less than the current remaining quantity.

heartbeat

Sent by the server every 15 seconds. No action required.

{"type":"heartbeat"}

authenticated

Sent after a successful authenticate message.

{
  "type": "authenticated",
  "trader_id": "9d64e278-8b56-46e9-9cab-18c5b22f2fb9",
  "username": "team-alpha"
}

trader_id

string

UUID identifying your trader account.

username

string

Your account username.

snapshot

Sent immediately after a subscribe. Contains the full L3 order book state at the given sequence number. Subsequent delta messages build on top of this sequence.

{
  "type": "snapshot",
  "channel": "l3",
  "market": "BTC-USD",
  "sequence": 0,
  "bids": [],
  "asks": []
}

sequence

number

The sequence number of this snapshot. The next expected delta will have sequence + 1.

bids

array

Array of resting bid orders. Each entry includes order_id, side, price, remaining, and created_at.

asks

array

Array of resting ask orders. Same shape as bids.

delta

A sequenced update to the order book. Each delta carries one or more events describing changes since the previous sequence number.Order added example:

{
  "type": "delta",
  "channel": "l3",
  "market": "BTC-USD",
  "sequence": 1,
  "events": [
    {
      "kind": "order_added",
      "order": {
        "order_id": "66377526-7b98-485a-8c40-7024e68fa3c5",
        "side": "BUY",
        "price": 100,
        "remaining": 2,
        "created_at": "2026-03-18T15:28:01.342510Z"
      }
    }
  ]
}

Trade (fill) example:

{
  "type": "delta",
  "channel": "l3",
  "market": "BTC-USD",
  "sequence": 3,
  "events": [
    {
      "kind": "order_removed",
      "order_id": "4d6c28f4-b349-4a4d-8927-8141c36eb6eb",
      "side": "SELL",
      "price": 100
    },
    {
      "kind": "trade",
      "maker_order_id": "4d6c28f4-b349-4a4d-8927-8141c36eb6eb",
      "taker_order_id": "66377526-7b98-485a-8c40-7024e68fa3c5",
      "price": 100,
      "quantity": 2
    }
  ]
}

sequence

number

Monotonically increasing sequence number. If you receive a delta where sequence is not exactly previous_sequence + 1, a gap has occurred — see Recovery and Resync.

events

array

One or more book change events. Each event has a kind field:

order_added — a new resting order was added to the book
order_updated — an order’s remaining quantity changed (e.g. after an amend or partial fill)
order_removed — an order was removed (cancelled or fully filled)
trade — a trade executed; includes maker_order_id, taker_order_id, price, and quantity

If you receive a delta whose sequence is not contiguous with the last seen sequence, discard your local book and resubscribe to get a fresh snapshot.

ack

Confirms that a trading operation was accepted.

{"type":"ack","op":"submit_order","request_id":"req-1"}

string

The operation that was acknowledged: "submit_order", "cancel_order", or "amend_order".

request_id

string

The request_id you supplied in the client message, if any.

reject

Returned when a trading operation fails validation or is rejected by the engine.

{
  "type": "reject",
  "op": "submit_order",
  "request_id": "req-1",
  "code": "position_limit_exceeded",
  "message": "projected net position for BTC-USD would be 1005; limit is +/-1000"
}

string

The operation that was rejected.

request_id

string

The request_id you supplied in the client message, if any.

code

string

Machine-readable error code. Common values include position_limit_exceeded, order_not_found, market_disabled, unauthenticated, and tick_size_violation.

message

string

Human-readable description of the rejection reason.

fill

Sent to both the maker and taker when a trade executes. Only delivered to authenticated connections.

{
  "type": "fill",
  "fill": {
    "fill_id": "fef1b4fd-d0b0-4270-8831-b4c51aa43f1d",
    "market": "BTC-USD",
    "maker_order_id": "4d6c28f4-b349-4a4d-8927-8141c36eb6eb",
    "taker_order_id": "66377526-7b98-485a-8c40-7024e68fa3c5",
    "price": 100,
    "quantity": 1,
    "occurred_at": "2026-03-18T15:28:04.132958Z"
  }
}

fill_id

string

UUID uniquely identifying this fill.

maker_order_id

string

UUID of the resting order that provided liquidity.

taker_order_id

string

UUID of the aggressing order that took liquidity.

price

number

Price at which the trade executed.

quantity

number

Quantity that traded.

occurred_at

string

ISO 8601 timestamp of when the fill occurred.

order_state

Sent to the owning trader whenever an order’s status changes (open, amended, filled, cancelled).

{
  "type": "order_state",
  "order": {
    "id": "66377526-7b98-485a-8c40-7024e68fa3c5",
    "trader_id": "9d64e278-8b56-46e9-9cab-18c5b22f2fb9",
    "market": "BTC-USD",
    "side": "BUY",
    "price": 100,
    "quantity": 2,
    "remaining": 1,
    "created_at": "2026-03-18T15:28:01.342510Z"
  },
  "status": "open"
}

status

string

Current order status: "open", "filled", or "canceled".

admin_message

Broadcast by operators to one or all authenticated traders.

{
  "type": "admin_message",
  "message": {
    "message_id": "26aa26f5-8d20-4a6c-9b66-99549585036f",
    "target_username": null,
    "market": "BTC-USD",
    "level": "info",
    "title": "Desk notice",
    "body": "Trading will stop in five minutes.",
    "created_at": "2026-03-18T16:05:00.000000Z"
  }
}

level

string

Severity of the message: "info", "warning", or "critical".

target_username

string

If non-null, this message was sent to a specific trader. If null, it is a broadcast to all authenticated connections.

unsubscribed

Sent by the server in response to an unsubscribe message confirming the subscription was cleared.

{
  "type": "unsubscribed",
  "channel": "l3",
  "market": "BTC-USD"
}

resync_required

Sent when the server detects that your local book state may be stale — either because a sequence gap was detected or because your connection fell behind the broadcast buffer.

{
  "type": "resync_required",
  "channel": "l3",
  "market": "BTC-USD",
  "expected_sequence": 5,
  "current_sequence": 9,
  "reason": "market data lagged by 3 messages; resubscribe for a fresh snapshot"
}

See Recovery and Resync for the recommended recovery flow.

Current limitations

One L3 market subscription per connection. To track multiple markets simultaneously, open one connection per market.
No replay endpoint. If you miss messages, you must resubscribe from a fresh snapshot.
No persisted user-event sequence numbers. User events do not carry a sequence number and cannot be replayed.
Only the l3 channel is supported. No trades-only or ticker channels are available.

Get Started

Authentication

REST API

Operator Guide

Examples

WebSocket API

Connection

authenticate

unsubscribe

submit_order

cancel_order

amend_order

heartbeat

authenticated

snapshot

delta

ack

reject

fill

order_state

admin_message

unsubscribed

resync_required

Current limitations

Build docs developers (and LLMs) love

Get Started

Authentication

REST API

WebSocket API

Operator Guide

Examples

​Connection

​authenticate

​subscribe

​unsubscribe

​submit_order

​cancel_order

​amend_order

​heartbeat

​authenticated

​snapshot

​delta

​ack

​reject

​fill

​order_state

​admin_message

​unsubscribed

​resync_required

​Current limitations

Build docs developers (and LLMs) love

Connection

authenticate

subscribe

unsubscribe

submit_order

cancel_order

amend_order

heartbeat

authenticated

snapshot

delta

ack

reject

fill

order_state

admin_message

unsubscribed

resync_required

Current limitations