Subscriptions

Subscriptions deliver real-time updates over WebSocket. You call subscribe with a list of channel names, and the server streams an update frame each time the underlying data changes.

Subscriptions are WebSocket-only. The subscribe / unsubscribe methods and the notification frames they produce are not available over HTTP POST. See Endpoints for the WebSocket endpoints.

Notification model

A subscription update is a JSON-RPC-style notification frame: it has a method of "subscription" and no id (it is server-pushed, not a reply to any request). The payload carries the channel that produced it and the data:

{
  "method": "subscription",
  "params": {
    "channel": "trades.ETH-PERP",
    "data": {}
  }
}

The shape of data depends on the channel. For the exact per-channel payload schema, see the generated Subscriptions reference under the API Reference tab.

Subscribing

Send a subscribe request with a channels array. The response reports a per-channel status and the connection’s full current_subscriptions set.

import { channel, DeriveClient } from '@derivexyz/derive-ts';

const client = new DeriveClient({ network: 'mainnet' });
// Subscriptions live on the websocket; connect() must come first.
await client.connect();

// channel() builds the concrete channel name from its template and
// carries the payload type, so each handler below is fully typed.
const trades = channel('trades.{instrument_name}', {
instrument_name: 'ETH-PERP',
});
const book = channel('orderbook.{instrument_name}.{group}.{depth}', {
instrument_name: 'ETH-PERP',
group: '10',
depth: '20',
});

const tradesSub = await client.subscriptions.subscribe(trades, (batch) => {
for (const trade of batch) {
console.log(
`trade: ${trade.direction} ${trade.trade_amount} @ ${trade.trade_price}`
);
}
});

const bookSub = await client.subscriptions.subscribe(book, (snapshot) => {
console.log(
`book #${snapshot.publish_id}: ${snapshot.bids.length} bids / ${snapshot.asks.length} asks`
);
});

// Later, drop the subscriptions (the last handler on a channel sends unsubscribe):
await tradesSub.unsubscribe();
await bookSub.unsubscribe();

# Coming soon.

// Coming soon.

{
  "id": 1,
  "method": "subscribe",
  "params": {
    "channels": ["trades.ETH-PERP", "orderbook.ETH-PERP.10.20"]
  }
}

{
  "id": 1,
  "result": {
    "status": {
      "trades.ETH-PERP": "ok",
      "orderbook.ETH-PERP.10.20": "ok"
    },
    "current_subscriptions": ["trades.ETH-PERP", "orderbook.ETH-PERP.10.20"]
  }
}

Each status entry is "ok", "already subscribed", or an error string for that channel. If every requested channel is invalid, the whole call fails with error code 13000 — Invalid channels. Private channels require an authenticated connection whose session key is authorized for the target subaccount. See Authentication for session login.

Unsubscribing

Send unsubscribe with a channels array to drop specific channels. Omit channels (or pass null) to unsubscribe from all channels on the connection. The response returns the per-channel status and the remaining_subscriptions set.

{
  "id": 2,
  "method": "unsubscribe",
  "params": { "channels": ["trades.ETH-PERP"] }
}

Channel-name template glossary

Channel names are dot-delimited. Segments in {braces} are parameters you fill in.

Parameter	Meaning	Values
`{instrument_name}`	An instrument identifier (e.g. `ETH-PERP`)	See Instrument names
`{instrument_type}`	Instrument class	`erc20`, `option`, `perp`
`{currency}`	Settlement/collateral currency (e.g. `ETH`)	See `public/get_all_currencies`
`{group}`	Orderbook price grouping	`1`, `10`, `100`
`{depth}`	Orderbook levels per side	`1`, `10`, `20`, `100`
`{interval}`	Slim-ticker publish interval (ms)	`100`, `1000`
`{tx_status}`	Settlement status filter	`settled`, `reverted`, `timed_out`
`{subaccount_id}`	Numeric subaccount id	Your authenticated subaccount
`{wallet}`	Wallet address	Your authenticated wallet

The legacy ticker.{instrument_name}.{interval} channel is deprecated — subscribing to it is rejected. Use ticker_slim.* instead.

Public channels

No authentication required.

Channel	Address template
Orderbook	`orderbook.{instrument_name}.{group}.{depth}`
Slim ticker	`ticker_slim.{instrument_name}.{interval}`
Spot feed	`spot_feed.{currency}`
Trades (by instrument)	`trades.{instrument_name}`
Trades (by type + currency)	`trades.{instrument_type}.{currency}`
Trades (by type + currency + status)	`trades.{instrument_type}.{currency}.{tx_status}`
Auctions	`auctions.watch`
Margin	`margin.watch`

margin.watch is an all-users firehose of margin and mark-to-market state. It is intended for administrative/monitoring use, not per-account data.

Slim ticker payload

Both the ticker_slim.* channel and public/get_ticker return the same compact snapshot, keyed by single letters to keep the feed small:

Key	Meaning
`t`	Snapshot timestamp (ms since epoch)
`a` / `A`	Best ask price / amount available at the best ask
`b` / `B`	Best bid price / amount available at the best bid
`M`	Mark price
`I`	Index price
`f`	Current hourly funding rate (perps; `null` otherwise)
`minp` / `maxp`	Min / max matchable price (the order price band)
`stats`	24h trading statistics (`c` change, `v` volume, `oi` open interest, …)
`option_pricing`	Greeks and implied vols for options (`d` delta, `g` gamma, `v` vega, `i` IV, …)

The public/get_ticker response schema in the API Reference tab carries every field’s full description.

Private channels

Require an authenticated connection. {subaccount_id} channels stream data for one of your subaccounts; {wallet} channels stream data for your wallet.

Channel	Address template
Balance updates	`{subaccount_id}.balances`
Order updates	`{subaccount_id}.orders`
Trade updates	`{subaccount_id}.trades`
Trade updates (by status)	`{subaccount_id}.trades.{tx_status}`
Quote updates	`{subaccount_id}.quotes`
Best-quote updates	`{subaccount_id}.best.quotes`
RFQ updates	`{wallet}.rfqs`

The Subscriptions reference in the API Reference tab is generated from the AsyncAPI spec and documents the exact data payload for every channel above.

Get Started

Authentication & Keys

Trading Concepts

Permissionless Vaults

WebSocket

Reference

Notification model

Subscribing

Unsubscribing

Channel-name template glossary

Public channels

Slim ticker payload

Private channels

​Notification model

​Subscribing

​Unsubscribing

​Channel-name template glossary

​Public channels

​Slim ticker payload

​Private channels

Notification model

Subscribing

Unsubscribing

Channel-name template glossary

Public channels

Slim ticker payload

Private channels