WebSocket›Trade WebSocket

WSS

Level2 Order Book

Establish a WebSocket connection to get real-time updates for order books. Subscribe to a live feed of all outstanding buy and sell orders on the market for specific coins and tokens. Send messages when specific market conditions occur.

Connection behavior

  • Heartbeat — the server sends a WebSocket ping about every 54 seconds and expects a pong within 60 seconds; standard clients respond automatically.
  • Reconnect — a disconnect clears all subscriptions; after reconnecting you must subscribe again.

Connection

WSS wss://app.bitgo-test.com/api/prime/trading/v1/ws

Channel level2

Authorization Send the BitGo access token as Authorization: Bearer {token} on the connection upgrade request. The token must have the trade_view scope. If the token is missing or invalid the upgrade is refused with HTTP 403 and no socket is opened. Authorization or permission failures that happen after the socket is open — for example subscribing to an account you do not have access to — come back as WebSocket error messages (the socket stays open), not as HTTP 403.

Messages sent

Subscribe / Unsubscribe

Event subscription details for Order Books.

object

  • type string required
    The event type (e.g. "subscribe" or "unsubscribe")
  • channel string required
    The subscription channel (e.g. "level2" for order books)
  • accountId string required
    The ID of the account
  • productId string required
    The ID of product. (e.g. "TBTC-TUSD*")
  • includeCumulative boolean
    Include cumulative size in each price level. When true, each level is [price, size, cumulativeSize] instead of [price, size]. cumulativeSize is the running total of size from the top of that side through the level.

    Defaults to false

Messages received

Order book snapshot

The full level2 order book. Sent on subscribe and refreshed as the book changes; each message is a complete snapshot.

object

  • channel string
    The channel name (e.g. "level2").
  • type string
    The type of the response (e.g. "snapshot").
  • product string
    The product name (e.g. "TBTC-TUSD*").
  • time string date-time
    The timestamp of the snapshot.
  • bids array of array
    An array of bid levels [price, size] or [price, size, cumulativeSize] when includeCumulative is true. cumulativeSize is the running total of size from the top of that side through the level.
  • asks array of array
    An array of ask levels [price, size] or [price, size, cumulativeSize] when includeCumulative is true. cumulativeSize is the running total of size from the top of that side through the level.

Subscription acknowledgement

Sent after every subscribe/unsubscribe request to confirm the outcome.

object

  • type string enum required
    Always "subscription_response".
    subscription_response
  • channel string enum required
    The channel the subscription applies to ("orders" or "level2").
    orderslevel2
  • status string enum required

    Outcome of the subscribe/unsubscribe request:

    • subscribed — subscription was accepted and is now active.
    • already_subscribed — (orders channel only) a subscription for this accountId was already active; no duplicate was created. For the level2 channel, duplicate subscribe requests return an error instead, because includeCumulative is fixed for the lifetime of a subscription and cannot be changed without unsubscribing first.
    • unsubscribed — subscription was successfully removed.
    subscribedalready_subscribedunsubscribed
  • accountId string
    The ID of the account
  • productId string
    The product ID, present for level2 subscriptions.
  • session_id string
    The session ID for this WebSocket connection.

System message

Connection-level status. Sent on connect with status connected.

object

  • type string enum required
    system
  • status string enum required
    Connection status.
    connected
  • session_id string
    Session ID for this WebSocket connection.

Error

Sent when a subscribe or other message cannot be processed after the connection is open — for example an invalid message, a product that is not supported, or an account you do not have access to. The socket stays open.

object

  • type string enum required
    Always "error".
    error
  • message string required
    Human-readable description of the error.
  • session_id string
    The session ID for this WebSocket connection.