Bullet Trading API WebSocket Specification

WebSocket endpoint: ws://<host>:<port>/ws

• Localnet: ws://localhost:3000/ws
• Staging: wss://tradingapi.staging.bullet.xyz/ws
• Testnet: wss://tradingapi.testnet.bullet.xyz/ws
• Mainnet: wss://tradingapi.bullet.xyz/ws

Timestamps: all timestamps in this API are microseconds since Unix epoch (16 digits, e.g. 1706745600000000). Binance uses milliseconds (13 digits). Divide by 1,000 if converting from Bullet to Binance format.

Connection Lifecycle

WebSocket connections go through three phases: establishment, keepalive, and disconnection. The server uses status messages to inform clients of connection state changes (e.g., successful connection, impending disconnection with reason).

Status Message

Connection Establishment

1. Client connects to WebSocket endpoint
2. Server assigns unique clientId
3. Server sends "connected" status message

{
  "e": "status",
  "E": 1706745600000000,
  "status": "connected",
  "clientId": "ws_abc123"
}

Disconnection

The server sends a "disconnecting" status message before closing:

{
  "e": "status",
  "E": 1706745600000000,
  "status": "disconnecting",
  "clientId": "ws_abc123",
  "reason": "pong_timeout"
}

Disconnect Reasons

Keepalive (Ping/Pong)

Connections are kept alive via WebSocket ping/pong frames. The server sends ping frames every 30 seconds; clients must respond with pong frames. Most WebSocket libraries answer ping frames automatically. Anything the client sends that proves liveness resets the keepalive timeout: a pong frame, the client’s own ping frame, or an application-level ping message.

Ping

Ping the server to check connection health. Alternatively clients can also send WebSocket ping frames.

{
  "method": "ping",
  "id": 4
}

Possible errors: ValidationError (message parse)

Responses: Pong

Pong

{
  "e": "pong",
  "id": 4,
  "E": 1706745600000000
}

Subscription Streams

All client messages use JSON format with method field. Method names are case-insensitive.

Subscribe

Subscribe to market data topics or user data streams.

{
  "method": "subscribe",
  "id": 1,
  "params": [
    "BTC-USD@aggTrade",
    "ETH-USD@depth10"
  ]
}

Behavior: Idempotent with atomic validation. All topics validated first - if any fails, entire request fails. Already-subscribed topics silently skipped.

Possible errors: ValidationError, TooManyRequests, InvalidSubscriptionFormat, Unauthorized, InvalidSymbol, ClientNotFound

Responses:

• Success: Subscribe
• Failure: Error

Subscribe (success)

{
  "e": "subscribe",
  "id": 1,
  "E": 1706745600000000,
  "result": "success"
}

Unsubscribe

Unsubscribe from market data topics or user data streams.

{
  "method": "unsubscribe",
  "id": 5,
  "params": [
    "BTC-USD@aggTrade"
  ]
}

Behavior: Idempotent - always succeeds. Invalid or non-subscribed topics silently skipped.

Possible errors: ValidationError (message parse)

Responses:

• Success: Unsubscribe

Unsubscribe (success)

{
  "e": "unsubscribe",
  "id": 5,
  "E": 1706745600000000,
  "result": "success"
}

ListSubscriptions

List all active subscriptions for the client.

{
  "method": "list_subscriptions",
  "id": 6
}

Possible errors: ValidationError (message parse)

Responses:

• Success: ListSubscriptions

ListSubscriptions (success)

{
  "e": "list_subscriptions",
  "id": 6,
  "E": 1706745600000000,
  "result": [
    "BTC-USD@depth10",
    "ETH-USD@aggTrade"
  ]
}

Request-Response

OrderPlace

Place an order via WebSocket.

{
  "method": "order.place",
  "id": 10,
  "params": {
    "tx": "c2lnbmVkX3RyYW5zYWN0aW9uX2J5dGVz"
  }
}

