Advanced Trade WebSocket Channels
In Beta: All WebSocket channels except User can be used without authentication. For the most reliable connection, authenticate with a CDP API key when subscribing.
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:
| Channel | Description | Requires Authentication |
|---|---|---|
| heartbeats | Real-time server pings to keep all connections open | No |
| candles | Real-time updates on product candles | No |
| status | Sends all products and currencies on a preset interval | No |
| ticker | Real-time price updates every time a match happens | No |
| ticker_batch | Real-time price updates every 5000 milli-seconds | No |
| level2 | All updates and easiest way to keep order book snapshot | No |
| user | Only sends messages that include the authenticated user | Yes |
| market_trades | Real-time updates every time a market trade happens | No |
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.
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"
}
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"
}
A candles message is of the type candles and some of its parameters include:
start- string representation of the UNIX timestamp of the candle.highandlow- highest and lowest prices during the bucket interval.openandclose- 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"
}
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. They are automatically subscribed to all products if product_ids is not provided.
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"
}
// 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"
}
// 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",
"best_bid": "21931.98",
"best_bid_quantity": "8000.21",
"best_ask": "21933.98",
"best_ask_quantity": "8038.07770938"
}
]
}
]
}
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"
}
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"
}
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.
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_idsarray. 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 withproduct_idsadded to the array.
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"
}
// 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",
"limit_price": "0",
"stop_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"
}
]
}
]
}
| Field | Description |
|---|---|
order_id | Unique identifier of order |
client_order_id | Unique identifier of order specified by client |
cumulative_quantity | Amount the order is filled, in base currency |
leaves_quantity | Amount remaining, in same currency as order was placed in (quote or base) |
avg_price | Average filled price of the order so far |
total_fees | Commission paid for the order |
status | Can be one of:
|
product_id | The product ID for which this order was placed |
creation_time | When the order was placed |
order_side | Can be one of: BUY, SELL |
order_type | Can be one of: Limit, Market, Stop Limit |
limit_price | Can be one of:
|
stop_price | Can be one of:
|
See Also: