Skip to main content

Advanced Trade WebSocket Channels

Use heartbeats to keep all subscriptions open

Most channels close within 60-90 seconds if no updates are sent. Subscribe to heartbeats to keep all subscriptions open.

The Coinbase Advanced Trade Market Data WebSocket feed provides the following channels:

ChannelDescription
heartbeatsReal-time server pings to keep all connections open
candlesReal-time updates on product candles
statusSends all products and currencies on a preset interval
tickerReal-time price updates every time a match happens
ticker_batchReal-time price updates every 5000 milli-seconds
level2All updates and easiest way to keep order book snapshot
userOnly sends messages that include the authenticated user
market_tradesReal-time updates every time a market trade happens

Refer to the documentation on subscribing to a WebSocket channel.

Heartbeats Channel

Subscribe to the heartbeats channel to receive heartbeats messages for specific products every second. Heartbeats include a heartbeat_counter which verifies that no messages were missed.

tip

Subscribing to the heartbeats channel, alongside other channels, ensures that all subscriptions stay open when updates are sparse. This is useful, for example, when fetching market data for illiquid pairs.

// Request
{
"type": "subscribe",
"product_ids": [
"ETH-USD"
],
"channel": "heartbeats",
"jwt": "XYZ",
"timestamp": 1675974199
}

A heartbeats message is of the type heartbeats as seen below.

// Heartbeats Message
{
"channel": "heartbeats",
"client_id": "",
"timestamp": "2023-06-23T20:31:26.122969572Z",
"sequence_num": 0,
"events": [
{
"current_time": "2023-06-23 20:31:56.121961769 +0000 UTC m=+91717.525857105",
"heartbeat_counter": "3049",
}
]
}

Candles Channel

Subscribe to the candles channel to receive candles messages for specific products with updates every second. Candles are grouped into buckets (granularities) of five minutes.

// Request
{
"type": "subscribe",
"product_ids": [
"ETH-USD"
],
"channel": "candles",
"jwt": "XYZ",
"timestamp": 1675974199
}

A candles message is of the type candles and some of its parameters include:

  • start - string representation of the UNIX timestamp of the candle.
  • high and low - highest and lowest prices during the bucket interval.
  • open and close - prices of the first and last trade respectively.
  • volume - base amount that has been traded during this interval.
  • product_id - product identifier for this candle
// Candles Message
{
"channel": "candles",
"client_id": "",
"timestamp": "2023-06-09T20:19:35.39625135Z",
"sequence_num": 0,
"events": [
{
"type": "snapshot",
"candles": [
{
"start": "1688998200",
"high": "1867.72",
"low": "1865.63",
"open": "1867.38",
"close": "1866.81",
"volume": "0.20269406",
"product_id": "ETH-USD",
}
]
}
]
}

Market Trades Channel

The market_trades channel sends market trades for a specified product on a preset interval. Clients should provide an array of product_ids for which they would like status subscriptions.

// Request
{
"type": "subscribe",
"product_ids": [
"ETH-USD",
"BTC-USD"
],
"channel": "market_trades",
"jwt": "XYZ",
"timestamp": 1675974199
}

A market trades message is of the type snapshot or update, and contains an array of market trades. Each market trade belongs to a side, which refers to the makers side, and can be of type BUY, or SELL. The channel collects all updates over the last 250 ms and sends them as an update -- so an update can contain one or many trades, depending on the last 250 ms of trading volume.

// Market Trades Message
{
"channel": "market_trades",
"client_id": "",
"timestamp": "2023-02-09T20:19:35.39625135Z",
"sequence_num": 0,
"events": [
{
"type": "snapshot",
"trades": [
{
"trade_id": "000000000",
"product_id": "ETH-USD",
"price": "1260.01",
"size": "0.3",
"side": "BUY",
"time": "2019-08-14T20:42:27.265Z",
}
]
}
]
}

Status Channel

The status channel sends all products and currencies on a preset interval. Clients should provide an array of product_ids for which they would like status subscriptions.

caution

The status channel, like most channels, closes within 60-90 seconds when there are no updates. For example, if you listen for BTC-USD updates and nothing changes within 60-90 seconds (which is common), the channel closes. To avoid this, subscribe to the heartbeats in addition to your other channels.

// Request
{
"type": "subscribe",
"product_ids": [
"ETH-USD",
"BTC-USD"
],
"channel": "status",
"jwt": "XYZ",
"timestamp": 1675974199
}
// Status Message
{
"channel": "status",
"client_id": "",
"timestamp": "2023-02-09T20:29:49.753424311Z",
"sequence_num": 0,
"events": [
{
"type": "snapshot",
"products": [
{
"product_type": "SPOT",
"id": "BTC-USD",
"base_currency": "BTC",
"quote_currency": "USD",
"base_increment": "0.00000001",
"quote_increment": "0.01",
"display_name": "BTC/USD",
"status": "online",
"status_message": "",
"min_market_funds": "1"
}
]
}
]
}

