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 |
futures_balance_summary | Real-time updates every time a user’s futures balance changes | Yes |
heartbeats
channel to receive heartbeats messages every second. Heartbeats include a heartbeat_counter
which verifies that no messages were missed.
heartbeats
as seen below.
candles
channel to receive candles messages for specific products with updates every second. Candles are grouped into buckets (granularities) of five minutes.
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 candlemarket_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.
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.
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.
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.ticker
channel provides real-time price updates every time a match happens. It batches updates in case of cascading matches, greatly reducing bandwidth requirements.
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
and it currently doesn’t provide best bid or best ask fields.
level2
channel guarantees delivery of all updates and is the easiest way to keep a snapshot of the order book.
level2
channel to guarantee that messages are delivered and your order book is in sync.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.
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.user
channel sends updates on all of a user’s open orders and current positions, including all subsequent updates of those orders and positions.
The user
channel expects one connection per user:
product_ids
array. If none are provided, the WebSocket subscription is open to all product IDs.product_ids
, close your previous connection by unsubscribing and open a new connection with product_ids
added to the array.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.Field | Description |
---|---|
avg_price | Average filled price of the order so far |
cancel_reason | Reason for order cancellation |
client_order_id | Unique identifier of order specified by client |
completion_percentage | Percentage of order completion |
contract_expiry_type | Can be one of:
|
cumulative_quantity | Amount the order is filled, in base currency |
filled_value | Value of the filled order |
leaves_quantity | Amount remaining, in same currency as order was placed in (quote or base) |
limit_price | Can be one of:
|
number_of_fills | Number of fills for the order |
order_id | Unique identifier of order |
order_side | Can be one of:
|
order_type | Can be one of:
|
outstanding_hold_amount | Outstanding hold amount for the order |
post_only | Can be one of:
|
product_id | The product ID for which this order was placed |
product_type | Can be one of:
|
reject_Reason | Reason for order rejection |
retail_portfolio_id | The ID of the portfolio this order is associated with. |
risk_managed_by | Can be one of:
|
status | Can be one of:
|
stop_price | Can be one of:
|
time_in_force | Can be one of:
|
total_fees | Commission paid for the order |
total_value_after_fees | Total value of the order after fees |
trigger_status | Can be one of:
|
creation_time | When the order was placed |
end_time |
|
start_time |
|
positions
fields are in beta and is currently returned as an empty array by default. To enable access to the positions
fields in the User WebSocket channel, please reach out to us through Discord.Field | Description |
---|---|
product_id | Name of the instrument the position is in, e.g. BTC-PERP-INTX |
portfolio_uuid | The uuid of the portfolio this order is associated with |
vwap | The price of the position based on the last settlement period |
entry_vwap | Volume weighted entry price of the position (not reset to the last funding price) |
position_side | The side of the position. Can be one of:
|
margin_type | The margin type of the position. Can be one of:
|
net_size | The size of the position with positive values reflecting a long position and negative values reflecting a short position |
buy_order_size | Cumulative size of all the open buy orders |
sell_order_size | Cumulative size of all the open sell orders |
leverage | The leverage of the position |
mark_price | The current mark price value for the instrument of this position used in risk and margin calculations |
liquidation_price | Price at which the position will be liquidated at |
im_notional | The amount this position contributes to the initial margin |
mm_notional | The amount this position contributes to the maintenance margin |
position_notional | The notional value of the position |
unrealized_pnl | The profit or loss of this position (resets to 0 after settlement) |
aggregated_pnl | The total profit or loss of this position since the initial opening of the position |
Field | Description |
---|---|
product_id | Name of the instrument the position is in, e.g. BTC-12Jun24-CDE |
side | The side of the position. Can be one of:
|
number_of_contracts | The size of your position in contracts |
realized_pnl | Your realized PnL for your position |
unrealized_pnl | Your current unrealized PnL for your position |
entry_price | The average entry price at which you entered your current position |
futures_balance_summary
channel sends updates on all of a user’s futures balances, including all subsequent updates of those balances.
Field | Description |
---|---|
futures_buying_power | The amount of your cash balance that is available to trade CFM futures |
total_usd_balance | Aggregate USD maintained across your CFTC-regulated futures account and your Coinbase Inc. spot account |
cbi_usd_balance | USD maintained in your Coinbase Inc. spot account |
cfm_usd_balance | USD maintained in your CFTC-regulated futures account. Funds held in your futures account are not available to trade spot |
total_open_orders_hold_amount | Your total balance on hold for spot and futures open orders |
unrealized_pnl | Your current unrealized PnL across all open positions |
daily_realized_pnl | Your realized PnL from the current trade date. May include profit or loss from positions you’ve closed on the current trade date |
initial_margin | Margin required to initiate futures positions. Once futures orders are placed, these funds cannot be used to trade spot. The actual amount of funds necessary to support executed futures orders will be moved to your futures account |
available_margin | Funds available to meet your anticipated margin requirement. This includes your CBI spot USD, CFM futures USD, and Futures PnL, less any holds for open spot or futures orders |
liquidation_threshold | When your available funds for collateral drop to the liquidation threshold, some or all of your futures positions will be liquidated |
liquidation_buffer_amount | Funds available in excess of the liquidation threshold, calculated as available margin minus liquidation threshold. If your liquidation buffer amount reaches 0, your futures positions and/or open orders will be liquidated as necessary |
liquidation_buffer_percentage | Funds available in excess of the liquidation threshold expressed as a percentage. If your liquidation buffer percentage reaches 0%, your futures positions and/or open orders will be liquidated as necessary |
intraday_margin_window_measure | The period of time used to calculate margin requirements for positions held intraday before settling overnight Includes:
|
overnight_margin_window_measure | The period of time used to calculate increased margin requirements for positions held and left unsettled overnight Includes:
|