Building the tx payload: see Place Orders (or Replace Orders for atomic quote refresh) for construction, Order Types and Fields for NewOrderArgs reference, and Signing for the sign → encode → submit flow.

Possible errors: ValidationError (empty tx), ServiceUnavailable (submission failed), Timeout, NewOrderRejected

Responses:

• Success: OrderResult
• Failure: OrderError

OrderCancel

Cancel an order via WebSocket.

{
  "method": "order.cancel",
  "id": 11,
  "params": {
    "tx": "c2lnbmVkX3RyYW5zYWN0aW9uX2J5dGVz"
  }
}

Building the tx payload: see Cancel Orders for construction and Signing for the sign → encode → submit flow.

Possible errors: ValidationError (empty tx), ServiceUnavailable (submission failed), Timeout, CancelRejected

Responses:

• Success: OrderResult
• Failure: OrderError

OrderAmend

Amend an existing order via WebSocket.

{
  "method": "order.amend",
  "params": {
    "tx": "<signed-base64-borsh-tx>"
  },
  "id": 7
}

Building the tx payload: see Amend Orders for construction and Signing for the sign → encode → submit flow.

Possible errors: ValidationError (empty tx), ServiceUnavailable (submission failed), Timeout, CancelRejected

Responses:

• Success: OrderResult
• Failure: OrderError

OrderCancelAll

Cancel all open orders for a market via WebSocket.

{
  "method": "order.cancelAll",
  "params": {
    "tx": "<signed-base64-borsh-tx>"
  },
  "id": 8
}

Building the tx payload: see Cancel Market Orders / Cancel All Orders for construction and Signing for the sign → encode → submit flow.

Possible errors: ValidationError (empty tx), ServiceUnavailable (submission failed), Timeout, CancelRejected

Responses:

• Success: OrderResult
• Failure: OrderError

Responses

Error

Error response to any client request.

{
  "e": "error",
  "id": 2,
  "E": 1706745600000000,
  "error": {
    "param": "invalid-topic-format",
    "code": -1004,
    "msg": "invalid subscription format: expected <symbol>@<stream>"
  }
}

OrderResult

Response to OrderPlace, OrderCancel, OrderAmend, or OrderCancelAll.

{
  "e": "order.place",
  "id": 10,
  "E": 1706745600000000,
  "results": {
    "tx_id": "0xabc123def456",
    "status": "processed",
    "order_ids": [
      1
    ],
    "client_order_ids": [
      1
    ]
  }
}

OrderError

Error response to OrderPlace, OrderCancel, OrderAmend, or OrderCancelAll.

{
  "id": 12,
  "E": 1706745600000000,
  "error": {
    "code": -2010,
    "msg": "new order rejected: insufficient margin"
  }
}

Tx Status Values

Most successful order operations return processed. If you receive dropped, the order was not placed — inspect the error and retry with a fresh uniqueness value.

Market Data

All market data messages are pushed to subscribed clients. No type wrapper.

DepthUpdate

Topic: SYMBOL@depth, SYMBOL@depth5, SYMBOL@depth10, SYMBOL@depth20, SYMBOL@depth100

{
  "e": "depthUpdate",
  "E": 1706745600000000,
  "T": 1706745600000000,
  "s": "BTC-USD",
  "U": 1000,
  "u": 1000,
  "pu": 0,
  "b": [
    [
      "50000.00",
      "1.5"
    ],
    [
      "49999.00",
      "2.0"
    ]
  ],
  "a": [
    [
      "50001.00",
      "1.2"
    ],
    [
      "50002.00",
      "3.0"
    ]
  ],
  "mt": "s"
}

Note: U equals u and as we don’t batch updates.

An update (mt: "u") describes how the top N levels of the subscribed depth changed since the previous message. A level that leaves the top N, including one pushed out by a better price, arrives with qty "0"; a level that enters the top N arrives with its full qty. Changes deeper in the book are not sent. Every depth receives each update, possibly with empty b and a, so its pu chain stays continuous.