Ticker Channel

The ticker channel provides real-time price updates every time a match happens. It batches updates in case of cascading matches, greatly reducing bandwidth requirements.

// Request
{
"type": "subscribe",
"product_ids": [
"ETH-USD",
"BTC-USD"
],
"channel": "ticker",
"jwt": "XYZ",
"timestamp": 1675974199
}
// Ticker messsage
{
"channel": "ticker",
"client_id": "",
"timestamp": "2023-02-09T20:30:37.167359596Z",
"sequence_num": 0,
"events": [
{
"type": "snapshot",
"tickers": [
{
"type": "ticker",
"product_id": "BTC-USD",
"price": "21932.98",
"volume_24_h": "16038.28770938",
"low_24_h": "21835.29",
"high_24_h": "23011.18",
"low_52_w": "15460",
"high_52_w": "48240",
"price_percent_chg_24_h": "-4.15775596190603"
}
]
}
]
}

Ticker Batch Channel

The ticker_batch channel provides latest price updates every 5000 milliseconds (5 seconds) if there is a change. It has the same JSON message schema as the ticker channel, except the channel field will have a value of ticker_batch.

// Request
{
"type": "subscribe",
"product_ids": [
"ETH-USD",
"BTC-USD"
],
"channel": "ticker_batch",
"jwt": "XYZ",
"timestamp": 1675974199
}

Level2 Channel

The level2 channel guarantees delivery of all updates and is the easiest way to keep a snapshot of the order book.

// Request
{
"type": "subscribe",
"product_ids": [
"ETH-USD",
"BTC-USD"
],
"channel": "level2",
"jwt": "XYZ",
"timestamp": 1675974199
}
tip

Subscribe to the level2 channel to guarantee that messages are delivered and your order book is in sync.

The level2 channel sends a message with fields, type ("snapshot" or "update"), product_id, and updates. The field updates is an array of objects of {price_level, new_quantity, event_time, side} to represent the entire order book. Theevent_time property is the time of the event as recorded by our trading engine.

info

The new_quantity property is the updated size at that price level, not a delta. A new_quantity of "0" indicates the price level can be removed.

// Example:
{
"channel": "l2_data",
"client_id": "",
"timestamp": "2023-02-09T20:32:50.714964855Z",
"sequence_num": 0,
"events": [
{
"type": "snapshot",
"product_id": "BTC-USD",
"updates": [
{
"side": "bid",
"event_time": "1970-01-01T00:00:00Z",
"price_level": "21921.73",
"new_quantity": "0.06317902"
},
{
"side": "bid",
"event_time": "1970-01-01T00:00:00Z",
"price_level": "21921.3",
"new_quantity": "0.02"
},
]
}
]
}

User Channel

The user channel sends updates on all of a user's open orders, including all subsequent updates of those orders.

The user channel expects one connection per user:

  • This connection accepts multiple product IDs in a product_ids array. If none are provided, the websocket subscription is open to all product IDs.
  • To subscribe to new product_ids, close your previous connection by unsubscribing and open a new connection with product_ids added to the array.
tip

Subscribing to the User channel returns all OPEN orders, batched by 50, in the first few messages of the stream. For example, if you have 109 orders, you will get a snapshot containing 50 orders, followed by a patch of 50 orders, followed by a patch of 9 orders. To know when all of your open orders are returned, look for the first message with less than 50 orders.

// Request must contain user_id 
{
"type": "subscribe",
"channel": "user",
"product_ids" :["BTC-USD"],
"jwt": "XYZ",
"timestamp": 1675974199
}
// User message
{
"channel": "user",
"client_id": "",
"timestamp": "2023-02-09T20:33:57.609931463Z",
"sequence_num": 0,
"events": [
{
"type": "snapshot",
"orders": [
{
"order_id": "XXX",
"client_order_id": "YYY",
"cumulative_quantity": "0",
"leaves_quantity": "0.000994",
"avg_price": "0",
"total_fees": "0",
"status": "OPEN",
"product_id": "BTC-USD",
"creation_time": "2022-12-07T19:42:18.719312Z",
"order_side": "BUY",
"order_type": "Limit"
},
]
}
]
}
FieldDescription
order_idUnique identifier of order
client_order_idUnique identifier of order specified by client
cumulative_quantityAmount the order is filled, in base currency
leaves_quantityAmount remaining, in same currency as order was placed in (quote or base)
avg_priceAverage filled price of the order so far
total_feesCommission paid for the order
statusCan be one of:
  • PENDING: Order is not yet open
  • OPEN: Order is waiting to be fully filled
  • FILLED: Order is 100% filled
  • CANCELLED: Order was cancelled by user or system
  • EXPIRED: TWAP order was not filled by the expiry time
  • FAILED: Order cannot be placed at all
product_idThe product ID for which this order was placed
creation_timeWhen the order was placed
order_sideCan be one of: BUY, SELL
order_typeCan be one of: Limit, Market, Stop Limit

See Also:

Was this helpful?