WebSocket Topics

Subscribe to WebSocket topics by sending a subscribe message. Topic names are case-insensitive for the pair segment at input time and are normalized by Stabyl. Examples use the canonical topic key USD_NGN.

{
  "type": "subscribe",
  "topics": ["orderbook.USD_NGN", "trades.USD_NGN"],
  "snapshot": true
}

Topic Catalog

Topic	Access	Snapshot	Description
`orderbook.{pair_key}`	Public	Yes	Order book snapshots and delta batches
`trades.{pair_key}`	Public	No	Public trade tape updates
`trades.*`	Public	No	Public trade updates for all available pairs
`ticker.{pair_key}`	Public	No	24-hour ticker updates
`ticker.*`	Public	No	Ticker updates for all available pairs
`candles.{pair_key}.{interval}`	Public	No	OHLCV candle updates for one interval
`candles.*`	Public	No	Candle updates across all pairs and intervals
`user.orders`	API key (`trades:view`)	No	Order status updates for your account
`user.fills`	API key (`trades:view`)	No	One message per fill for your account
`user.fills.batch`	API key (`trades:view`)	No	Fills for your account grouped per batch; not replayed on resume
`user.balances`	API key (`wallets:view`)	No	Wallet balance changes for your account
`user.credit`	API key (`wallets:view`)	No	Credit standing changes for your account

Supported candle intervals are 1m, 5m, 15m, 1h, 4h, and 1d. Subscribing to a private topic without the required scope returns an error with code forbidden.

orderbook.* is not supported. Subscribe to exact order book topics such as orderbook.USD_NGN.

Subscription Response

When a subscription succeeds, the server responds with subscribed.

{
  "type": "subscribed",
  "topics": ["orderbook.USD_NGN", "trades.USD_NGN"],
  "epoch": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91b",
  "snapshots": [
    {
      "topic": "orderbook.USD_NGN",
      "data": {
        "pair_id": "USD/NGN",
        "bids": [{ "price": "1650.00", "quantity": "10.00" }],
        "asks": [{ "price": "1650.50", "quantity": "8.00" }],
        "sequence": 901234
      },
      "ts": "2026-01-14T10:30:00Z"
    }
  ]
}

Snapshots are best effort and currently apply to exact order book topics. If a snapshot is omitted, fetch the REST order book snapshot before applying live deltas.

Data Envelope

All topic updates use the same outer envelope:

{
  "type": "data",
  "topic": "trades.USD_NGN",
  "data": {},
  "seq": 12345,
  "ts": "2026-01-14T10:30:00Z",
  "epoch": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91b"
}

Use the envelope seq for WebSocket recovery. Payloads may also include their own domain sequence fields.

Order Book Payloads

An orderbook.{pair_key} message can carry either a snapshot-style payload or a delta batch. Snapshot style payload:

{
  "type": "data",
  "topic": "orderbook.USD_NGN",
  "seq": 901234,
  "ts": "2026-01-14T10:30:00Z",
  "epoch": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91b",
  "data": {
    "pair_id": "USD/NGN",
    "bids": [{ "price": "1650.00", "quantity": "10.00" }],
    "asks": [{ "price": "1650.50", "quantity": "8.00" }],
    "sequence": 901234,
    "timestamp": "2026-01-14T10:30:00Z"
  }
}

Delta batch payload:

{
  "type": "data",
  "topic": "orderbook.USD_NGN",
  "seq": 901235,
  "ts": "2026-01-14T10:30:02Z",
  "epoch": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91b",
  "data": {
    "pair_id": "USD/NGN",
    "updates": [
      {
        "side": "bid",
        "price": "1650.00",
        "quantity": "12.00",
        "sequence": 901235
      }
    ],
    "timestamp": "2026-01-14T10:30:02Z"
  }
}

Recommended recovery:

Fetch GET /partner/exchange/orderbook/USD%2FNGN/snapshot.
Subscribe to orderbook.USD_NGN with snapshot: true.
Apply updates in seq order.
If a gap is detected, fetch a fresh REST snapshot and resume from the new baseline.

Trade Payload

trades.{pair_key} and trades.* carry public trade tape updates.

{
  "type": "data",
  "topic": "trades.USD_NGN",
  "seq": 901235,
  "ts": "2026-01-14T10:31:00Z",
  "epoch": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91b",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174222",
    "pair_id": "USD/NGN",
    "price": "1649.50",
    "quantity": "25.00",
    "side": "buy",
    "sequence": 901235,
    "timestamp": "2026-01-14T10:31:00Z"
  }
}

Use GET /partner/exchange/trades for backfills and WebSocket trades for live updates.

Ticker Payload

ticker.{pair_key} and ticker.* carry current 24-hour market statistics.