AggTrade

Topic: SYMBOL@aggTrade

{
  "e": "aggTrade",
  "E": 1706745600000000,
  "s": "BTC-USD",
  "a": 200001,
  "p": "50000.50",
  "q": "0.5",
  "f": 200001,
  "l": 200001,
  "T": 1706745600000000,
  "m": false,
  "th": "0xabc123def456",
  "ua": "",
  "oi": 0,
  "mk": false,
  "ff": false,
  "lq": false,
  "fe": "0",
  "nf": "0",
  "fa": "",
  "co": 0,
  "sd": "",
  "ft": "",
  "z": "0",
  "Z": "0",
  "rs": "0"
}

BookTicker

Topic: SYMBOL@bookTicker, !bookTicker

{
  "e": "bookTicker",
  "u": 1000,
  "E": 1706745600000000,
  "T": 1706745600000000,
  "s": "BTC-USD",
  "b": "50000.00",
  "B": "1.5",
  "a": "50001.00",
  "A": "1.2",
  "mt": "s"
}

MarkPrice

Topic: SYMBOL@markPrice, !markPrice@arr

{
  "e": "markPriceUpdate",
  "E": 1706745600000000,
  "s": "BTC-USD",
  "p": "50000.50",
  "i": "50000.00",
  "r": "0.0001",
  "T": 1706774400000000
}

Mark-price E is publication time in Unix microseconds. Oracle and funding updates can republish the same cached mark with a new E.

Two optional DEX fields identify the actual cached mark event:

These fields and th refer to the mark event, even when an oracle or funding update triggers publication. Startup REST snapshots and upstream events without a transaction hash or event number omit the new fields: their mark execution identity is unknown. Never reinterpret E or the client’s receive time as archived execution time.

To join recent mark history, subscribe and buffer live events before fetching history. Merge identified events by (th, mark_event_number) (history calls th txHash), using execution timestamps for ordering and second buckets. Repeated publications of the same mark add no observation. Take the greatest (timestampUs, eventNumber, txHash) per UTC second, comparing event numbers as integers, and retain the winning event’s actual execution timestamp. Do not shift history to publication time or overwrite a newer live tail with an older HTTP result. Unknown-identity snapshots may update a current-price label, but must not seed historical observations. Missing intervals remain gaps; do not forward-fill them for volatility. Late history can repair older buckets but must not reset the current live price or replay chart animations.

Liquidation (ForceOrder)

Topic: SYMBOL@liquidations, SYMBOL@forceOrder, !liquidations, !forceOrder, liquidations, forceOrders

{
  "e": "liquidation",
  "E": 1706745600000000,
  "o": {
    "s": "BTC-USD",
    "S": "SELL",
    "o": "LIMIT",
    "f": "IOC",
    "p": "49000.00",
    "ap": "49000.00",
    "X": "FILLED",
    "l": "1.0",
    "T": 1706745600000000,
    "th": "0xabc123def456",
    "ua": "0xuser123",
    "oi": 100001,
    "ti": 200001
  }
}

Market Status

Topic: marketStatus, marketStatuses, !marketStatus, !marketStatus@arr

Every market’s trading status. On subscribe you get a full snapshot (mt: "s"); after that only what changed (mt: "u"). Each update message carries every change observed in one refresh, so a single message may list several markets. The status vocabulary is the same as the status field of GET /fapi/v1/exchangeInfo, and the feed covers the same symbols (perpetuals; spot markets are not reported).

{
  "e": "marketStatusUpdate",
  "E": 1706745600000000,
  "mt": "s",
  "m": [
    {
      "s": "BTC-USD",
      "i": 1,
      "st": "TRADING"
    },
    {
      "s": "ETH-USD",
      "i": 2,
      "st": "POST_ONLY"
    }
  ]
}

