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".

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".

string

required

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

string

required

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

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".

string

required

Must be "l3".

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".

string

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

string

required

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

string

required

"BUY" or "SELL".

number

required

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

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".

string

Client-assigned correlation identifier.

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".

string

Client-assigned correlation identifier.

string

required

UUID of the order to amend.

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

string

UUID identifying your trader account.

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": []
}

number

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

array

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

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

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.

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".

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.

string

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

string

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

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

string

UUID uniquely identifying this fill.

string

UUID of the resting order that provided liquidity.

string

UUID of the aggressing order that took liquidity.

number

Price at which the trade executed.

number

Quantity that traded.

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

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

string

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

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

​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

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