WebSocket

WebSocket Overview

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 and trade order status monitoring.

The Trade WebSocket endpoint is currently available for BitGo Prime trading and supports two subscription channels:

  • Order books (level2) — Receive a snapshot of the current order book followed by incremental updates as bids and asks change.
  • Trade orders (orders) — Receive real-time lifecycle events for your trade orders, including fills, cancellations, and errors.

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.

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

Authentication

WebSocket connections require a valid BitGo access token with the trade_view scope. Pass the token in the Authorization header when establishing the connection. For more information, see Access Tokens.

See Also