{
  "e": "marketStatusUpdate",
  "E": 1706745600000000,
  "mt": "u",
  "m": [
    {
      "s": "BTC-USD",
      "i": 1,
      "st": "HALT",
      "ps": "TRADING",
      "ch": "status"
    },
    {
      "s": "SOL-USD",
      "i": 3,
      "st": "POST_ONLY",
      "ch": "listed"
    },
    {
      "s": "OLD-USD",
      "i": 7,
      "st": "CLOSE",
      "ch": "delisted"
    }
  ]
}

Status values (st):

Change values (ch):

ch: "status" covers any change to an existing market’s reported state: its status, its symbol, or both. ps is the previous status, so ps == st means only the symbol changed. Every entry carries the market’s current s and st in full, so applying the entry as-is converges either way.

Deltas are idempotent — applying one twice leaves you in the same state — so a client may safely replay the last message it received.

Notes:

• The snapshot arrives once the server has synced the market registry. A client that subscribes before the very first sync receives nothing until it lands.
• Most status changes are picked up from the rollup as they happen; if that event stream is interrupted, they still arrive on the registry’s periodic refresh.
• One transition is only ever observed on that periodic refresh, because the rollup emits no event for it: a market moving to CLOSE during force-settle.

OrderUpdate

Topic: ADDRESS@user.orders, ADDRESS@ORDER_TRADE_UPDATE

Published for order lifecycle events (NEW, TRADE, CANCELED).

{
  "e": "orderTradeUpdate",
  "E": 1706745600000000,
  "o": {
    "s": "BTC-USD",
    "i": 100001,
    "X": "NEW",
    "x": "NEW",
    "T": 1706745600000000,
    "th": "0xabc123def456",
    "ua": "",
    "S": "BUY",
    "o": "LIMIT",
    "f": "GTC",
    "p": "50000.00",
    "q": "1.0"
  }
}

Common fields (all events):

NEW order additional fields:

TRADE fill additional fields:

{
  "e": "orderTradeUpdate",
  "E": 1706745600000000,
  "o": {
    "s": "BTC-USD",
    "i": 100001,
    "X": "FILLED",
    "x": "TRADE",
    "T": 1706745600000000,
    "th": "0xabc123def456",
    "ua": "",
    "S": "BUY",
    "ap": "50000",
    "l": "1.0",
    "L": "50000.00",
    "n": "0.025",
    "N": "USDC",
    "m": false,
    "isDegen": false,
    "t": 200001,
    "rp": "10.50",
    "ft": "o",
    "z": "1.0",
    "Z": "50000.00",
    "rs": "0"
  }
}

Fill type values (ft):

Topics

Symbol-Based Topics

Symbol format: Bullet uses BTC-USD (hyphen), Binance uses btcusdt (lowercase, no separator)

Kline intervals: 1m, 5m, 15m, 30m, 1h, 4h, 1d (coming soon)

Parse errors: InvalidFormat, MissingSymbol, InvalidDepth, InvalidInterval, UnknownTopic Resolution errors: SymbolNotFound

Broadcast Topics

Parse errors: InvalidFormat, UnknownTopic

User Data Topics

Key difference: Bullet uses address-prefixed topics directly. Binance requires a listenKey from REST API.

Note: Use your main account address, not the delegate address. Order updates for delegate trades are published under the main account.

Resolution errors: MissingUserAddress (when address not provided)

Speed Suffixes

Speed suffixes are accepted but ignored: @100ms, @500ms, @1s

Example: BTC-USD@depth@100ms is equivalent to BTC-USD@depth

Error Codes

General

Parameters

Subscriptions

Orders

Internal

Notes

DEX-Specific Fields

DEX-specific fields use 2-letter codes for compactness:

Message Type Field

The mt field in orderbook and BBO messages indicates:

• "s" - snapshot (complete state at that depth level)
• "u" - update (incremental changes since last update)

Response Format Differences

• All responses use e field for event type (e.g., "e":"subscribe", "e":"error")
• Order responses still use Binance-style format with status code
• Market data messages use e field for event type (e.g., "e":"depthUpdate")