WebSocket

BitGo WebSocket

Overview

The BitGo WebSocket API provides real-time, bidirectional communication over a persistent connection. Unlike REST endpoints, which require you to poll for updates, the WebSocket API pushes data to your client as events occur. This makes it well suited for latency-sensitive use cases such as live order book feeds, trade order status monitoring, and low-latency order placement and cancellation.

The Trade WebSocket endpoint is available for BitGo Prime trading and supports the following channels and operations:

  • Order books (level2) — Subscribe to a live feed of outstanding buy and sell orders for specific products. Receive a snapshot of the current order book followed by incremental updates as bids and asks change.
  • Orders (orders) — Subscribe to live status updates for your orders, including individual fills, cancellations, and errors.
  • Place order (place_order) — Place a new order on an established connection. On acceptance, the response returns id and clientOrderId; subscribe to orders for full lifecycle updates. Order fields and validation match the REST Place Order endpoint.
  • Cancel order (cancel_order) — Request cancellation of a previously placed order. The response confirms the cancel request was accepted; confirm final status on the orders channel or Get Order. See the REST Cancel Order endpoint for validation error codes.

OpenAPI 3.0 Specification

You can download the BitGo WebSocket OpenAPI 3.0 specification as a JSON or YAML file and run it in tools like Swagger UI or Postman.

Connect

Establish a WebSocket connection to the BitGo Trade WebSocket endpoint:

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

Include your access token in the Authorization header:

wscat \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --connect wss://app.bitgo.com/api/prime/trading/v1/ws

For the test environment, replace app.bitgo.com with app.bitgo-test.com.

On Connect

When the connection is established, the server sends a system message with status: connected and a session_id for the connection.

Subscribe

After connecting, send a JSON subscribe message to begin receiving events. Each channel requires its own subscribe message.

Order Books

{
  "type": "subscribe",
  "channel": "level2",
  "accountId": "f230fdebfa084ffebc7e00515f54603f",
  "productId": "BTC-USD"
}

Trade Orders

{
  "type": "subscribe",
  "channel": "orders",
  "accountId": "f230fdebfa084ffebc7e00515f54603f"
}

Unsubscribe

To stop receiving events for a channel, send an unsubscribe message:

{
  "type": "unsubscribe",
  "channel": "orders",
  "accountId": "f230fdebfa084ffebc7e00515f54603f"
}

Place Order

Send a place_order message on an established connection to place a new order. When status is accepted, the response contains only id and clientOrderId. Subscribe to the orders channel for fills and status changes.

clientOrderId is required on WebSocket (optional on REST). If a place_order_response is lost, retry with the same clientOrderId and a new reqId.

{
  "type": "place_order",
  "reqId": "c2a8e4f0-9b1d-4e7a-8c3f-1e2d3f4a5b6c",
  "accountId": "f230fdebfa084ffebc7e00515f54603f",
  "order": {
    "clientOrderId": "my-order-uuid-2026-06-16-001",
    "type": "limit",
    "product": "BTC-USD",
    "side": "buy",
    "quantity": "0.5",
    "quantityCurrency": "BTC",
    "limitPrice": "100000",
    "timeInForce": "GTC"
  }
}

The order object matches REST NewOrderRequest (market, limit, TWAP, steady_pace, stop). See Place Order for the full schema, and the Trade Guide for order-type fields.

Note

Retrying with the same clientOrderId on WebSocket returns accepted with the original order. The REST Place Order endpoint returns 409 for a duplicate clientOrderId instead.

Cancel Order

Send a cancel_order message on an established connection to cancel a previously placed order. A successful response confirms the cancel request was accepted, not that the order is already canceled.

{
  "type": "cancel_order",
  "reqId": "c2a8e4f0-9b1d-4e7a-8c3f-1e2d3f4a5b6c",
  "accountId": "f230fdebfa084ffebc7e00515f54603f",
  "orderId": "8a1f2e3d-4c5b-6a7e-8f9d-0a1b2c3d4e5f"
}

See Cancel Order for the full request schema and response examples.

Authentication

Opening a WebSocket connection requires an access token with the trade_view scope. Placing or canceling orders requires trade_trade on that same token. Scopes are declared on the access token supplied in the Authorization header during the HTTP upgrade — they are not sent on individual WebSocket frames.

For more information, see Access Tokens.

  • Subscribe to the orders channel on a connection used for order lifecycle updates (fills, completion, cancellation).
  • Prefer a dedicated connection (or prioritize outbound handling) for place_order / cancel_order if you also subscribe to high-volume channels such as level2 — write acknowledgements share the same outbound channel as other messages.
  • Generate a unique reqId for each place_order or cancel_order send to correlate the matching *_response. Do not use reqId for idempotency or order lookup.
  • Use clientOrderId for idempotent placement: if a place_order_response is lost, resend with the same clientOrderId and a new reqId.
  • Treat place_order_response and cancel_order_response as request acknowledgements only. Confirm final order state on the orders channel or via Get Order.

See Also