{
  "type": "data",
  "topic": "ticker.USD_NGN",
  "seq": 1201,
  "ts": "2026-01-14T10:31:00Z",
  "epoch": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91b",
  "data": {
    "pair_id": "USD/NGN",
    "open": "1640.00",
    "high": "1655.00",
    "low": "1638.50",
    "last": "1650.00",
    "price_change": "10.00",
    "price_change_pct": 0.61,
    "volume": "10000.00",
    "volume_quote": "16500000.00",
    "trade_count": 412,
    "best_bid": "1649.50",
    "best_ask": "1650.50",
    "timestamp": "2026-01-14T10:31:00Z"
  }
}

Every field is always present. open, high, low, last, price_change, price_change_pct, best_bid, and best_ask are null when there is no data for them.

Candle Payload

candles.{pair_key}.{interval} and candles.* carry OHLCV candle updates.

{
  "type": "data",
  "topic": "candles.USD_NGN.1m",
  "seq": 3201,
  "ts": "2026-01-14T10:31:00Z",
  "epoch": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91b",
  "data": {
    "pair_id": "USD/NGN",
    "interval": "1m",
    "timestamp": "2026-01-14T10:31:00Z",
    "open": "1649.00",
    "high": "1651.00",
    "low": "1648.50",
    "close": "1650.00",
    "volume": "125.00",
    "volume_quote": "206250.00",
    "trade_count": 8
  }
}

Private Order Update

user.orders carries order updates for your account. Subscribe with an API key that has trades:view.

{
  "type": "data",
  "topic": "user.orders",
  "seq": 44,
  "ts": "2026-01-14T10:31:00Z",
  "epoch": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91b",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "order_id": "123e4567-e89b-12d3-a456-426614174000",
    "user_id": "0197f1f0-0000-7000-8000-000000000001",
    "pair_id": "USD/NGN",
    "side": "buy",
    "order_type": "limit",
    "time_in_force": "gtc",
    "status": "partially_filled",
    "quantity": "100.00",
    "filled_quantity": "50.00",
    "remaining_quantity": "50.00",
    "price": "1650.00",
    "avg_fill_price": "1649.50",
    "client_order_id": "cli-123",
    "created_at": "2026-01-14T10:30:00Z",
    "replace": {
      "replaces_order_id": null,
      "replaced_by_order_id": null
    },
    "reject_reason": null,
    "cancel_reason": null,
    "timestamp": "2026-01-14T10:31:00Z"
  }
}

order_id is a deprecated alias of id; read id. status is one of pending, cancelling, replacing, accepted, partially_filled, filled, cancelled, rejected, or expired. Treat filled, cancelled, rejected, and expired as terminal. Confirm final state with GET /partner/exchange/orders/{order_id} when needed.

Private Fill Update

user.fills carries fills for your account. It does not expose counterparty identity.

{
  "type": "data",
  "topic": "user.fills",
  "seq": 45,
  "ts": "2026-01-14T10:31:00Z",
  "epoch": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91b",
  "data": {
    "fill_id": "123e4567-e89b-12d3-a456-426614174222",
    "pair_id": "USD/NGN",
    "order_id": "123e4567-e89b-12d3-a456-426614174000",
    "side": "buy",
    "liquidity": "maker",
    "price": "1649.50",
    "quantity": "25.00",
    "notional": "41237.50",
    "fee": "0.25",
    "fee_currency": "USD",
    "applied_fee_bps": 2,
    "maker_rebate": "0.01",
    "sequence": 901235,
    "timestamp": "2026-01-14T10:31:00Z"
  }
}

applied_fee_bps and maker_rebate are present only when they apply to the fill.

Resume

Send resume when reconnecting:

{
  "type": "subscribe",
  "topics": ["orderbook.USD_NGN", "trades.USD_NGN", "user.orders"],
  "snapshot": true,
  "resume": {
    "epoch": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91b",
    "seq": {
      "orderbook.USD_NGN": 901235,
      "trades.USD_NGN": 901235,
      "user.orders": 44
    }
  }
}

Resume is supported for exact topics, including user.orders, user.fills, user.balances, and user.credit. Wildcard topics such as trades.* and the user.fills.batch topic are not replayed. If the server cannot resume, it may omit replayed messages or send connection_reset. Rebuild the affected topic from REST, then continue processing new data messages.

Get Started

Wallets

Exchange

Webhooks

WebSocket

Topic Catalog

Subscription Response

Data Envelope

Order Book Payloads

Trade Payload

Ticker Payload

Candle Payload

Private Order Update

Private Fill Update

Resume

​Topic Catalog

​Subscription Response

​Data Envelope

​Order Book Payloads

​Trade Payload

​Ticker Payload

​Candle Payload

​Private Order Update

​Private Fill Update

​Resume

Topic Catalog

Subscription Response

Data Envelope

Order Book Payloads

Trade Payload

Ticker Payload

Candle Payload

Private Order Update

Private Fill Update

Resume