WebSocket›Trade WebSocket

WSS

Orders

Establish a WebSocket connection for order updates and order write operations.

Opening the connection requires an access token with the trade_view scope. Placing or canceling orders requires trade_trade on that same token.

Subscribe to live status updates for your orders, including individual fills.

You can also send place_order and cancel_order messages on an established WebSocket connection (see those operations). Subscribe to the orders channel to receive full lifecycle updates after placement or cancellation.

Correlation: Supply a unique reqId on each place_order or cancel_order to match the corresponding *_response. Use reqId only for response correlation — not for idempotency or order lookup (clientOrderId / orderId serve those roles).

Message ordering: place_order_response, cancel_order_response, and orders channel updates may arrive out of order on the same connection.

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 orders

Authorization Send the BitGo access token as Authorization: Bearer {token} on the connection upgrade request. The token must have the trade_view scope (and trade_trade if you will send place_order / cancel_order messages on this connection). 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 Orders.

object

  • type string enum required
    The event type ("subscribe" or "unsubscribe")
    subscribeunsubscribe
  • channel string enum required
    The subscription channel for order events ("orders")
    orders
  • accountId string required
    The ID of the account

Messages received

Order event

Order status updates and individual fills for the accounts you subscribe to.

ONE OF

  • channel string
    The channel you are subscribed to.
  • time string date-time
  • creationDate string date-time
  • completionDate string date-time
  • settleDate string date-time
  • scheduledDate string date-time
    Date to schedule the order. If not provided, the order will be placed immediately.
  • lastFillDate string date-time
  • accountId string
    The ID of the account
  • clientOrderId string
    Client-supplied identifier for a single logical order. Must be unique among concurrent open orders in your account. Reuse the same clientOrderId when retrying a place_order after a lost or ambiguous acknowledgement — the server treats a duplicate placement with the same clientOrderId as an idempotent retry (unlike REST, which returns 409). Do not reuse a clientOrderId for a different order.

    up to 256 characters

  • orderId string
    The ID of the order.
  • product string
    Product name.
  • fundingType string enum

    The funding type of the order.

    • Funded orders will be placed using the Go account balance.
    • Margin orders will be placed using the margin account balances. See our Trade Guide for more details on each funding type.

    Defaults to funded

    marginfunded
  • status string enum
    pending_openopencompletedpending_cancelcancelederrorscheduled
  • execType string

    The type of update, using FIX 4.4 ExecType (tag 150) values. Use this field to distinguish order status updates from fill events.

    • F (Trade) — a fill occurred; check tradeId, fillQuantity, fillPrice for fill details
    • 0 (New) — order accepted by the exchange
    • A (Pending New) — order submitted, awaiting acceptance
    • 6 (Pending Cancel) — cancel request sent
    • 4 (Canceled) — order canceled
    • 8 (Rejected) — order rejected or internal failure
    • I (Order Status) — terminal status summary (e.g. completed)
  • type string enum
    The type of order to be placed. See our Trade Guide for more details on each order type.
    markettwaplimitsteady_pacestop
  • side string enum
    buysell
  • quantity string decimal
    The specified quantity.
  • quantityCurrency string
    The specified quantity currency.
  • cumulativeQuantity string decimal
    The total base quantity filled for the order.
  • cumulativeQuoteQuantity string decimal
    The total quote quantity filled for the order.
  • leavesQuantity string decimal

    For orders created with base currency, this field is set to the remaining unfilled base quantity.

    • Only one of leavesQuantity or leavesQuoteQuantity will be set.
    • This field is set to null for orders created with quote currency.
  • leavesQuoteQuantity string decimal

    For orders created with quote currency, this field is set to the remaining unfilled quote quantity.

    • Only one of leavesQuantity or leavesQuoteQuantity will be set.
    • This field is set to null for orders created with base currency.
  • averagePrice string decimal
    The average price for the order's fills.
  • tradeId string
    The ID of the trade.
  • fillQuantity string decimal
    The quantity of the fill for the trade.
  • fillPrice string decimal
    The price of the fill for the trade.
  • source string

    The originating channel for the order.

    • api_fix — order placed via FIX 4.4 session
    • api_rest — order placed via REST API
    • api_websocket — order placed via WebSocket API
  • triggerPrice string decimal nullable
    Stop/trigger price for stop and stop-limit orders. Null for other order types.
  • limitPrice string decimal nullable
    Limit price for limit, TWAP-with-limit, and SteadyPace-with-limit orders. Null when not set.
  • timeInForce string nullable
    Time-in-force (1 GTC, 3 IOC, 4 FOK, 6 GTD). Null when not set.
  • duration integer nullable
    Order duration in seconds for TWAP and SteadyPace orders. Null for other order types.
  • twapInterval integer nullable
    TWAP slice interval in minutes when isTimeSliced is true. Null for non-TWAP orders and when not time-sliced.
  • isTimeSliced boolean nullable
    TWAP time-slicing flag. Null for non-TWAP orders. When true, use twapInterval; when false, boundsControl may be set instead.
  • boundsControl string nullable
    TWAP bounds control (narrow, standard, wide) for non-time-sliced TWAP orders. Null for time-sliced TWAP and non-TWAP orders.
  • interval integer nullable
    SteadyPace interval length. Null for non-SteadyPace orders.
  • intervalUnit string nullable
    SteadyPace interval unit (second, minute, hour). Null for non-SteadyPace orders.
  • subOrderSize string decimal nullable
    SteadyPace sub-order size. Null for non-SteadyPace orders.
  • variance string decimal nullable
    Optional SteadyPace sub-order size variance (0–1). Null for non-SteadyPace orders.

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.

Place order response

Acknowledgement or rejection for a place_order request sent on this connection. See the Place Order operation for the full schema and examples.

ONE OF

  • type string enum required
    place_order_response
  • reqId string
    Echoed when the client supplied a valid reqId.
  • status string enum required
    accepted
  • order object required
    Slim acknowledgement returned on accepted place_order_response. Contains only identity fields.
    order object
    • id string uuid required
      Assigned order ID.
    • clientOrderId string
      Client-supplied order ID from the request.

Cancel order response

Acknowledgement or rejection for a cancel_order request sent on this connection. See the Cancel Order operation for the full schema and examples.

ONE OF

  • type string enum required
    cancel_order_response
  • reqId string
    Echoed when the client supplied a valid reqId.
  • status string enum required
    accepted
  • orderId string uuid required
    Echoes the orderId from the cancel_order request.

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 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.