{ "asyncapi": "3.0.0", "channels": { "announcements": { "address": "announcements", "description": "General announcements concerning the Deribit platform.\n\nSubscribe to receive operational messages such as maintenance notices, incidents, and important platform updates.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to `announcements` channel. This channel does not require any additional parameters.", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "announcements" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "announcements" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `announcements` subscription - contains the data payload", "name": "announcements_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "action": { "description": "Action taken by the platform administrators. Published a `new` announcement, or `delete`d the old one", "enum": [ "deleted", "new" ], "type": "string" }, "body": { "description": "HTML-formatted announcement body", "example": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "type": "string" }, "confirmation": { "description": "Whether the user confirmation is required for this announcement", "type": "boolean" }, "id": { "description": "Announcement's identifier", "example": 1532593832021, "type": "integer" }, "important": { "description": "Whether the announcement is marked as important", "type": "boolean" }, "publication_timestamp": { "description": "The timestamp (milliseconds since the Unix epoch) of announcement publication", "example": 1532593832021, "type": "integer" }, "title": { "description": "Announcement's title", "example": "Example announcement", "type": "string" }, "unread": { "description": "The number of previous unread announcements (optional, only for authorized users).", "type": "integer" } }, "required": [ "action", "body", "id", "important", "publication_timestamp", "title" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": {}, "servers": [ { "$ref": "#/servers/public" } ], "summary": "General announcements concerning the Deribit platform.\n\nSubscribe to receive operational messages such as maintenance notices, incidents, and important platform updates.\n", "tags": [ { "name": "Announcements" } ], "title": "announcements " }, "book.(instrument_name).(group).(depth).(interval)": { "address": "book.{instrument_name}.{group}.{depth}.{interval}", "description": "Aggregated order book updates for a specific instrument.\n\nNotifications are sent once per specified `interval`, with prices grouped (rounded) according to `group`, and the book truncated to the specified `depth` (number of price levels).\n\nThe `asks` and `bids` fields are both lists of `[price, amount]` pairs.\n\n- `price`: price level, rounded according to `group` (USD per BTC)\n- `amount`: total amount at that price level\n\nFor Starbase-routed instruments, the published price levels include accepted mass-quote liquidity.\n\n**Units:** For perpetual and inverse futures the amount is in USD units. For options and linear futures it is in the underlying base currency coin.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to book channel. Channel name format: `book.(instrument_name).(group).(depth).(interval)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "book.BTC-PERPETUAL.none.10.100ms" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "book.BTC-PERPETUAL.none.10.100ms" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `book.(instrument_name).(group).(depth).(interval)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "asks": [ [ 161, 20 ] ], "bids": [ [ 160, 40 ] ], "change_id": 109615, "instrument_name": "ETH-PERPETUAL", "timestamp": 1554375447971 } }, "summary": "Repeated notification example" } ], "name": "book_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "asks": { "items": { "description": "List of asks (price-amount pairs)", "items": { "type": "number" }, "maxItems": 2, "minItems": 2, "type": "array" }, "type": "array" }, "bids": { "items": { "description": "List of bids (price-amount pairs)", "items": { "type": "number" }, "maxItems": 2, "minItems": 2, "type": "array" }, "type": "array" }, "change_id": { "description": "id of the notification", "type": "integer" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "timestamp": { "description": "The timestamp of last change (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" } }, "required": [ "asks", "bids", "change_id", "instrument_name" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "depth": { "description": "Number of price levels to be included\n\n**Allowed values:** `1`, `10`, `20`", "enum": [ "1", "10", "20" ] }, "group": { "description": "Group prices (by rounding). Use `none` for no grouping.\n\nFor ETH cryptocurrency, the real `group` is divided by `100.0`. Example: a value of `5` means using `0.05`.\n\nAllowed values:\n\n- BTC: `none`, `1`, `2`, `5`, `10`\n- ETH: `none`, `5`, `10`, `25`, `100`, `250`\n\n**Allowed values:** `none`, `1`, `2`, `5`, `10`, `25`, `100`, `250`", "enum": [ "1", "10", "100", "2", "25", "250", "5", "none" ] }, "instrument_name": { "description": "The name of the instrument" }, "interval": { "description": "Frequency of notifications. Events will be aggregated over this interval. The value `raw` selects the finest granularity - events are aggregated over a 1 millisecond interval **(Please note that `raw` interval is only available to authorized users)**\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] } }, "servers": [ { "$ref": "#/servers/public" } ], "summary": "Aggregated order book updates for a specific instrument.\n\nNotifications are sent once per specified `interval`, with prices grouped (rounded) according to `group`, and the book truncated to the specified `depth` (number of price levels).\n\nThe `asks` and `bids` fields are both lists of `[price, amount]` pairs.\n\n- `price`: price level, rounded according to `group` (USD per BTC)\n- `amount`: total amount at that price level\n\nFor Starbase-routed instruments, the published price levels include accepted mass-quote liquidity.\n\n**Units:** For perpetual and inverse futures the amount is in USD units. For options and linear futures it is in the underlying base currency coin.\n", "tags": [ { "name": "Orderbook" }, { "name": "Market Data" } ], "title": "book.(instrument_name).(group).(depth).(interval) " }, "book.(instrument_name).(interval)": { "address": "book.{instrument_name}.{interval}", "description": "Real-time order book updates for a specific instrument.\n\n- The first notification contains a full snapshot of the book (bids and asks for **all price levels** — no depth limit).\n- Subsequent notifications contain only incremental changes to individual price levels.\n- Updates are tuples in the form `[action, price, amount]`, where `action` is one of: `new`, `change`, `delete`.\n\nEach notification includes a `change_id`. Every message except the first also contains `prev_change_id`. If `prev_change_id` equals the `change_id` of the previous message, it indicates that no messages were missed.\n\nFor Starbase-routed instruments, the published price levels include accepted mass-quote liquidity.\n\n**Depth:** This channel delivers the complete order book with no depth restriction. If you need a depth-limited, price-grouped snapshot, use `book.{instrument_name}.{group}.{depth}.{interval}` instead.\n\n**Units:** For perpetuals and futures, `amount` is in USD units. For options, `amount` is in the corresponding cryptocurrency contracts (e.g., BTC or ETH).\n", "messages": { "subscribe_request": { "description": "Request to subscribe to book channel. Channel name format: `book.(instrument_name).(interval)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "book.BTC-PERPETUAL.100ms" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "book.BTC-PERPETUAL.100ms" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `book.(instrument_name).(interval)` subscription - contains the data payload", "examples": [ { "name": "first", "payload": { "data": { "asks": [ [ "new", 5042.64, 40 ], [ "new", 5043.3, 40 ] ], "bids": [ [ "new", 5042.34, 30 ], [ "new", 5041.94, 20 ] ], "change_id": 297217, "instrument_name": "BTC-PERPETUAL", "timestamp": 1554373962454, "type": "snapshot" } }, "summary": "First notification example" }, { "name": "repeated", "payload": { "data": { "asks": [], "bids": [ [ "delete", 5041.94, 0 ], [ "delete", 5042.34, 0 ] ], "change_id": 297218, "instrument_name": "BTC-PERPETUAL", "prev_change_id": 297217, "timestamp": 1554373911330, "type": "change" } }, "summary": "Repeated notification example" } ], "name": "book_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "asks": { "description": "", "type": "array" }, "bids": { "description": "", "type": "array" }, "change_id": { "description": "Identifier of the notification", "type": "integer" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "prev_change_id": { "description": "Identifier of the previous notification (it's **not** included for the first notification)", "type": "integer" }, "timestamp": { "description": "The timestamp of last change (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" }, "type": { "description": "Type of notification: `snapshot` for initial, `change` for others", "enum": [ "change", "snapshot" ], "type": "string" } }, "required": [ "asks", "bids", "change_id", "instrument_name" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "instrument_name": { "description": "The name of the instrument" }, "interval": { "description": "Frequency of notifications. Events will be aggregated over this interval. The value `raw` selects the finest granularity - events are aggregated over a 1 millisecond interval **(Please note that `raw` interval is only available to authorized users)**\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] } }, "servers": [ { "$ref": "#/servers/public" } ], "summary": "Real-time order book updates for a specific instrument.\n\n- The first notification contains a full snapshot of the book (bids and asks for **all price levels** — no depth limit).\n- Subsequent notifications contain only incremental changes to individual price levels.\n- Updates are tuples in the form `[action, price, amount]`, where `action` is one of: `new`, `change`, `delete`.\n\nEach notification includes a `change_id`. Every message except the first also contains `prev_change_id`. If `prev_change_id` equals the `change_id` of the previous message, it indicates that no messages were missed.\n\nFor Starbase-routed instruments, the published price levels include accepted mass-quote liquidity.\n\n**Depth:** This channel delivers the complete order book with no depth restriction. If you need a depth-limited, price-grouped snapshot, use `book.{instrument_name}.{group}.{depth}.{interval}` instead.\n\n**Units:** For perpetuals and futures, `amount` is in USD units. For options, `amount` is in the corresponding cryptocurrency contracts (e.g., BTC or ETH).\n", "tags": [ { "name": "Orderbook" }, { "name": "Market Data" } ], "title": "book.(instrument_name).(interval) " }, "chart.trades.(instrument_name).(resolution)": { "address": "chart.trades.{instrument_name}.{resolution}", "description": "Publicly available market data used to generate a TradingView trade candle chart.\n\nDuring a single resolution period, many events can be sent, each with updated values for the recent period.\n\n**Notice:** When there is no trade during the requested resolution period (e.g. 1 minute), a filling sample is generated which uses data from the last available trade candle (open and close values).\n\n**Note:** For spot instruments routed to Coinbase Exchange, this channel is not supported. Use [Get product candles](https://docs.cdp.coinbase.com/api-reference/exchange-api/rest-api/products/get-product-candles) instead.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to chart channel. Channel name format: `chart.trades.(instrument_name).(resolution)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "chart.trades.BTC-PERPETUAL.1" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "chart.trades.BTC-PERPETUAL.1" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `chart.trades.(instrument_name).(resolution)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "close": 8791.25, "cost": 460, "high": 8870.31, "low": 8788.25, "open": 8869.79, "tick": 1573645080000, "volume": 0.05219351 } }, "summary": "Repeated notification example" } ], "name": "chart_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "close": { "description": "The close price for the candle", "type": "number" }, "cost": { "description": "Cost data for the candle", "type": "number" }, "high": { "description": "The highest price level for the candle", "type": "number" }, "low": { "description": "The lowest price level for the candle", "type": "number" }, "open": { "description": "The open price for the candle'", "type": "number" }, "tick": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" }, "volume": { "description": "Volume data for the candle", "type": "number" } }, "required": [ "close", "cost", "high", "low", "open", "tick", "volume" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "instrument_name": { "description": "The name of the instrument" }, "resolution": { "description": "Chart bars resolution given in full minutes or keyword `1D` (only some specific resolutions are supported)\n\n**Allowed values:** `1`, `3`, `5`, `10`, `15`, ... (total 12 values)", "enum": [ "1", "10", "120", "15", "180", "1D", "3", "30", "360", "5", "60", "720" ] } }, "servers": [ { "$ref": "#/servers/public" } ], "summary": "Publicly available market data used to generate a TradingView trade candle chart.\n\nDuring a single resolution period, many events can be sent, each with updated values for the recent period.\n\n**Notice:** When there is no trade during the requested resolution period (e.g. 1 minute), a filling sample is generated which uses data from the last available trade candle (open and close values).\n\n**Note:** For spot instruments routed to Coinbase Exchange, this channel is not supported. Use [Get product candles](https://docs.cdp.coinbase.com/api-reference/exchange-api/rest-api/products/get-product-candles) instead.\n", "tags": [ { "name": "Market Data" } ], "title": "chart.trades.(instrument_name).(resolution) " }, "deribit_price_index.(index_name)": { "address": "deribit_price_index.{index_name}", "description": "Deribit index price updates for the given `index_name` (current index value).\n\nUse this channel to track the real-time value of a Deribit index (e.g., `btc_usd`), which is used across pricing, margining, and settlement-related calculations.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to deribit_price_index channel. Channel name format: `deribit_price_index.(index_name)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "deribit_price_index.btc_usd" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "deribit_price_index.btc_usd" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `deribit_price_index.(index_name)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "index_name": "btc_usd", "price": 3937.89, "timestamp": 1550588002899 } }, "summary": "Repeated notification example" } ], "name": "deribit_price_index_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "index_name": { "description": "Index identifier, matches (base) cryptocurrency with quote currency", "enum": [ "ada_usdc", "algo_usdc", "avax_usdc", "bch_usdc", "bnb_usdc", "btc_eurr", "btc_usd", "btc_usdc", "btc_usde", "btc_usdt", "btc_usyc", "btcdvol_usdc", "buidl_usdc", "doge_usdc", "dot_usdc", "drbfix-btc_usdc", "drbfix-eth_usdc", "eth_btc", "eth_eurr", "eth_usd", "eth_usdc", "eth_usde", "eth_usdt", "eth_usyc", "ethdvol_usdc", "eurr_usdc", "eurr_usdt", "hype_usdc", "link_usdc", "ltc_usdc", "near_usdc", "paxg_btc", "paxg_usdc", "shib_usdc", "sol_usdc", "sol_usdt", "steth_eth", "steth_usdc", "steth_usdt", "ton_usdc", "trump_usdc", "trx_usdc", "uni_usdc", "usdc_usdt", "usde_usdc", "usde_usdt", "usyc_usdc", "xrp_usdc" ], "type": "string" }, "price": { "description": "Current index price", "example": 8247.27, "type": "number" }, "timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" } }, "required": [ "index_name", "price", "timestamp" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "index_name": { "description": "Index identifier, matches (base) cryptocurrency with quote currency\n\n**Allowed values:** `btc_usd`, `eth_usd`, `ada_usdc`, `algo_usdc`, `avax_usdc`, ... (total 47 values)", "enum": [ "ada_usdc", "algo_usdc", "avax_usdc", "bch_usdc", "bnb_usdc", "btc_eurr", "btc_usd", "btc_usdc", "btc_usde", "btc_usdt", "btc_usyc", "btcdvol_usdc", "buidl_usdc", "doge_usdc", "dot_usdc", "drbfix-btc_usdc", "drbfix-eth_usdc", "eth_btc", "eth_eurr", "eth_usd", "eth_usdc", "eth_usde", "eth_usdt", "eth_usyc", "ethdvol_usdc", "eurr_usdc", "eurr_usdt", "link_usdc", "ltc_usdc", "near_usdc", "paxg_btc", "paxg_usdc", "shib_usdc", "sol_usdc", "sol_usdt", "steth_eth", "steth_usdc", "steth_usdt", "ton_usdc", "trump_usdc", "trx_usdc", "uni_usdc", "usdc_usdt", "usde_usdc", "usde_usdt", "usyc_usdc", "xrp_usdc" ] } }, "servers": [ { "$ref": "#/servers/public" } ], "summary": "Deribit index price updates for the given `index_name` (current index value).\n\nUse this channel to track the real-time value of a Deribit index (e.g., `btc_usd`), which is used across pricing, margining, and settlement-related calculations.\n", "tags": [ { "name": "Market Data" } ], "title": "deribit_price_index.(index_name) " }, "deribit_price_ranking.(index_name)": { "address": "deribit_price_ranking.{index_name}", "description": "Price ranking updates for the component exchanges used to calculate the Deribit index.\n\nUse this channel to see per-exchange price contributions that feed into the index calculation for the given `index_name`.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to deribit_price_ranking channel. Channel name format: `deribit_price_ranking.(index_name)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "deribit_price_ranking.btc_usd" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "deribit_price_ranking.btc_usd" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `deribit_price_ranking.(index_name)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": [ { "enabled": true, "identifier": "bitfinex", "original_price": 41160.5, "price": 41160.5, "timestamp": 1702465142997, "weight": 16.666667 }, { "enabled": true, "identifier": "binance", "original_price": 41119, "price": 41119, "timestamp": 1702465143045, "weight": 16.666667 }, { "enabled": true, "identifier": "coinbase", "original_price": 41115.53, "price": 41115.53, "timestamp": 1702465139000, "weight": 16.666667 }, { "enabled": true, "identifier": "gemini", "original_price": 41116.42, "price": 41116.42, "timestamp": 1702465142921, "weight": 16.666667 }, { "enabled": true, "identifier": "itbit", "original_price": 41108.88, "price": 41108.88, "timestamp": 1702465141954, "weight": 16.666667 }, { "enabled": true, "identifier": "kraken", "original_price": 41108.35, "price": 41108.35, "timestamp": 1702465142906, "weight": 16.666667 } ] }, "summary": "Repeated notification example" } ], "name": "deribit_price_ranking_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "enabled": { "description": "Stock exchange status", "type": "boolean" }, "identifier": { "description": "Stock exchange identifier", "example": "binance", "type": "string" }, "original_price": { "description": "Index price retrieved from stock's data", "type": "number" }, "price": { "description": "Adjusted stock exchange index price, used for Deribit price index calculations", "type": "number" }, "timestamp": { "description": "The timestamp of the last update from stock exchange (milliseconds since the UNIX epoch)", "example": 1536569522277, "type": "integer" }, "weight": { "description": "The weight of the ranking given in percent", "type": "number" } }, "required": [], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "index_name": { "description": "Index identifier, matches (base) cryptocurrency with quote currency\n\n**Allowed values:** `btc_usd`, `eth_usd`, `ada_usdc`, `algo_usdc`, `avax_usdc`, ... (total 47 values)", "enum": [ "ada_usdc", "algo_usdc", "avax_usdc", "bch_usdc", "bnb_usdc", "btc_eurr", "btc_usd", "btc_usdc", "btc_usde", "btc_usdt", "btc_usyc", "btcdvol_usdc", "buidl_usdc", "doge_usdc", "dot_usdc", "drbfix-btc_usdc", "drbfix-eth_usdc", "eth_btc", "eth_eurr", "eth_usd", "eth_usdc", "eth_usde", "eth_usdt", "eth_usyc", "ethdvol_usdc", "eurr_usdc", "eurr_usdt", "link_usdc", "ltc_usdc", "near_usdc", "paxg_btc", "paxg_usdc", "shib_usdc", "sol_usdc", "sol_usdt", "steth_eth", "steth_usdc", "steth_usdt", "ton_usdc", "trump_usdc", "trx_usdc", "uni_usdc", "usdc_usdt", "usde_usdc", "usde_usdt", "usyc_usdc", "xrp_usdc" ] } }, "servers": [ { "$ref": "#/servers/public" } ], "summary": "Price ranking updates for the component exchanges used to calculate the Deribit index.\n\nUse this channel to see per-exchange price contributions that feed into the index calculation for the given `index_name`.\n", "tags": [ { "name": "Market Data" } ], "title": "deribit_price_ranking.(index_name) " }, "deribit_price_statistics.(index_name)": { "address": "deribit_price_statistics.{index_name}", "description": "Basic statistics for the Deribit index.\n\nProvides statistical information related to the given `index_name` (e.g., aggregated stats derived from index updates). Useful for monitoring index behavior over time.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to deribit_price_statistics channel. Channel name format: `deribit_price_statistics.(index_name)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "deribit_price_statistics.btc_usd" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "deribit_price_statistics.btc_usd" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `deribit_price_statistics.(index_name)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "change24h": 1009.61, "high24h": 59311.42, "high_volatility": false, "index_name": "btc_usd", "low24h": 58012.08 } }, "summary": "Repeated notification example" } ], "name": "deribit_price_statistics_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "change24h": { "description": "The price index change calculated between the first and last point within most recent 24 hours window", "type": "number" }, "fast_market": { "description": "Indicates the fast moving prices period on the market. The value `true` is set when the price index value drastically changed within the last 1 hour. This indicator remains active even for 2 more hours after the prices calm down", "type": "boolean" }, "high24h": { "description": "The highest recorded price within the last 24 hours", "type": "number" }, "index_name": { "description": "Index identifier, matches (base) cryptocurrency with quote currency", "enum": [ "ada_usdc", "algo_usdc", "avax_usdc", "bch_usdc", "bnb_usdc", "btc_eurr", "btc_usd", "btc_usdc", "btc_usde", "btc_usdt", "btc_usyc", "btcdvol_usdc", "buidl_usdc", "doge_usdc", "dot_usdc", "drbfix-btc_usdc", "drbfix-eth_usdc", "eth_btc", "eth_eurr", "eth_usd", "eth_usdc", "eth_usde", "eth_usdt", "eth_usyc", "ethdvol_usdc", "eurr_usdc", "eurr_usdt", "hype_usdc", "link_usdc", "ltc_usdc", "near_usdc", "paxg_btc", "paxg_usdc", "shib_usdc", "sol_usdc", "sol_usdt", "steth_eth", "steth_usdc", "steth_usdt", "ton_usdc", "trump_usdc", "trx_usdc", "uni_usdc", "usdc_usdt", "usde_usdc", "usde_usdt", "usyc_usdc", "xrp_usdc" ], "type": "string" }, "low24h": { "description": "The lowest recorded price within the last 24 hours", "type": "number" } }, "required": [ "change24h", "high24h", "index_name", "low24h" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "index_name": { "description": "Index identifier, matches (base) cryptocurrency with quote currency\n\n**Allowed values:** `btc_usd`, `eth_usd`, `ada_usdc`, `algo_usdc`, `avax_usdc`, ... (total 47 values)", "enum": [ "ada_usdc", "algo_usdc", "avax_usdc", "bch_usdc", "bnb_usdc", "btc_eurr", "btc_usd", "btc_usdc", "btc_usde", "btc_usdt", "btc_usyc", "btcdvol_usdc", "buidl_usdc", "doge_usdc", "dot_usdc", "drbfix-btc_usdc", "drbfix-eth_usdc", "eth_btc", "eth_eurr", "eth_usd", "eth_usdc", "eth_usde", "eth_usdt", "eth_usyc", "ethdvol_usdc", "eurr_usdc", "eurr_usdt", "link_usdc", "ltc_usdc", "near_usdc", "paxg_btc", "paxg_usdc", "shib_usdc", "sol_usdc", "sol_usdt", "steth_eth", "steth_usdc", "steth_usdt", "ton_usdc", "trump_usdc", "trx_usdc", "uni_usdc", "usdc_usdt", "usde_usdc", "usde_usdt", "usyc_usdc", "xrp_usdc" ] } }, "servers": [ { "$ref": "#/servers/public" } ], "summary": "Basic statistics for the Deribit index.\n\nProvides statistical information related to the given `index_name` (e.g., aggregated stats derived from index updates). Useful for monitoring index behavior over time.\n", "tags": [ { "name": "Market Data" } ], "title": "deribit_price_statistics.(index_name) " }, "deribit_volatility_index.(index_name)": { "address": "deribit_volatility_index.{index_name}", "description": "Volatility index updates for the given `index_name`.\n\nUse this channel to receive volatility index values (e.g., DVOL-like measures) as they update.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to deribit_volatility_index channel. Channel name format: `deribit_volatility_index.(index_name)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "deribit_volatility_index.btc_usd" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "deribit_volatility_index.btc_usd" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `deribit_volatility_index.(index_name)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "index_name": "btc_usd", "timestamp": 1619777946007, "volatility": 129.36 } }, "summary": "Repeated notification example" } ], "name": "deribit_volatility_index_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "index_name": { "description": "Index identifier supported for DVOL", "enum": [ "btc_usd", "eth_usd" ], "type": "string" }, "timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" }, "volatility": { "description": "Value of the corresponding volatility", "type": "number" } }, "required": [ "index_name", "timestamp", "volatility" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "index_name": { "description": "Index identifier, matches (base) cryptocurrency with quote currency\n\n**Allowed values:** `btc_usd`, `eth_usd`, `ada_usdc`, `algo_usdc`, `avax_usdc`, ... (total 47 values)", "enum": [ "ada_usdc", "algo_usdc", "avax_usdc", "bch_usdc", "bnb_usdc", "btc_eurr", "btc_usd", "btc_usdc", "btc_usde", "btc_usdt", "btc_usyc", "btcdvol_usdc", "buidl_usdc", "doge_usdc", "dot_usdc", "drbfix-btc_usdc", "drbfix-eth_usdc", "eth_btc", "eth_eurr", "eth_usd", "eth_usdc", "eth_usde", "eth_usdt", "eth_usyc", "ethdvol_usdc", "eurr_usdc", "eurr_usdt", "link_usdc", "ltc_usdc", "near_usdc", "paxg_btc", "paxg_usdc", "shib_usdc", "sol_usdc", "sol_usdt", "steth_eth", "steth_usdc", "steth_usdt", "ton_usdc", "trump_usdc", "trx_usdc", "uni_usdc", "usdc_usdt", "usde_usdc", "usde_usdt", "usyc_usdc", "xrp_usdc" ] } }, "servers": [ { "$ref": "#/servers/public" } ], "summary": "Volatility index updates for the given `index_name`.\n\nUse this channel to receive volatility index values (e.g., DVOL-like measures) as they update.\n", "tags": [ { "name": "Market Data" } ], "title": "deribit_volatility_index.(index_name) " }, "estimated_expiration_price.(index_name)": { "address": "estimated_expiration_price.{index_name}", "description": "Estimated expiration (delivery) price updates for the given `index_name`.\n\nProvides calculated estimates of the ending price used around expirations/settlement. Useful for monitoring expected settlement levels.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to estimated_expiration_price channel. Channel name format: `estimated_expiration_price.(index_name)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "estimated_expiration_price.btc_usd" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "estimated_expiration_price.btc_usd" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `estimated_expiration_price.(index_name)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "is_estimated": false, "price": 3939.73, "seconds": 180929 } }, "summary": "Repeated notification example" } ], "name": "estimated_expiration_price_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "is_estimated": { "description": "Indicates whether the price is an estimated value. When `true`, the price represents a calculated estimated ending price for expiration. When `false`, the price is the current index price.", "type": "boolean" }, "left_ticks": { "description": "Number of time ticks remaining until expiration. This field is only present when `is_estimated` is `true`.", "type": "number" }, "price": { "description": "The current index price or the estimated expiration price for the index. When `is_estimated` is `true`, this represents the calculated estimated ending price; otherwise, it is the current index price.", "example": 8247.27, "type": "number" }, "seconds": { "description": "Number of seconds remaining until the expiration of the nearest expiring instrument", "type": "integer" }, "total_ticks": { "description": "Total number of time ticks for the expiration period. This field is only present when `is_estimated` is `true`.", "type": "number" } }, "required": [ "is_estimated", "price", "seconds" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "index_name": { "description": "Index identifier, matches (base) cryptocurrency with quote currency\n\n**Allowed values:** `btc_usd`, `eth_usd`, `ada_usdc`, `algo_usdc`, `avax_usdc`, ... (total 47 values)", "enum": [ "ada_usdc", "algo_usdc", "avax_usdc", "bch_usdc", "bnb_usdc", "btc_eurr", "btc_usd", "btc_usdc", "btc_usde", "btc_usdt", "btc_usyc", "btcdvol_usdc", "buidl_usdc", "doge_usdc", "dot_usdc", "drbfix-btc_usdc", "drbfix-eth_usdc", "eth_btc", "eth_eurr", "eth_usd", "eth_usdc", "eth_usde", "eth_usdt", "eth_usyc", "ethdvol_usdc", "eurr_usdc", "eurr_usdt", "link_usdc", "ltc_usdc", "near_usdc", "paxg_btc", "paxg_usdc", "shib_usdc", "sol_usdc", "sol_usdt", "steth_eth", "steth_usdc", "steth_usdt", "ton_usdc", "trump_usdc", "trx_usdc", "uni_usdc", "usdc_usdt", "usde_usdc", "usde_usdt", "usyc_usdc", "xrp_usdc" ] } }, "servers": [ { "$ref": "#/servers/public" } ], "summary": "Estimated expiration (delivery) price updates for the given `index_name`.\n\nProvides calculated estimates of the ending price used around expirations/settlement. Useful for monitoring expected settlement levels.\n", "tags": [ { "name": "Market Data" } ], "title": "estimated_expiration_price.(index_name) " }, "incremental_ticker.(instrument_name)": { "address": "incremental_ticker.{instrument_name}", "description": "Real-time ticker updates for an instrument, delivered as a snapshot followed by incremental updates.\n\n- The first notification contains the full ticker snapshot.\n- Subsequent notifications contain only fields that changed since the previous update.\n\nThis event is sent at most once per second.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to incremental_ticker channel. Channel name format: `incremental_ticker.(instrument_name)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "incremental_ticker.BTC-PERPETUAL" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "incremental_ticker.BTC-PERPETUAL" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `incremental_ticker.(instrument_name)` subscription - contains the data payload", "examples": [ { "name": "first", "payload": { "data": { "best_ask_amount": 100, "best_ask_price": 36443, "best_bid_amount": 5000, "best_bid_price": 36442.5, "current_funding": 0, "estimated_delivery_price": 36441.64, "funding_8h": 0.0000211, "index_price": 36441.64, "instrument_name": "BTC-PERPETUAL", "last_price": 36457.5, "mark_price": 36446.51, "max_price": 36991.72, "min_price": 35898.37, "open_interest": 502097590, "settlement_price": 36169.49, "state": "open", "stats": { "high": 36824.5, "low": 35213.5, "price_change": 0.7229, "volume": 7871.02139035, "volume_usd": 284061480 }, "timestamp": 1623060194301, "type": "snapshot" } }, "summary": "First notification example" }, { "name": "repeated", "payload": { "data": { "best_ask_amount": 120, "best_bid_amount": 300, "best_bid_price": 36452.5, "funding_8h": 0.0000311, "index_price": 36442.64, "instrument_name": "BTC-PERPETUAL", "mark_price": 36448.61, "stats": { "volume": 7872.02139035, "volume_usd": 284073480 }, "timestamp": 1623060199024, "type": "change" } }, "summary": "Repeated notification example" } ], "name": "incremental_ticker_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "ask_iv": { "description": "(Only for option) implied volatility for best ask", "type": "number" }, "best_ask_amount": { "description": "It represents the requested order size of all best asks", "type": "number" }, "best_ask_price": { "description": "The current best ask price, `null` if there aren't any asks", "type": "number" }, "best_bid_amount": { "description": "It represents the requested order size of all best bids", "type": "number" }, "best_bid_price": { "description": "The current best bid price, `null` if there aren't any bids", "type": "number" }, "bid_iv": { "description": "(Only for option) implied volatility for best bid", "type": "number" }, "current_funding": { "description": "Current funding (perpetual only)", "type": "number" }, "delivery_price": { "description": "The settlement price for the instrument. Only when `state = closed`", "type": "number" }, "estimated_delivery_price": { "description": "Estimated delivery price for the market. For more details, see Contract Specification > General Documentation > Expiration Price", "example": 11628.81, "type": "number" }, "funding_8h": { "description": "Funding 8h (perpetual only)", "type": "number" }, "greeks": { "description": "Only for options. Greeks are risk measures that describe how the option's price changes with respect to various factors.\n\n**Delta (Δ)**\n\nDeribit uses two different Deltas:\n- **DeltaTotal** in the account summary uses the **Net Transaction Delta (NTD)**\n- **Delta** for individual option expiries is the **Black Scholes Delta**\n\nIn the settings section you can toggle Net Transaction Delta instead.\n\n**What is DeltaTotal in the account summary?**\n`DeltaTotal = Net Transaction Delta of options + BTC Position of Futures`\n\n**What is Net Transaction Delta?**\n`Net Transaction Delta = Black Scholes Delta - Mark Price of Options`\n\n**Why do we use a Net Transaction Delta?**\nThe Delta Total uses the Net Transaction Delta (or price adjusted Delta) of the options. This is because, from a risk perspective, we are interested in the change in Bitcoin price as the underlying changes.\n\nYou should actually treat your delta as **Equity + Delta Total** if you want to have less risk for your USD PnL.\n\n**Example:** Consider a call option with strike 0, which has a Black Scholes Delta of 1 and Net Transaction Delta = 0.\n\nImagine you have 2 BTC equity and no positions and BTC price is at USD 60k. In that case you would short 2 Futures contracts to hedge your USD exposure to BTC.\n\nNow let's say you buy one call with strike 0. The question is if you should sell another future?\n\nThe call will always have a price of 1 BTC. So you buy it at 1 BTC which equates to USD 60k. Let's say the price increases to USD 70k. The value of the call is still 1 BTC. At settlement you receive 1 BTC for the call. So you paid 1 BTC and then receive 1 BTC which means your USD PnL on buying the call is 0. If you sold a future on it, then you would actually lose on the future.\n\n⚠️ **During the 30 minute settlement period we decay your Delta.** See [Delta decay during settlement](https://support.deribit.com/hc/en-us/articles/25944751433757-Delta-decay-during-settlement) for more details.\n\n**Theta (Θ)**\n\nThe Theta that Deribit uses is the **minimum of (1 day Theta, lifetime theta of the option)**. So if you take an option with 1 hour to expire for example, generally Black Scholes Theta will give you the equivalent 1 day Theta. Whereas we show the 1 hour Theta, so our Theta would differ from Black Scholes Theta when time to expiry is less than 1 day.\n\n**Vega, Gamma, and Rho**\n\nVega (not actually a Greek symbol), Gamma, Theta and Rho values shown on Deribit are calculated using **standard Black Scholes without adjustments**.\n", "properties": { "delta": { "description": "(Only for option) The delta value for the option. This is the **Black Scholes Delta** for individual option expiries. \n\nNote that DeltaTotal in account summary uses Net Transaction Delta instead. See the greeks object description for more details.\n", "type": "number" }, "gamma": { "description": "(Only for option) The gamma value for the option. Calculated using standard Black Scholes without adjustments.\n\nGamma measures the rate of change of delta with respect to changes in the underlying asset price.\n", "type": "number" }, "rho": { "description": "(Only for option) The rho value for the option. Calculated using standard Black Scholes without adjustments.\n\nRho measures the sensitivity of the option price to changes in the risk-free interest rate.\n", "type": "number" }, "theta": { "description": "(Only for option) The theta value for the option. Deribit uses the **minimum of (1 day Theta, lifetime theta of the option)**.\n\nSo if you take an option with 1 hour to expire for example, generally Black Scholes Theta will give you the equivalent 1 day Theta. Whereas we show the 1 hour Theta, so our Theta would differ from Black Scholes Theta when time to expiry is less than 1 day.\n\nTheta measures the rate of change of the option price with respect to time decay.\n", "type": "number" }, "vega": { "description": "(Only for option) The vega value for the option. Calculated using standard Black Scholes without adjustments.\n\nVega (not actually a Greek symbol) measures the sensitivity of the option price to changes in implied volatility.\n", "type": "number" } }, "required": [ "delta", "gamma", "rho", "theta", "vega" ], "type": "object" }, "index_price": { "description": "Current index price", "example": 8247.27, "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "interest_rate": { "description": "Interest rate used in implied volatility calculations (options only)", "type": "number" }, "last_price": { "description": "The price for the last trade", "type": "number" }, "mark_iv": { "description": "(Only for option) implied volatility for mark price", "type": "number" }, "mark_price": { "description": "The mark price for the instrument", "type": "number" }, "max_price": { "description": "The maximum price for the future. Any buy orders you submit higher than this price, will be clamped to this maximum.", "type": "number" }, "min_price": { "description": "The minimum price for the future. Any sell orders you submit lower than this price will be clamped to this minimum.", "type": "number" }, "open_interest": { "description": "The total amount of outstanding contracts in the corresponding amount units. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.", "type": "number" }, "settlement_price": { "description": "Optional (not added for spot). The settlement price for the instrument. Only when `state = open`", "type": "number" }, "state": { "description": "The state of the order book. Represents the current lifecycle stage of the instrument.\n\n**State Lifecycle and Meanings:**\n\n- `open`: Default state for running books. In this state book is accepting new orders, edits, cancels; prices should be updated, trading is live.\n- `settlement`: Books enters to this state during settlement/delivery. New orders, edits, cancels are not accepted. After this state normally next state should be `open` if it was settlement, or `delivered` if it was delivery. On enter to this state good till day orders in book are canceled.\n- `delivered`: Final state of book that has been delivered. New orders, edits, cancels are not accepted. After some time book process will be terminated and, instrument moved to `expired_instruments` and its `instrument_state` will become archivized. On enter to this all open orders in book are canceled.\n- `inactive`: After a book is deactivated, this state is set on book. New orders, edits, cancels are not accepted. On enter to this all open orders in book are canceled. Book in this state is not considered as open. This can be also final state for book.\n- `locked`: New orders, edits, are not accepted, only cancels ARE accepted. In some cases when configured books can start as locked or it may become locked on admin request. Settlement is possible on locked books.\n- `halted`: The state that books enter as a result of an error. Settlement is not possible when there is at least one book in this state.\n- `archivized`: Set when instrument is moved to `expired_instruments` table, final state.\n", "enum": [ "archivized", "delivered", "halted", "inactive", "locked", "open", "settlement" ], "type": "string" }, "stats": { "properties": { "high": { "description": "Highest price during 24h", "type": "number" }, "low": { "description": "Lowest price during 24h", "type": "number" }, "price_change": { "description": "24-hour price change expressed as a percentage, `null` if there weren't any trades", "example": 10.23, "type": "number" }, "volume": { "description": "Volume during last 24h in base currency", "type": "number" }, "volume_usd": { "description": "Volume in usd (futures only)", "type": "number" } }, "required": [ "high", "low", "volume" ], "type": "object" }, "timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" }, "type": { "description": "Type of notification: `snapshot` for initial, `change` for others.", "enum": [ "change", "snapshot" ], "type": "string" }, "underlying_index": { "description": "Name of the underlying future, or `index_price` (options only)", "type": "number" }, "underlying_price": { "description": "Underlying price for implied volatility calculations (options only)", "type": "number" } }, "required": [ "instrument_name", "timestamp" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "instrument_name": { "description": "The name of the instrument" } }, "servers": [ { "$ref": "#/servers/public" } ], "summary": "Real-time ticker updates for an instrument, delivered as a snapshot followed by incremental updates.\n\n- The first notification contains the full ticker snapshot.\n- Subsequent notifications contain only fields that changed since the previous update.\n\nThis event is sent at most once per second.\n", "tags": [ { "name": "Market Data" } ], "title": "incremental_ticker.(instrument_name) " }, "instrument.creation.(kind).(currency)": { "address": "instrument.creation.{kind}.{currency}", "description": "Notification published once when an instrument is created, carrying full instrument data in the same format as `public/get_instruments`.\n\nThe notification fires exactly once at creation time, regardless of the instrument's initial state.\n\n**Subscription examples:**\n\n| Channel | Description |\n|---|---|\n| `instrument.creation.any.any` | All instruments |\n| `instrument.creation.future.BTC` | BTC futures only |\n| `instrument.creation.option.any` | All options |\n", "messages": { "subscribe_request": { "description": "Request to subscribe to instrument channel. Channel name format: `instrument.creation.(kind).(currency)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "instrument.creation.future.USDC" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "instrument.creation.future.USDC" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `instrument.creation.(kind).(currency)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "base_currency": "BTC", "block_trade_commission": 0.00015, "block_trade_min_trade_amount": 25, "block_trade_tick_size": 0.0001, "contract_size": 1, "counter_currency": "USD", "creation_timestamp": 1671696002000, "expiration_timestamp": 1673596800000, "index_id": 1000033, "instrument_id": 144613, "instrument_name": "BTC-13JAN23-16000-P", "is_active": true, "kind": "option", "lot_size": 1, "maker_commission": 0.0003, "min_trade_amount": 0.1, "option_type": "put", "price_index": "btc_usd", "product_group": "BTC", "quote_currency": "BTC", "settlement_currency": "BTC", "settlement_period": "week", "state": "open", "strike": 16000, "taker_commission": 0.0003, "tick_size": 0.0005, "tick_size_steps": [ { "above_price": 120, "tick_size": 0.001 } ], "timestamp": 1671696002000 } }, "summary": "Repeated notification example" } ], "name": "instrument_subscription_notification_data", "payload": { "additionalProperties": false, "description": "The actual notification data", "properties": { "data": { "additionalProperties": true, "description": "The actual notification data", "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "currency": { "description": "Currency code or `any` for all\n\n**Allowed values:** `BTC`, `ETH`, `USDC`, `USDT`, `EURR`, `any`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT", "any" ] }, "kind": { "description": "Instrument kind\n\n**Allowed values:** `future`, `option`, `spot`, `future_combo`, `option_combo`", "enum": [ "future", "future_combo", "option", "option_combo", "spot" ] } }, "servers": [ { "$ref": "#/servers/public" } ], "summary": "Notification published once when an instrument is created, carrying full instrument data in the same format as `public/get_instruments`.\n\nThe notification fires exactly once at creation time, regardless of the instrument's initial state.\n\n**Subscription examples:**\n\n| Channel | Description |\n|---|---|\n| `instrument.creation.any.any` | All instruments |\n| `instrument.creation.future.BTC` | BTC futures only |\n| `instrument.creation.option.any` | All options |\n", "tags": [ { "name": "Market Data" } ], "title": "instrument.creation.(kind).(currency) " }, "instrument.state.(kind).(currency)": { "address": "instrument.state.{kind}.{currency}", "description": "Notifications about new or terminated instruments of a given kind in a given currency.\n\nUse this channel to track instrument lifecycle events (new listings, expirations/terminations) without polling.\n\n**Note:** Our system does not send notifications when currencies are locked. Users are advised to subscribe to the [platform_state](https://docs.deribit.com/subscriptions/platform/platform_state) channel to monitor the state of currencies actively.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to instrument channel. Channel name format: `instrument.state.(kind).(currency)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "instrument.state.future.USDC" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "instrument.state.future.USDC" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `instrument.state.(kind).(currency)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "instrument_name": "BTC-22MAR19", "state": "open", "timestamp": 1553080940000 } }, "summary": "Repeated notification example" } ], "name": "instrument_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "state": { "description": "The state of the order book. Represents the current lifecycle stage of the instrument.\n\n**State Lifecycle and Meanings:**\n\n- `open`: Default state for running books. In this state book is accepting new orders, edits, cancels; prices should be updated, trading is live.\n- `settlement`: Books enters to this state during settlement/delivery. New orders, edits, cancels are not accepted. After this state normally next state should be `open` if it was settlement, or `delivered` if it was delivery. On enter to this state good till day orders in book are canceled.\n- `delivered`: Final state of book that has been delivered. New orders, edits, cancels are not accepted. After some time book process will be terminated and, instrument moved to `expired_instruments` and its `instrument_state` will become archivized. On enter to this all open orders in book are canceled.\n- `inactive`: After a book is deactivated, this state is set on book. New orders, edits, cancels are not accepted. On enter to this all open orders in book are canceled. Book in this state is not considered as open. This can be also final state for book.\n- `locked`: New orders, edits, are not accepted, only cancels ARE accepted. In some cases when configured books can start as locked or it may become locked on admin request. Settlement is possible on locked books.\n- `halted`: The state that books enter as a result of an error. Settlement is not possible when there is at least one book in this state.\n- `archivized`: Set when instrument is moved to `expired_instruments` table, final state.\n", "enum": [ "archivized", "delivered", "halted", "inactive", "locked", "open", "settlement" ], "type": "string" }, "timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" } }, "required": [], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "currency": { "description": "Currency code or `any` for all\n\n**Allowed values:** `BTC`, `ETH`, `USDC`, `USDT`, `EURR`, `any`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT", "any" ] }, "kind": { "description": "Instrument kind\n\n**Allowed values:** `future`, `option`, `spot`, `future_combo`, `option_combo`", "enum": [ "future", "future_combo", "option", "option_combo", "spot" ] } }, "servers": [ { "$ref": "#/servers/public" } ], "summary": "Notifications about new or terminated instruments of a given kind in a given currency.\n\nUse this channel to track instrument lifecycle events (new listings, expirations/terminations) without polling.\n\n**Note:** Our system does not send notifications when currencies are locked. Users are advised to subscribe to the [platform_state](https://docs.deribit.com/subscriptions/platform/platform_state) channel to monitor the state of currencies actively.\n", "tags": [ { "name": "Market Data" } ], "title": "instrument.state.(kind).(currency) " }, "markprice.options.(index_name)": { "address": "markprice.options.{index_name}", "description": "Options mark price updates for the given `index_name`.\n\nUse this channel to receive mark prices for options under the given index, useful for valuation, risk monitoring, and P&L calculations.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to markprice channel. Channel name format: `markprice.options.(index_name)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "markprice.options.btc_usd" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "markprice.options.btc_usd" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `markprice.options.(index_name)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": [ { "instrument_name": "BTC-2JUN21-37000-P", "iv": 0.9, "mark_price": 0.0333, "timestamp": 1622470378005 }, { "instrument_name": "BTC-4JUN21-40500-P", "iv": 0.9, "mark_price": 0.117, "timestamp": 1622470378005 }, { "instrument_name": "BTC-4JUN21-38250-C", "iv": 0.9, "mark_price": 0.0177, "timestamp": 1622470378005 }, { "instrument_name": "BTC-1JUN21-37000-C", "iv": 0.9, "mark_price": 0.0098, "timestamp": 1622470378005 }, { "instrument_name": "BTC-4JUN21-36500-P", "iv": 0.9, "mark_price": 0.0371, "timestamp": 1622470378005 } ] }, "summary": "Repeated notification example" } ], "name": "markprice_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "description": "", "properties": { "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "iv": { "description": "Value of the volatility of the underlying instrument", "type": "number" }, "mark_price": { "description": "The mark price for the instrument", "type": "number" }, "timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" } }, "required": [], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "index_name": { "description": "Index identifier, matches (base) cryptocurrency with quote currency\n\n**Allowed values:** `btc_usd`, `eth_usd`, `ada_usdc`, `algo_usdc`, `avax_usdc`, ... (total 47 values)", "enum": [ "ada_usdc", "algo_usdc", "avax_usdc", "bch_usdc", "bnb_usdc", "btc_eurr", "btc_usd", "btc_usdc", "btc_usde", "btc_usdt", "btc_usyc", "btcdvol_usdc", "buidl_usdc", "doge_usdc", "dot_usdc", "drbfix-btc_usdc", "drbfix-eth_usdc", "eth_btc", "eth_eurr", "eth_usd", "eth_usdc", "eth_usde", "eth_usdt", "eth_usyc", "ethdvol_usdc", "eurr_usdc", "eurr_usdt", "link_usdc", "ltc_usdc", "near_usdc", "paxg_btc", "paxg_usdc", "shib_usdc", "sol_usdc", "sol_usdt", "steth_eth", "steth_usdc", "steth_usdt", "ton_usdc", "trump_usdc", "trx_usdc", "uni_usdc", "usdc_usdt", "usde_usdc", "usde_usdt", "usyc_usdc", "xrp_usdc" ] } }, "servers": [ { "$ref": "#/servers/public" } ], "summary": "Options mark price updates for the given `index_name`.\n\nUse this channel to receive mark prices for options under the given index, useful for valuation, risk monitoring, and P&L calculations.\n", "tags": [ { "name": "Market Data" } ], "title": "markprice.options.(index_name) " }, "perpetual.(instrument_name).(interval)": { "address": "perpetual.{instrument_name}.{interval}", "description": "Provide current interest rate - but only for **perpetual** instruments. Other types won't generate any notification.", "messages": { "subscribe_request": { "description": "Request to subscribe to perpetual channel. Channel name format: `perpetual.(instrument_name).(interval)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "perpetual.BTC-PERPETUAL.100ms" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "perpetual.BTC-PERPETUAL.100ms" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `perpetual.(instrument_name).(interval)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "index_price": 7872.88, "interest": 0.004999511380756577, "timestamp": 1571386349530 } }, "summary": "Repeated notification example" } ], "name": "perpetual_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "index_price": { "description": "Current index price", "example": 8247.27, "type": "number" }, "interest": { "description": "Current interest", "type": "number" }, "timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" } }, "required": [ "index_price", "interest", "timestamp" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "instrument_name": { "description": "The name of the instrument" }, "interval": { "description": "Frequency of notifications. Events will be aggregated over this interval. The value `raw` selects the finest granularity - events are aggregated over a 1 millisecond interval **(Please note that `raw` interval is only available to authorized users)**\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] } }, "servers": [ { "$ref": "#/servers/public" } ], "summary": "Provide current interest rate - but only for **perpetual** instruments. Other types won't generate any notification.", "tags": [ { "name": "Market Data" } ], "title": "perpetual.(instrument_name).(interval) " }, "platform_state": { "address": "platform_state", "description": "Platform state notifications.\n\nUse this channel to monitor whether the Deribit platform is operational and to detect maintenance periods or partial outages that may affect trading, authentication, or market data.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to `platform_state` channel. This channel does not require any additional parameters.", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "platform_state" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "platform_state" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `platform_state` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "locked": true, "price_index": "sol_usdc" } }, "summary": "Repeated notification example" } ], "name": "platform_state_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "locked": { "description": "Value is set to 'true' when index is locked on platform, sent only with `price_index` field", "example": false, "type": "boolean" }, "maintenance": { "description": "Value is set to `true` when the maintenance break begins", "example": true, "type": "boolean" }, "price_index": { "description": "Name of index that is locked or unlocked, sent only with `locked` field", "example": "btc_usdc", "type": "string" } }, "required": [], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": {}, "servers": [ { "$ref": "#/servers/public" } ], "summary": "Platform state notifications.\n\nUse this channel to monitor whether the Deribit platform is operational and to detect maintenance periods or partial outages that may affect trading, authentication, or market data.\n", "tags": [ { "name": "Platform" } ], "title": "platform_state " }, "platform_state.public_methods_state": { "address": "platform_state.public_methods_state", "description": "Notifications indicating whether unauthenticated (public) requests are currently allowed.\n\nThis is useful for monitoring service availability for public endpoints (e.g., market data) without authentication.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to `platform_state.public_methods_state` channel. This channel does not require any additional parameters.", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "platform_state.public_methods_state" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "platform_state.public_methods_state" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `platform_state.public_methods_state` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "allow_unauthenticated_public_requests": true } }, "summary": "Repeated notification example" } ], "name": "platform_state_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "allow_unauthenticated_public_requests": { "description": "Value is set to 'true' when unauthorized public requests are allowed", "type": "boolean" } }, "required": [ "allow_unauthenticated_public_requests" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": {}, "servers": [ { "$ref": "#/servers/public" } ], "summary": "Notifications indicating whether unauthenticated (public) requests are currently allowed.\n\nThis is useful for monitoring service availability for public endpoints (e.g., market data) without authentication.\n", "tags": [ { "name": "Platform" } ], "title": "platform_state.public_methods_state " }, "quote.(instrument_name)": { "address": "quote.{instrument_name}", "description": "Best bid/ask price and size for a specific instrument.\n\nThis subscription provides top-of-book updates (best bid and best ask) without the full depth of the order book. Use it when you only need the current spread and top sizes.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to quote channel. Channel name format: `quote.(instrument_name)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "quote.BTC-PERPETUAL" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "quote.BTC-PERPETUAL" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `quote.(instrument_name)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "best_ask_amount": 50, "best_ask_price": 3996.61, "best_bid_amount": 40, "best_bid_price": 3914.97, "instrument_name": "BTC-PERPETUAL", "timestamp": 1550658624149 } }, "summary": "Repeated notification example" } ], "name": "quote_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "best_ask_amount": { "description": "It represents the requested order size of all best asks", "type": "number" }, "best_ask_price": { "description": "The current best ask price, `null` if there aren't any asks", "type": "number" }, "best_bid_amount": { "description": "It represents the requested order size of all best bids", "type": "number" }, "best_bid_price": { "description": "The current best bid price, `null` if there aren't any bids", "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" } }, "required": [ "best_add_amount", "best_add_price", "best_bid_amount", "best_bid_price", "instrument_name", "timestamp" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "instrument_name": { "description": "The name of the instrument" } }, "servers": [ { "$ref": "#/servers/public" } ], "summary": "Best bid/ask price and size for a specific instrument.\n\nThis subscription provides top-of-book updates (best bid and best ask) without the full depth of the order book. Use it when you only need the current spread and top sizes.\n", "tags": [ { "name": "Market Data" } ], "title": "quote.(instrument_name) " }, "ticker.(instrument_name).(interval)": { "address": "ticker.{instrument_name}.{interval}", "description": "Real-time ticker data providing comprehensive market information for the specified instrument.\n\nThis subscription delivers key market metrics including:\n\n- **Price data:** Best bid/ask prices and amounts, last trade price, mark price, index price, settlement price, and estimated delivery price\n- **Market statistics:** 24-hour volume (in base currency and USD for futures), high/low prices, price change percentage, and open interest\n- **Order book state:** Current state of the instrument (open, settlement, delivered, inactive, locked, halted, or archivized)\n- **Price limits:** Minimum and maximum price constraints for order placement\n- **Options-specific data:** Implied volatility (bid/ask/mark IV), Greeks (delta, gamma, theta, vega, rho), underlying price, and interest rate\n- **Perpetual-specific data:** Current funding rate and 8-hour funding rate\n- **Futures-specific data:** Interest value and delivery price\n\nThe `interval` parameter controls the frequency of updates: `raw` (finest granularity - events aggregated over a 1 millisecond interval, authorized users only), `100ms` (aggregated every 100 milliseconds), or `agg2` (aggregated every 2 seconds).\n\nThis is the recommended method for real-time market data updates, as it provides efficient push-based notifications instead of requiring polling.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to ticker channel. Channel name format: `ticker.(instrument_name).(interval)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "ticker.BTC-PERPETUAL.100ms" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "ticker.BTC-PERPETUAL.100ms" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `ticker.(instrument_name).(interval)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "best_ask_amount": 100, "best_ask_price": 36443, "best_bid_amount": 5000, "best_bid_price": 36442.5, "current_funding": 0, "estimated_delivery_price": 36441.64, "funding_8h": 0.0000211, "index_price": 36441.64, "instrument_name": "BTC-PERPETUAL", "interest_value": 1.7362511643080387, "last_price": 36457.5, "mark_price": 36446.51, "max_price": 36991.72, "min_price": 35898.37, "open_interest": 502097590, "settlement_price": 36169.49, "state": "open", "stats": { "high": 36824.5, "low": 35213.5, "price_change": 0.7229, "volume": 7871.02139035, "volume_usd": 284061480 }, "timestamp": 1623060194301 } }, "summary": "Repeated notification example" } ], "name": "ticker_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "anchor_max_price": { "description": "The upper bound of the anchor price band, computed as `anchor_price * (1 + bandwidth)`. Only present for RWA perpetual instruments when an anchor price and bandwidth are defined.", "type": "number" }, "anchor_min_price": { "description": "The lower bound of the anchor price band, computed as `anchor_price * (1 - bandwidth)`. Only present for RWA perpetual instruments when an anchor price and bandwidth are defined.", "type": "number" }, "ask_iv": { "description": "(Only for option) implied volatility for best ask", "type": "number" }, "best_ask_amount": { "description": "It represents the requested order size of all best asks", "type": "number" }, "best_ask_price": { "description": "The current best ask price, `null` if there aren't any asks", "type": "number" }, "best_bid_amount": { "description": "It represents the requested order size of all best bids", "type": "number" }, "best_bid_price": { "description": "The current best bid price, `null` if there aren't any bids", "type": "number" }, "bid_iv": { "description": "(Only for option) implied volatility for best bid", "type": "number" }, "current_funding": { "description": "Current funding (perpetual only)", "type": "number" }, "delivery_price": { "description": "The settlement price for the instrument. Only when `state = closed`", "type": "number" }, "estimated_delivery_price": { "description": "Estimated delivery price for the market. For more details, see Contract Specification > General Documentation > Expiration Price", "example": 11628.81, "type": "number" }, "funding_8h": { "description": "Funding 8h (perpetual only)", "type": "number" }, "greeks": { "description": "Only for options. Greeks are risk measures that describe how the option's price changes with respect to various factors.\n\n**Delta (Δ)**\n\nDeribit uses two different Deltas:\n- **DeltaTotal** in the account summary uses the **Net Transaction Delta (NTD)**\n- **Delta** for individual option expiries is the **Black Scholes Delta**\n\nIn the settings section you can toggle Net Transaction Delta instead.\n\n**What is DeltaTotal in the account summary?**\n`DeltaTotal = Net Transaction Delta of options + BTC Position of Futures`\n\n**What is Net Transaction Delta?**\n`Net Transaction Delta = Black Scholes Delta - Mark Price of Options`\n\n**Why do we use a Net Transaction Delta?**\nThe Delta Total uses the Net Transaction Delta (or price adjusted Delta) of the options. This is because, from a risk perspective, we are interested in the change in Bitcoin price as the underlying changes.\n\nYou should actually treat your delta as **Equity + Delta Total** if you want to have less risk for your USD PnL.\n\n**Example:** Consider a call option with strike 0, which has a Black Scholes Delta of 1 and Net Transaction Delta = 0.\n\nImagine you have 2 BTC equity and no positions and BTC price is at USD 60k. In that case you would short 2 Futures contracts to hedge your USD exposure to BTC.\n\nNow let's say you buy one call with strike 0. The question is if you should sell another future?\n\nThe call will always have a price of 1 BTC. So you buy it at 1 BTC which equates to USD 60k. Let's say the price increases to USD 70k. The value of the call is still 1 BTC. At settlement you receive 1 BTC for the call. So you paid 1 BTC and then receive 1 BTC which means your USD PnL on buying the call is 0. If you sold a future on it, then you would actually lose on the future.\n\n⚠️ **During the 30 minute settlement period we decay your Delta.** See [Delta decay during settlement](https://support.deribit.com/hc/en-us/articles/25944751433757-Delta-decay-during-settlement) for more details.\n\n**Theta (Θ)**\n\nThe Theta that Deribit uses is the **minimum of (1 day Theta, lifetime theta of the option)**. So if you take an option with 1 hour to expire for example, generally Black Scholes Theta will give you the equivalent 1 day Theta. Whereas we show the 1 hour Theta, so our Theta would differ from Black Scholes Theta when time to expiry is less than 1 day.\n\n**Vega, Gamma, and Rho**\n\nVega (not actually a Greek symbol), Gamma, Theta and Rho values shown on Deribit are calculated using **standard Black Scholes without adjustments**.\n", "properties": { "delta": { "description": "(Only for option) The delta value for the option. This is the **Black Scholes Delta** for individual option expiries. \n\nNote that DeltaTotal in account summary uses Net Transaction Delta instead. See the greeks object description for more details.\n", "type": "number" }, "gamma": { "description": "(Only for option) The gamma value for the option. Calculated using standard Black Scholes without adjustments.\n\nGamma measures the rate of change of delta with respect to changes in the underlying asset price.\n", "type": "number" }, "rho": { "description": "(Only for option) The rho value for the option. Calculated using standard Black Scholes without adjustments.\n\nRho measures the sensitivity of the option price to changes in the risk-free interest rate.\n", "type": "number" }, "theta": { "description": "(Only for option) The theta value for the option. Deribit uses the **minimum of (1 day Theta, lifetime theta of the option)**.\n\nSo if you take an option with 1 hour to expire for example, generally Black Scholes Theta will give you the equivalent 1 day Theta. Whereas we show the 1 hour Theta, so our Theta would differ from Black Scholes Theta when time to expiry is less than 1 day.\n\nTheta measures the rate of change of the option price with respect to time decay.\n", "type": "number" }, "vega": { "description": "(Only for option) The vega value for the option. Calculated using standard Black Scholes without adjustments.\n\nVega (not actually a Greek symbol) measures the sensitivity of the option price to changes in implied volatility.\n", "type": "number" } }, "required": [ "delta", "gamma", "rho", "theta", "vega" ], "type": "object" }, "index_price": { "description": "Current index price", "example": 8247.27, "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "interest_rate": { "description": "Interest rate used in implied volatility calculations (options only)", "type": "number" }, "interest_value": { "description": "Value used to calculate `realized_funding` in positions (perpetual only)", "type": "number" }, "is_anchor_breached": { "description": "Whether the mark price has breached the anchor price band. Only present for RWA perpetual instruments when an anchor price is active.", "type": "boolean" }, "last_price": { "description": "The price for the last trade", "type": "number" }, "mark_iv": { "description": "(Only for option) implied volatility for mark price", "type": "number" }, "mark_price": { "description": "The mark price for the instrument", "type": "number" }, "max_price": { "description": "The maximum price for the future. Any buy orders you submit higher than this price, will be clamped to this maximum.", "type": "number" }, "min_price": { "description": "The minimum price for the future. Any sell orders you submit lower than this price will be clamped to this minimum.", "type": "number" }, "open_interest": { "description": "The total amount of outstanding contracts in the corresponding amount units. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.", "type": "number" }, "settlement_price": { "description": "Optional (not added for spot). The settlement price for the instrument. Only when `state = open`", "type": "number" }, "state": { "description": "The state of the order book. Represents the current lifecycle stage of the instrument.\n\n**State Lifecycle and Meanings:**\n\n- `open`: Default state for running books. In this state book is accepting new orders, edits, cancels; prices should be updated, trading is live.\n- `settlement`: Books enters to this state during settlement/delivery. New orders, edits, cancels are not accepted. After this state normally next state should be `open` if it was settlement, or `delivered` if it was delivery. On enter to this state good till day orders in book are canceled.\n- `delivered`: Final state of book that has been delivered. New orders, edits, cancels are not accepted. After some time book process will be terminated and, instrument moved to `expired_instruments` and its `instrument_state` will become archivized. On enter to this all open orders in book are canceled.\n- `inactive`: After a book is deactivated, this state is set on book. New orders, edits, cancels are not accepted. On enter to this all open orders in book are canceled. Book in this state is not considered as open. This can be also final state for book.\n- `locked`: New orders, edits, are not accepted, only cancels ARE accepted. In some cases when configured books can start as locked or it may become locked on admin request. Settlement is possible on locked books.\n- `halted`: The state that books enter as a result of an error. Settlement is not possible when there is at least one book in this state.\n- `archivized`: Set when instrument is moved to `expired_instruments` table, final state.\n", "enum": [ "archivized", "delivered", "halted", "inactive", "locked", "open", "settlement" ], "type": "string" }, "stats": { "properties": { "high": { "description": "Highest price during 24h", "type": "number" }, "low": { "description": "Lowest price during 24h", "type": "number" }, "price_change": { "description": "24-hour price change expressed as a percentage, `null` if there weren't any trades", "example": 10.23, "type": "number" }, "volume": { "description": "Volume during last 24h in base currency", "type": "number" }, "volume_usd": { "description": "Volume in usd (futures only)", "type": "number" } }, "required": [ "high", "low", "volume" ], "type": "object" }, "timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" }, "underlying_index": { "description": "Name of the underlying future, or `index_price` (options only)", "type": "number" }, "underlying_price": { "description": "Underlying price for implied volatility calculations (options only)", "type": "number" } }, "required": [ "best_ask_amount", "best_ask_price", "best_bid_amount", "best_bid_price", "estimated_delivery_price", "index_price", "instrument_name", "last_price", "mark_price", "max_price", "min_price", "open_interest", "state", "stats", "timestamp" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "instrument_name": { "description": "The name of the instrument" }, "interval": { "description": "Frequency of notifications. Events will be aggregated over this interval. The value `raw` selects the finest granularity - events are aggregated over a 1 millisecond interval **(Please note that `raw` interval is only available to authorized users)**\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] } }, "servers": [ { "$ref": "#/servers/public" } ], "summary": "Real-time ticker data providing comprehensive market information for the specified instrument.\n\nThis subscription delivers key market metrics including:\n\n- **Price data:** Best bid/ask prices and amounts, last trade price, mark price, index price, settlement price, and estimated delivery price\n- **Market statistics:** 24-hour volume (in base currency and USD for futures), high/low prices, price change percentage, and open interest\n- **Order book state:** Current state of the instrument (open, settlement, delivered, inactive, locked, halted, or archivized)\n- **Price limits:** Minimum and maximum price constraints for order placement\n- **Options-specific data:** Implied volatility (bid/ask/mark IV), Greeks (delta, gamma, theta, vega, rho), underlying price, and interest rate\n- **Perpetual-specific data:** Current funding rate and 8-hour funding rate\n- **Futures-specific data:** Interest value and delivery price\n\nThe `interval` parameter controls the frequency of updates: `raw` (finest granularity - events aggregated over a 1 millisecond interval, authorized users only), `100ms` (aggregated every 100 milliseconds), or `agg2` (aggregated every 2 seconds).\n\nThis is the recommended method for real-time market data updates, as it provides efficient push-based notifications instead of requiring polling.\n", "tags": [ { "name": "Market Data" } ], "title": "ticker.(instrument_name).(interval) " }, "trades.(instrument_name).(interval)": { "address": "trades.{instrument_name}.{interval}", "description": "Trade notifications for a specific instrument.\n\nUse this channel to receive executed trades as they happen for the given instrument. The `interval` controls how frequently trade events are aggregated.\n\n**Note:** For spot instruments routed to Coinbase Exchange, this channel is not supported. Use the [`matches` channel](https://docs.cdp.coinbase.com/exchange/websocket-feed/channels) for the full trade tape. For user trades, orders and changes, use the `user` channels.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to trades channel. Channel name format: `trades.(instrument_name).(interval)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "trades.BTC-PERPETUAL.100ms" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "trades.BTC-PERPETUAL.100ms" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `trades.(instrument_name).(interval)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": [ { "amount": 10, "contracts": 1, "direction": "sell", "index_price": 8955.88, "instrument_name": "BTC-PERPETUAL", "mark_price": 8948.9, "price": 8950, "tick_direction": 2, "timestamp": 1590484512188, "trade_id": "48079269", "trade_seq": 30289442 }, { "amount": 20, "contracts": 2, "direction": "buy", "index_price": 8955.88, "instrument_name": "BTC-PERPETUAL", "liquidation": "T", "mark_price": 8948.9, "price": 8960, "tick_direction": 0, "timestamp": 1590484513004, "trade_id": "48079270", "trade_seq": 30289443 } ] }, "summary": "Repeated notification example" } ], "name": "trades_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "amount": { "description": "Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.", "type": "number" }, "block_rfq_id": { "description": "ID of the Block RFQ - when trade was part of the Block RFQ", "type": "integer" }, "block_trade_id": { "description": "Block trade id - when trade was part of a block trade", "example": "154", "type": "string" }, "block_trade_leg_count": { "description": "Block trade leg count - when trade was part of a block trade", "example": 3, "type": "integer" }, "combo_id": { "description": "Optional field containing combo instrument name if the trade is a combo trade", "type": "string" }, "combo_trade_id": { "description": "Optional field containing combo trade identifier if the trade is a combo trade", "type": "string" }, "contracts": { "description": "Trade size in contract units (optional, may be absent in historical trades)", "type": "number" }, "direction": { "description": "Direction: `buy`, or `sell`", "enum": [ "buy", "sell" ], "type": "string" }, "index_price": { "description": "Index Price at the moment of trade", "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "iv": { "description": "Option implied volatility for the price (Option only)", "type": "number" }, "liquidation": { "description": "Optional field (only for trades caused by liquidation): `\"M\"` when maker side of trade was under liquidation, `\"T\"` when taker side was under liquidation, `\"MT\"` when both sides of trade were under liquidation", "enum": [ "M", "MT", "T" ], "type": "string" }, "mark_price": { "description": "Mark Price at the moment of trade", "type": "number" }, "price": { "description": "Price in base currency", "type": "number" }, "starbase_match_id": { "description": "Optional field containing the Starbase match identifier (present only for trades matched via Starbase)", "type": "integer" }, "starbase_timestamp": { "description": "The Starbase causal timestamp of the trade (nanoseconds since the Unix epoch)", "example": 1536569522277000000, "type": "integer" }, "tick_direction": { "description": "Direction of the \"tick\" (`0` = Plus Tick, `1` = Zero-Plus Tick, `2` = Minus Tick, `3` = Zero-Minus Tick).", "enum": [ 0, 1, 2, 3 ], "type": "integer" }, "timestamp": { "description": "The timestamp of the trade (milliseconds since the UNIX epoch)", "example": 1517329113791, "type": "integer" }, "trade_id": { "description": "Unique (per currency) trade identifier", "type": "string" }, "trade_seq": { "description": "The sequence number of the trade within instrument", "type": "integer" } }, "required": [ "amount", "direction", "index_price", "instrument_name", "mark_price", "price", "tick_direction", "timestamp", "trade_id", "trade_seq" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "instrument_name": { "description": "The name of the instrument" }, "interval": { "description": "Frequency of notifications. Events will be aggregated over this interval. The value `raw` selects the finest granularity - events are aggregated over a 1 millisecond interval **(Please note that `raw` interval is only available to authorized users)**\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] } }, "servers": [ { "$ref": "#/servers/public" } ], "summary": "Trade notifications for a specific instrument.\n\nUse this channel to receive executed trades as they happen for the given instrument. The `interval` controls how frequently trade events are aggregated.\n\n**Note:** For spot instruments routed to Coinbase Exchange, this channel is not supported. Use the [`matches` channel](https://docs.cdp.coinbase.com/exchange/websocket-feed/channels) for the full trade tape. For user trades, orders and changes, use the `user` channels.\n", "tags": [ { "name": "Trades" }, { "name": "Market Data" } ], "title": "trades.(instrument_name).(interval) " }, "trades.(kind).(currency).(interval)": { "address": "trades.{kind}.{currency}.{interval}", "description": "Trade notifications across all instruments for a given kind and currency.\n\nUse this channel when you want a consolidated stream of trades across all instruments of a specific `kind` (e.g., futures, options) and `currency`. The `interval` controls aggregation frequency.\n\n**Note:** For spot instruments routed to Coinbase Exchange, this channel is not supported with `kind` = `spot`: the subscription is rejected for any currency that is the base or the quote of a routed pair, and for `currency` = `any` whenever any pair is routed. Other kinds are unaffected. Use the [`matches` channel](https://docs.cdp.coinbase.com/exchange/websocket-feed/channels) for the full trade tape.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to trades channel. Channel name format: `trades.(kind).(currency).(interval)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "public/subscribe", "params": { "channels": [ "trades.future.USDC.100ms" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "public/subscribe", "description": "`public/subscribe` on the public WebSocket.", "enum": [ "public/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "trades.future.USDC.100ms" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `trades.(kind).(currency).(interval)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": [ { "amount": 3, "contracts": 3, "direction": "sell", "index_price": 8956.17, "instrument_name": "BTC-27MAY20-9000-C", "iv": 47.58, "mark_price": 0.01062686, "price": 0.0075, "tick_direction": 2, "timestamp": 1590484589306, "trade_id": "48079289", "trade_seq": 2 } ] }, "summary": "Repeated notification example" } ], "name": "trades_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "description": "", "properties": { "amount": { "description": "Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.", "type": "number" }, "block_rfq_id": { "description": "ID of the Block RFQ - when trade was part of the Block RFQ", "type": "integer" }, "block_trade_id": { "description": "Block trade id - when trade was part of a block trade", "example": "154", "type": "string" }, "block_trade_leg_count": { "description": "Block trade leg count - when trade was part of a block trade", "example": 3, "type": "integer" }, "combo_id": { "description": "Optional field containing combo instrument name if the trade is a combo trade", "type": "string" }, "combo_trade_id": { "description": "Optional field containing combo trade identifier if the trade is a combo trade", "type": "string" }, "contracts": { "description": "Trade size in contract units (optional, may be absent in historical trades)", "type": "number" }, "direction": { "description": "Direction: `buy`, or `sell`", "enum": [ "buy", "sell" ], "type": "string" }, "index_price": { "description": "Index Price at the moment of trade", "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "iv": { "description": "Option implied volatility for the price (Option only)", "type": "number" }, "liquidation": { "description": "Optional field (only for trades caused by liquidation): `\"M\"` when maker side of trade was under liquidation, `\"T\"` when taker side was under liquidation, `\"MT\"` when both sides of trade were under liquidation", "enum": [ "M", "MT", "T" ], "type": "string" }, "mark_price": { "description": "Mark Price at the moment of trade", "type": "number" }, "price": { "description": "Price in base currency", "type": "number" }, "starbase_match_id": { "description": "Optional field containing the Starbase match identifier (present only for trades matched via Starbase)", "type": "integer" }, "starbase_timestamp": { "description": "The Starbase causal timestamp of the trade (nanoseconds since the Unix epoch)", "example": 1536569522277000000, "type": "integer" }, "tick_direction": { "description": "Direction of the \"tick\" (`0` = Plus Tick, `1` = Zero-Plus Tick, `2` = Minus Tick, `3` = Zero-Minus Tick).", "enum": [ 0, 1, 2, 3 ], "type": "integer" }, "timestamp": { "description": "The timestamp of the trade (milliseconds since the UNIX epoch)", "example": 1517329113791, "type": "integer" }, "trade_id": { "description": "Unique (per currency) trade identifier", "type": "string" }, "trade_seq": { "description": "The sequence number of the trade within instrument", "type": "integer" } }, "required": [ "amount", "direction", "index_price", "instrument_name", "mark_price", "price", "tick_direction", "timestamp", "trade_id", "trade_seq" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "currency": { "description": "Currency code or `any` for all\n\n**Allowed values:** `BTC`, `ETH`, `USDC`, `USDT`, `EURR`, `any`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT", "any" ] }, "interval": { "description": "Frequency of notifications. Events will be aggregated over this interval. The value `raw` selects the finest granularity - events are aggregated over a 1 millisecond interval **(Please note that `raw` interval is only available to authorized users)**\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] }, "kind": { "description": "Instrument kind\n\n**Allowed values:** `future`, `option`, `spot`, `future_combo`, `option_combo`", "enum": [ "future", "future_combo", "option", "option_combo", "spot" ] } }, "servers": [ { "$ref": "#/servers/public" } ], "summary": "Trade notifications across all instruments for a given kind and currency.\n\nUse this channel when you want a consolidated stream of trades across all instruments of a specific `kind` (e.g., futures, options) and `currency`. The `interval` controls aggregation frequency.\n\n**Note:** For spot instruments routed to Coinbase Exchange, this channel is not supported with `kind` = `spot`: the subscription is rejected for any currency that is the base or the quote of a routed pair, and for `currency` = `any` whenever any pair is routed. Other kinds are unaffected. Use the [`matches` channel](https://docs.cdp.coinbase.com/exchange/websocket-feed/channels) for the full trade tape.\n", "tags": [ { "name": "Trades" }, { "name": "Market Data" } ], "title": "trades.(kind).(currency).(interval) " }, "user.access_log": { "address": "user.access_log", "description": "Security event notifications for the account.\n\nUse this channel to monitor account-related security events (e.g., access log entries) and build alerting around suspicious activity.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to `user.access_log` channel. This channel does not require any additional parameters.", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.access_log" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.access_log" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.access_log` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "city": "Pekin", "country": "China", "id": 243343, "ip": "8.9.10.11", "log": "success", "timestamp": 1632488963633 } }, "summary": "Repeated notification example" } ], "name": "user_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "city": { "description": "City where the IP address is registered (estimated)", "type": "string" }, "country": { "description": "Country where the IP address is registered (estimated)", "type": "string" }, "data": { "description": "Optional, additional information about action, type depends on `log` value", "oneOf": [ { "type": "object" }, { "type": "string" } ] }, "id": { "description": "Unique identifier", "example": 5967413, "type": "integer" }, "ip": { "description": "IP address of source that generated action", "type": "string" }, "log": { "description": "Action description. Possible values:\n\n- ``changed_email`` - email was changed\n- ``changed_password`` - password was changed\n- ``disabled_tfa`` - TFA was disabled\n- ``enabled_tfa`` - TFA was enabled\n- ``success`` - successful login\n- ``failure`` - login failure\n- ``enabled_subaccount_login`` - login was enabled for subaccount (in `data` - subaccount uid)\n- ``disabled_subaccount_login`` - login was disabled for subaccount (in `data` - subaccount uid)\n- ``new_api_key`` - API key was created (in `data` key client id)\n- ``removed_api_key`` - API key was removed (in `data` key client id)\n- ``changed_scope`` - scope of API key was changed (in `data` key client id)\n- ``changed_whitelist`` - whitelist of API key was edited (in `data` key client id)\n- ``disabled_api_key`` - API key was disabled (in `data` key client id)\n- ``enabled_api_key`` - API key was enabled (in `data` key client id)\n- ``reset_api_key`` - API key was reset (in `data` key client id)\n", "type": "string" }, "timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" } }, "required": [ "city", "country", "id", "ip", "log", "timestamp" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": {}, "servers": [ { "$ref": "#/servers/private" } ], "summary": "Security event notifications for the account.\n\nUse this channel to monitor account-related security events (e.g., access log entries) and build alerting around suspicious activity.\n", "tags": [ { "name": "User" }, { "name": "Private" } ], "title": "user.access_log " }, "user.changes.(instrument_name).(interval)": { "address": "user.changes.{instrument_name}.{interval}", "description": "User change stream (orders, trades, and related updates) for a specific instrument.\n\nThis channel provides a consolidated private update stream for your account for the given instrument. Use it when you want a single feed instead of subscribing to orders and trades separately.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to user channel. Channel name format: `user.changes.(instrument_name).(interval)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.changes.BTC-PERPETUAL.100ms" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.changes.BTC-PERPETUAL.100ms" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.changes.(instrument_name).(interval)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "instrument_name": "BTC-PERPETUAL", "orders": [ { "amount": 10, "api": false, "average_price": 17391, "creation_timestamp": 1605780344032, "direction": "sell", "filled_amount": 10, "instrument_name": "BTC-PERPETUAL", "is_liquidation": false, "is_rebalance": false, "label": "", "last_update_timestamp": 1605780344032, "max_show": 10, "order_id": "3398016", "order_state": "filled", "order_type": "market", "post_only": false, "price": 15665.5, "reduce_only": false, "replaced": false, "time_in_force": "good_til_cancelled", "web": true } ], "positions": [ { "average_price": 15000, "delta": 10.646886321, "direction": "buy", "floating_profit_loss": 0.906961435, "index_price": 17501.88, "initial_margin": 0.319750953, "instrument_name": "BTC-PERPETUAL", "interest_value": 1.7362511643080387, "kind": "future", "leverage": 33, "maintenance_margin": 0.234575865, "mark_price": 17391, "realized_funding": 0.01235663, "realized_profit_loss": 0.012454598, "settlement_price": 16025.83, "size": 185160, "size_currency": 10.646886321, "total_profit_loss": 1.69711368, "user_id": 1234 } ], "trades": [ { "amount": 10, "direction": "sell", "fee": 1.6e-7, "fee_currency": "BTC", "index_price": 17501.88, "instrument_name": "BTC-PERPETUAL", "liquidity": "T", "mark_price": 17391, "matching_id": null, "order_id": "3398016", "order_type": "market", "post_only": false, "price": 17391, "profit_loss": 0.00004898, "reduce_only": false, "state": "filled", "tick_direction": 1, "timestamp": 1605780344032, "trade_id": "1430914", "trade_seq": 866638 } ] } }, "summary": "Repeated notification example" } ], "name": "user_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "orders": { "additionalProperties": false, "description": "", "properties": { "advanced": { "description": "advanced type: `\"usd\"` or `\"implv\"` (Only for options; field is omitted if not applicable).\n", "enum": [ "implv", "usd" ], "type": "string" }, "amount": { "description": "It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.", "type": "number" }, "api": { "description": "`true` if created with API", "type": "boolean" }, "app_name": { "description": "The name of the application that placed the order on behalf of the user (optional).", "example": "Example Application", "type": "string" }, "auto_replaced": { "description": "Options, advanced orders only - `true` if last modification of the order was performed by the pricing engine, otherwise `false`.", "type": "boolean" }, "average_price": { "description": "Average fill price of the order", "type": "number" }, "block_trade": { "description": "`true` if order made from block_trade trade, added only in that case.", "example": true, "type": "boolean" }, "cancel_reason": { "description": "Enumerated reason behind cancel `\"user_request\"`, `\"autoliquidation\"`, `\"cancel_on_disconnect\"`, `\"risk_mitigation\"`, `\"pme_risk_reduction\"` (portfolio margining risk reduction), `\"pme_account_locked\"` (portfolio margining account locked per currency), `\"position_locked\"`, `\"mmp_trigger\"` (market maker protection), `\"mmp_config_curtailment\"` (market maker configured quantity decreased), `\"edit_post_only_reject\"` (cancelled on edit because of `reject_post_only` setting), `\"oco_other_closed\"` (the oco order linked to this order was closed), `\"oto_primary_closed\"` (the oto primary order that was going to trigger this order was cancelled), `\"settlement\"` (closed because of a settlement event, e.g. good-til-day orders are cancelled when an instrument enters the daily settlement). Note: orders cancelled because an instrument expired (delivery) currently do not include a `cancel_reason` field.", "enum": [ "autoliquidation", "cancel_on_disconnect", "edit_post_only_reject", "mmp_config_curtailment", "mmp_trigger", "oco_other_closed", "oto_primary_closed", "pme_account_locked", "pme_risk_reduction", "position_locked", "risk_mitigation", "settlement", "user_request" ], "type": "string" }, "combo_order_id": { "description": "Id of the combo order that created this order (only present for orders that were created as legs of a combo order).", "example": "103148386169", "type": "string" }, "contracts": { "description": "It represents the order size in contract units. (Optional, may be absent in historical data).", "type": "number" }, "creation_timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" }, "direction": { "description": "Direction: `buy`, or `sell`", "enum": [ "buy", "sell" ], "type": "string" }, "display_amount": { "description": "The actual display amount of iceberg order. Absent for other types of orders.", "type": "number" }, "filled_amount": { "description": "Filled amount of the order. For perpetual and futures the filled_amount is in USD units, for options - in units or corresponding cryptocurrency contracts, e.g., BTC or ETH.", "type": "number" }, "implv": { "description": "Implied volatility in percent. (Only if `advanced=\"implv\"`)", "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "is_liquidation": { "description": "Optional (not added for spot). `true` if order was automatically created during liquidation", "type": "boolean" }, "is_primary_otoco": { "description": "`true` if the order is an order that can trigger an OCO pair, otherwise not present.", "type": "boolean" }, "is_rebalance": { "description": "Optional (only for spot). `true` if order was automatically created during cross-collateral balance restoration", "type": "boolean" }, "is_secondary_oto": { "description": "`true` if the order is an order that can be triggered by another order, otherwise not present.", "type": "boolean" }, "label": { "description": "User defined label (up to 64 characters)", "type": "string" }, "last_update_timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" }, "mmp": { "description": "`true` if the order is a MMP order, otherwise `false`.", "type": "boolean" }, "mmp_cancelled": { "description": "`true` if order was cancelled by mmp trigger (optional)", "example": true, "type": "boolean" }, "mmp_group": { "description": "Name of the MMP group supplied in the `private/mass_quote` request. Only present for quote orders.", "type": "string" }, "mobile": { "description": "Optional field with value `true` added only when created with Mobile Application", "type": "boolean" }, "oco_ref": { "description": "Unique reference that identifies a one_cancels_others (OCO) pair.", "type": "string" }, "order_id": { "description": "Unique order identifier", "example": "ETH-100234", "type": "string" }, "order_state": { "description": "Order state: `\"open\"`, `\"filled\"`, `\"rejected\"`, `\"cancelled\"`, `\"untriggered\"`", "enum": [ "cancelled", "filled", "open", "rejected", "triggered", "untriggered" ], "type": "string" }, "order_type": { "description": "Order type: `\"limit\"`, `\"market\"`, `\"stop_limit\"`, `\"stop_market\"`, `\"take_limit\"`, `\"take_market\"`, `\"trailing_stop\"`", "enum": [ "limit", "market", "stop_limit", "stop_market", "take_limit", "take_market", "trailing_stop" ], "type": "string" }, "original_order_type": { "description": "Original API order type when an order is represented internally as a limit order. For example, Starbase market orders use `\"limit\"` as `order_type` with `\"market\"` in this optional field.", "enum": [ "market", "market_limit" ], "type": "string" }, "oto_order_ids": { "additionalProperties": true, "description": "The Ids of the orders that will be triggered if the order is filled", "properties": {}, "type": "object" }, "post_only": { "description": "`true` for post-only orders only", "type": "boolean" }, "price": { "description": "Price in base currency or \"market_price\" in case of open trigger market orders" }, "primary_order_id": { "description": "Unique order identifier", "example": "ETH-100234", "type": "string" }, "quote": { "description": "If order is a quote. Present only if true.", "type": "boolean" }, "quote_id": { "description": "The same QuoteID as supplied in the `private/mass_quote` request. Only present for quote orders.", "type": "string" }, "quote_set_id": { "description": "Identifier of the QuoteSet supplied in the `private/mass_quote` request. Only present for quote orders.", "type": "string" }, "reduce_only": { "description": "Optional (not added for spot). '`true` for reduce-only orders only'", "type": "boolean" }, "refresh_amount": { "description": "The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders", "type": "number" }, "reject_post_only": { "description": "`true` if order has `reject_post_only` flag (field is present only when `post_only` is `true`)", "type": "boolean" }, "replaced": { "description": "`true` if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise `false`.", "type": "boolean" }, "risk_reducing": { "description": "`true` if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise `false`.", "type": "boolean" }, "starbase_client_order_id": { "description": "Client order id of an order submitted directly to [Starbase](https://docs.deribit.com/starbase/overview) via direct access; not returned for orders placed through the Deribit API (combo legs inherit the parent combo order's client order id)", "type": "string" }, "starbase_last_update_timestamp": { "description": "The Starbase causal timestamp (nanoseconds since the Unix epoch) of the last book update that affected this order. Present only for orders placed in Starbase, including combo leg order updates; not always available for direct access orders", "example": 1536569522277000000, "type": "integer" }, "starbase_order_id": { "description": "Raw Starbase order id, in Starbase's own (non currency-prefixed) id namespace. Only present for orders placed in Starbase. Combo leg orders expose the parent combo order's Starbase order id.", "example": 103148386170, "type": "integer" }, "time_in_force": { "description": "Order time in force: `\"good_til_cancelled\"`, `\"good_til_day\"`, `\"fill_or_kill\"` or `\"immediate_or_cancel\"`", "enum": [ "fill_or_kill", "good_til_cancelled", "good_til_day", "immediate_or_cancel" ], "type": "string" }, "trigger": { "description": "Trigger type (only for trigger orders). Allowed values: `\"index_price\"`, `\"mark_price\"`, `\"last_price\"`.", "enum": [ "index_price", "last_price", "mark_price" ], "type": "string" }, "trigger_fill_condition": { "description": "

The fill condition of the linked order (Only for linked order types), default: `first_hit`.

", "enum": [ "complete_fill", "first_hit", "incremental" ], "type": "string" }, "trigger_offset": { "description": "The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)", "type": "number" }, "trigger_order_id": { "description": "Id of the trigger order that created the order (Only for orders that were created by triggered orders).", "example": "SLIB-370", "type": "string" }, "trigger_price": { "description": "Trigger price (Only for future trigger orders)", "type": "number" }, "trigger_reference_price": { "description": "The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)", "type": "number" }, "triggered": { "description": "Whether the trigger order has been triggered", "type": "boolean" }, "usd": { "description": "Option price in USD (Only if `advanced=\"usd\"`)", "type": "number" }, "web": { "description": "`true` if created via Deribit frontend (optional)", "type": "boolean" } }, "required": [ "api", "creation_timestamp", "direction", "instrument_name", "label", "last_update_timestamp", "order_id", "order_state", "order_type", "post_only", "price", "time_in_force" ], "type": "object" }, "position": { "additionalProperties": false, "description": "", "properties": { "average_price": { "description": "Average price of trades that built this position", "type": "number" }, "average_price_usd": { "description": "Only for options, average price in USD", "type": "number" }, "delta": { "description": "Delta parameter", "type": "number" }, "direction": { "description": "Direction: `buy`, `sell` or `zero`", "enum": [ "buy", "sell", "zero" ], "type": "string" }, "floating_profit_loss": { "description": "Floating profit or loss", "type": "number" }, "floating_profit_loss_usd": { "description": "Only for options, floating profit or loss in USD", "type": "number" }, "gamma": { "description": "Only for options, Gamma parameter", "type": "number" }, "index_price": { "description": "Current index price", "type": "number" }, "initial_margin": { "description": "Initial margin", "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "interest_value": { "description": "Value used to calculate `realized_funding` (perpetual only)", "type": "number" }, "kind": { "description": "Instrument kind: `\"future\"`, `\"option\"`, `\"spot\"`, `\"future_combo\"`, `\"option_combo\"`", "enum": [ "future", "future_combo", "option", "option_combo", "spot" ], "type": "string" }, "leverage": { "description": "Current available leverage for future position", "type": "integer" }, "maintenance_margin": { "description": "Maintenance margin", "type": "number" }, "mark_price": { "description": "Current mark price for position's instrument", "type": "number" }, "realized_funding": { "description": "Realized Funding in current session included in session realized profit or loss, only for positions of perpetual instruments", "type": "number" }, "realized_profit_loss": { "description": "Realized profit or loss", "type": "number" }, "settlement_price": { "description": "Optional (not added for spot). Last settlement price for position's instrument 0 if instrument wasn't settled yet", "type": "number" }, "size": { "description": "Position size for futures size in quote currency (e.g. USD), for options size is in base currency (e.g. BTC)", "type": "number" }, "size_currency": { "description": "Only for futures, position size in base currency", "type": "number" }, "theta": { "description": "Only for options, Theta parameter", "type": "number" }, "total_profit_loss": { "description": "Profit or loss from position", "type": "number" }, "user_id": { "description": "Unique user identifier", "example": 57874, "type": "integer" }, "vega": { "description": "Only for options, Vega parameter", "type": "number" } }, "required": [ "average_price", "delta", "direction", "floating_profit_loss", "index_price", "initial_margin", "instrument_name", "kind", "maintenance_margin", "mark_price", "realized_profit_loss", "settlement_price", "size", "total_profit_loss", "user_id" ], "type": "object" }, "trades": { "additionalProperties": false, "description": "", "properties": { "advanced": { "description": "Advanced type of user order: `\"usd\"` or `\"implv\"` (only for options; omitted if not applicable)", "enum": [ "implv", "usd" ], "type": "string" }, "amount": { "description": "Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.", "type": "number" }, "api": { "description": "`true` if user order was created with API", "type": "boolean" }, "block_rfq_id": { "description": "ID of the Block RFQ - when trade was part of the Block RFQ", "type": "integer" }, "block_rfq_quote_id": { "description": "ID of the Block RFQ quote - when trade was part of the Block RFQ", "type": "integer" }, "block_trade_id": { "description": "Block trade id - when trade was part of a block trade", "example": "154", "type": "string" }, "block_trade_leg_count": { "description": "Block trade leg count - when trade was part of a block trade", "example": 3, "type": "integer" }, "combo_id": { "description": "Optional field containing combo instrument name if the trade is a combo trade", "type": "string" }, "combo_trade_id": { "description": "Optional field containing combo trade identifier if the trade is a combo trade", "type": "string" }, "contracts": { "description": "Trade size in contract units (optional, may be absent in historical trades)", "type": "number" }, "direction": { "description": "Direction: `buy`, or `sell`", "enum": [ "buy", "sell" ], "type": "string" }, "fee": { "description": "User's fee in units of the specified `fee_currency`", "type": "number" }, "fee_currency": { "description": "Currency, i.e `\"BTC\"`, `\"ETH\"`, `\"USDC\"`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT" ], "type": "string" }, "index_price": { "description": "Index Price at the moment of trade", "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "iv": { "description": "Option implied volatility for the price (Option only)", "type": "number" }, "label": { "description": "User defined label (presented only when previously set for order by user)", "type": "string" }, "legs": { "description": "Optional field containing leg trades if trade is a combo trade (present when querying for **only** combo trades and in `combo_trades` events). Each leg trade has the same fields as a top-level user trade, including `starbase_match_id`, `starbase_order_id`, and `starbase_timestamp` when matched in Starbase, and `starbase_client_order_id` for orders submitted via [Starbase](https://docs.deribit.com/starbase/overview) direct access.", "type": "array" }, "liquidation": { "description": "Optional field (only for trades caused by liquidation): `\"M\"` when maker side of trade was under liquidation, `\"T\"` when taker side was under liquidation, `\"MT\"` when both sides of trade were under liquidation", "enum": [ "M", "MT", "T" ], "type": "string" }, "liquidity": { "description": "Describes what was role of users order: `\"M\"` when it was maker order, `\"T\"` when it was taker order", "enum": [ "M", "T" ], "type": "string" }, "mark_price": { "description": "Mark Price at the moment of trade", "type": "number" }, "matching_id": { "description": "Always `null`", "type": "string" }, "mmp": { "description": "`true` if user order is MMP", "type": "boolean" }, "order_id": { "description": "Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade", "type": "string" }, "order_type": { "description": "Order type: `\"limit\"`, `\"market\"`, or `\"liquidation\"`", "enum": [ "limit", "liquidation", "market" ], "type": "string" }, "original_order_type": { "description": "Original API order type when an order is represented internally as a limit order. For example, Starbase market orders use `\"limit\"` as `order_type` with `\"market\"` in this optional field.", "enum": [ "market", "market_limit" ], "type": "string" }, "post_only": { "description": "`true` if user order is post-only", "type": "string" }, "price": { "description": "Price in base currency", "type": "number" }, "profit_loss": { "description": "Profit and loss in base currency.", "type": "number" }, "quote_id": { "description": "QuoteID of the user order (optional, present only for orders placed with `private/mass_quote`)", "type": "string" }, "quote_set_id": { "description": "QuoteSet of the user order (optional, present only for orders placed with `private/mass_quote`)", "type": "string" }, "reduce_only": { "description": "`true` if user order is reduce-only", "type": "string" }, "risk_reducing": { "description": "`true` if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)", "type": "boolean" }, "starbase_client_order_id": { "description": "Client order id of the user's own order (maker or taker side) submitted directly to [Starbase](https://docs.deribit.com/starbase/overview) via direct access; not returned for orders placed through the Deribit API; for self-trades this is the taker order's client order id", "type": "string" }, "starbase_match_id": { "description": "Optional field containing the Starbase match identifier (present only for trades matched via Starbase)", "type": "integer" }, "starbase_order_id": { "description": "Raw Starbase order id of the user's order, in Starbase's own (non currency-prefixed) id namespace (present only for trades matched in Starbase)", "example": 103148386170, "type": "integer" }, "starbase_timestamp": { "description": "The Starbase causal timestamp of the trade (nanoseconds since the Unix epoch)", "example": 1536569522277000000, "type": "integer" }, "state": { "description": "Order state: `\"open\"`, `\"filled\"`, `\"rejected\"`, `\"cancelled\"`, `\"untriggered\"` or `\"archive\"` (if order was archived)", "enum": [ "archive", "cancelled", "filled", "open", "rejected", "untriggered" ], "type": "string" }, "tick_direction": { "description": "Direction of the \"tick\" (`0` = Plus Tick, `1` = Zero-Plus Tick, `2` = Minus Tick, `3` = Zero-Minus Tick).", "enum": [ 0, 1, 2, 3 ], "type": "integer" }, "timestamp": { "description": "The timestamp of the trade (milliseconds since the UNIX epoch)", "example": 1517329113791, "type": "integer" }, "trade_allocations": { "additionalProperties": false, "description": "List of allocations for Block RFQ pre-allocation. Each allocation specifies `user_id`, `amount`, and `fee` for the allocated part of the trade. For broker client allocations, a `client_info` object will be included.", "properties": { "amount": { "description": "Amount allocated to this user.", "type": "number" }, "client_info": { "description": "Optional client allocation info for brokers.", "properties": { "client_id": { "description": "ID of a client; available to broker. Represents a group of users under a common name.", "type": "integer" }, "client_link_id": { "description": "ID assigned to a single user in a client; available to broker.", "type": "integer" }, "name": { "description": "Name of the linked user within the client; available to broker.", "type": "string" } }, "type": "object" }, "fee": { "description": "Fee for the allocated part of the trade.", "type": "number" }, "user_id": { "description": "User ID to which part of the trade is allocated. For brokers the User ID is obstructed.", "type": "integer" } }, "required": [ "amount", "fee" ], "type": "object" }, "trade_id": { "description": "Unique (per currency) trade identifier", "type": "string" }, "trade_seq": { "description": "The sequence number of the trade within instrument", "type": "integer" }, "underlying_price": { "description": "Underlying price for implied volatility calculations (Options only)", "type": "number" } }, "required": [ "amount", "direction", "fee", "fee_currency", "index_price", "instrument_name", "mark_price", "matching_id", "order_id", "price", "state", "tick_direction", "timestamp", "trade_id", "trade_seq" ], "type": "object" } }, "required": [], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "instrument_name": { "description": "The name of the instrument" }, "interval": { "description": "Frequency of notifications. Events will be aggregated over this interval. The value `raw` selects the finest granularity - events are aggregated over a 1 millisecond interval **(Please note that `raw` interval is only available to authorized users)**\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] } }, "servers": [ { "$ref": "#/servers/private" } ], "summary": "User change stream (orders, trades, and related updates) for a specific instrument.\n\nThis channel provides a consolidated private update stream for your account for the given instrument. Use it when you want a single feed instead of subscribing to orders and trades separately.\n", "tags": [ { "name": "User" }, { "name": "Private" } ], "title": "user.changes.(instrument_name).(interval) " }, "user.changes.(kind).(currency).(interval)": { "address": "user.changes.{kind}.{currency}.{interval}", "description": "User change stream (orders, trades, and related updates) across all instruments for a given kind and currency.\n\nThis channel provides a consolidated private update stream for your account across all matching instruments. Use it when you want a single feed instead of subscribing to orders and trades separately.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to user channel. Channel name format: `user.changes.(kind).(currency).(interval)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.changes.future.USDC.100ms" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.changes.future.USDC.100ms" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.changes.(kind).(currency).(interval)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "instrument_name": "BTC-PERPETUAL", "orders": [ { "amount": 10, "api": false, "average_price": 17391, "creation_timestamp": 1605780344032, "direction": "sell", "filled_amount": 10, "instrument_name": "BTC-PERPETUAL", "is_liquidation": false, "is_rebalance": false, "label": "", "last_update_timestamp": 1605780344032, "max_show": 10, "order_id": "3398016", "order_state": "filled", "order_type": "market", "post_only": false, "price": 15665.5, "reduce_only": false, "replaced": false, "time_in_force": "good_til_cancelled", "web": true } ], "positions": [ { "average_price": 15000, "delta": 10.646886321, "direction": "buy", "floating_profit_loss": 0.906961435, "index_price": 17501.88, "initial_margin": 0.319750953, "instrument_name": "BTC-PERPETUAL", "interest_value": 1.7362511643080387, "kind": "future", "leverage": 33, "maintenance_margin": 0.234575865, "mark_price": 17391, "realized_funding": 0.01235663, "realized_profit_loss": 0.012454598, "settlement_price": 16025.83, "size": 185160, "size_currency": 10.646886321, "total_profit_loss": 1.69711368, "user_id": 1234 } ], "trades": [ { "amount": 10, "direction": "sell", "fee": 1.6e-7, "fee_currency": "BTC", "index_price": 17501.88, "instrument_name": "BTC-PERPETUAL", "liquidity": "T", "mark_price": 17391, "matching_id": null, "order_id": "3398016", "order_type": "market", "post_only": false, "price": 17391, "profit_loss": 0.00004898, "reduce_only": false, "state": "filled", "tick_direction": 1, "timestamp": 1605780344032, "trade_id": "1430914", "trade_seq": 866638 } ] } }, "summary": "Repeated notification example" } ], "name": "user_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "orders": { "additionalProperties": false, "description": "", "properties": { "advanced": { "description": "advanced type: `\"usd\"` or `\"implv\"` (Only for options; field is omitted if not applicable).\n", "enum": [ "implv", "usd" ], "type": "string" }, "amount": { "description": "It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.", "type": "number" }, "api": { "description": "`true` if created with API", "type": "boolean" }, "app_name": { "description": "The name of the application that placed the order on behalf of the user (optional).", "example": "Example Application", "type": "string" }, "auto_replaced": { "description": "Options, advanced orders only - `true` if last modification of the order was performed by the pricing engine, otherwise `false`.", "type": "boolean" }, "average_price": { "description": "Average fill price of the order", "type": "number" }, "block_trade": { "description": "`true` if order made from block_trade trade, added only in that case.", "example": true, "type": "boolean" }, "cancel_reason": { "description": "Enumerated reason behind cancel `\"user_request\"`, `\"autoliquidation\"`, `\"cancel_on_disconnect\"`, `\"risk_mitigation\"`, `\"pme_risk_reduction\"` (portfolio margining risk reduction), `\"pme_account_locked\"` (portfolio margining account locked per currency), `\"position_locked\"`, `\"mmp_trigger\"` (market maker protection), `\"mmp_config_curtailment\"` (market maker configured quantity decreased), `\"edit_post_only_reject\"` (cancelled on edit because of `reject_post_only` setting), `\"oco_other_closed\"` (the oco order linked to this order was closed), `\"oto_primary_closed\"` (the oto primary order that was going to trigger this order was cancelled), `\"settlement\"` (closed because of a settlement event, e.g. good-til-day orders are cancelled when an instrument enters the daily settlement). Note: orders cancelled because an instrument expired (delivery) currently do not include a `cancel_reason` field.", "enum": [ "autoliquidation", "cancel_on_disconnect", "edit_post_only_reject", "mmp_config_curtailment", "mmp_trigger", "oco_other_closed", "oto_primary_closed", "pme_account_locked", "pme_risk_reduction", "position_locked", "risk_mitigation", "settlement", "user_request" ], "type": "string" }, "combo_order_id": { "description": "Id of the combo order that created this order (only present for orders that were created as legs of a combo order).", "example": "103148386169", "type": "string" }, "contracts": { "description": "It represents the order size in contract units. (Optional, may be absent in historical data).", "type": "number" }, "creation_timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" }, "direction": { "description": "Direction: `buy`, or `sell`", "enum": [ "buy", "sell" ], "type": "string" }, "display_amount": { "description": "The actual display amount of iceberg order. Absent for other types of orders.", "type": "number" }, "filled_amount": { "description": "Filled amount of the order. For perpetual and futures the filled_amount is in USD units, for options - in units or corresponding cryptocurrency contracts, e.g., BTC or ETH.", "type": "number" }, "implv": { "description": "Implied volatility in percent. (Only if `advanced=\"implv\"`)", "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "is_liquidation": { "description": "Optional (not added for spot). `true` if order was automatically created during liquidation", "type": "boolean" }, "is_primary_otoco": { "description": "`true` if the order is an order that can trigger an OCO pair, otherwise not present.", "type": "boolean" }, "is_rebalance": { "description": "Optional (only for spot). `true` if order was automatically created during cross-collateral balance restoration", "type": "boolean" }, "is_secondary_oto": { "description": "`true` if the order is an order that can be triggered by another order, otherwise not present.", "type": "boolean" }, "label": { "description": "User defined label (up to 64 characters)", "type": "string" }, "last_update_timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" }, "mmp": { "description": "`true` if the order is a MMP order, otherwise `false`.", "type": "boolean" }, "mmp_cancelled": { "description": "`true` if order was cancelled by mmp trigger (optional)", "example": true, "type": "boolean" }, "mmp_group": { "description": "Name of the MMP group supplied in the `private/mass_quote` request. Only present for quote orders.", "type": "string" }, "mobile": { "description": "Optional field with value `true` added only when created with Mobile Application", "type": "boolean" }, "oco_ref": { "description": "Unique reference that identifies a one_cancels_others (OCO) pair.", "type": "string" }, "order_id": { "description": "Unique order identifier", "example": "ETH-100234", "type": "string" }, "order_state": { "description": "Order state: `\"open\"`, `\"filled\"`, `\"rejected\"`, `\"cancelled\"`, `\"untriggered\"`", "enum": [ "cancelled", "filled", "open", "rejected", "triggered", "untriggered" ], "type": "string" }, "order_type": { "description": "Order type: `\"limit\"`, `\"market\"`, `\"stop_limit\"`, `\"stop_market\"`, `\"take_limit\"`, `\"take_market\"`, `\"trailing_stop\"`", "enum": [ "limit", "market", "stop_limit", "stop_market", "take_limit", "take_market", "trailing_stop" ], "type": "string" }, "original_order_type": { "description": "Original API order type when an order is represented internally as a limit order. For example, Starbase market orders use `\"limit\"` as `order_type` with `\"market\"` in this optional field.", "enum": [ "market", "market_limit" ], "type": "string" }, "oto_order_ids": { "additionalProperties": true, "description": "The Ids of the orders that will be triggered if the order is filled", "properties": {}, "type": "object" }, "post_only": { "description": "`true` for post-only orders only", "type": "boolean" }, "price": { "description": "Price in base currency or \"market_price\" in case of open trigger market orders" }, "primary_order_id": { "description": "Unique order identifier", "example": "ETH-100234", "type": "string" }, "quote": { "description": "If order is a quote. Present only if true.", "type": "boolean" }, "quote_id": { "description": "The same QuoteID as supplied in the `private/mass_quote` request. Only present for quote orders.", "type": "string" }, "quote_set_id": { "description": "Identifier of the QuoteSet supplied in the `private/mass_quote` request. Only present for quote orders.", "type": "string" }, "reduce_only": { "description": "Optional (not added for spot). '`true` for reduce-only orders only'", "type": "boolean" }, "refresh_amount": { "description": "The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders", "type": "number" }, "reject_post_only": { "description": "`true` if order has `reject_post_only` flag (field is present only when `post_only` is `true`)", "type": "boolean" }, "replaced": { "description": "`true` if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise `false`.", "type": "boolean" }, "risk_reducing": { "description": "`true` if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise `false`.", "type": "boolean" }, "starbase_client_order_id": { "description": "Client order id of an order submitted directly to [Starbase](https://docs.deribit.com/starbase/overview) via direct access; not returned for orders placed through the Deribit API (combo legs inherit the parent combo order's client order id)", "type": "string" }, "starbase_last_update_timestamp": { "description": "The Starbase causal timestamp (nanoseconds since the Unix epoch) of the last book update that affected this order. Present only for orders placed in Starbase, including combo leg order updates; not always available for direct access orders", "example": 1536569522277000000, "type": "integer" }, "starbase_order_id": { "description": "Raw Starbase order id, in Starbase's own (non currency-prefixed) id namespace. Only present for orders placed in Starbase. Combo leg orders expose the parent combo order's Starbase order id.", "example": 103148386170, "type": "integer" }, "time_in_force": { "description": "Order time in force: `\"good_til_cancelled\"`, `\"good_til_day\"`, `\"fill_or_kill\"` or `\"immediate_or_cancel\"`", "enum": [ "fill_or_kill", "good_til_cancelled", "good_til_day", "immediate_or_cancel" ], "type": "string" }, "trigger": { "description": "Trigger type (only for trigger orders). Allowed values: `\"index_price\"`, `\"mark_price\"`, `\"last_price\"`.", "enum": [ "index_price", "last_price", "mark_price" ], "type": "string" }, "trigger_fill_condition": { "description": "

The fill condition of the linked order (Only for linked order types), default: `first_hit`.

", "enum": [ "complete_fill", "first_hit", "incremental" ], "type": "string" }, "trigger_offset": { "description": "The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)", "type": "number" }, "trigger_order_id": { "description": "Id of the trigger order that created the order (Only for orders that were created by triggered orders).", "example": "SLIB-370", "type": "string" }, "trigger_price": { "description": "Trigger price (Only for future trigger orders)", "type": "number" }, "trigger_reference_price": { "description": "The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)", "type": "number" }, "triggered": { "description": "Whether the trigger order has been triggered", "type": "boolean" }, "usd": { "description": "Option price in USD (Only if `advanced=\"usd\"`)", "type": "number" }, "web": { "description": "`true` if created via Deribit frontend (optional)", "type": "boolean" } }, "required": [ "api", "creation_timestamp", "direction", "instrument_name", "label", "last_update_timestamp", "order_id", "order_state", "order_type", "post_only", "price", "time_in_force" ], "type": "object" }, "position": { "additionalProperties": false, "description": "", "properties": { "average_price": { "description": "Average price of trades that built this position", "type": "number" }, "average_price_usd": { "description": "Only for options, average price in USD", "type": "number" }, "delta": { "description": "Delta parameter", "type": "number" }, "direction": { "description": "Direction: `buy`, `sell` or `zero`", "enum": [ "buy", "sell", "zero" ], "type": "string" }, "floating_profit_loss": { "description": "Floating profit or loss", "type": "number" }, "floating_profit_loss_usd": { "description": "Only for options, floating profit or loss in USD", "type": "number" }, "gamma": { "description": "Only for options, Gamma parameter", "type": "number" }, "index_price": { "description": "Current index price", "type": "number" }, "initial_margin": { "description": "Initial margin", "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "interest_value": { "description": "Value used to calculate `realized_funding` (perpetual only)", "type": "number" }, "kind": { "description": "Instrument kind: `\"future\"`, `\"option\"`, `\"spot\"`, `\"future_combo\"`, `\"option_combo\"`", "enum": [ "future", "future_combo", "option", "option_combo", "spot" ], "type": "string" }, "leverage": { "description": "Current available leverage for future position", "type": "integer" }, "maintenance_margin": { "description": "Maintenance margin", "type": "number" }, "mark_price": { "description": "Current mark price for position's instrument", "type": "number" }, "realized_funding": { "description": "Realized Funding in current session included in session realized profit or loss, only for positions of perpetual instruments", "type": "number" }, "realized_profit_loss": { "description": "Realized profit or loss", "type": "number" }, "settlement_price": { "description": "Optional (not added for spot). Last settlement price for position's instrument 0 if instrument wasn't settled yet", "type": "number" }, "size": { "description": "Position size for futures size in quote currency (e.g. USD), for options size is in base currency (e.g. BTC)", "type": "number" }, "size_currency": { "description": "Only for futures, position size in base currency", "type": "number" }, "theta": { "description": "Only for options, Theta parameter", "type": "number" }, "total_profit_loss": { "description": "Profit or loss from position", "type": "number" }, "user_id": { "description": "Unique user identifier", "example": 57874, "type": "integer" }, "vega": { "description": "Only for options, Vega parameter", "type": "number" } }, "required": [ "average_price", "delta", "direction", "floating_profit_loss", "index_price", "initial_margin", "instrument_name", "kind", "maintenance_margin", "mark_price", "realized_profit_loss", "settlement_price", "size", "total_profit_loss", "user_id" ], "type": "object" }, "trades": { "additionalProperties": false, "description": "", "properties": { "advanced": { "description": "Advanced type of user order: `\"usd\"` or `\"implv\"` (only for options; omitted if not applicable)", "enum": [ "implv", "usd" ], "type": "string" }, "amount": { "description": "Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.", "type": "number" }, "api": { "description": "`true` if user order was created with API", "type": "boolean" }, "block_rfq_id": { "description": "ID of the Block RFQ - when trade was part of the Block RFQ", "type": "integer" }, "block_rfq_quote_id": { "description": "ID of the Block RFQ quote - when trade was part of the Block RFQ", "type": "integer" }, "block_trade_id": { "description": "Block trade id - when trade was part of a block trade", "example": "154", "type": "string" }, "block_trade_leg_count": { "description": "Block trade leg count - when trade was part of a block trade", "example": 3, "type": "integer" }, "combo_id": { "description": "Optional field containing combo instrument name if the trade is a combo trade", "type": "string" }, "combo_trade_id": { "description": "Optional field containing combo trade identifier if the trade is a combo trade", "type": "string" }, "contracts": { "description": "Trade size in contract units (optional, may be absent in historical trades)", "type": "number" }, "direction": { "description": "Direction: `buy`, or `sell`", "enum": [ "buy", "sell" ], "type": "string" }, "fee": { "description": "User's fee in units of the specified `fee_currency`", "type": "number" }, "fee_currency": { "description": "Currency, i.e `\"BTC\"`, `\"ETH\"`, `\"USDC\"`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT" ], "type": "string" }, "index_price": { "description": "Index Price at the moment of trade", "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "iv": { "description": "Option implied volatility for the price (Option only)", "type": "number" }, "label": { "description": "User defined label (presented only when previously set for order by user)", "type": "string" }, "legs": { "description": "Optional field containing leg trades if trade is a combo trade (present when querying for **only** combo trades and in `combo_trades` events). Each leg trade has the same fields as a top-level user trade, including `starbase_match_id`, `starbase_order_id`, and `starbase_timestamp` when matched in Starbase, and `starbase_client_order_id` for orders submitted via [Starbase](https://docs.deribit.com/starbase/overview) direct access.", "type": "array" }, "liquidation": { "description": "Optional field (only for trades caused by liquidation): `\"M\"` when maker side of trade was under liquidation, `\"T\"` when taker side was under liquidation, `\"MT\"` when both sides of trade were under liquidation", "enum": [ "M", "MT", "T" ], "type": "string" }, "liquidity": { "description": "Describes what was role of users order: `\"M\"` when it was maker order, `\"T\"` when it was taker order", "enum": [ "M", "T" ], "type": "string" }, "mark_price": { "description": "Mark Price at the moment of trade", "type": "number" }, "matching_id": { "description": "Always `null`", "type": "string" }, "mmp": { "description": "`true` if user order is MMP", "type": "boolean" }, "order_id": { "description": "Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade", "type": "string" }, "order_type": { "description": "Order type: `\"limit\"`, `\"market\"`, or `\"liquidation\"`", "enum": [ "limit", "liquidation", "market" ], "type": "string" }, "original_order_type": { "description": "Original API order type when an order is represented internally as a limit order. For example, Starbase market orders use `\"limit\"` as `order_type` with `\"market\"` in this optional field.", "enum": [ "market", "market_limit" ], "type": "string" }, "post_only": { "description": "`true` if user order is post-only", "type": "string" }, "price": { "description": "Price in base currency", "type": "number" }, "profit_loss": { "description": "Profit and loss in base currency.", "type": "number" }, "quote_id": { "description": "QuoteID of the user order (optional, present only for orders placed with `private/mass_quote`)", "type": "string" }, "quote_set_id": { "description": "QuoteSet of the user order (optional, present only for orders placed with `private/mass_quote`)", "type": "string" }, "reduce_only": { "description": "`true` if user order is reduce-only", "type": "string" }, "risk_reducing": { "description": "`true` if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)", "type": "boolean" }, "starbase_client_order_id": { "description": "Client order id of the user's own order (maker or taker side) submitted directly to [Starbase](https://docs.deribit.com/starbase/overview) via direct access; not returned for orders placed through the Deribit API; for self-trades this is the taker order's client order id", "type": "string" }, "starbase_match_id": { "description": "Optional field containing the Starbase match identifier (present only for trades matched via Starbase)", "type": "integer" }, "starbase_order_id": { "description": "Raw Starbase order id of the user's order, in Starbase's own (non currency-prefixed) id namespace (present only for trades matched in Starbase)", "example": 103148386170, "type": "integer" }, "starbase_timestamp": { "description": "The Starbase causal timestamp of the trade (nanoseconds since the Unix epoch)", "example": 1536569522277000000, "type": "integer" }, "state": { "description": "Order state: `\"open\"`, `\"filled\"`, `\"rejected\"`, `\"cancelled\"`, `\"untriggered\"` or `\"archive\"` (if order was archived)", "enum": [ "archive", "cancelled", "filled", "open", "rejected", "untriggered" ], "type": "string" }, "tick_direction": { "description": "Direction of the \"tick\" (`0` = Plus Tick, `1` = Zero-Plus Tick, `2` = Minus Tick, `3` = Zero-Minus Tick).", "enum": [ 0, 1, 2, 3 ], "type": "integer" }, "timestamp": { "description": "The timestamp of the trade (milliseconds since the UNIX epoch)", "example": 1517329113791, "type": "integer" }, "trade_allocations": { "additionalProperties": false, "description": "List of allocations for Block RFQ pre-allocation. Each allocation specifies `user_id`, `amount`, and `fee` for the allocated part of the trade. For broker client allocations, a `client_info` object will be included.", "properties": { "amount": { "description": "Amount allocated to this user.", "type": "number" }, "client_info": { "description": "Optional client allocation info for brokers.", "properties": { "client_id": { "description": "ID of a client; available to broker. Represents a group of users under a common name.", "type": "integer" }, "client_link_id": { "description": "ID assigned to a single user in a client; available to broker.", "type": "integer" }, "name": { "description": "Name of the linked user within the client; available to broker.", "type": "string" } }, "type": "object" }, "fee": { "description": "Fee for the allocated part of the trade.", "type": "number" }, "user_id": { "description": "User ID to which part of the trade is allocated. For brokers the User ID is obstructed.", "type": "integer" } }, "required": [ "amount", "fee" ], "type": "object" }, "trade_id": { "description": "Unique (per currency) trade identifier", "type": "string" }, "trade_seq": { "description": "The sequence number of the trade within instrument", "type": "integer" }, "underlying_price": { "description": "Underlying price for implied volatility calculations (Options only)", "type": "number" } }, "required": [ "amount", "direction", "fee", "fee_currency", "index_price", "instrument_name", "mark_price", "matching_id", "order_id", "price", "state", "tick_direction", "timestamp", "trade_id", "trade_seq" ], "type": "object" } }, "required": [], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "currency": { "description": "Currency code or `any` for all\n\n**Allowed values:** `BTC`, `ETH`, `USDC`, `USDT`, `EURR`, `any`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT", "any" ] }, "interval": { "description": "Frequency of notifications. Events will be aggregated over this interval. The value `raw` selects the finest granularity - events are aggregated over a 1 millisecond interval **(Please note that `raw` interval is only available to authorized users)**\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] }, "kind": { "description": "Instrument kind\n\n**Allowed values:** `future`, `option`, `spot`, `future_combo`, `option_combo`", "enum": [ "future", "future_combo", "option", "option_combo", "spot" ] } }, "servers": [ { "$ref": "#/servers/private" } ], "summary": "User change stream (orders, trades, and related updates) across all instruments for a given kind and currency.\n\nThis channel provides a consolidated private update stream for your account across all matching instruments. Use it when you want a single feed instead of subscribing to orders and trades separately.\n", "tags": [ { "name": "User" }, { "name": "Private" } ], "title": "user.changes.(kind).(currency).(interval) " }, "user.combo_trades.(instrument_name).(interval)": { "address": "user.combo_trades.{instrument_name}.{interval}", "description": "User trade notifications for a specific combo instrument.\n\nTrades include a `legs` field describing the underlying legs of the combo. The `interval` controls aggregation frequency.\n\n**Block RFQ trades:** Block RFQ does not support combo instruments. RFQ-executed trades do not appear in this channel.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to user channel. Channel name format: `user.combo_trades.(instrument_name).(interval)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.combo_trades.BTC-PERPETUAL.100ms" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.combo_trades.BTC-PERPETUAL.100ms" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.combo_trades.(instrument_name).(interval)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": [ { "amount": 10, "api": false, "direction": "sell", "fee": 0, "fee_currency": "BTC", "index_price": 20332.44, "instrument_name": "BTC-FS-2SEP22_PERP", "legs": [ { "amount": 10, "api": false, "combo_id": "BTC-FS-2SEP22_PERP", "combo_trade_id": "1154", "direction": "buy", "fee": 5e-8, "fee_currency": "BTC", "index_price": 20332.44, "instrument_name": "BTC-PERPETUAL", "liquidity": "T", "mark_price": 20220.61, "matching_id": null, "mmp": false, "order_id": "720078", "order_type": "limit", "post_only": false, "price": 20008.5, "profit_loss": 0, "reduce_only": false, "risk_reducing": false, "state": "filled", "tick_direction": 2, "timestamp": 1661867454335, "trade_id": "1156", "trade_seq": 179 }, { "amount": 10, "api": false, "combo_id": "BTC-FS-2SEP22_PERP", "combo_trade_id": "1154", "direction": "sell", "fee": 5e-8, "fee_currency": "BTC", "index_price": 20332.44, "instrument_name": "BTC-2SEP22", "liquidity": "T", "mark_price": 20988.21, "matching_id": null, "mmp": false, "order_id": "720077", "order_type": "limit", "post_only": false, "price": 21200.32, "profit_loss": 0, "reduce_only": false, "risk_reducing": false, "state": "filled", "tick_direction": 0, "timestamp": 1661867454335, "trade_id": "1155", "trade_seq": 159 } ], "liquidity": "T", "mark_price": 767.6, "matching_id": null, "mmp": false, "order_id": "720074", "order_type": "limit", "post_only": false, "price": 1191.82, "profit_loss": null, "reduce_only": false, "risk_reducing": false, "state": "filled", "tick_direction": 2, "timestamp": 1661867454334, "trade_id": "1154", "trade_seq": 39 } ] }, "summary": "Repeated notification example" } ], "name": "user_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "description": "", "properties": { "advanced": { "description": "Advanced type of user order: `\"usd\"` or `\"implv\"` (only for options; omitted if not applicable)", "enum": [ "implv", "usd" ], "type": "string" }, "amount": { "description": "Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.", "type": "number" }, "api": { "description": "`true` if user order was created with API", "type": "boolean" }, "block_rfq_id": { "description": "ID of the Block RFQ - when trade was part of the Block RFQ", "type": "integer" }, "block_rfq_quote_id": { "description": "ID of the Block RFQ quote - when trade was part of the Block RFQ", "type": "integer" }, "block_trade_id": { "description": "Block trade id - when trade was part of a block trade", "example": "154", "type": "string" }, "block_trade_leg_count": { "description": "Block trade leg count - when trade was part of a block trade", "example": 3, "type": "integer" }, "combo_id": { "description": "Optional field containing combo instrument name if the trade is a combo trade", "type": "string" }, "combo_trade_id": { "description": "Optional field containing combo trade identifier if the trade is a combo trade", "type": "string" }, "contracts": { "description": "Trade size in contract units (optional, may be absent in historical trades)", "type": "number" }, "direction": { "description": "Direction: `buy`, or `sell`", "enum": [ "buy", "sell" ], "type": "string" }, "fee": { "description": "User's fee in units of the specified `fee_currency`", "type": "number" }, "fee_currency": { "description": "Currency, i.e `\"BTC\"`, `\"ETH\"`, `\"USDC\"`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT" ], "type": "string" }, "index_price": { "description": "Index Price at the moment of trade", "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "iv": { "description": "Option implied volatility for the price (Option only)", "type": "number" }, "label": { "description": "User defined label (presented only when previously set for order by user)", "type": "string" }, "legs": { "description": "Optional field containing leg trades if trade is a combo trade (present when querying for **only** combo trades and in `combo_trades` events). Each leg trade has the same fields as a top-level user trade, including `starbase_match_id`, `starbase_order_id`, and `starbase_timestamp` when matched in Starbase, and `starbase_client_order_id` for orders submitted via [Starbase](https://docs.deribit.com/starbase/overview) direct access.", "type": "array" }, "liquidation": { "description": "Optional field (only for trades caused by liquidation): `\"M\"` when maker side of trade was under liquidation, `\"T\"` when taker side was under liquidation, `\"MT\"` when both sides of trade were under liquidation", "enum": [ "M", "MT", "T" ], "type": "string" }, "liquidity": { "description": "Describes what was role of users order: `\"M\"` when it was maker order, `\"T\"` when it was taker order", "enum": [ "M", "T" ], "type": "string" }, "mark_price": { "description": "Mark Price at the moment of trade", "type": "number" }, "matching_id": { "description": "Always `null`", "type": "string" }, "mmp": { "description": "`true` if user order is MMP", "type": "boolean" }, "order_id": { "description": "Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade", "type": "string" }, "order_type": { "description": "Order type: `\"limit\"`, `\"market\"`, or `\"liquidation\"`", "enum": [ "limit", "liquidation", "market" ], "type": "string" }, "original_order_type": { "description": "Original API order type when an order is represented internally as a limit order. For example, Starbase market orders use `\"limit\"` as `order_type` with `\"market\"` in this optional field.", "enum": [ "market", "market_limit" ], "type": "string" }, "post_only": { "description": "`true` if user order is post-only", "type": "string" }, "price": { "description": "Price in base currency", "type": "number" }, "profit_loss": { "description": "Profit and loss in base currency.", "type": "number" }, "quote_id": { "description": "QuoteID of the user order (optional, present only for orders placed with `private/mass_quote`)", "type": "string" }, "quote_set_id": { "description": "QuoteSet of the user order (optional, present only for orders placed with `private/mass_quote`)", "type": "string" }, "reduce_only": { "description": "`true` if user order is reduce-only", "type": "string" }, "risk_reducing": { "description": "`true` if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)", "type": "boolean" }, "starbase_client_order_id": { "description": "Client order id of the user's own order (maker or taker side) submitted directly to [Starbase](https://docs.deribit.com/starbase/overview) via direct access; not returned for orders placed through the Deribit API; for self-trades this is the taker order's client order id", "type": "string" }, "starbase_match_id": { "description": "Optional field containing the Starbase match identifier (present only for trades matched via Starbase)", "type": "integer" }, "starbase_order_id": { "description": "Raw Starbase order id of the user's order, in Starbase's own (non currency-prefixed) id namespace (present only for trades matched in Starbase)", "example": 103148386170, "type": "integer" }, "starbase_timestamp": { "description": "The Starbase causal timestamp of the trade (nanoseconds since the Unix epoch)", "example": 1536569522277000000, "type": "integer" }, "state": { "description": "Order state: `\"open\"`, `\"filled\"`, `\"rejected\"`, `\"cancelled\"`, `\"untriggered\"` or `\"archive\"` (if order was archived)", "enum": [ "archive", "cancelled", "filled", "open", "rejected", "untriggered" ], "type": "string" }, "tick_direction": { "description": "Direction of the \"tick\" (`0` = Plus Tick, `1` = Zero-Plus Tick, `2` = Minus Tick, `3` = Zero-Minus Tick).", "enum": [ 0, 1, 2, 3 ], "type": "integer" }, "timestamp": { "description": "The timestamp of the trade (milliseconds since the UNIX epoch)", "example": 1517329113791, "type": "integer" }, "trade_allocations": { "additionalProperties": false, "description": "List of allocations for Block RFQ pre-allocation. Each allocation specifies `user_id`, `amount`, and `fee` for the allocated part of the trade. For broker client allocations, a `client_info` object will be included.", "properties": { "amount": { "description": "Amount allocated to this user.", "type": "number" }, "client_info": { "description": "Optional client allocation info for brokers.", "properties": { "client_id": { "description": "ID of a client; available to broker. Represents a group of users under a common name.", "type": "integer" }, "client_link_id": { "description": "ID assigned to a single user in a client; available to broker.", "type": "integer" }, "name": { "description": "Name of the linked user within the client; available to broker.", "type": "string" } }, "type": "object" }, "fee": { "description": "Fee for the allocated part of the trade.", "type": "number" }, "user_id": { "description": "User ID to which part of the trade is allocated. For brokers the User ID is obstructed.", "type": "integer" } }, "required": [ "amount", "fee" ], "type": "object" }, "trade_id": { "description": "Unique (per currency) trade identifier", "type": "string" }, "trade_seq": { "description": "The sequence number of the trade within instrument", "type": "integer" }, "underlying_price": { "description": "Underlying price for implied volatility calculations (Options only)", "type": "number" } }, "required": [ "amount", "direction", "fee", "fee_currency", "index_price", "instrument_name", "mark_price", "matching_id", "order_id", "price", "state", "tick_direction", "timestamp", "trade_id", "trade_seq" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "instrument_name": { "description": "The name of the instrument" }, "interval": { "description": "Frequency of notifications. Events will be aggregated over this interval. The value `raw` selects the finest granularity - events are aggregated over a 1 millisecond interval **(Please note that `raw` interval is only available to authorized users)**\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] } }, "servers": [ { "$ref": "#/servers/private" } ], "summary": "User trade notifications for a specific combo instrument.\n\nTrades include a `legs` field describing the underlying legs of the combo. The `interval` controls aggregation frequency.\n\n**Block RFQ trades:** Block RFQ does not support combo instruments. RFQ-executed trades do not appear in this channel.\n", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Trades" } ], "title": "user.combo_trades.(instrument_name).(interval) " }, "user.combo_trades.(kind).(currency).(interval)": { "address": "user.combo_trades.{kind}.{currency}.{interval}", "description": "User trade notifications across all combo instruments for a given kind and currency.\n\nTrades include a `legs` field describing the underlying legs. The `interval` controls aggregation frequency.\n\n**Block RFQ trades:** Block RFQ does not support combo instruments. RFQ-executed trades do not appear in this channel.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to user channel. Channel name format: `user.combo_trades.(kind).(currency).(interval)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.combo_trades.future.USDC.100ms" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.combo_trades.future.USDC.100ms" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.combo_trades.(kind).(currency).(interval)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": [ { "amount": 10, "api": false, "direction": "sell", "fee": 0, "fee_currency": "BTC", "index_price": 20332.44, "instrument_name": "BTC-FS-2SEP22_PERP", "legs": [ { "amount": 10, "api": false, "combo_id": "BTC-FS-2SEP22_PERP", "combo_trade_id": "1154", "direction": "buy", "fee": 5e-8, "fee_currency": "BTC", "index_price": 20332.44, "instrument_name": "BTC-PERPETUAL", "liquidity": "T", "mark_price": 20220.61, "matching_id": null, "mmp": false, "order_id": "720078", "order_type": "limit", "post_only": false, "price": 20008.5, "profit_loss": 0, "reduce_only": false, "risk_reducing": false, "state": "filled", "tick_direction": 2, "timestamp": 1661867454335, "trade_id": "1156", "trade_seq": 179 }, { "amount": 10, "api": false, "combo_id": "BTC-FS-2SEP22_PERP", "combo_trade_id": "1154", "direction": "sell", "fee": 5e-8, "fee_currency": "BTC", "index_price": 20332.44, "instrument_name": "BTC-2SEP22", "liquidity": "T", "mark_price": 20988.21, "matching_id": null, "mmp": false, "order_id": "720077", "order_type": "limit", "post_only": false, "price": 21200.32, "profit_loss": 0, "reduce_only": false, "risk_reducing": false, "state": "filled", "tick_direction": 0, "timestamp": 1661867454335, "trade_id": "1155", "trade_seq": 159 } ], "liquidity": "T", "mark_price": 767.6, "matching_id": null, "mmp": false, "order_id": "720074", "order_type": "limit", "post_only": false, "price": 1191.82, "profit_loss": null, "reduce_only": false, "risk_reducing": false, "state": "filled", "tick_direction": 2, "timestamp": 1661867454334, "trade_id": "1154", "trade_seq": 39 } ] }, "summary": "Repeated notification example" } ], "name": "user_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "description": "", "properties": { "advanced": { "description": "Advanced type of user order: `\"usd\"` or `\"implv\"` (only for options; omitted if not applicable)", "enum": [ "implv", "usd" ], "type": "string" }, "amount": { "description": "Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.", "type": "number" }, "api": { "description": "`true` if user order was created with API", "type": "boolean" }, "block_rfq_id": { "description": "ID of the Block RFQ - when trade was part of the Block RFQ", "type": "integer" }, "block_rfq_quote_id": { "description": "ID of the Block RFQ quote - when trade was part of the Block RFQ", "type": "integer" }, "block_trade_id": { "description": "Block trade id - when trade was part of a block trade", "example": "154", "type": "string" }, "block_trade_leg_count": { "description": "Block trade leg count - when trade was part of a block trade", "example": 3, "type": "integer" }, "combo_id": { "description": "Optional field containing combo instrument name if the trade is a combo trade", "type": "string" }, "combo_trade_id": { "description": "Optional field containing combo trade identifier if the trade is a combo trade", "type": "string" }, "contracts": { "description": "Trade size in contract units (optional, may be absent in historical trades)", "type": "number" }, "direction": { "description": "Direction: `buy`, or `sell`", "enum": [ "buy", "sell" ], "type": "string" }, "fee": { "description": "User's fee in units of the specified `fee_currency`", "type": "number" }, "fee_currency": { "description": "Currency, i.e `\"BTC\"`, `\"ETH\"`, `\"USDC\"`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT" ], "type": "string" }, "index_price": { "description": "Index Price at the moment of trade", "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "iv": { "description": "Option implied volatility for the price (Option only)", "type": "number" }, "label": { "description": "User defined label (presented only when previously set for order by user)", "type": "string" }, "legs": { "description": "Optional field containing leg trades if trade is a combo trade (present when querying for **only** combo trades and in `combo_trades` events). Each leg trade has the same fields as a top-level user trade, including `starbase_match_id`, `starbase_order_id`, and `starbase_timestamp` when matched in Starbase, and `starbase_client_order_id` for orders submitted via [Starbase](https://docs.deribit.com/starbase/overview) direct access.", "type": "array" }, "liquidation": { "description": "Optional field (only for trades caused by liquidation): `\"M\"` when maker side of trade was under liquidation, `\"T\"` when taker side was under liquidation, `\"MT\"` when both sides of trade were under liquidation", "enum": [ "M", "MT", "T" ], "type": "string" }, "liquidity": { "description": "Describes what was role of users order: `\"M\"` when it was maker order, `\"T\"` when it was taker order", "enum": [ "M", "T" ], "type": "string" }, "mark_price": { "description": "Mark Price at the moment of trade", "type": "number" }, "matching_id": { "description": "Always `null`", "type": "string" }, "mmp": { "description": "`true` if user order is MMP", "type": "boolean" }, "order_id": { "description": "Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade", "type": "string" }, "order_type": { "description": "Order type: `\"limit\"`, `\"market\"`, or `\"liquidation\"`", "enum": [ "limit", "liquidation", "market" ], "type": "string" }, "original_order_type": { "description": "Original API order type when an order is represented internally as a limit order. For example, Starbase market orders use `\"limit\"` as `order_type` with `\"market\"` in this optional field.", "enum": [ "market", "market_limit" ], "type": "string" }, "post_only": { "description": "`true` if user order is post-only", "type": "string" }, "price": { "description": "Price in base currency", "type": "number" }, "profit_loss": { "description": "Profit and loss in base currency.", "type": "number" }, "quote_id": { "description": "QuoteID of the user order (optional, present only for orders placed with `private/mass_quote`)", "type": "string" }, "quote_set_id": { "description": "QuoteSet of the user order (optional, present only for orders placed with `private/mass_quote`)", "type": "string" }, "reduce_only": { "description": "`true` if user order is reduce-only", "type": "string" }, "risk_reducing": { "description": "`true` if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)", "type": "boolean" }, "starbase_client_order_id": { "description": "Client order id of the user's own order (maker or taker side) submitted directly to [Starbase](https://docs.deribit.com/starbase/overview) via direct access; not returned for orders placed through the Deribit API; for self-trades this is the taker order's client order id", "type": "string" }, "starbase_match_id": { "description": "Optional field containing the Starbase match identifier (present only for trades matched via Starbase)", "type": "integer" }, "starbase_order_id": { "description": "Raw Starbase order id of the user's order, in Starbase's own (non currency-prefixed) id namespace (present only for trades matched in Starbase)", "example": 103148386170, "type": "integer" }, "starbase_timestamp": { "description": "The Starbase causal timestamp of the trade (nanoseconds since the Unix epoch)", "example": 1536569522277000000, "type": "integer" }, "state": { "description": "Order state: `\"open\"`, `\"filled\"`, `\"rejected\"`, `\"cancelled\"`, `\"untriggered\"` or `\"archive\"` (if order was archived)", "enum": [ "archive", "cancelled", "filled", "open", "rejected", "untriggered" ], "type": "string" }, "tick_direction": { "description": "Direction of the \"tick\" (`0` = Plus Tick, `1` = Zero-Plus Tick, `2` = Minus Tick, `3` = Zero-Minus Tick).", "enum": [ 0, 1, 2, 3 ], "type": "integer" }, "timestamp": { "description": "The timestamp of the trade (milliseconds since the UNIX epoch)", "example": 1517329113791, "type": "integer" }, "trade_allocations": { "additionalProperties": false, "description": "List of allocations for Block RFQ pre-allocation. Each allocation specifies `user_id`, `amount`, and `fee` for the allocated part of the trade. For broker client allocations, a `client_info` object will be included.", "properties": { "amount": { "description": "Amount allocated to this user.", "type": "number" }, "client_info": { "description": "Optional client allocation info for brokers.", "properties": { "client_id": { "description": "ID of a client; available to broker. Represents a group of users under a common name.", "type": "integer" }, "client_link_id": { "description": "ID assigned to a single user in a client; available to broker.", "type": "integer" }, "name": { "description": "Name of the linked user within the client; available to broker.", "type": "string" } }, "type": "object" }, "fee": { "description": "Fee for the allocated part of the trade.", "type": "number" }, "user_id": { "description": "User ID to which part of the trade is allocated. For brokers the User ID is obstructed.", "type": "integer" } }, "required": [ "amount", "fee" ], "type": "object" }, "trade_id": { "description": "Unique (per currency) trade identifier", "type": "string" }, "trade_seq": { "description": "The sequence number of the trade within instrument", "type": "integer" }, "underlying_price": { "description": "Underlying price for implied volatility calculations (Options only)", "type": "number" } }, "required": [ "amount", "direction", "fee", "fee_currency", "index_price", "instrument_name", "mark_price", "matching_id", "order_id", "price", "state", "tick_direction", "timestamp", "trade_id", "trade_seq" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "currency": { "description": "Currency code or `any` for all\n\n**Allowed values:** `BTC`, `ETH`, `USDC`, `USDT`, `EURR`, `any`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT", "any" ] }, "interval": { "description": "Frequency of notifications. Events will be aggregated over this interval. The value `raw` selects the finest granularity - events are aggregated over a 1 millisecond interval **(Please note that `raw` interval is only available to authorized users)**\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] }, "kind": { "description": "Instrument kind\n\n**Allowed values:** `future`, `option`, `spot`, `future_combo`, `option_combo`", "enum": [ "future", "future_combo", "option", "option_combo", "spot" ] } }, "servers": [ { "$ref": "#/servers/private" } ], "summary": "User trade notifications across all combo instruments for a given kind and currency.\n\nTrades include a `legs` field describing the underlying legs. The `interval` controls aggregation frequency.\n\n**Block RFQ trades:** Block RFQ does not support combo instruments. RFQ-executed trades do not appear in this channel.\n", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Trades" } ], "title": "user.combo_trades.(kind).(currency).(interval) " }, "user.isolated.changes.(instrument_name).(interval)": { "address": "user.isolated.changes.{instrument_name}.{interval}", "description": "Lets a **main** account observe position, order, and trade state changes across all of its **isolated-margin subaccounts** for a specific instrument.\n\nDelivers combined notifications of state changes across all isolated-margin subaccounts bound to the specified instrument. Requires the `trade:read` scope on an API key belonging to the **main account**.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to `user.isolated.changes.(instrument_name).(interval)` channel.", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.isolated.changes.SOL_USDC-PERPETUAL.100ms" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.isolated.changes.SOL_USDC-PERPETUAL.100ms" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.isolated.changes.(instrument_name).(interval)` subscription - contains state change updates.", "examples": [ { "name": "subscription_message_example", "payload": { "jsonrpc": "2.0", "method": "subscription", "params": { "channel": "user.isolated.changes.SOL_USDC-PERPETUAL.100ms", "data": { "instrument_name": "SOL_USDC-PERPETUAL", "isolated": true, "main_uid": 1000, "orders": [], "positions": [], "trades": [], "user_id": 123456 } } }, "summary": "Subscription notification example" } ], "name": "user_isolated_changes_instrument_name_interval_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "description": "Combined state changes payload", "properties": { "instrument_name": { "description": "Instrument name", "type": "string" }, "isolated": { "description": "Always true for isolated change events", "type": "boolean" }, "main_uid": { "description": "Owning main account user ID", "type": "integer" }, "orders": { "description": "List of updated order objects", "items": { "type": "object" }, "type": "array" }, "positions": { "description": "List of updated position objects", "items": { "type": "object" }, "type": "array" }, "trades": { "description": "List of executed trade objects", "items": { "type": "object" }, "type": "array" }, "user_id": { "description": "Subaccount slot ID", "type": "integer" } }, "required": [ "instrument_name", "isolated", "main_uid", "user_id" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "instrument_name": { "description": "Instrument name\n\n**Example:** `SOL_USDC-PERPETUAL`" }, "interval": { "description": "Frequency of notifications.\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] } }, "servers": [ { "$ref": "#/servers/private" } ], "summary": "Lets a **main** account observe position, order, and trade state changes across all of its **isolated-margin subaccounts** for a specific instrument.\n\nDelivers combined notifications of state changes across all isolated-margin subaccounts bound to the specified instrument. Requires the `trade:read` scope on an API key belonging to the **main account**.\n", "tags": [ { "name": "User" }, { "name": "Private" } ], "title": "user.isolated.changes.(instrument_name).(interval) " }, "user.isolated.changes.(kind).(currency).(interval)": { "address": "user.isolated.changes.{kind}.{currency}.{interval}", "description": "Lets a **main** account observe position, order, and trade state changes across all of its **isolated-margin subaccounts** for a given instrument kind and currency.\n\nDelivers combined notifications of state changes across all isolated-margin subaccounts. Isolated margin supports futures trading only. Requires the `trade:read` scope on an API key belonging to the **main account**.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to `user.isolated.changes.(kind).(currency).(interval)` channel.", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.isolated.changes.any.USDC.100ms" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.isolated.changes.any.USDC.100ms" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.isolated.changes.(kind).(currency).(interval)` subscription - contains state change updates.", "examples": [ { "name": "subscription_message_example", "payload": { "jsonrpc": "2.0", "method": "subscription", "params": { "channel": "user.isolated.changes.any.USDC.100ms", "data": { "instrument_name": "SOL_USDC-PERPETUAL", "isolated": true, "main_uid": 1000, "orders": [], "positions": [], "trades": [], "user_id": 123456 } } }, "summary": "Subscription notification example" } ], "name": "user_isolated_changes_kind_currency_interval_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "description": "Combined state changes payload", "properties": { "instrument_name": { "description": "Instrument name", "type": "string" }, "isolated": { "description": "Always true for isolated change events", "type": "boolean" }, "main_uid": { "description": "Owning main account user ID", "type": "integer" }, "orders": { "description": "List of updated order objects", "items": { "type": "object" }, "type": "array" }, "positions": { "description": "List of updated position objects", "items": { "type": "object" }, "type": "array" }, "trades": { "description": "List of executed trade objects", "items": { "type": "object" }, "type": "array" }, "user_id": { "description": "Subaccount slot ID", "type": "integer" } }, "required": [ "instrument_name", "isolated", "main_uid", "user_id" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "currency": { "description": "Currency code or `any` for all\n\n**Allowed values:** `BTC`, `ETH`, `USDC`, `USDT`, `EURR`, `any`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT", "any" ] }, "interval": { "description": "Frequency of notifications.\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] }, "kind": { "description": "Instrument kind. Isolated margin supports futures trading.\n\n**Allowed values:** `future`, `any`", "enum": [ "any", "future" ] } }, "servers": [ { "$ref": "#/servers/private" } ], "summary": "Lets a **main** account observe position, order, and trade state changes across all of its **isolated-margin subaccounts** for a given instrument kind and currency.\n\nDelivers combined notifications of state changes across all isolated-margin subaccounts. Isolated margin supports futures trading only. Requires the `trade:read` scope on an API key belonging to the **main account**.\n", "tags": [ { "name": "User" }, { "name": "Private" } ], "title": "user.isolated.changes.(kind).(currency).(interval) " }, "user.isolated.liquidation": { "address": "user.isolated.liquidation", "description": "Lets a **main** account observe the liquidation, ADL, and LSP activity of all of its **isolated-margin subaccounts**, without subscribing to each subaccount's own `user.liquidation` channel individually.\n\nEvery event on this channel is a fan-out copy of an event also delivered on the affected subaccount's own `user.liquidation` channel — the payload is identical, including `isolated: true` and the subaccount's `user_id`. The main account's *own* liquidation activity is never delivered here; it stays on the main account's regular `user.liquidation` channel.\n\nRequires the `account:read` scope on an API key belonging to the **main account**, and is only available while isolated margin is enabled on the platform.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to `user.isolated.liquidation` channel. This channel does not require any additional parameters.", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.isolated.liquidation" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.isolated.liquidation" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.isolated.liquidation` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "close_out_margin": 130, "currency": "USDC", "equity": 110, "initial_margin": 150, "isolated": true, "maintenance_margin": 120, "margin_balance": 110, "state": "liquidation_started", "timestamp": 1750000400000, "user_id": 220042 } }, "summary": "Repeated notification example" } ], "name": "user_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "amount": { "description": "Present for `lsp_transfer`, `adl_transfer`, and `adl_transfer_received`.", "type": "number" }, "close_out_margin": { "description": "Present for `liquidation_started`, `liquidation_completed`, `close_out_liquidation_started`, and `close_out_liquidation_completed`.", "type": "number" }, "commission": { "description": "Present for `lsp_transfer`, `adl_transfer`, and `adl_transfer_received`. The commission charged (on `lsp_transfer`/`adl_transfer`) or this account's share of the commission (on `adl_transfer_received`, proportional to the position this account absorbed). Intra-account subaccount ADL moves are commissioned the same way as moves onto another user's account.", "type": "number" }, "currency": { "description": "Currency, i.e `\"BTC\"`, `\"ETH\"`, `\"USDC\"`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT" ], "type": "string" }, "direction": { "description": "Present for `lsp_transfer`, `adl_transfer`, and `adl_transfer_received`. This account's own resulting position side.", "enum": [ "buy", "sell" ], "type": "string" }, "equity": { "description": "Present for `liquidation_started`, `liquidation_completed`, `close_out_liquidation_started`, and `close_out_liquidation_completed`.", "type": "number" }, "initial_margin": { "description": "Present for `liquidation_started`, `liquidation_completed`, `close_out_liquidation_started`, and `close_out_liquidation_completed`.", "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "isolated": { "description": "Present and `true` only when this event applies to an isolated-margin subaccount.", "type": "boolean" }, "maintenance_margin": { "description": "Present for `liquidation_started`, `liquidation_completed`, `close_out_liquidation_started`, and `close_out_liquidation_completed`.", "type": "number" }, "margin_balance": { "description": "Present for `liquidation_started`, `liquidation_completed`, `close_out_liquidation_started`, and `close_out_liquidation_completed`.", "type": "number" }, "price": { "description": "Present for `lsp_transfer`, `adl_transfer`, and `adl_transfer_received`. The transfer price applied.", "type": "number" }, "state": { "description": "The stage of the liquidation/ADL/LSP process this notification represents:\n- `liquidation_started` / `liquidation_completed`: The standard (order-book) liquidation process has started or completed for this account.\n- `close_out_liquidation_started` / `close_out_liquidation_completed`: The LSP/ADL close-out process has started or completed for this account. An account can go through this pair, the `liquidation_started`/`liquidation_completed` pair, or both in sequence (e.g. LSP/ADL close-out first, handed off to standard liquidation if it can't fully resolve the breach).\n- `lsp_transfer`: A position was transferred off this account to an LSP participant. Sent to the liquidated (source) account — see the `user.lsp` channel for the notification sent to the receiving participant.\n- `adl_transfer`: A position was auto-deleveraged off this account. Sent to the account being deleveraged (source).\n- `adl_transfer_received`: A position was auto-deleveraged onto this account from a counterparty. Sent to the receiving (counterparty) account.\n", "enum": [ "adl_transfer", "adl_transfer_received", "close_out_liquidation_completed", "close_out_liquidation_started", "liquidation_completed", "liquidation_started", "lsp_transfer" ], "type": "string" }, "timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" }, "user_id": { "description": "Unique user identifier", "example": 57874, "type": "integer" } }, "required": [ "state", "timestamp", "user_id" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": {}, "servers": [ { "$ref": "#/servers/private" } ], "summary": "Lets a **main** account observe the liquidation, ADL, and LSP activity of all of its **isolated-margin subaccounts**, without subscribing to each subaccount's own `user.liquidation` channel individually.\n\nEvery event on this channel is a fan-out copy of an event also delivered on the affected subaccount's own `user.liquidation` channel — the payload is identical, including `isolated: true` and the subaccount's `user_id`. The main account's *own* liquidation activity is never delivered here; it stays on the main account's regular `user.liquidation` channel.\n\nRequires the `account:read` scope on an API key belonging to the **main account**, and is only available while isolated margin is enabled on the platform.\n", "tags": [ { "name": "User" }, { "name": "Lsp" }, { "name": "Private" } ], "title": "user.isolated.liquidation " }, "user.isolated.orders.(instrument_name).(interval)": { "address": "user.isolated.orders.{instrument_name}.{interval}", "description": "Lets a **main** account observe order updates across all of its **isolated-margin subaccounts** for a specific instrument, without subscribing to each subaccount individually.\n\nDelivers real-time order state changes (placement, fill, edit, cancellation) for isolated-margin subaccounts bound to the specified instrument. Requires the `trade:read` scope on an API key belonging to the **main account**.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to `user.isolated.orders.(instrument_name).(interval)` channel.", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.isolated.orders.SOL_USDC-PERPETUAL.raw" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.isolated.orders.SOL_USDC-PERPETUAL.raw" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.isolated.orders.(instrument_name).(interval)` subscription - contains order update data.", "examples": [ { "name": "subscription_message_example", "payload": { "jsonrpc": "2.0", "method": "subscription", "params": { "channel": "user.isolated.orders.SOL_USDC-PERPETUAL.raw", "data": { "amount": 10, "direction": "buy", "filled_amount": 0, "instrument_name": "SOL_USDC-PERPETUAL", "isolated": true, "main_uid": 1000, "order_id": "12345678", "order_state": "open", "price": 100, "user_id": 123456 } } }, "summary": "Subscription notification example" } ], "name": "user_isolated_orders_instrument_name_interval_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "description": "Order update payload", "properties": { "amount": { "description": "Order amount in base currency", "type": "number" }, "average_price": { "description": "Average fill price", "type": "number" }, "creation_timestamp": { "description": "Creation timestamp in ms", "type": "integer" }, "direction": { "description": "Order direction: buy or sell", "type": "string" }, "filled_amount": { "description": "Filled amount in base currency", "type": "number" }, "instrument_name": { "description": "Instrument name", "type": "string" }, "isolated": { "description": "Always true for isolated order events", "type": "boolean" }, "last_update_timestamp": { "description": "Last update timestamp in ms", "type": "integer" }, "main_uid": { "description": "Owning main account user ID", "type": "integer" }, "order_id": { "description": "Unique order identifier", "type": "string" }, "order_state": { "description": "Order state: open, filled, rejected, cancelled", "type": "string" }, "order_type": { "description": "Order type: limit, market, etc.", "type": "string" }, "price": { "description": "Order price", "type": "number" }, "user_id": { "description": "Subaccount slot ID owning the order", "type": "integer" } }, "required": [ "amount", "direction", "instrument_name", "isolated", "main_uid", "order_id", "order_state", "user_id" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "instrument_name": { "description": "Instrument name\n\n**Example:** `SOL_USDC-PERPETUAL`" }, "interval": { "description": "Frequency of notifications. Events will be aggregated over this interval. The value `raw` selects the finest granularity.\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] } }, "servers": [ { "$ref": "#/servers/private" } ], "summary": "Lets a **main** account observe order updates across all of its **isolated-margin subaccounts** for a specific instrument, without subscribing to each subaccount individually.\n\nDelivers real-time order state changes (placement, fill, edit, cancellation) for isolated-margin subaccounts bound to the specified instrument. Requires the `trade:read` scope on an API key belonging to the **main account**.\n", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Orders" } ], "title": "user.isolated.orders.(instrument_name).(interval) " }, "user.isolated.orders.(kind).(currency).(interval)": { "address": "user.isolated.orders.{kind}.{currency}.{interval}", "description": "Lets a **main** account observe order updates across all of its **isolated-margin subaccounts** for a given instrument kind and currency, without subscribing to each subaccount individually.\n\nDelivers real-time order state changes for isolated-margin subaccounts. Isolated margin supports futures trading only. Requires the `trade:read` scope on an API key belonging to the **main account**.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to `user.isolated.orders.(kind).(currency).(interval)` channel.", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.isolated.orders.any.USDC.100ms" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.isolated.orders.any.USDC.100ms" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.isolated.orders.(kind).(currency).(interval)` subscription - contains order update data.", "examples": [ { "name": "subscription_message_example", "payload": { "jsonrpc": "2.0", "method": "subscription", "params": { "channel": "user.isolated.orders.any.USDC.100ms", "data": { "amount": 10, "direction": "buy", "filled_amount": 0, "instrument_name": "SOL_USDC-PERPETUAL", "isolated": true, "main_uid": 1000, "order_id": "12345678", "order_state": "open", "price": 100, "user_id": 123456 } } }, "summary": "Subscription notification example" } ], "name": "user_isolated_orders_kind_currency_interval_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "description": "Order update payload", "properties": { "amount": { "description": "Order amount in base currency", "type": "number" }, "average_price": { "description": "Average fill price", "type": "number" }, "creation_timestamp": { "description": "Creation timestamp in ms", "type": "integer" }, "direction": { "description": "Order direction: buy or sell", "type": "string" }, "filled_amount": { "description": "Filled amount in base currency", "type": "number" }, "instrument_name": { "description": "Instrument name", "type": "string" }, "isolated": { "description": "Always true for isolated order events", "type": "boolean" }, "last_update_timestamp": { "description": "Last update timestamp in ms", "type": "integer" }, "main_uid": { "description": "Owning main account user ID", "type": "integer" }, "order_id": { "description": "Unique order identifier", "type": "string" }, "order_state": { "description": "Order state: open, filled, rejected, cancelled", "type": "string" }, "order_type": { "description": "Order type: limit, market, etc.", "type": "string" }, "price": { "description": "Order price", "type": "number" }, "user_id": { "description": "Subaccount slot ID owning the order", "type": "integer" } }, "required": [ "amount", "direction", "instrument_name", "isolated", "main_uid", "order_id", "order_state", "user_id" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "currency": { "description": "Currency code or `any` for all\n\n**Allowed values:** `BTC`, `ETH`, `USDC`, `USDT`, `EURR`, `any`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT", "any" ] }, "interval": { "description": "Frequency of notifications. Events will be aggregated over this interval. The value `raw` selects the finest granularity.\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] }, "kind": { "description": "Instrument kind. Isolated margin supports futures trading.\n\n**Allowed values:** `future`, `any`", "enum": [ "any", "future" ] } }, "servers": [ { "$ref": "#/servers/private" } ], "summary": "Lets a **main** account observe order updates across all of its **isolated-margin subaccounts** for a given instrument kind and currency, without subscribing to each subaccount individually.\n\nDelivers real-time order state changes for isolated-margin subaccounts. Isolated margin supports futures trading only. Requires the `trade:read` scope on an API key belonging to the **main account**.\n", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Orders" } ], "title": "user.isolated.orders.(kind).(currency).(interval) " }, "user.isolated.portfolio.(currency)": { "address": "user.isolated.portfolio.{currency}", "description": "Lets a **main** account observe portfolio balance and risk updates across all of its active **isolated-margin subaccounts** for a specified currency (or `any`).\n\nDelivers real-time account and portfolio notifications for active isolated-margin subaccounts. Requires the `trade:read` or `account:read` scope on an API key belonging to the **main account**.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to `user.isolated.portfolio.(currency)` channel.", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.isolated.portfolio.USDC" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.isolated.portfolio.USDC" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.isolated.portfolio.(currency)` subscription - contains portfolio data payload.", "examples": [ { "name": "subscription_message_example", "payload": { "jsonrpc": "2.0", "method": "subscription", "params": { "channel": "user.isolated.portfolio.USDC", "data": { "available_funds": 40, "currency": "USDC", "equity": 50, "initial_margin": 10, "main_uid": 1000, "maintenance_margin": 5, "margin_balance": 50, "user_id": 123456 } } }, "summary": "Subscription notification example" } ], "name": "user_isolated_portfolio_currency_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "description": "Portfolio data payload for the isolated subaccount", "properties": { "available_funds": { "description": "Available funds for trading", "type": "number" }, "currency": { "description": "Currency code", "type": "string" }, "equity": { "description": "Total account equity", "type": "number" }, "initial_margin": { "description": "Initial margin requirement", "type": "number" }, "main_uid": { "description": "Owning main account user ID", "type": "integer" }, "maintenance_margin": { "description": "Maintenance margin requirement", "type": "number" }, "margin_balance": { "description": "Margin balance", "type": "number" }, "user_id": { "description": "Subaccount slot ID", "type": "integer" } }, "required": [ "currency", "equity", "margin_balance", "user_id" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "currency": { "description": "Currency code or `any` for all\n\n**Allowed values:** `BTC`, `ETH`, `USDC`, `USDT`, `EURR`, `any`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT", "any" ] } }, "servers": [ { "$ref": "#/servers/private" } ], "summary": "Lets a **main** account observe portfolio balance and risk updates across all of its active **isolated-margin subaccounts** for a specified currency (or `any`).\n\nDelivers real-time account and portfolio notifications for active isolated-margin subaccounts. Requires the `trade:read` or `account:read` scope on an API key belonging to the **main account**.\n", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Portfolio" } ], "title": "user.isolated.portfolio.(currency) " }, "user.isolated.trades.(instrument_name).(interval)": { "address": "user.isolated.trades.{instrument_name}.{interval}", "description": "Lets a **main** account observe trade executions across all of its **isolated-margin subaccounts** for a specific instrument, without subscribing to each subaccount individually.\n\nDelivers real-time trade execution notifications for isolated-margin subaccounts bound to the specified instrument. Requires the `trade:read` scope on an API key belonging to the **main account**.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to `user.isolated.trades.(instrument_name).(interval)` channel.", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.isolated.trades.SOL_USDC-PERPETUAL.100ms" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.isolated.trades.SOL_USDC-PERPETUAL.100ms" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.isolated.trades.(instrument_name).(interval)` subscription - contains trade execution data.", "examples": [ { "name": "subscription_message_example", "payload": { "jsonrpc": "2.0", "method": "subscription", "params": { "channel": "user.isolated.trades.SOL_USDC-PERPETUAL.100ms", "data": [ { "amount": 10, "direction": "buy", "fee": 0.05, "instrument_name": "SOL_USDC-PERPETUAL", "isolated": true, "main_uid": 1000, "order_id": "12345678", "price": 100, "timestamp": 1787109600000, "trade_id": "T-998811", "user_id": 123456 } ] } }, "summary": "Subscription notification example" } ], "name": "user_isolated_trades_instrument_name_interval_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "description": "List of trade execution records", "items": { "properties": { "amount": { "description": "Trade amount in base currency", "type": "number" }, "direction": { "description": "Trade direction: buy or sell", "type": "string" }, "fee": { "description": "Fee amount", "type": "number" }, "instrument_name": { "description": "Instrument name", "type": "string" }, "isolated": { "description": "Always true for isolated trade events", "type": "boolean" }, "main_uid": { "description": "Owning main account user ID", "type": "integer" }, "order_id": { "description": "Order identifier", "type": "string" }, "price": { "description": "Trade price", "type": "number" }, "timestamp": { "description": "Trade timestamp in ms", "type": "integer" }, "trade_id": { "description": "Unique trade identifier", "type": "string" }, "user_id": { "description": "Subaccount slot ID owning the trade", "type": "integer" } }, "required": [ "amount", "direction", "instrument_name", "isolated", "main_uid", "order_id", "price", "trade_id", "user_id" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "instrument_name": { "description": "Instrument name\n\n**Example:** `SOL_USDC-PERPETUAL`" }, "interval": { "description": "Frequency of notifications.\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] } }, "servers": [ { "$ref": "#/servers/private" } ], "summary": "Lets a **main** account observe trade executions across all of its **isolated-margin subaccounts** for a specific instrument, without subscribing to each subaccount individually.\n\nDelivers real-time trade execution notifications for isolated-margin subaccounts bound to the specified instrument. Requires the `trade:read` scope on an API key belonging to the **main account**.\n", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Trades" } ], "title": "user.isolated.trades.(instrument_name).(interval) " }, "user.isolated.trades.(kind).(currency).(interval)": { "address": "user.isolated.trades.{kind}.{currency}.{interval}", "description": "Lets a **main** account observe trade executions across all of its **isolated-margin subaccounts** for a given instrument kind and currency, without subscribing to each subaccount individually.\n\nDelivers real-time trade execution notifications for isolated-margin subaccounts. Isolated margin supports futures trading only. Requires the `trade:read` scope on an API key belonging to the **main account**.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to `user.isolated.trades.(kind).(currency).(interval)` channel.", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.isolated.trades.any.USDC.100ms" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.isolated.trades.any.USDC.100ms" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.isolated.trades.(kind).(currency).(interval)` subscription - contains trade execution data.", "examples": [ { "name": "subscription_message_example", "payload": { "jsonrpc": "2.0", "method": "subscription", "params": { "channel": "user.isolated.trades.any.USDC.100ms", "data": [ { "amount": 10, "direction": "buy", "fee": 0.05, "instrument_name": "SOL_USDC-PERPETUAL", "isolated": true, "main_uid": 1000, "order_id": "12345678", "price": 100, "timestamp": 1787109600000, "trade_id": "T-998811", "user_id": 123456 } ] } }, "summary": "Subscription notification example" } ], "name": "user_isolated_trades_kind_currency_interval_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "description": "List of trade execution records", "items": { "properties": { "amount": { "description": "Trade amount in base currency", "type": "number" }, "direction": { "description": "Trade direction: buy or sell", "type": "string" }, "fee": { "description": "Fee amount", "type": "number" }, "instrument_name": { "description": "Instrument name", "type": "string" }, "isolated": { "description": "Always true for isolated trade events", "type": "boolean" }, "main_uid": { "description": "Owning main account user ID", "type": "integer" }, "order_id": { "description": "Order identifier", "type": "string" }, "price": { "description": "Trade price", "type": "number" }, "timestamp": { "description": "Trade timestamp in ms", "type": "integer" }, "trade_id": { "description": "Unique trade identifier", "type": "string" }, "user_id": { "description": "Subaccount slot ID owning the trade", "type": "integer" } }, "required": [ "amount", "direction", "instrument_name", "isolated", "main_uid", "order_id", "price", "trade_id", "user_id" ], "type": "object" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "currency": { "description": "Currency code or `any` for all\n\n**Allowed values:** `BTC`, `ETH`, `USDC`, `USDT`, `EURR`, `any`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT", "any" ] }, "interval": { "description": "Frequency of notifications.\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] }, "kind": { "description": "Instrument kind. Isolated margin supports futures trading.\n\n**Allowed values:** `future`, `any`", "enum": [ "any", "future" ] } }, "servers": [ { "$ref": "#/servers/private" } ], "summary": "Lets a **main** account observe trade executions across all of its **isolated-margin subaccounts** for a given instrument kind and currency, without subscribing to each subaccount individually.\n\nDelivers real-time trade execution notifications for isolated-margin subaccounts. Isolated margin supports futures trading only. Requires the `trade:read` scope on an API key belonging to the **main account**.\n", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Trades" } ], "title": "user.isolated.trades.(kind).(currency).(interval) " }, "user.lock": { "address": "user.lock", "description": "Notifications when the account is locked or unlocked.\n\nUse this channel to react to account lock events (e.g., pause trading workflows) and to detect when access is restored.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to `user.lock` channel. This channel does not require any additional parameters.", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.lock" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.lock" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.lock` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "currency": "ALL", "locked": true } }, "summary": "Repeated notification example" } ], "name": "user_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "currency": { "description": "Currency on which account lock has changed, `ALL` if changed for all currencies", "example": "BTC, ALL", "type": "string" }, "locked": { "description": "Value is set to 'true' when user account is locked in currency", "example": false, "type": "boolean" } }, "required": [ "currency", "locked" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": {}, "servers": [ { "$ref": "#/servers/private" } ], "summary": "Notifications when the account is locked or unlocked.\n\nUse this channel to react to account lock events (e.g., pause trading workflows) and to detect when access is restored.\n", "tags": [ { "name": "User" }, { "name": "Private" } ], "title": "user.lock " }, "user.orders.(instrument_name).(interval)": { "address": "user.orders.{instrument_name}.{interval}", "description": "User order updates for a specific instrument (aggregated).\n\nUse this channel to receive private order updates for the given instrument, aggregated according to `interval`.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to user channel. Channel name format: `user.orders.(instrument_name).(interval)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.orders.BTC-PERPETUAL.100ms" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.orders.BTC-PERPETUAL.100ms" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.orders.(instrument_name).(interval)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": [ { "amount": 200, "api": false, "average_price": 0, "creation_timestamp": 1581507159533, "direction": "buy", "filled_amount": 0, "instrument_name": "BTC-PERPETUAL", "is_liquidation": false, "is_rebalance": false, "label": "", "last_update_timestamp": 1581507159533, "max_show": 200, "order_id": "4", "order_state": "open", "order_type": "limit", "original_order_type": "market", "post_only": false, "price": 10460.43, "reduce_only": false, "replaced": false, "time_in_force": "good_til_cancelled" } ] }, "summary": "Repeated notification example" } ], "name": "user_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "description": "", "properties": { "advanced": { "description": "advanced type: `\"usd\"` or `\"implv\"` (Only for options; field is omitted if not applicable).\n", "enum": [ "implv", "usd" ], "type": "string" }, "amount": { "description": "It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.", "type": "number" }, "api": { "description": "`true` if created with API", "type": "boolean" }, "app_name": { "description": "The name of the application that placed the order on behalf of the user (optional).", "example": "Example Application", "type": "string" }, "auto_replaced": { "description": "Options, advanced orders only - `true` if last modification of the order was performed by the pricing engine, otherwise `false`.", "type": "boolean" }, "average_price": { "description": "Average fill price of the order", "type": "number" }, "block_trade": { "description": "`true` if order made from block_trade trade, added only in that case.", "example": true, "type": "boolean" }, "cancel_reason": { "description": "Enumerated reason behind cancel `\"user_request\"`, `\"autoliquidation\"`, `\"cancel_on_disconnect\"`, `\"risk_mitigation\"`, `\"pme_risk_reduction\"` (portfolio margining risk reduction), `\"pme_account_locked\"` (portfolio margining account locked per currency), `\"position_locked\"`, `\"mmp_trigger\"` (market maker protection), `\"mmp_config_curtailment\"` (market maker configured quantity decreased), `\"edit_post_only_reject\"` (cancelled on edit because of `reject_post_only` setting), `\"oco_other_closed\"` (the oco order linked to this order was closed), `\"oto_primary_closed\"` (the oto primary order that was going to trigger this order was cancelled), `\"settlement\"` (closed because of a settlement event, e.g. good-til-day orders are cancelled when an instrument enters the daily settlement). Note: orders cancelled because an instrument expired (delivery) currently do not include a `cancel_reason` field.", "enum": [ "autoliquidation", "cancel_on_disconnect", "edit_post_only_reject", "mmp_config_curtailment", "mmp_trigger", "oco_other_closed", "oto_primary_closed", "pme_account_locked", "pme_risk_reduction", "position_locked", "risk_mitigation", "settlement", "user_request" ], "type": "string" }, "combo_order_id": { "description": "Id of the combo order that created this order (only present for orders that were created as legs of a combo order).", "example": "103148386169", "type": "string" }, "contracts": { "description": "It represents the order size in contract units. (Optional, may be absent in historical data).", "type": "number" }, "creation_timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" }, "direction": { "description": "Direction: `buy`, or `sell`", "enum": [ "buy", "sell" ], "type": "string" }, "display_amount": { "description": "The actual display amount of iceberg order. Absent for other types of orders.", "type": "number" }, "filled_amount": { "description": "Filled amount of the order. For perpetual and futures the filled_amount is in USD units, for options - in units or corresponding cryptocurrency contracts, e.g., BTC or ETH.", "type": "number" }, "implv": { "description": "Implied volatility in percent. (Only if `advanced=\"implv\"`)", "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "is_liquidation": { "description": "Optional (not added for spot). `true` if order was automatically created during liquidation", "type": "boolean" }, "is_primary_otoco": { "description": "`true` if the order is an order that can trigger an OCO pair, otherwise not present.", "type": "boolean" }, "is_rebalance": { "description": "Optional (only for spot). `true` if order was automatically created during cross-collateral balance restoration", "type": "boolean" }, "is_secondary_oto": { "description": "`true` if the order is an order that can be triggered by another order, otherwise not present.", "type": "boolean" }, "label": { "description": "User defined label (up to 64 characters)", "type": "string" }, "last_update_timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" }, "mmp": { "description": "`true` if the order is a MMP order, otherwise `false`.", "type": "boolean" }, "mmp_cancelled": { "description": "`true` if order was cancelled by mmp trigger (optional)", "example": true, "type": "boolean" }, "mmp_group": { "description": "Name of the MMP group supplied in the `private/mass_quote` request. Only present for quote orders.", "type": "string" }, "mobile": { "description": "Optional field with value `true` added only when created with Mobile Application", "type": "boolean" }, "oco_ref": { "description": "Unique reference that identifies a one_cancels_others (OCO) pair.", "type": "string" }, "order_id": { "description": "Unique order identifier", "example": "ETH-100234", "type": "string" }, "order_state": { "description": "Order state: `\"open\"`, `\"filled\"`, `\"rejected\"`, `\"cancelled\"`, `\"untriggered\"`", "enum": [ "cancelled", "filled", "open", "rejected", "triggered", "untriggered" ], "type": "string" }, "order_type": { "description": "Order type: `\"limit\"`, `\"market\"`, `\"stop_limit\"`, `\"stop_market\"`, `\"take_limit\"`, `\"take_market\"`, `\"trailing_stop\"`", "enum": [ "limit", "market", "stop_limit", "stop_market", "take_limit", "take_market", "trailing_stop" ], "type": "string" }, "original_order_type": { "description": "Original API order type when an order is represented internally as a limit order. For example, Starbase market orders use `\"limit\"` as `order_type` with `\"market\"` in this optional field.", "enum": [ "market", "market_limit" ], "type": "string" }, "oto_order_ids": { "additionalProperties": true, "description": "The Ids of the orders that will be triggered if the order is filled", "properties": {}, "type": "object" }, "post_only": { "description": "`true` for post-only orders only", "type": "boolean" }, "price": { "description": "Price in base currency or \"market_price\" in case of open trigger market orders" }, "primary_order_id": { "description": "Unique order identifier", "example": "ETH-100234", "type": "string" }, "quote": { "description": "If order is a quote. Present only if true.", "type": "boolean" }, "quote_id": { "description": "The same QuoteID as supplied in the `private/mass_quote` request. Only present for quote orders.", "type": "string" }, "quote_set_id": { "description": "Identifier of the QuoteSet supplied in the `private/mass_quote` request. Only present for quote orders.", "type": "string" }, "reduce_only": { "description": "Optional (not added for spot). '`true` for reduce-only orders only'", "type": "boolean" }, "refresh_amount": { "description": "The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders", "type": "number" }, "reject_post_only": { "description": "`true` if order has `reject_post_only` flag (field is present only when `post_only` is `true`)", "type": "boolean" }, "replaced": { "description": "`true` if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise `false`.", "type": "boolean" }, "risk_reducing": { "description": "`true` if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise `false`.", "type": "boolean" }, "starbase_client_order_id": { "description": "Client order id of an order submitted directly to [Starbase](https://docs.deribit.com/starbase/overview) via direct access; not returned for orders placed through the Deribit API (combo legs inherit the parent combo order's client order id)", "type": "string" }, "starbase_last_update_timestamp": { "description": "The Starbase causal timestamp (nanoseconds since the Unix epoch) of the last book update that affected this order. Present only for orders placed in Starbase, including combo leg order updates; not always available for direct access orders", "example": 1536569522277000000, "type": "integer" }, "starbase_order_id": { "description": "Raw Starbase order id, in Starbase's own (non currency-prefixed) id namespace. Only present for orders placed in Starbase. Combo leg orders expose the parent combo order's Starbase order id.", "example": 103148386170, "type": "integer" }, "time_in_force": { "description": "Order time in force: `\"good_til_cancelled\"`, `\"good_til_day\"`, `\"fill_or_kill\"` or `\"immediate_or_cancel\"`", "enum": [ "fill_or_kill", "good_til_cancelled", "good_til_day", "immediate_or_cancel" ], "type": "string" }, "trigger": { "description": "Trigger type (only for trigger orders). Allowed values: `\"index_price\"`, `\"mark_price\"`, `\"last_price\"`.", "enum": [ "index_price", "last_price", "mark_price" ], "type": "string" }, "trigger_fill_condition": { "description": "

The fill condition of the linked order (Only for linked order types), default: `first_hit`.

", "enum": [ "complete_fill", "first_hit", "incremental" ], "type": "string" }, "trigger_offset": { "description": "The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)", "type": "number" }, "trigger_order_id": { "description": "Id of the trigger order that created the order (Only for orders that were created by triggered orders).", "example": "SLIB-370", "type": "string" }, "trigger_price": { "description": "Trigger price (Only for future trigger orders)", "type": "number" }, "trigger_reference_price": { "description": "The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)", "type": "number" }, "triggered": { "description": "Whether the trigger order has been triggered", "type": "boolean" }, "usd": { "description": "Option price in USD (Only if `advanced=\"usd\"`)", "type": "number" }, "web": { "description": "`true` if created via Deribit frontend (optional)", "type": "boolean" } }, "required": [ "api", "creation_timestamp", "direction", "instrument_name", "label", "last_update_timestamp", "order_id", "order_state", "order_type", "post_only", "price", "time_in_force" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "instrument_name": { "description": "The name of the instrument" }, "interval": { "description": "Frequency of notifications. Events will be aggregated over this interval. The value `raw` selects the finest granularity - events are aggregated over a 1 millisecond interval **(Please note that `raw` interval is only available to authorized users)**\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] } }, "servers": [ { "$ref": "#/servers/private" } ], "summary": "User order updates for a specific instrument (aggregated).\n\nUse this channel to receive private order updates for the given instrument, aggregated according to `interval`.\n", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Orders" } ], "title": "user.orders.(instrument_name).(interval) " }, "user.orders.(instrument_name).raw": { "address": "user.orders.{instrument_name}.raw", "description": "User order updates for a specific instrument (raw stream).\n\nUse this channel to receive private order updates for the given instrument with the highest granularity (raw). Prefer this for real-time order state tracking.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to user channel. Channel name format: `user.orders.(instrument_name).raw`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.orders.BTC-PERPETUAL.raw" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.orders.BTC-PERPETUAL.raw" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.orders.(instrument_name).raw` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "amount": 200, "api": false, "average_price": 0, "creation_timestamp": 1581507423789, "direction": "buy", "filled_amount": 0, "instrument_name": "BTC-PERPETUAL", "is_liquidation": false, "is_rebalance": false, "label": "", "last_update_timestamp": 1581507423789, "max_show": 200, "order_id": "5", "order_state": "open", "order_type": "limit", "original_order_type": "market", "post_only": false, "price": 10502.52, "reduce_only": false, "replaced": false, "time_in_force": "good_til_cancelled" } }, "summary": "Repeated notification example" } ], "name": "user_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "advanced": { "description": "advanced type: `\"usd\"` or `\"implv\"` (Only for options; field is omitted if not applicable).\n", "enum": [ "implv", "usd" ], "type": "string" }, "amount": { "description": "It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.", "type": "number" }, "api": { "description": "`true` if created with API", "type": "boolean" }, "app_name": { "description": "The name of the application that placed the order on behalf of the user (optional).", "example": "Example Application", "type": "string" }, "auto_replaced": { "description": "Options, advanced orders only - `true` if last modification of the order was performed by the pricing engine, otherwise `false`.", "type": "boolean" }, "average_price": { "description": "Average fill price of the order", "type": "number" }, "block_trade": { "description": "`true` if order made from block_trade trade, added only in that case.", "example": true, "type": "boolean" }, "cancel_reason": { "description": "Enumerated reason behind cancel `\"user_request\"`, `\"autoliquidation\"`, `\"cancel_on_disconnect\"`, `\"risk_mitigation\"`, `\"pme_risk_reduction\"` (portfolio margining risk reduction), `\"pme_account_locked\"` (portfolio margining account locked per currency), `\"position_locked\"`, `\"mmp_trigger\"` (market maker protection), `\"mmp_config_curtailment\"` (market maker configured quantity decreased), `\"edit_post_only_reject\"` (cancelled on edit because of `reject_post_only` setting), `\"oco_other_closed\"` (the oco order linked to this order was closed), `\"oto_primary_closed\"` (the oto primary order that was going to trigger this order was cancelled), `\"settlement\"` (closed because of a settlement event, e.g. good-til-day orders are cancelled when an instrument enters the daily settlement). Note: orders cancelled because an instrument expired (delivery) currently do not include a `cancel_reason` field.", "enum": [ "autoliquidation", "cancel_on_disconnect", "edit_post_only_reject", "mmp_config_curtailment", "mmp_trigger", "oco_other_closed", "oto_primary_closed", "pme_account_locked", "pme_risk_reduction", "position_locked", "risk_mitigation", "settlement", "user_request" ], "type": "string" }, "combo_order_id": { "description": "Id of the combo order that created this order (only present for orders that were created as legs of a combo order).", "example": "103148386169", "type": "string" }, "contracts": { "description": "It represents the order size in contract units. (Optional, may be absent in historical data).", "type": "number" }, "creation_timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" }, "direction": { "description": "Direction: `buy`, or `sell`", "enum": [ "buy", "sell" ], "type": "string" }, "display_amount": { "description": "The actual display amount of iceberg order. Absent for other types of orders.", "type": "number" }, "filled_amount": { "description": "Filled amount of the order. For perpetual and futures the filled_amount is in USD units, for options - in units or corresponding cryptocurrency contracts, e.g., BTC or ETH.", "type": "number" }, "implv": { "description": "Implied volatility in percent. (Only if `advanced=\"implv\"`)", "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "is_liquidation": { "description": "Optional (not added for spot). `true` if order was automatically created during liquidation", "type": "boolean" }, "is_primary_otoco": { "description": "`true` if the order is an order that can trigger an OCO pair, otherwise not present.", "type": "boolean" }, "is_rebalance": { "description": "Optional (only for spot). `true` if order was automatically created during cross-collateral balance restoration", "type": "boolean" }, "is_secondary_oto": { "description": "`true` if the order is an order that can be triggered by another order, otherwise not present.", "type": "boolean" }, "label": { "description": "User defined label (up to 64 characters)", "type": "string" }, "last_update_timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" }, "mmp": { "description": "`true` if the order is a MMP order, otherwise `false`.", "type": "boolean" }, "mmp_cancelled": { "description": "`true` if order was cancelled by mmp trigger (optional)", "example": true, "type": "boolean" }, "mmp_group": { "description": "Name of the MMP group supplied in the `private/mass_quote` request. Only present for quote orders.", "type": "string" }, "mobile": { "description": "Optional field with value `true` added only when created with Mobile Application", "type": "boolean" }, "oco_ref": { "description": "Unique reference that identifies a one_cancels_others (OCO) pair.", "type": "string" }, "order_id": { "description": "Unique order identifier", "example": "ETH-100234", "type": "string" }, "order_state": { "description": "Order state: `\"open\"`, `\"filled\"`, `\"rejected\"`, `\"cancelled\"`, `\"untriggered\"`", "enum": [ "cancelled", "filled", "open", "rejected", "triggered", "untriggered" ], "type": "string" }, "order_type": { "description": "Order type: `\"limit\"`, `\"market\"`, `\"stop_limit\"`, `\"stop_market\"`, `\"take_limit\"`, `\"take_market\"`, `\"trailing_stop\"`", "enum": [ "limit", "market", "stop_limit", "stop_market", "take_limit", "take_market", "trailing_stop" ], "type": "string" }, "original_order_type": { "description": "Original API order type when an order is represented internally as a limit order. For example, Starbase market orders use `\"limit\"` as `order_type` with `\"market\"` in this optional field.", "enum": [ "market", "market_limit" ], "type": "string" }, "oto_order_ids": { "additionalProperties": true, "description": "The Ids of the orders that will be triggered if the order is filled", "properties": {}, "type": "object" }, "post_only": { "description": "`true` for post-only orders only", "type": "boolean" }, "price": { "description": "Price in base currency or \"market_price\" in case of open trigger market orders" }, "primary_order_id": { "description": "Unique order identifier", "example": "ETH-100234", "type": "string" }, "quote": { "description": "If order is a quote. Present only if true.", "type": "boolean" }, "quote_id": { "description": "The same QuoteID as supplied in the `private/mass_quote` request. Only present for quote orders.", "type": "string" }, "quote_set_id": { "description": "Identifier of the QuoteSet supplied in the `private/mass_quote` request. Only present for quote orders.", "type": "string" }, "reduce_only": { "description": "Optional (not added for spot). '`true` for reduce-only orders only'", "type": "boolean" }, "refresh_amount": { "description": "The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders", "type": "number" }, "reject_post_only": { "description": "`true` if order has `reject_post_only` flag (field is present only when `post_only` is `true`)", "type": "boolean" }, "replaced": { "description": "`true` if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise `false`.", "type": "boolean" }, "risk_reducing": { "description": "`true` if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise `false`.", "type": "boolean" }, "starbase_client_order_id": { "description": "Client order id of an order submitted directly to [Starbase](https://docs.deribit.com/starbase/overview) via direct access; not returned for orders placed through the Deribit API (combo legs inherit the parent combo order's client order id)", "type": "string" }, "starbase_last_update_timestamp": { "description": "The Starbase causal timestamp (nanoseconds since the Unix epoch) of the last book update that affected this order. Present only for orders placed in Starbase, including combo leg order updates; not always available for direct access orders", "example": 1536569522277000000, "type": "integer" }, "starbase_order_id": { "description": "Raw Starbase order id, in Starbase's own (non currency-prefixed) id namespace. Only present for orders placed in Starbase. Combo leg orders expose the parent combo order's Starbase order id.", "example": 103148386170, "type": "integer" }, "time_in_force": { "description": "Order time in force: `\"good_til_cancelled\"`, `\"good_til_day\"`, `\"fill_or_kill\"` or `\"immediate_or_cancel\"`", "enum": [ "fill_or_kill", "good_til_cancelled", "good_til_day", "immediate_or_cancel" ], "type": "string" }, "trigger": { "description": "Trigger type (only for trigger orders). Allowed values: `\"index_price\"`, `\"mark_price\"`, `\"last_price\"`.", "enum": [ "index_price", "last_price", "mark_price" ], "type": "string" }, "trigger_fill_condition": { "description": "

The fill condition of the linked order (Only for linked order types), default: `first_hit`.

", "enum": [ "complete_fill", "first_hit", "incremental" ], "type": "string" }, "trigger_offset": { "description": "The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)", "type": "number" }, "trigger_order_id": { "description": "Id of the trigger order that created the order (Only for orders that were created by triggered orders).", "example": "SLIB-370", "type": "string" }, "trigger_price": { "description": "Trigger price (Only for future trigger orders)", "type": "number" }, "trigger_reference_price": { "description": "The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)", "type": "number" }, "triggered": { "description": "Whether the trigger order has been triggered", "type": "boolean" }, "usd": { "description": "Option price in USD (Only if `advanced=\"usd\"`)", "type": "number" }, "web": { "description": "`true` if created via Deribit frontend (optional)", "type": "boolean" } }, "required": [ "api", "creation_timestamp", "direction", "instrument_name", "label", "last_update_timestamp", "order_id", "order_state", "order_type", "post_only", "price", "time_in_force" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "instrument_name": { "description": "The name of the instrument" } }, "servers": [ { "$ref": "#/servers/private" } ], "summary": "User order updates for a specific instrument (raw stream).\n\nUse this channel to receive private order updates for the given instrument with the highest granularity (raw). Prefer this for real-time order state tracking.\n", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Orders" } ], "title": "user.orders.(instrument_name).raw " }, "user.orders.(kind).(currency).(interval)": { "address": "user.orders.{kind}.{currency}.{interval}", "description": "User order updates across all instruments for a given kind and currency (aggregated).\n\nUse this channel to receive private order updates across all matching instruments, aggregated according to `interval`.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to user channel. Channel name format: `user.orders.(kind).(currency).(interval)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.orders.future.USDC.100ms" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.orders.future.USDC.100ms" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.orders.(kind).(currency).(interval)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": [ { "amount": 120, "api": false, "average_price": 0, "creation_timestamp": 1550826337209, "direction": "buy", "filled_amount": 0, "instrument_name": "BTC-PERPETUAL", "is_liquidation": false, "is_rebalance": false, "label": "", "last_update_timestamp": 1550826337209, "max_show": 120, "order_id": "476137", "order_state": "open", "order_type": "limit", "post_only": false, "price": 3928.5, "reduce_only": false, "time_in_force": "good_til_cancelled" } ] }, "summary": "Repeated notification example" } ], "name": "user_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "description": "", "properties": { "advanced": { "description": "advanced type: `\"usd\"` or `\"implv\"` (Only for options; field is omitted if not applicable).\n", "enum": [ "implv", "usd" ], "type": "string" }, "amount": { "description": "It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.", "type": "number" }, "api": { "description": "`true` if created with API", "type": "boolean" }, "app_name": { "description": "The name of the application that placed the order on behalf of the user (optional).", "example": "Example Application", "type": "string" }, "auto_replaced": { "description": "Options, advanced orders only - `true` if last modification of the order was performed by the pricing engine, otherwise `false`.", "type": "boolean" }, "average_price": { "description": "Average fill price of the order", "type": "number" }, "block_trade": { "description": "`true` if order made from block_trade trade, added only in that case.", "example": true, "type": "boolean" }, "cancel_reason": { "description": "Enumerated reason behind cancel `\"user_request\"`, `\"autoliquidation\"`, `\"cancel_on_disconnect\"`, `\"risk_mitigation\"`, `\"pme_risk_reduction\"` (portfolio margining risk reduction), `\"pme_account_locked\"` (portfolio margining account locked per currency), `\"position_locked\"`, `\"mmp_trigger\"` (market maker protection), `\"mmp_config_curtailment\"` (market maker configured quantity decreased), `\"edit_post_only_reject\"` (cancelled on edit because of `reject_post_only` setting), `\"oco_other_closed\"` (the oco order linked to this order was closed), `\"oto_primary_closed\"` (the oto primary order that was going to trigger this order was cancelled), `\"settlement\"` (closed because of a settlement event, e.g. good-til-day orders are cancelled when an instrument enters the daily settlement). Note: orders cancelled because an instrument expired (delivery) currently do not include a `cancel_reason` field.", "enum": [ "autoliquidation", "cancel_on_disconnect", "edit_post_only_reject", "mmp_config_curtailment", "mmp_trigger", "oco_other_closed", "oto_primary_closed", "pme_account_locked", "pme_risk_reduction", "position_locked", "risk_mitigation", "settlement", "user_request" ], "type": "string" }, "combo_order_id": { "description": "Id of the combo order that created this order (only present for orders that were created as legs of a combo order).", "example": "103148386169", "type": "string" }, "contracts": { "description": "It represents the order size in contract units. (Optional, may be absent in historical data).", "type": "number" }, "creation_timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" }, "direction": { "description": "Direction: `buy`, or `sell`", "enum": [ "buy", "sell" ], "type": "string" }, "display_amount": { "description": "The actual display amount of iceberg order. Absent for other types of orders.", "type": "number" }, "filled_amount": { "description": "Filled amount of the order. For perpetual and futures the filled_amount is in USD units, for options - in units or corresponding cryptocurrency contracts, e.g., BTC or ETH.", "type": "number" }, "implv": { "description": "Implied volatility in percent. (Only if `advanced=\"implv\"`)", "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "is_liquidation": { "description": "Optional (not added for spot). `true` if order was automatically created during liquidation", "type": "boolean" }, "is_primary_otoco": { "description": "`true` if the order is an order that can trigger an OCO pair, otherwise not present.", "type": "boolean" }, "is_rebalance": { "description": "Optional (only for spot). `true` if order was automatically created during cross-collateral balance restoration", "type": "boolean" }, "is_secondary_oto": { "description": "`true` if the order is an order that can be triggered by another order, otherwise not present.", "type": "boolean" }, "label": { "description": "User defined label (up to 64 characters)", "type": "string" }, "last_update_timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" }, "mmp": { "description": "`true` if the order is a MMP order, otherwise `false`.", "type": "boolean" }, "mmp_cancelled": { "description": "`true` if order was cancelled by mmp trigger (optional)", "example": true, "type": "boolean" }, "mmp_group": { "description": "Name of the MMP group supplied in the `private/mass_quote` request. Only present for quote orders.", "type": "string" }, "mobile": { "description": "Optional field with value `true` added only when created with Mobile Application", "type": "boolean" }, "oco_ref": { "description": "Unique reference that identifies a one_cancels_others (OCO) pair.", "type": "string" }, "order_id": { "description": "Unique order identifier", "example": "ETH-100234", "type": "string" }, "order_state": { "description": "Order state: `\"open\"`, `\"filled\"`, `\"rejected\"`, `\"cancelled\"`, `\"untriggered\"`", "enum": [ "cancelled", "filled", "open", "rejected", "triggered", "untriggered" ], "type": "string" }, "order_type": { "description": "Order type: `\"limit\"`, `\"market\"`, `\"stop_limit\"`, `\"stop_market\"`, `\"take_limit\"`, `\"take_market\"`, `\"trailing_stop\"`", "enum": [ "limit", "market", "stop_limit", "stop_market", "take_limit", "take_market", "trailing_stop" ], "type": "string" }, "original_order_type": { "description": "Original API order type when an order is represented internally as a limit order. For example, Starbase market orders use `\"limit\"` as `order_type` with `\"market\"` in this optional field.", "enum": [ "market", "market_limit" ], "type": "string" }, "oto_order_ids": { "additionalProperties": true, "description": "The Ids of the orders that will be triggered if the order is filled", "properties": {}, "type": "object" }, "post_only": { "description": "`true` for post-only orders only", "type": "boolean" }, "price": { "description": "Price in base currency or \"market_price\" in case of open trigger market orders" }, "primary_order_id": { "description": "Unique order identifier", "example": "ETH-100234", "type": "string" }, "quote": { "description": "If order is a quote. Present only if true.", "type": "boolean" }, "quote_id": { "description": "The same QuoteID as supplied in the `private/mass_quote` request. Only present for quote orders.", "type": "string" }, "quote_set_id": { "description": "Identifier of the QuoteSet supplied in the `private/mass_quote` request. Only present for quote orders.", "type": "string" }, "reduce_only": { "description": "Optional (not added for spot). '`true` for reduce-only orders only'", "type": "boolean" }, "refresh_amount": { "description": "The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders", "type": "number" }, "reject_post_only": { "description": "`true` if order has `reject_post_only` flag (field is present only when `post_only` is `true`)", "type": "boolean" }, "replaced": { "description": "`true` if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise `false`.", "type": "boolean" }, "risk_reducing": { "description": "`true` if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise `false`.", "type": "boolean" }, "starbase_client_order_id": { "description": "Client order id of an order submitted directly to [Starbase](https://docs.deribit.com/starbase/overview) via direct access; not returned for orders placed through the Deribit API (combo legs inherit the parent combo order's client order id)", "type": "string" }, "starbase_last_update_timestamp": { "description": "The Starbase causal timestamp (nanoseconds since the Unix epoch) of the last book update that affected this order. Present only for orders placed in Starbase, including combo leg order updates; not always available for direct access orders", "example": 1536569522277000000, "type": "integer" }, "starbase_order_id": { "description": "Raw Starbase order id, in Starbase's own (non currency-prefixed) id namespace. Only present for orders placed in Starbase. Combo leg orders expose the parent combo order's Starbase order id.", "example": 103148386170, "type": "integer" }, "time_in_force": { "description": "Order time in force: `\"good_til_cancelled\"`, `\"good_til_day\"`, `\"fill_or_kill\"` or `\"immediate_or_cancel\"`", "enum": [ "fill_or_kill", "good_til_cancelled", "good_til_day", "immediate_or_cancel" ], "type": "string" }, "trigger": { "description": "Trigger type (only for trigger orders). Allowed values: `\"index_price\"`, `\"mark_price\"`, `\"last_price\"`.", "enum": [ "index_price", "last_price", "mark_price" ], "type": "string" }, "trigger_fill_condition": { "description": "

The fill condition of the linked order (Only for linked order types), default: `first_hit`.

", "enum": [ "complete_fill", "first_hit", "incremental" ], "type": "string" }, "trigger_offset": { "description": "The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)", "type": "number" }, "trigger_order_id": { "description": "Id of the trigger order that created the order (Only for orders that were created by triggered orders).", "example": "SLIB-370", "type": "string" }, "trigger_price": { "description": "Trigger price (Only for future trigger orders)", "type": "number" }, "trigger_reference_price": { "description": "The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)", "type": "number" }, "triggered": { "description": "Whether the trigger order has been triggered", "type": "boolean" }, "usd": { "description": "Option price in USD (Only if `advanced=\"usd\"`)", "type": "number" }, "web": { "description": "`true` if created via Deribit frontend (optional)", "type": "boolean" } }, "required": [ "api", "creation_timestamp", "direction", "instrument_name", "label", "last_update_timestamp", "order_id", "order_state", "order_type", "post_only", "price", "time_in_force" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "currency": { "description": "Currency code or `any` for all\n\n**Allowed values:** `BTC`, `ETH`, `USDC`, `USDT`, `EURR`, `any`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT", "any" ] }, "interval": { "description": "Frequency of notifications. Events will be aggregated over this interval. The value `raw` selects the finest granularity - events are aggregated over a 1 millisecond interval **(Please note that `raw` interval is only available to authorized users)**\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] }, "kind": { "description": "Instrument kind\n\n**Allowed values:** `future`, `option`, `spot`, `future_combo`, `option_combo`", "enum": [ "future", "future_combo", "option", "option_combo", "spot" ] } }, "servers": [ { "$ref": "#/servers/private" } ], "summary": "User order updates across all instruments for a given kind and currency (aggregated).\n\nUse this channel to receive private order updates across all matching instruments, aggregated according to `interval`.\n", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Orders" } ], "title": "user.orders.(kind).(currency).(interval) " }, "user.orders.(kind).(currency).raw": { "address": "user.orders.{kind}.{currency}.raw", "description": "User order updates across all instruments for a given kind and currency (raw stream).\n\nUse this channel to receive private order updates across all matching instruments with the highest granularity (raw).\n", "messages": { "subscribe_request": { "description": "Request to subscribe to user channel. Channel name format: `user.orders.(kind).(currency).raw`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.orders.future.USDC.raw" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.orders.future.USDC.raw" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.orders.(kind).(currency).raw` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "amount": 200, "api": false, "average_price": 0, "creation_timestamp": 1581507583024, "direction": "buy", "filled_amount": 0, "instrument_name": "BTC-PERPETUAL", "is_liquidation": false, "is_rebalance": false, "label": "", "last_update_timestamp": 1581507583024, "max_show": 200, "order_id": "6", "order_state": "open", "order_type": "limit", "original_order_type": "market", "post_only": false, "price": 10542.68, "reduce_only": false, "replaced": false, "time_in_force": "good_til_cancelled" } }, "summary": "Repeated notification example" } ], "name": "user_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "advanced": { "description": "advanced type: `\"usd\"` or `\"implv\"` (Only for options; field is omitted if not applicable).\n", "enum": [ "implv", "usd" ], "type": "string" }, "amount": { "description": "It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.", "type": "number" }, "api": { "description": "`true` if created with API", "type": "boolean" }, "app_name": { "description": "The name of the application that placed the order on behalf of the user (optional).", "example": "Example Application", "type": "string" }, "auto_replaced": { "description": "Options, advanced orders only - `true` if last modification of the order was performed by the pricing engine, otherwise `false`.", "type": "boolean" }, "average_price": { "description": "Average fill price of the order", "type": "number" }, "block_trade": { "description": "`true` if order made from block_trade trade, added only in that case.", "example": true, "type": "boolean" }, "cancel_reason": { "description": "Enumerated reason behind cancel `\"user_request\"`, `\"autoliquidation\"`, `\"cancel_on_disconnect\"`, `\"risk_mitigation\"`, `\"pme_risk_reduction\"` (portfolio margining risk reduction), `\"pme_account_locked\"` (portfolio margining account locked per currency), `\"position_locked\"`, `\"mmp_trigger\"` (market maker protection), `\"mmp_config_curtailment\"` (market maker configured quantity decreased), `\"edit_post_only_reject\"` (cancelled on edit because of `reject_post_only` setting), `\"oco_other_closed\"` (the oco order linked to this order was closed), `\"oto_primary_closed\"` (the oto primary order that was going to trigger this order was cancelled), `\"settlement\"` (closed because of a settlement event, e.g. good-til-day orders are cancelled when an instrument enters the daily settlement). Note: orders cancelled because an instrument expired (delivery) currently do not include a `cancel_reason` field.", "enum": [ "autoliquidation", "cancel_on_disconnect", "edit_post_only_reject", "mmp_config_curtailment", "mmp_trigger", "oco_other_closed", "oto_primary_closed", "pme_account_locked", "pme_risk_reduction", "position_locked", "risk_mitigation", "settlement", "user_request" ], "type": "string" }, "combo_order_id": { "description": "Id of the combo order that created this order (only present for orders that were created as legs of a combo order).", "example": "103148386169", "type": "string" }, "contracts": { "description": "It represents the order size in contract units. (Optional, may be absent in historical data).", "type": "number" }, "creation_timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" }, "direction": { "description": "Direction: `buy`, or `sell`", "enum": [ "buy", "sell" ], "type": "string" }, "display_amount": { "description": "The actual display amount of iceberg order. Absent for other types of orders.", "type": "number" }, "filled_amount": { "description": "Filled amount of the order. For perpetual and futures the filled_amount is in USD units, for options - in units or corresponding cryptocurrency contracts, e.g., BTC or ETH.", "type": "number" }, "implv": { "description": "Implied volatility in percent. (Only if `advanced=\"implv\"`)", "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "is_liquidation": { "description": "Optional (not added for spot). `true` if order was automatically created during liquidation", "type": "boolean" }, "is_primary_otoco": { "description": "`true` if the order is an order that can trigger an OCO pair, otherwise not present.", "type": "boolean" }, "is_rebalance": { "description": "Optional (only for spot). `true` if order was automatically created during cross-collateral balance restoration", "type": "boolean" }, "is_secondary_oto": { "description": "`true` if the order is an order that can be triggered by another order, otherwise not present.", "type": "boolean" }, "label": { "description": "User defined label (up to 64 characters)", "type": "string" }, "last_update_timestamp": { "description": "The timestamp (milliseconds since the Unix epoch)", "example": 1536569522277, "type": "integer" }, "mmp": { "description": "`true` if the order is a MMP order, otherwise `false`.", "type": "boolean" }, "mmp_cancelled": { "description": "`true` if order was cancelled by mmp trigger (optional)", "example": true, "type": "boolean" }, "mmp_group": { "description": "Name of the MMP group supplied in the `private/mass_quote` request. Only present for quote orders.", "type": "string" }, "mobile": { "description": "Optional field with value `true` added only when created with Mobile Application", "type": "boolean" }, "oco_ref": { "description": "Unique reference that identifies a one_cancels_others (OCO) pair.", "type": "string" }, "order_id": { "description": "Unique order identifier", "example": "ETH-100234", "type": "string" }, "order_state": { "description": "Order state: `\"open\"`, `\"filled\"`, `\"rejected\"`, `\"cancelled\"`, `\"untriggered\"`", "enum": [ "cancelled", "filled", "open", "rejected", "triggered", "untriggered" ], "type": "string" }, "order_type": { "description": "Order type: `\"limit\"`, `\"market\"`, `\"stop_limit\"`, `\"stop_market\"`, `\"take_limit\"`, `\"take_market\"`, `\"trailing_stop\"`", "enum": [ "limit", "market", "stop_limit", "stop_market", "take_limit", "take_market", "trailing_stop" ], "type": "string" }, "original_order_type": { "description": "Original API order type when an order is represented internally as a limit order. For example, Starbase market orders use `\"limit\"` as `order_type` with `\"market\"` in this optional field.", "enum": [ "market", "market_limit" ], "type": "string" }, "oto_order_ids": { "additionalProperties": true, "description": "The Ids of the orders that will be triggered if the order is filled", "properties": {}, "type": "object" }, "post_only": { "description": "`true` for post-only orders only", "type": "boolean" }, "price": { "description": "Price in base currency or \"market_price\" in case of open trigger market orders" }, "primary_order_id": { "description": "Unique order identifier", "example": "ETH-100234", "type": "string" }, "quote": { "description": "If order is a quote. Present only if true.", "type": "boolean" }, "quote_id": { "description": "The same QuoteID as supplied in the `private/mass_quote` request. Only present for quote orders.", "type": "string" }, "quote_set_id": { "description": "Identifier of the QuoteSet supplied in the `private/mass_quote` request. Only present for quote orders.", "type": "string" }, "reduce_only": { "description": "Optional (not added for spot). '`true` for reduce-only orders only'", "type": "boolean" }, "refresh_amount": { "description": "The initial display amount of iceberg order. Iceberg order display amount will be refreshed to that value after match consuming actual display amount. Absent for other types of orders", "type": "number" }, "reject_post_only": { "description": "`true` if order has `reject_post_only` flag (field is present only when `post_only` is `true`)", "type": "boolean" }, "replaced": { "description": "`true` if the order was edited (by user or - in case of advanced options orders - by pricing engine), otherwise `false`.", "type": "boolean" }, "risk_reducing": { "description": "`true` if the order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users), otherwise `false`.", "type": "boolean" }, "starbase_client_order_id": { "description": "Client order id of an order submitted directly to [Starbase](https://docs.deribit.com/starbase/overview) via direct access; not returned for orders placed through the Deribit API (combo legs inherit the parent combo order's client order id)", "type": "string" }, "starbase_last_update_timestamp": { "description": "The Starbase causal timestamp (nanoseconds since the Unix epoch) of the last book update that affected this order. Present only for orders placed in Starbase, including combo leg order updates; not always available for direct access orders", "example": 1536569522277000000, "type": "integer" }, "starbase_order_id": { "description": "Raw Starbase order id, in Starbase's own (non currency-prefixed) id namespace. Only present for orders placed in Starbase. Combo leg orders expose the parent combo order's Starbase order id.", "example": 103148386170, "type": "integer" }, "time_in_force": { "description": "Order time in force: `\"good_til_cancelled\"`, `\"good_til_day\"`, `\"fill_or_kill\"` or `\"immediate_or_cancel\"`", "enum": [ "fill_or_kill", "good_til_cancelled", "good_til_day", "immediate_or_cancel" ], "type": "string" }, "trigger": { "description": "Trigger type (only for trigger orders). Allowed values: `\"index_price\"`, `\"mark_price\"`, `\"last_price\"`.", "enum": [ "index_price", "last_price", "mark_price" ], "type": "string" }, "trigger_fill_condition": { "description": "

The fill condition of the linked order (Only for linked order types), default: `first_hit`.

", "enum": [ "complete_fill", "first_hit", "incremental" ], "type": "string" }, "trigger_offset": { "description": "The maximum deviation from the price peak beyond which the order will be triggered (Only for trailing trigger orders)", "type": "number" }, "trigger_order_id": { "description": "Id of the trigger order that created the order (Only for orders that were created by triggered orders).", "example": "SLIB-370", "type": "string" }, "trigger_price": { "description": "Trigger price (Only for future trigger orders)", "type": "number" }, "trigger_reference_price": { "description": "The price of the given trigger at the time when the order was placed (Only for trailing trigger orders)", "type": "number" }, "triggered": { "description": "Whether the trigger order has been triggered", "type": "boolean" }, "usd": { "description": "Option price in USD (Only if `advanced=\"usd\"`)", "type": "number" }, "web": { "description": "`true` if created via Deribit frontend (optional)", "type": "boolean" } }, "required": [ "api", "creation_timestamp", "direction", "instrument_name", "label", "last_update_timestamp", "order_id", "order_state", "order_type", "post_only", "price", "time_in_force" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "currency": { "description": "Currency code or `any` for all\n\n**Allowed values:** `BTC`, `ETH`, `USDC`, `USDT`, `EURR`, `any`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT", "any" ] }, "kind": { "description": "Instrument kind\n\n**Allowed values:** `future`, `option`, `spot`, `future_combo`, `option_combo`", "enum": [ "future", "future_combo", "option", "option_combo", "spot" ] } }, "servers": [ { "$ref": "#/servers/private" } ], "summary": "User order updates across all instruments for a given kind and currency (raw stream).\n\nUse this channel to receive private order updates across all matching instruments with the highest granularity (raw).\n", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Orders" } ], "title": "user.orders.(kind).(currency).raw " }, "user.portfolio.(currency)": { "address": "user.portfolio.{currency}", "description": "Real-time notifications for user portfolio information. This subscription provides comprehensive account and portfolio data for the specified currency, including balances, margins, profit and loss, and Greeks.\n\nEach notification includes:\n\n- **Account balances:** Current balance, equity, margin balance, available funds, and available withdrawal funds\n- **Margin information:** Initial margin, maintenance margin, and projected margins\n- **Profit and Loss:** Total P&L, session unrealized P&L (UPL), session realized P&L (RPL), and separate P&L for options and futures\n- **Options Greeks:** Delta, gamma, theta, vega, and options value, with per-index mappings\n- **Position data:** Delta total, projected delta total, and delta total map per index\n- **Account settings:** Portfolio margining status, cross collateral status, and margin model\n- **Cross collateral data:** Total equity, margins, and delta in USD (when cross collateral is enabled)\n- **Additional reserves:** Fee balance and additional reserve information\n\nWhen cross collateral is enabled, aggregated values are calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.\n\nSubscribe to a specific currency (BTC, ETH, USDC, USDT, etc.) or use `any` to receive portfolio updates for all currencies.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to user channel. Channel name format: `user.portfolio.(currency)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.portfolio.USDC" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.portfolio.USDC" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.portfolio.(currency)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": { "additional_reserve": 0, "available_funds": 301.38036328, "available_withdrawal_funds": 301.35426172, "balance": 302.60065765, "cross_collateral_enabled": false, "currency": "BTC", "delta_total": 31.602298, "delta_total_map": { "btc_usd": 31.594397699 }, "equity": 302.6188592, "fee_balance": 0, "futures_pl": -0.32434225, "futures_session_rpl": -0.03311399, "futures_session_upl": 0.05921555, "initial_margin": 1.24639592, "maintenance_margin": 0.8854841, "margin_balance": 302.62675921, "margin_model": "segregated_sm", "options_delta": -1.01958, "options_gamma": 0.00001, "options_gamma_map": { "btc_usd": 0.00001 }, "options_pl": -0.0058, "options_session_rpl": 0, "options_session_upl": -0.0058, "options_theta": 16.13825, "options_theta_map": { "btc_usd": 16.13825 }, "options_value": -0.0079, "options_vega": 0.07976, "options_vega_map": { "btc_usd": 0.07976 }, "portfolio_margining_enabled": false, "projected_delta_total": 32.613978, "projected_initial_margin": 1.01529592, "projected_maintenance_margin": 0.7543841, "session_rpl": -0.03311399, "session_upl": 0.05341555, "spot_reserve": 0, "total_pl": -0.33014225 } }, "summary": "Repeated notification example" } ], "name": "user_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "additional_reserve": { "description": "The account's balance reserved for open buy option orders and option combo orders (the premium payable if they fill). Only non-zero on the `cross_sm` margin model; balance reserved by spot orders is reported separately in `spot_reserve`.", "example": 0.3, "type": "number" }, "available_funds": { "description": "Funds available to increase margin usage (open or enlarge positions). Equal to `margin_balance - initial_margin`, floored at `0` in the API response. When initial margin usage exceeds 100%, this is `0` and only reducing orders can be placed. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.", "example": 2.2638913, "type": "number" }, "available_withdrawal_funds": { "description": "Funds available to withdraw in the selected currency. Typically lower than `available_funds` because withdrawals also exclude positive session profit, locked balance, `spot_reserve`, `additional_reserve`, and non-withdrawable external/implied equity components. Always ≥ `0`.", "example": 2.26, "type": "number" }, "balance": { "description": "The account's cash balance in the selected currency (deposits, withdrawals, transfers, option premiums, settlements/deliveries, corrections, costs, and insurance refills). Does not include open futures PnL or options mark value.", "example": 3.4906363, "type": "number" }, "close_out_margin": { "description": "Close-out margin threshold in the selected currency, equal to 50% of the positional maintenance margin.\nBecause it sits below `maintenance_margin`, it marks a later and more severe stage than ordinary liquidation: when `margin_balance` falls to or below this level, close-out liquidation takes over.\nOn a cross account with an outstanding loan it is not exactly half of the reported `maintenance_margin`: the loan's maintenance margin is included in `maintenance_margin` but excluded from the close-out threshold.\nReturned only when close-out margin is enabled on the platform.\n", "example": 0, "type": "number" }, "cross_collateral_enabled": { "description": "When `true` cross collateral is enabled for user", "example": true, "type": "boolean" }, "currency": { "description": "The selected currency", "example": "ETH", "type": "string" }, "delta_total": { "description": "The sum of position deltas. \n\n**DeltaTotal = Net Transaction Delta of options + BTC Position of Futures**\n\nThe DeltaTotal uses the Net Transaction Delta (or price adjusted Delta) of the options, where Net Transaction Delta = Black Scholes Delta - Mark Price of Options.\n\nThis is because, from a risk perspective, we are interested in the change in Bitcoin price as the underlying changes.\n\nYou should actually treat your delta as **Equity + Delta Total** if you want to have less risk for your USD PnL.\n\n⚠️ **During the 30 minute settlement period we decay your Delta.** See [Delta decay during settlement](https://support.deribit.com/hc/en-us/articles/25944751433757-Delta-decay-during-settlement) for more details.\n", "example": 0.1334, "type": "number" }, "delta_total_map": { "additionalProperties": { "type": "number" }, "description": "Map of position delta sums by price index (e.g. `btc_usd`), covering both futures and options positions.\nThese are raw position deltas: they are not price-adjusted for linear instruments and the options mark value is not subtracted.\nThey therefore do not add up to `delta_total`, which is calculated on the Net Transaction Delta basis described under `delta_total`.\n", "type": "object" }, "equity": { "description": "The account's equity in the selected currency: `balance + futures (session UPL + RPL) + options mark value` (plus any external/implied equity). Related: `margin_balance` excludes options mark value under standard margin.", "example": 2.6437733, "type": "number" }, "fee_balance": { "description": "The account's fee balance (it can be used to pay for fees)", "type": "number" }, "futures_pl": { "description": "Combined profit and loss of all futures and perpetual positions included in `total_pl` (`total_pl - options_pl`).", "example": 0, "type": "number" }, "futures_session_rpl": { "description": "Session realized profit and loss for futures and perpetual positions (resets at daily settlement).", "example": 0, "type": "number" }, "futures_session_upl": { "description": "Session unrealized profit and loss for open futures and perpetual positions.", "example": 0, "type": "number" }, "initial_margin": { "description": "Minimum margin required to open or increase positions (includes margin for open orders). If initial margin usage exceeds 100%, `available_funds` is `0`. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.", "example": 0.379882, "type": "number" }, "locked_balance": { "description": "Portion of the account balance that is locked and excluded from available withdrawal calculations.", "example": 0, "type": "number" }, "maintenance_margin": { "description": "Minimum margin required to keep positions open. If `margin_balance` falls below maintenance margin, positions are liquidated. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.", "example": 0.1334519, "type": "number" }, "margin_balance": { "description": "Collateral available against margin requirements. Under standard margin (SM): `equity - options_value` (cash balance plus futures session UPL and RPL). Under portfolio margin (PM): equal to `equity` on a segregated account, and `equity - outstanding_loan_amount` on a cross account. When cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.", "example": 2.25, "type": "number" }, "margin_model": { "description": "Name of user's currently enabled margin model", "example": "segregated_sm", "type": "string" }, "options_delta": { "description": "Sum of the deltas of all options positions. For inverse (coin-margined) options this is the Black-Scholes delta; for linear options it is the index-price-adjusted delta. Unlike account-level `delta_total`, the options mark value is not subtracted.", "example": 0, "type": "number" }, "options_gamma": { "description": "Sum of options position gammas (Black-Scholes).", "example": 0, "type": "number" }, "options_gamma_map": { "description": "Map of options' gammas per index", "type": "object" }, "options_pl": { "description": "Combined profit and loss of all options positions included in `total_pl`.", "example": 0, "type": "number" }, "options_session_rpl": { "description": "Session realized profit and loss for options positions (resets at daily settlement).", "example": 0, "type": "number" }, "options_session_upl": { "description": "Session unrealized profit and loss for open options positions.", "example": 0, "type": "number" }, "options_theta": { "description": "Sum of the thetas of all options positions. Theta is expressed per day; for options with less than one day left to expiry it is scaled down to the fraction of a day remaining.", "example": 0, "type": "number" }, "options_theta_map": { "description": "Map of options' thetas per index", "type": "object" }, "options_value": { "description": "Mark value of all open options positions in the selected currency. Under standard margin, `margin_balance = equity - options_value`.", "example": 0, "type": "number" }, "options_vega": { "description": "Sum of options position vegas (Black-Scholes).", "example": 0, "type": "number" }, "options_vega_map": { "description": "Map of options' vegas per index", "type": "object" }, "portfolio_margining_enabled": { "description": "When `true` portfolio margining is enabled for user", "example": true, "type": "boolean" }, "projected_close_out_margin": { "description": "Close-out margin calculated as if instruments expiring at the nearest expiration were excluded, i.e. 50% of the projected positional maintenance margin.\nAs with `close_out_margin`, the loan maintenance margin counted in `projected_maintenance_margin` is excluded here, so on a cross account with an outstanding loan the two are not exactly proportional.\nReturned only when close-out margin is enabled on the platform.\n", "example": 0, "type": "number" }, "projected_delta_total": { "description": "The sum of position deltas excluding positions that expire at the nearest expiration, so it shows the delta that will remain once those positions have expired.\nCalculated on the same Net Transaction Delta basis as `delta_total`, including delta decay during the settlement period.\n", "example": 0.1334, "type": "number" }, "projected_initial_margin": { "description": "Initial margin calculated as if instruments expiring at the nearest expiration were excluded, so it shows the requirement that will remain once those instruments have expired.\nWhen cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.\n", "example": 1, "type": "number" }, "projected_maintenance_margin": { "description": "Maintenance margin calculated as if instruments expiring at the nearest expiration were excluded, so it shows the requirement that will remain once those instruments have expired.\nWhen cross collateral is enabled, this aggregated value is calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.\n", "example": 1, "type": "number" }, "session_rpl": { "description": "Realized profit and loss accrued in the current trading session (since the last daily settlement). Resets at each daily settlement.", "example": 0.1, "type": "number" }, "session_upl": { "description": "Unrealized profit and loss on open positions in the current trading session (since the last daily settlement).", "example": 0.846863, "type": "number" }, "total_delta_total_usd": { "description": "Optional (only for users using cross margin). The account's total delta total in all cross collateral currencies, expressed in USD", "example": 1.8, "type": "number" }, "total_equity_usd": { "description": "Optional (only for users using cross margin). The account's total equity in all cross collateral currencies, expressed in USD", "example": 2.6437733, "type": "number" }, "total_initial_margin_usd": { "description": "Optional (only for users using cross margin). The account's total initial margin in all cross collateral currencies, expressed in USD", "example": 0.379882, "type": "number" }, "total_maintenance_margin_usd": { "description": "Optional (only for users using cross margin). The account's total maintenance margin in all cross collateral currencies, expressed in USD", "example": 0.1334519, "type": "number" }, "total_margin_balance_usd": { "description": "Optional (only for users using cross margin). The account's total margin balance in all cross collateral currencies, expressed in USD", "example": 2.25, "type": "number" }, "total_pl": { "description": "Total profit and loss of all open positions since each position was opened (not limited to the current session). Differs from `session_rpl` + `session_upl`, which reset at daily settlement.", "example": 0.02032221, "type": "number" } }, "required": [ "available_funds", "available_withdrawal_funds", "balance", "cross_collateral_enabled", "currency", "delta_total_map", "equity", "futures_pl", "futures_session_rpl", "futures_session_upl", "initial_margin", "maintenance_margin", "margin_balance", "margin_model", "options_delta", "options_gamma", "options_gamma_map", "options_pl", "options_session_rpl", "options_session_upl", "options_theta", "options_theta_map", "options_value", "options_vega", "options_vega_map", "portfolio_margining_enabled", "projected_delta_total", "projected_maintenance_margin", "session_rpl", "session_upl", "total_pl" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "currency": { "description": "Currency code or `any` for all\n\n**Allowed values:** `BTC`, `ETH`, `USDC`, `USDT`, `EURR`, `any`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT", "any" ] } }, "servers": [ { "$ref": "#/servers/private" } ], "summary": "Real-time notifications for user portfolio information. This subscription provides comprehensive account and portfolio data for the specified currency, including balances, margins, profit and loss, and Greeks.\n\nEach notification includes:\n\n- **Account balances:** Current balance, equity, margin balance, available funds, and available withdrawal funds\n- **Margin information:** Initial margin, maintenance margin, and projected margins\n- **Profit and Loss:** Total P&L, session unrealized P&L (UPL), session realized P&L (RPL), and separate P&L for options and futures\n- **Options Greeks:** Delta, gamma, theta, vega, and options value, with per-index mappings\n- **Position data:** Delta total, projected delta total, and delta total map per index\n- **Account settings:** Portfolio margining status, cross collateral status, and margin model\n- **Cross collateral data:** Total equity, margins, and delta in USD (when cross collateral is enabled)\n- **Additional reserves:** Fee balance and additional reserve information\n\nWhen cross collateral is enabled, aggregated values are calculated by converting the sum of each cross collateral currency's value to the given currency, using each cross collateral currency's index.\n\nSubscribe to a specific currency (BTC, ETH, USDC, USDT, etc.) or use `any` to receive portfolio updates for all currencies.\n", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Portfolio" } ], "title": "user.portfolio.(currency) " }, "user.position_lock": { "address": "user.position_lock", "description": "Notifications when position lock state is enabled or disabled for the user.\n\nUse this channel to monitor risk-control position lock events (which restrict opening or expanding positions) and react immediately when restrictions are updated.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to `user.position_lock` channel. This channel does not require any additional parameters.", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.position_lock" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.position_lock" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.position_lock` subscription - contains the data payload", "examples": [ { "name": "subscription_message_example", "payload": { "jsonrpc": "2.0", "method": "subscription", "params": { "channel": "user.position_lock", "data": { "locked": true } } }, "summary": "Subscription notification example" } ], "name": "user_position_lock_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "properties": { "locked": { "description": "Value is set to `true` when user position lock is active, `false` when removed", "example": true, "type": "boolean" } }, "required": [ "locked" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": {}, "servers": [ { "$ref": "#/servers/private" } ], "summary": "Notifications when position lock state is enabled or disabled for the user.\n\nUse this channel to monitor risk-control position lock events (which restrict opening or expanding positions) and react immediately when restrictions are updated.\n", "tags": [ { "name": "User" }, { "name": "Private" } ], "title": "user.position_lock " }, "user.trades.(instrument_name).(interval)": { "address": "user.trades.{instrument_name}.{interval}", "description": "User trade notifications for a specific instrument.\n\nReceive private trade events for your account for the given instrument. The `interval` controls how frequently events are aggregated.\n\n**Block RFQ trades:** Trades resulting from Block RFQ execution are included in this channel. These trades carry the following additional fields:\n- `block_rfq_id` — ID of the Block RFQ.\n- `block_trade_id` — ID of the resulting block trade.\n- `block_rfq_quote_id` — ID of the accepted quote (present on the **maker** side only).\n- `order_id` — always present for direct trade participants (makers and takers).\n", "messages": { "subscribe_request": { "description": "Request to subscribe to user channel. Channel name format: `user.trades.(instrument_name).(interval)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.trades.BTC-PERPETUAL.100ms" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.trades.BTC-PERPETUAL.100ms" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.trades.(instrument_name).(interval)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": [ { "amount": 20, "direction": "sell", "fee": 0.00000168, "fee_currency": "BTC", "index_price": 8956.73, "instrument_name": "BTC-PERPETUAL", "liquidity": "T", "mark_price": 8952.86, "matching_id": null, "order_id": "4008965646", "order_type": "market", "post_only": false, "price": 8954, "reduce_only": false, "state": "filled", "tick_direction": 0, "timestamp": 1590484156350, "trade_id": "48079254", "trade_seq": 30289432 }, { "amount": 20, "direction": "sell", "fee": 0.00000168, "fee_currency": "BTC", "index_price": 8956.73, "instrument_name": "BTC-PERPETUAL", "liquidity": "T", "mark_price": 8952.86, "matching_id": null, "order_id": "4008965646", "order_type": "market", "post_only": false, "price": 8954, "reduce_only": false, "state": "filled", "tick_direction": 1, "timestamp": 1590484156350, "trade_id": "48079255", "trade_seq": 30289433 } ] }, "summary": "Repeated notification example" } ], "name": "user_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "description": "", "properties": { "advanced": { "description": "Advanced type of user order: `\"usd\"` or `\"implv\"` (only for options; omitted if not applicable)", "enum": [ "implv", "usd" ], "type": "string" }, "amount": { "description": "Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.", "type": "number" }, "api": { "description": "`true` if user order was created with API", "type": "boolean" }, "block_rfq_id": { "description": "ID of the Block RFQ - when trade was part of the Block RFQ", "type": "integer" }, "block_rfq_quote_id": { "description": "ID of the Block RFQ quote - when trade was part of the Block RFQ", "type": "integer" }, "block_trade_id": { "description": "Block trade id - when trade was part of a block trade", "example": "154", "type": "string" }, "block_trade_leg_count": { "description": "Block trade leg count - when trade was part of a block trade", "example": 3, "type": "integer" }, "combo_id": { "description": "Optional field containing combo instrument name if the trade is a combo trade", "type": "string" }, "combo_trade_id": { "description": "Optional field containing combo trade identifier if the trade is a combo trade", "type": "string" }, "contracts": { "description": "Trade size in contract units (optional, may be absent in historical trades)", "type": "number" }, "direction": { "description": "Direction: `buy`, or `sell`", "enum": [ "buy", "sell" ], "type": "string" }, "fee": { "description": "User's fee in units of the specified `fee_currency`", "type": "number" }, "fee_currency": { "description": "Currency, i.e `\"BTC\"`, `\"ETH\"`, `\"USDC\"`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT" ], "type": "string" }, "index_price": { "description": "Index Price at the moment of trade", "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "iv": { "description": "Option implied volatility for the price (Option only)", "type": "number" }, "label": { "description": "User defined label (presented only when previously set for order by user)", "type": "string" }, "legs": { "description": "Optional field containing leg trades if trade is a combo trade (present when querying for **only** combo trades and in `combo_trades` events). Each leg trade has the same fields as a top-level user trade, including `starbase_match_id`, `starbase_order_id`, and `starbase_timestamp` when matched in Starbase, and `starbase_client_order_id` for orders submitted via [Starbase](https://docs.deribit.com/starbase/overview) direct access.", "type": "array" }, "liquidation": { "description": "Optional field (only for trades caused by liquidation): `\"M\"` when maker side of trade was under liquidation, `\"T\"` when taker side was under liquidation, `\"MT\"` when both sides of trade were under liquidation", "enum": [ "M", "MT", "T" ], "type": "string" }, "liquidity": { "description": "Describes what was role of users order: `\"M\"` when it was maker order, `\"T\"` when it was taker order", "enum": [ "M", "T" ], "type": "string" }, "mark_price": { "description": "Mark Price at the moment of trade", "type": "number" }, "matching_id": { "description": "Always `null`", "type": "string" }, "mmp": { "description": "`true` if user order is MMP", "type": "boolean" }, "order_id": { "description": "Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade", "type": "string" }, "order_type": { "description": "Order type: `\"limit\"`, `\"market\"`, or `\"liquidation\"`", "enum": [ "limit", "liquidation", "market" ], "type": "string" }, "original_order_type": { "description": "Original API order type when an order is represented internally as a limit order. For example, Starbase market orders use `\"limit\"` as `order_type` with `\"market\"` in this optional field.", "enum": [ "market", "market_limit" ], "type": "string" }, "post_only": { "description": "`true` if user order is post-only", "type": "string" }, "price": { "description": "Price in base currency", "type": "number" }, "profit_loss": { "description": "Profit and loss in base currency.", "type": "number" }, "quote_id": { "description": "QuoteID of the user order (optional, present only for orders placed with `private/mass_quote`)", "type": "string" }, "quote_set_id": { "description": "QuoteSet of the user order (optional, present only for orders placed with `private/mass_quote`)", "type": "string" }, "reduce_only": { "description": "`true` if user order is reduce-only", "type": "string" }, "risk_reducing": { "description": "`true` if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)", "type": "boolean" }, "starbase_client_order_id": { "description": "Client order id of the user's own order (maker or taker side) submitted directly to [Starbase](https://docs.deribit.com/starbase/overview) via direct access; not returned for orders placed through the Deribit API; for self-trades this is the taker order's client order id", "type": "string" }, "starbase_match_id": { "description": "Optional field containing the Starbase match identifier (present only for trades matched via Starbase)", "type": "integer" }, "starbase_order_id": { "description": "Raw Starbase order id of the user's order, in Starbase's own (non currency-prefixed) id namespace (present only for trades matched in Starbase)", "example": 103148386170, "type": "integer" }, "starbase_timestamp": { "description": "The Starbase causal timestamp of the trade (nanoseconds since the Unix epoch)", "example": 1536569522277000000, "type": "integer" }, "state": { "description": "Order state: `\"open\"`, `\"filled\"`, `\"rejected\"`, `\"cancelled\"`, `\"untriggered\"` or `\"archive\"` (if order was archived)", "enum": [ "archive", "cancelled", "filled", "open", "rejected", "untriggered" ], "type": "string" }, "tick_direction": { "description": "Direction of the \"tick\" (`0` = Plus Tick, `1` = Zero-Plus Tick, `2` = Minus Tick, `3` = Zero-Minus Tick).", "enum": [ 0, 1, 2, 3 ], "type": "integer" }, "timestamp": { "description": "The timestamp of the trade (milliseconds since the UNIX epoch)", "example": 1517329113791, "type": "integer" }, "trade_allocations": { "additionalProperties": false, "description": "List of allocations for Block RFQ pre-allocation. Each allocation specifies `user_id`, `amount`, and `fee` for the allocated part of the trade. For broker client allocations, a `client_info` object will be included.", "properties": { "amount": { "description": "Amount allocated to this user.", "type": "number" }, "client_info": { "description": "Optional client allocation info for brokers.", "properties": { "client_id": { "description": "ID of a client; available to broker. Represents a group of users under a common name.", "type": "integer" }, "client_link_id": { "description": "ID assigned to a single user in a client; available to broker.", "type": "integer" }, "name": { "description": "Name of the linked user within the client; available to broker.", "type": "string" } }, "type": "object" }, "fee": { "description": "Fee for the allocated part of the trade.", "type": "number" }, "user_id": { "description": "User ID to which part of the trade is allocated. For brokers the User ID is obstructed.", "type": "integer" } }, "required": [ "amount", "fee" ], "type": "object" }, "trade_id": { "description": "Unique (per currency) trade identifier", "type": "string" }, "trade_seq": { "description": "The sequence number of the trade within instrument", "type": "integer" }, "underlying_price": { "description": "Underlying price for implied volatility calculations (Options only)", "type": "number" } }, "required": [ "amount", "direction", "fee", "fee_currency", "index_price", "instrument_name", "mark_price", "matching_id", "order_id", "price", "state", "tick_direction", "timestamp", "trade_id", "trade_seq" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "instrument_name": { "description": "The name of the instrument" }, "interval": { "description": "Frequency of notifications. Events will be aggregated over this interval. The value `raw` selects the finest granularity - events are aggregated over a 1 millisecond interval **(Please note that `raw` interval is only available to authorized users)**\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] } }, "servers": [ { "$ref": "#/servers/private" } ], "summary": "User trade notifications for a specific instrument.\n\nReceive private trade events for your account for the given instrument. The `interval` controls how frequently events are aggregated.\n\n**Block RFQ trades:** Trades resulting from Block RFQ execution are included in this channel. These trades carry the following additional fields:\n- `block_rfq_id` — ID of the Block RFQ.\n- `block_trade_id` — ID of the resulting block trade.\n- `block_rfq_quote_id` — ID of the accepted quote (present on the **maker** side only).\n- `order_id` — always present for direct trade participants (makers and takers).\n", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Trades" } ], "title": "user.trades.(instrument_name).(interval) " }, "user.trades.(kind).(currency).(interval)": { "address": "user.trades.{kind}.{currency}.{interval}", "description": "User trade notifications across all instruments for a given kind and currency.\n\nReceive a consolidated stream of your private trades across all instruments matching the specified `kind` and `currency`. The `interval` controls aggregation frequency.\n\n**Block RFQ trades:** Trades resulting from Block RFQ execution are included in this channel. See `user.trades.{instrument_name}.{interval}` for the complete list of Block RFQ-specific fields.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to user channel. Channel name format: `user.trades.(kind).(currency).(interval)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.trades.future.USDC.100ms" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.trades.future.USDC.100ms" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel. Please refer to [Notification page](https://deribit.mintlify.app/articles/notifications) for more information.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.trades.(kind).(currency).(interval)` subscription - contains the data payload", "examples": [ { "name": "repeated", "payload": { "data": [ { "amount": 8940, "direction": "sell", "fee": 0.00049961, "fee_currency": "BTC", "index_price": 8953.53, "instrument_name": "BTC-25SEP20", "liquidity": "T", "mark_price": 8970.03, "matching_id": null, "order_id": "4008978075", "order_type": "limit", "post_only": false, "price": 8947, "reduce_only": false, "state": "filled", "tick_direction": 2, "timestamp": 1590484255886, "trade_id": "48079262", "trade_seq": 74405 } ] }, "summary": "Repeated notification example" } ], "name": "user_subscription_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": false, "description": "", "properties": { "advanced": { "description": "Advanced type of user order: `\"usd\"` or `\"implv\"` (only for options; omitted if not applicable)", "enum": [ "implv", "usd" ], "type": "string" }, "amount": { "description": "Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.", "type": "number" }, "api": { "description": "`true` if user order was created with API", "type": "boolean" }, "block_rfq_id": { "description": "ID of the Block RFQ - when trade was part of the Block RFQ", "type": "integer" }, "block_rfq_quote_id": { "description": "ID of the Block RFQ quote - when trade was part of the Block RFQ", "type": "integer" }, "block_trade_id": { "description": "Block trade id - when trade was part of a block trade", "example": "154", "type": "string" }, "block_trade_leg_count": { "description": "Block trade leg count - when trade was part of a block trade", "example": 3, "type": "integer" }, "combo_id": { "description": "Optional field containing combo instrument name if the trade is a combo trade", "type": "string" }, "combo_trade_id": { "description": "Optional field containing combo trade identifier if the trade is a combo trade", "type": "string" }, "contracts": { "description": "Trade size in contract units (optional, may be absent in historical trades)", "type": "number" }, "direction": { "description": "Direction: `buy`, or `sell`", "enum": [ "buy", "sell" ], "type": "string" }, "fee": { "description": "User's fee in units of the specified `fee_currency`", "type": "number" }, "fee_currency": { "description": "Currency, i.e `\"BTC\"`, `\"ETH\"`, `\"USDC\"`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT" ], "type": "string" }, "index_price": { "description": "Index Price at the moment of trade", "type": "number" }, "instrument_name": { "description": "Unique instrument identifier", "example": "BTC-PERPETUAL", "type": "string" }, "iv": { "description": "Option implied volatility for the price (Option only)", "type": "number" }, "label": { "description": "User defined label (presented only when previously set for order by user)", "type": "string" }, "legs": { "description": "Optional field containing leg trades if trade is a combo trade (present when querying for **only** combo trades and in `combo_trades` events). Each leg trade has the same fields as a top-level user trade, including `starbase_match_id`, `starbase_order_id`, and `starbase_timestamp` when matched in Starbase, and `starbase_client_order_id` for orders submitted via [Starbase](https://docs.deribit.com/starbase/overview) direct access.", "type": "array" }, "liquidation": { "description": "Optional field (only for trades caused by liquidation): `\"M\"` when maker side of trade was under liquidation, `\"T\"` when taker side was under liquidation, `\"MT\"` when both sides of trade were under liquidation", "enum": [ "M", "MT", "T" ], "type": "string" }, "liquidity": { "description": "Describes what was role of users order: `\"M\"` when it was maker order, `\"T\"` when it was taker order", "enum": [ "M", "T" ], "type": "string" }, "mark_price": { "description": "Mark Price at the moment of trade", "type": "number" }, "matching_id": { "description": "Always `null`", "type": "string" }, "mmp": { "description": "`true` if user order is MMP", "type": "boolean" }, "order_id": { "description": "Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade", "type": "string" }, "order_type": { "description": "Order type: `\"limit\"`, `\"market\"`, or `\"liquidation\"`", "enum": [ "limit", "liquidation", "market" ], "type": "string" }, "original_order_type": { "description": "Original API order type when an order is represented internally as a limit order. For example, Starbase market orders use `\"limit\"` as `order_type` with `\"market\"` in this optional field.", "enum": [ "market", "market_limit" ], "type": "string" }, "post_only": { "description": "`true` if user order is post-only", "type": "string" }, "price": { "description": "Price in base currency", "type": "number" }, "profit_loss": { "description": "Profit and loss in base currency.", "type": "number" }, "quote_id": { "description": "QuoteID of the user order (optional, present only for orders placed with `private/mass_quote`)", "type": "string" }, "quote_set_id": { "description": "QuoteSet of the user order (optional, present only for orders placed with `private/mass_quote`)", "type": "string" }, "reduce_only": { "description": "`true` if user order is reduce-only", "type": "string" }, "risk_reducing": { "description": "`true` if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)", "type": "boolean" }, "starbase_client_order_id": { "description": "Client order id of the user's own order (maker or taker side) submitted directly to [Starbase](https://docs.deribit.com/starbase/overview) via direct access; not returned for orders placed through the Deribit API; for self-trades this is the taker order's client order id", "type": "string" }, "starbase_match_id": { "description": "Optional field containing the Starbase match identifier (present only for trades matched via Starbase)", "type": "integer" }, "starbase_order_id": { "description": "Raw Starbase order id of the user's order, in Starbase's own (non currency-prefixed) id namespace (present only for trades matched in Starbase)", "example": 103148386170, "type": "integer" }, "starbase_timestamp": { "description": "The Starbase causal timestamp of the trade (nanoseconds since the Unix epoch)", "example": 1536569522277000000, "type": "integer" }, "state": { "description": "Order state: `\"open\"`, `\"filled\"`, `\"rejected\"`, `\"cancelled\"`, `\"untriggered\"` or `\"archive\"` (if order was archived)", "enum": [ "archive", "cancelled", "filled", "open", "rejected", "untriggered" ], "type": "string" }, "tick_direction": { "description": "Direction of the \"tick\" (`0` = Plus Tick, `1` = Zero-Plus Tick, `2` = Minus Tick, `3` = Zero-Minus Tick).", "enum": [ 0, 1, 2, 3 ], "type": "integer" }, "timestamp": { "description": "The timestamp of the trade (milliseconds since the UNIX epoch)", "example": 1517329113791, "type": "integer" }, "trade_allocations": { "additionalProperties": false, "description": "List of allocations for Block RFQ pre-allocation. Each allocation specifies `user_id`, `amount`, and `fee` for the allocated part of the trade. For broker client allocations, a `client_info` object will be included.", "properties": { "amount": { "description": "Amount allocated to this user.", "type": "number" }, "client_info": { "description": "Optional client allocation info for brokers.", "properties": { "client_id": { "description": "ID of a client; available to broker. Represents a group of users under a common name.", "type": "integer" }, "client_link_id": { "description": "ID assigned to a single user in a client; available to broker.", "type": "integer" }, "name": { "description": "Name of the linked user within the client; available to broker.", "type": "string" } }, "type": "object" }, "fee": { "description": "Fee for the allocated part of the trade.", "type": "number" }, "user_id": { "description": "User ID to which part of the trade is allocated. For brokers the User ID is obstructed.", "type": "integer" } }, "required": [ "amount", "fee" ], "type": "object" }, "trade_id": { "description": "Unique (per currency) trade identifier", "type": "string" }, "trade_seq": { "description": "The sequence number of the trade within instrument", "type": "integer" }, "underlying_price": { "description": "Underlying price for implied volatility calculations (Options only)", "type": "number" } }, "required": [ "amount", "direction", "fee", "fee_currency", "index_price", "instrument_name", "mark_price", "matching_id", "order_id", "price", "state", "tick_direction", "timestamp", "trade_id", "trade_seq" ], "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "currency": { "description": "Currency code or `any` for all\n\n**Allowed values:** `BTC`, `ETH`, `USDC`, `USDT`, `EURR`, `any`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT", "any" ] }, "interval": { "description": "Frequency of notifications. Events will be aggregated over this interval. The value `raw` selects the finest granularity - events are aggregated over a 1 millisecond interval **(Please note that `raw` interval is only available to authorized users)**\n\n**Allowed values:** `raw`, `100ms`, `agg2`", "enum": [ "100ms", "agg2", "raw" ] }, "kind": { "description": "Instrument kind\n\n**Allowed values:** `future`, `option`, `spot`, `future_combo`, `option_combo`", "enum": [ "future", "future_combo", "option", "option_combo", "spot" ] } }, "servers": [ { "$ref": "#/servers/private" } ], "summary": "User trade notifications across all instruments for a given kind and currency.\n\nReceive a consolidated stream of your private trades across all instruments matching the specified `kind` and `currency`. The `interval` controls aggregation frequency.\n\n**Block RFQ trades:** Trades resulting from Block RFQ execution are included in this channel. See `user.trades.{instrument_name}.{interval}` for the complete list of Block RFQ-specific fields.\n", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Trades" } ], "title": "user.trades.(kind).(currency).(interval) " }, "user.trailing_orders.trigger_price.(currency)": { "address": "user.trailing_orders.trigger_price.{currency}", "description": "Real-time notifications for active trailing order trigger prices in the specified currency.\n\nUse this channel to track updated trigger prices for active trailing stop orders as market index or mark prices move.\n", "messages": { "subscribe_request": { "description": "Request to subscribe to trailing order trigger price channel. Channel name format: `user.trailing_orders.trigger_price.(currency)`", "examples": [ { "name": "subscribe_request_example", "payload": { "id": 42, "jsonrpc": "2.0", "method": "private/subscribe", "params": { "channels": [ "user.trailing_orders.trigger_price.eth" ] } }, "summary": "Subscription request example" } ], "name": "subscribe_request", "payload": { "additionalProperties": false, "properties": { "id": { "default": 42, "description": "Client request id, echoed in the response.", "type": "integer" }, "jsonrpc": { "default": "2.0", "description": "JSON-RPC version. Always `2.0`.", "type": "string" }, "method": { "default": "private/subscribe", "description": "`private/subscribe` on the private WebSocket, after `public/auth`.", "enum": [ "private/subscribe" ], "type": "string" }, "params": { "additionalProperties": false, "properties": { "channels": { "default": [ "user.trailing_orders.trigger_price.eth" ], "description": "Stream names to subscribe to, for example `quote.BTC-PERPETUAL`.", "items": { "type": "string" }, "type": "array" } }, "required": [ "channels" ], "type": "object" } }, "required": [ "id", "jsonrpc", "method", "params" ], "type": "object" }, "summary": "Client sends subscription request to subscribe to notification channel.", "title": "Subscription Request" }, "subscription_message": { "description": "Message schema for `user.trailing_orders.trigger_price.(currency)` subscription - contains the data payload", "examples": [ { "name": "subscription_message_example", "payload": { "jsonrpc": "2.0", "method": "subscription", "params": { "channel": "user.trailing_orders.trigger_price.eth", "data": { "eth-usdt-buy-98765": 3450.75 } } }, "summary": "Subscription notification example" } ], "name": "user_trailing_orders_trigger_price_notification_data", "payload": { "additionalProperties": false, "description": "Response containing notification data", "properties": { "data": { "additionalProperties": { "description": "Updated trailing trigger price", "type": "number" }, "description": "Map of secondary order IDs (`sid`) to updated trigger prices", "example": { "eth-usdt-buy-98765": 3450.75 }, "type": "object" } }, "required": [ "data" ], "type": "object" }, "summary": "Server sends subscription notification data", "title": "Subscription Notification Data" } }, "parameters": { "currency": { "description": "Currency code or `any` for all currencies\n\n**Allowed values:** `BTC`, `ETH`, `USDC`, `USDT`, `EURR`, `any`", "enum": [ "BTC", "ETH", "EURR", "USDC", "USDT", "any" ] } }, "servers": [ { "$ref": "#/servers/private" } ], "summary": "Real-time notifications for active trailing order trigger prices in the specified currency.\n\nUse this channel to track updated trigger prices for active trailing stop orders as market index or mark prices move.\n", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Orders" } ], "title": "user.trailing_orders.trigger_price.(currency) " } }, "components": { "messages": {}, "schemas": { "DeribitMessage": { "description": "Base message structure for Deribit WebSocket messages", "properties": { "jsonrpc": { "const": "2.0", "type": "string" }, "method": { "description": "The subscription method", "type": "string" }, "params": { "description": "Method parameters", "type": "object" } }, "required": [ "jsonrpc", "method" ], "type": "object" } } }, "defaultContentType": "application/json", "id": "https://deribit.com/api/v2/subscriptions", "info": { "contact": { "name": "Deribit API Support", "url": "https://docs.deribit.com" }, "description": "Coinbase Retail Advanced Trade API for derivatives trading.", "title": "Coinbase Retail Advanced Trade (Deribit) API (WebSocket)", "version": "1.0.0" }, "operations": { "receive_announcements": { "action": "receive", "channel": { "$ref": "#/channels/announcements" }, "description": "Receive announcements notifications from the server", "messages": [ { "$ref": "#/channels/announcements/messages/subscribe_request" } ], "summary": "Client receives announcements notifications", "tags": [ { "name": "Announcements" } ], "title": "Receive announcements" }, "receive_book_instrument_name_group_depth_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/book.(instrument_name).(group).(depth).(interval)" }, "description": "Receive order book update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/book.(instrument_name).(group).(depth).(interval)/messages/subscribe_request" } ], "summary": "Client receives order book update notifications", "tags": [ { "name": "Orderbook" }, { "name": "Market Data" } ], "title": "Receive order book updates" }, "receive_book_instrument_name_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/book.(instrument_name).(interval)" }, "description": "Receive order book update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/book.(instrument_name).(interval)/messages/subscribe_request" } ], "summary": "Client receives order book update notifications", "tags": [ { "name": "Orderbook" }, { "name": "Market Data" } ], "title": "Receive order book updates" }, "receive_chart_trades_instrument_name_resolution_updates": { "action": "receive", "channel": { "$ref": "#/channels/chart.trades.(instrument_name).(resolution)" }, "description": "Receive chart update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/chart.trades.(instrument_name).(resolution)/messages/subscribe_request" } ], "summary": "Client receives chart update notifications", "tags": [ { "name": "Market Data" } ], "title": "Receive chart updates" }, "receive_deribit_price_index_index_name_updates": { "action": "receive", "channel": { "$ref": "#/channels/deribit_price_index.(index_name)" }, "description": "Receive deribit_price_index update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/deribit_price_index.(index_name)/messages/subscribe_request" } ], "summary": "Client receives deribit_price_index update notifications", "tags": [ { "name": "Market Data" } ], "title": "Receive deribit_price_index updates" }, "receive_deribit_price_ranking_index_name_updates": { "action": "receive", "channel": { "$ref": "#/channels/deribit_price_ranking.(index_name)" }, "description": "Receive deribit_price_ranking update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/deribit_price_ranking.(index_name)/messages/subscribe_request" } ], "summary": "Client receives deribit_price_ranking update notifications", "tags": [ { "name": "Market Data" } ], "title": "Receive deribit_price_ranking updates" }, "receive_deribit_price_statistics_index_name_updates": { "action": "receive", "channel": { "$ref": "#/channels/deribit_price_statistics.(index_name)" }, "description": "Receive deribit_price_statistics update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/deribit_price_statistics.(index_name)/messages/subscribe_request" } ], "summary": "Client receives deribit_price_statistics update notifications", "tags": [ { "name": "Market Data" } ], "title": "Receive deribit_price_statistics updates" }, "receive_deribit_volatility_index_index_name_updates": { "action": "receive", "channel": { "$ref": "#/channels/deribit_volatility_index.(index_name)" }, "description": "Receive deribit_volatility_index update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/deribit_volatility_index.(index_name)/messages/subscribe_request" } ], "summary": "Client receives deribit_volatility_index update notifications", "tags": [ { "name": "Market Data" } ], "title": "Receive deribit_volatility_index updates" }, "receive_estimated_expiration_price_index_name_updates": { "action": "receive", "channel": { "$ref": "#/channels/estimated_expiration_price.(index_name)" }, "description": "Receive estimated_expiration_price update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/estimated_expiration_price.(index_name)/messages/subscribe_request" } ], "summary": "Client receives estimated_expiration_price update notifications", "tags": [ { "name": "Market Data" } ], "title": "Receive estimated_expiration_price updates" }, "receive_incremental_ticker_instrument_name_updates": { "action": "receive", "channel": { "$ref": "#/channels/incremental_ticker.(instrument_name)" }, "description": "Receive incremental_ticker update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/incremental_ticker.(instrument_name)/messages/subscribe_request" } ], "summary": "Client receives incremental_ticker update notifications", "tags": [ { "name": "Market Data" } ], "title": "Receive incremental_ticker updates" }, "receive_instrument_creation_kind_currency_updates": { "action": "receive", "channel": { "$ref": "#/channels/instrument.creation.(kind).(currency)" }, "description": "Receive instrument update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/instrument.creation.(kind).(currency)/messages/subscribe_request" } ], "summary": "Client receives instrument update notifications", "tags": [ { "name": "Market Data" } ], "title": "Receive instrument updates" }, "receive_instrument_state_kind_currency_updates": { "action": "receive", "channel": { "$ref": "#/channels/instrument.state.(kind).(currency)" }, "description": "Receive instrument update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/instrument.state.(kind).(currency)/messages/subscribe_request" } ], "summary": "Client receives instrument update notifications", "tags": [ { "name": "Market Data" } ], "title": "Receive instrument updates" }, "receive_markprice_options_index_name_updates": { "action": "receive", "channel": { "$ref": "#/channels/markprice.options.(index_name)" }, "description": "Receive markprice update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/markprice.options.(index_name)/messages/subscribe_request" } ], "summary": "Client receives markprice update notifications", "tags": [ { "name": "Market Data" } ], "title": "Receive markprice updates" }, "receive_perpetual_instrument_name_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/perpetual.(instrument_name).(interval)" }, "description": "Receive perpetual update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/perpetual.(instrument_name).(interval)/messages/subscribe_request" } ], "summary": "Client receives perpetual update notifications", "tags": [ { "name": "Market Data" } ], "title": "Receive perpetual updates" }, "receive_platform_state": { "action": "receive", "channel": { "$ref": "#/channels/platform_state" }, "description": "Receive platform_state notifications from the server", "messages": [ { "$ref": "#/channels/platform_state/messages/subscribe_request" } ], "summary": "Client receives platform_state notifications", "tags": [ { "name": "Platform" } ], "title": "Receive platform_state" }, "receive_platform_state_public_methods_state": { "action": "receive", "channel": { "$ref": "#/channels/platform_state.public_methods_state" }, "description": "Receive platform_state notifications from the server", "messages": [ { "$ref": "#/channels/platform_state.public_methods_state/messages/subscribe_request" } ], "summary": "Client receives platform_state notifications", "tags": [ { "name": "Platform" } ], "title": "Receive platform_state" }, "receive_quote_instrument_name_updates": { "action": "receive", "channel": { "$ref": "#/channels/quote.(instrument_name)" }, "description": "Receive quote update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/quote.(instrument_name)/messages/subscribe_request" } ], "summary": "Client receives quote update notifications", "tags": [ { "name": "Market Data" } ], "title": "Receive quote updates" }, "receive_ticker_instrument_name_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/ticker.(instrument_name).(interval)" }, "description": "Receive ticker update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/ticker.(instrument_name).(interval)/messages/subscribe_request" } ], "summary": "Client receives ticker update notifications", "tags": [ { "name": "Market Data" } ], "title": "Receive ticker updates" }, "receive_trades_instrument_name_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/trades.(instrument_name).(interval)" }, "description": "Receive trades update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/trades.(instrument_name).(interval)/messages/subscribe_request" } ], "summary": "Client receives trades update notifications", "tags": [ { "name": "Trades" }, { "name": "Market Data" } ], "title": "Receive trades updates" }, "receive_trades_kind_currency_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/trades.(kind).(currency).(interval)" }, "description": "Receive trades update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/trades.(kind).(currency).(interval)/messages/subscribe_request" } ], "summary": "Client receives trades update notifications", "tags": [ { "name": "Trades" }, { "name": "Market Data" } ], "title": "Receive trades updates" }, "receive_user_access_log": { "action": "receive", "channel": { "$ref": "#/channels/user.access_log" }, "description": "Receive user notifications from the server", "messages": [ { "$ref": "#/channels/user.access_log/messages/subscribe_request" } ], "summary": "Client receives user notifications", "tags": [ { "name": "User" }, { "name": "Private" } ], "title": "Receive user" }, "receive_user_changes_instrument_name_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.changes.(instrument_name).(interval)" }, "description": "Receive user update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/user.changes.(instrument_name).(interval)/messages/subscribe_request" } ], "summary": "Client receives user update notifications", "tags": [ { "name": "User" }, { "name": "Private" } ], "title": "Receive user updates" }, "receive_user_changes_kind_currency_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.changes.(kind).(currency).(interval)" }, "description": "Receive user update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/user.changes.(kind).(currency).(interval)/messages/subscribe_request" } ], "summary": "Client receives user update notifications", "tags": [ { "name": "User" }, { "name": "Private" } ], "title": "Receive user updates" }, "receive_user_combo_trades_instrument_name_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.combo_trades.(instrument_name).(interval)" }, "description": "Receive user update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/user.combo_trades.(instrument_name).(interval)/messages/subscribe_request" } ], "summary": "Client receives user update notifications", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Trades" } ], "title": "Receive user updates" }, "receive_user_combo_trades_kind_currency_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.combo_trades.(kind).(currency).(interval)" }, "description": "Receive user update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/user.combo_trades.(kind).(currency).(interval)/messages/subscribe_request" } ], "summary": "Client receives user update notifications", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Trades" } ], "title": "Receive user updates" }, "receive_user_isolated_changes_instrument_name_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.isolated.changes.(instrument_name).(interval)" }, "description": "Receive isolated state change update notifications from the server for a specific instrument", "messages": [ { "$ref": "#/channels/user.isolated.changes.(instrument_name).(interval)/messages/subscribe_request" } ], "summary": "Client receives isolated state change update notifications by instrument", "tags": [ { "name": "Trading" }, { "name": "Private" } ], "title": "Receive isolated changes by instrument" }, "receive_user_isolated_changes_kind_currency_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.isolated.changes.(kind).(currency).(interval)" }, "description": "Receive isolated state change update notifications from the server for a specific kind and currency", "messages": [ { "$ref": "#/channels/user.isolated.changes.(kind).(currency).(interval)/messages/subscribe_request" } ], "summary": "Client receives isolated state change update notifications by kind and currency", "tags": [ { "name": "Trading" }, { "name": "Private" } ], "title": "Receive isolated changes by kind and currency" }, "receive_user_isolated_liquidation": { "action": "receive", "channel": { "$ref": "#/channels/user.isolated.liquidation" }, "description": "Receive user notifications from the server", "messages": [ { "$ref": "#/channels/user.isolated.liquidation/messages/subscribe_request" } ], "summary": "Client receives user notifications", "tags": [ { "name": "User" }, { "name": "Lsp" }, { "name": "Private" } ], "title": "Receive user" }, "receive_user_isolated_orders_instrument_name_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.isolated.orders.(instrument_name).(interval)" }, "description": "Receive isolated order update notifications from the server for a specific instrument", "messages": [ { "$ref": "#/channels/user.isolated.orders.(instrument_name).(interval)/messages/subscribe_request" } ], "summary": "Client receives isolated order update notifications by instrument", "tags": [ { "name": "Trading" }, { "name": "Private" } ], "title": "Receive isolated order updates by instrument" }, "receive_user_isolated_orders_kind_currency_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.isolated.orders.(kind).(currency).(interval)" }, "description": "Receive isolated order update notifications from the server for a specific kind and currency", "messages": [ { "$ref": "#/channels/user.isolated.orders.(kind).(currency).(interval)/messages/subscribe_request" } ], "summary": "Client receives isolated order update notifications by kind and currency", "tags": [ { "name": "Trading" }, { "name": "Private" } ], "title": "Receive isolated order updates by kind and currency" }, "receive_user_isolated_portfolio_currency_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.isolated.portfolio.(currency)" }, "description": "Receive isolated portfolio update notifications from the server for a specific currency", "messages": [ { "$ref": "#/channels/user.isolated.portfolio.(currency)/messages/subscribe_request" } ], "summary": "Client receives isolated portfolio update notifications", "tags": [ { "name": "Account Management" }, { "name": "Private" } ], "title": "Receive isolated portfolio updates" }, "receive_user_isolated_trades_instrument_name_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.isolated.trades.(instrument_name).(interval)" }, "description": "Receive isolated trade update notifications from the server for a specific instrument", "messages": [ { "$ref": "#/channels/user.isolated.trades.(instrument_name).(interval)/messages/subscribe_request" } ], "summary": "Client receives isolated trade update notifications by instrument", "tags": [ { "name": "Trading" }, { "name": "Private" } ], "title": "Receive isolated trade updates by instrument" }, "receive_user_isolated_trades_kind_currency_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.isolated.trades.(kind).(currency).(interval)" }, "description": "Receive isolated trade update notifications from the server for a specific kind and currency", "messages": [ { "$ref": "#/channels/user.isolated.trades.(kind).(currency).(interval)/messages/subscribe_request" } ], "summary": "Client receives isolated trade update notifications by kind and currency", "tags": [ { "name": "Trading" }, { "name": "Private" } ], "title": "Receive isolated trade updates by kind and currency" }, "receive_user_lock": { "action": "receive", "channel": { "$ref": "#/channels/user.lock" }, "description": "Receive user notifications from the server", "messages": [ { "$ref": "#/channels/user.lock/messages/subscribe_request" } ], "summary": "Client receives user notifications", "tags": [ { "name": "User" }, { "name": "Private" } ], "title": "Receive user" }, "receive_user_orders_instrument_name_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.orders.(instrument_name).(interval)" }, "description": "Receive user update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/user.orders.(instrument_name).(interval)/messages/subscribe_request" } ], "summary": "Client receives user update notifications", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Orders" } ], "title": "Receive user updates" }, "receive_user_orders_instrument_name_raw_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.orders.(instrument_name).raw" }, "description": "Receive user update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/user.orders.(instrument_name).raw/messages/subscribe_request" } ], "summary": "Client receives user update notifications", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Orders" } ], "title": "Receive user updates" }, "receive_user_orders_kind_currency_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.orders.(kind).(currency).(interval)" }, "description": "Receive user update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/user.orders.(kind).(currency).(interval)/messages/subscribe_request" } ], "summary": "Client receives user update notifications", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Orders" } ], "title": "Receive user updates" }, "receive_user_orders_kind_currency_raw_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.orders.(kind).(currency).raw" }, "description": "Receive user update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/user.orders.(kind).(currency).raw/messages/subscribe_request" } ], "summary": "Client receives user update notifications", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Orders" } ], "title": "Receive user updates" }, "receive_user_portfolio_currency_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.portfolio.(currency)" }, "description": "Receive user update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/user.portfolio.(currency)/messages/subscribe_request" } ], "summary": "Client receives user update notifications", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Portfolio" } ], "title": "Receive user updates" }, "receive_user_position_lock_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.position_lock" }, "description": "Receive position lock update notifications from the server", "messages": [ { "$ref": "#/channels/user.position_lock/messages/subscribe_request" } ], "summary": "Client receives position lock update notifications", "tags": [ { "name": "User" }, { "name": "Private" } ], "title": "Receive position lock updates" }, "receive_user_trades_instrument_name_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.trades.(instrument_name).(interval)" }, "description": "Receive user update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/user.trades.(instrument_name).(interval)/messages/subscribe_request" } ], "summary": "Client receives user update notifications", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Trades" } ], "title": "Receive user updates" }, "receive_user_trades_kind_currency_interval_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.trades.(kind).(currency).(interval)" }, "description": "Receive user update notifications from the server for the subscribed instrument", "messages": [ { "$ref": "#/channels/user.trades.(kind).(currency).(interval)/messages/subscribe_request" } ], "summary": "Client receives user update notifications", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Trades" } ], "title": "Receive user updates" }, "receive_user_trailing_orders_trigger_price_currency_updates": { "action": "receive", "channel": { "$ref": "#/channels/user.trailing_orders.trigger_price.(currency)" }, "description": "Receive trailing order trigger price update notifications from the server", "messages": [ { "$ref": "#/channels/user.trailing_orders.trigger_price.(currency)/messages/subscribe_request" } ], "summary": "Client receives trailing order trigger price update notifications", "tags": [ { "name": "Trading" }, { "name": "Private" } ], "title": "Receive trailing order trigger price updates" }, "send_subscribe_announcements": { "action": "send", "channel": { "$ref": "#/channels/announcements" }, "description": "Send a subscription request to receive announcements notifications. This channel does not require any additional parameters.", "messages": [ { "$ref": "#/channels/announcements/messages/subscription_message" } ], "summary": "Client sends subscription request for announcements", "tags": [ { "name": "Announcements" } ], "title": "Send subscribe request" }, "send_subscribe_book_instrument_name_group_depth_interval": { "action": "send", "channel": { "$ref": "#/channels/book.(instrument_name).(group).(depth).(interval)" }, "description": "Send a subscription request to receive order book updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/book.(instrument_name).(group).(depth).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for order book updates", "tags": [ { "name": "Orderbook" }, { "name": "Market Data" } ], "title": "Send subscribe request for order book" }, "send_subscribe_book_instrument_name_interval": { "action": "send", "channel": { "$ref": "#/channels/book.(instrument_name).(interval)" }, "description": "Send a subscription request to receive order book updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/book.(instrument_name).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for order book updates", "tags": [ { "name": "Orderbook" }, { "name": "Market Data" } ], "title": "Send subscribe request for order book" }, "send_subscribe_chart_trades_instrument_name_resolution": { "action": "send", "channel": { "$ref": "#/channels/chart.trades.(instrument_name).(resolution)" }, "description": "Send a subscription request to receive chart updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/chart.trades.(instrument_name).(resolution)/messages/subscription_message" } ], "summary": "Client sends subscription request for chart updates", "tags": [ { "name": "Market Data" } ], "title": "Send subscribe request for chart" }, "send_subscribe_deribit_price_index_index_name": { "action": "send", "channel": { "$ref": "#/channels/deribit_price_index.(index_name)" }, "description": "Send a subscription request to receive deribit_price_index updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/deribit_price_index.(index_name)/messages/subscription_message" } ], "summary": "Client sends subscription request for deribit_price_index updates", "tags": [ { "name": "Market Data" } ], "title": "Send subscribe request for deribit_price_index" }, "send_subscribe_deribit_price_ranking_index_name": { "action": "send", "channel": { "$ref": "#/channels/deribit_price_ranking.(index_name)" }, "description": "Send a subscription request to receive deribit_price_ranking updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/deribit_price_ranking.(index_name)/messages/subscription_message" } ], "summary": "Client sends subscription request for deribit_price_ranking updates", "tags": [ { "name": "Market Data" } ], "title": "Send subscribe request for deribit_price_ranking" }, "send_subscribe_deribit_price_statistics_index_name": { "action": "send", "channel": { "$ref": "#/channels/deribit_price_statistics.(index_name)" }, "description": "Send a subscription request to receive deribit_price_statistics updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/deribit_price_statistics.(index_name)/messages/subscription_message" } ], "summary": "Client sends subscription request for deribit_price_statistics updates", "tags": [ { "name": "Market Data" } ], "title": "Send subscribe request for deribit_price_statistics" }, "send_subscribe_deribit_volatility_index_index_name": { "action": "send", "channel": { "$ref": "#/channels/deribit_volatility_index.(index_name)" }, "description": "Send a subscription request to receive deribit_volatility_index updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/deribit_volatility_index.(index_name)/messages/subscription_message" } ], "summary": "Client sends subscription request for deribit_volatility_index updates", "tags": [ { "name": "Market Data" } ], "title": "Send subscribe request for deribit_volatility_index" }, "send_subscribe_estimated_expiration_price_index_name": { "action": "send", "channel": { "$ref": "#/channels/estimated_expiration_price.(index_name)" }, "description": "Send a subscription request to receive estimated_expiration_price updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/estimated_expiration_price.(index_name)/messages/subscription_message" } ], "summary": "Client sends subscription request for estimated_expiration_price updates", "tags": [ { "name": "Market Data" } ], "title": "Send subscribe request for estimated_expiration_price" }, "send_subscribe_incremental_ticker_instrument_name": { "action": "send", "channel": { "$ref": "#/channels/incremental_ticker.(instrument_name)" }, "description": "Send a subscription request to receive incremental_ticker updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/incremental_ticker.(instrument_name)/messages/subscription_message" } ], "summary": "Client sends subscription request for incremental_ticker updates", "tags": [ { "name": "Market Data" } ], "title": "Send subscribe request for incremental_ticker" }, "send_subscribe_instrument_creation_kind_currency": { "action": "send", "channel": { "$ref": "#/channels/instrument.creation.(kind).(currency)" }, "description": "Send a subscription request to receive instrument updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/instrument.creation.(kind).(currency)/messages/subscription_message" } ], "summary": "Client sends subscription request for instrument updates", "tags": [ { "name": "Market Data" } ], "title": "Send subscribe request for instrument" }, "send_subscribe_instrument_state_kind_currency": { "action": "send", "channel": { "$ref": "#/channels/instrument.state.(kind).(currency)" }, "description": "Send a subscription request to receive instrument updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/instrument.state.(kind).(currency)/messages/subscription_message" } ], "summary": "Client sends subscription request for instrument updates", "tags": [ { "name": "Market Data" } ], "title": "Send subscribe request for instrument" }, "send_subscribe_markprice_options_index_name": { "action": "send", "channel": { "$ref": "#/channels/markprice.options.(index_name)" }, "description": "Send a subscription request to receive markprice updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/markprice.options.(index_name)/messages/subscription_message" } ], "summary": "Client sends subscription request for markprice updates", "tags": [ { "name": "Market Data" } ], "title": "Send subscribe request for markprice" }, "send_subscribe_perpetual_instrument_name_interval": { "action": "send", "channel": { "$ref": "#/channels/perpetual.(instrument_name).(interval)" }, "description": "Send a subscription request to receive perpetual updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/perpetual.(instrument_name).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for perpetual updates", "tags": [ { "name": "Market Data" } ], "title": "Send subscribe request for perpetual" }, "send_subscribe_platform_state": { "action": "send", "channel": { "$ref": "#/channels/platform_state" }, "description": "Send a subscription request to receive platform_state notifications. This channel does not require any additional parameters.", "messages": [ { "$ref": "#/channels/platform_state/messages/subscription_message" } ], "summary": "Client sends subscription request for platform_state", "tags": [ { "name": "Platform" } ], "title": "Send subscribe request" }, "send_subscribe_platform_state_public_methods_state": { "action": "send", "channel": { "$ref": "#/channels/platform_state.public_methods_state" }, "description": "Send a subscription request to receive platform_state notifications. This channel does not require any additional parameters.", "messages": [ { "$ref": "#/channels/platform_state.public_methods_state/messages/subscription_message" } ], "summary": "Client sends subscription request for platform_state", "tags": [ { "name": "Platform" } ], "title": "Send subscribe request" }, "send_subscribe_quote_instrument_name": { "action": "send", "channel": { "$ref": "#/channels/quote.(instrument_name)" }, "description": "Send a subscription request to receive quote updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/quote.(instrument_name)/messages/subscription_message" } ], "summary": "Client sends subscription request for quote updates", "tags": [ { "name": "Market Data" } ], "title": "Send subscribe request for quote" }, "send_subscribe_ticker_instrument_name_interval": { "action": "send", "channel": { "$ref": "#/channels/ticker.(instrument_name).(interval)" }, "description": "Send a subscription request to receive ticker updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/ticker.(instrument_name).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for ticker updates", "tags": [ { "name": "Market Data" } ], "title": "Send subscribe request for ticker" }, "send_subscribe_trades_instrument_name_interval": { "action": "send", "channel": { "$ref": "#/channels/trades.(instrument_name).(interval)" }, "description": "Send a subscription request to receive trades updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/trades.(instrument_name).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for trades updates", "tags": [ { "name": "Trades" }, { "name": "Market Data" } ], "title": "Send subscribe request for trades" }, "send_subscribe_trades_kind_currency_interval": { "action": "send", "channel": { "$ref": "#/channels/trades.(kind).(currency).(interval)" }, "description": "Send a subscription request to receive trades updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/trades.(kind).(currency).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for trades updates", "tags": [ { "name": "Trades" }, { "name": "Market Data" } ], "title": "Send subscribe request for trades" }, "send_subscribe_user_access_log": { "action": "send", "channel": { "$ref": "#/channels/user.access_log" }, "description": "Send a subscription request to receive user notifications. This channel does not require any additional parameters.", "messages": [ { "$ref": "#/channels/user.access_log/messages/subscription_message" } ], "summary": "Client sends subscription request for user", "tags": [ { "name": "User" }, { "name": "Private" } ], "title": "Send subscribe request" }, "send_subscribe_user_changes_instrument_name_interval": { "action": "send", "channel": { "$ref": "#/channels/user.changes.(instrument_name).(interval)" }, "description": "Send a subscription request to receive user updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/user.changes.(instrument_name).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for user updates", "tags": [ { "name": "User" }, { "name": "Private" } ], "title": "Send subscribe request for user" }, "send_subscribe_user_changes_kind_currency_interval": { "action": "send", "channel": { "$ref": "#/channels/user.changes.(kind).(currency).(interval)" }, "description": "Send a subscription request to receive user updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/user.changes.(kind).(currency).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for user updates", "tags": [ { "name": "User" }, { "name": "Private" } ], "title": "Send subscribe request for user" }, "send_subscribe_user_combo_trades_instrument_name_interval": { "action": "send", "channel": { "$ref": "#/channels/user.combo_trades.(instrument_name).(interval)" }, "description": "Send a subscription request to receive user updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/user.combo_trades.(instrument_name).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for user updates", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Trades" } ], "title": "Send subscribe request for user" }, "send_subscribe_user_combo_trades_kind_currency_interval": { "action": "send", "channel": { "$ref": "#/channels/user.combo_trades.(kind).(currency).(interval)" }, "description": "Send a subscription request to receive user updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/user.combo_trades.(kind).(currency).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for user updates", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Trades" } ], "title": "Send subscribe request for user" }, "send_subscribe_user_isolated_changes_instrument_name_interval": { "action": "send", "channel": { "$ref": "#/channels/user.isolated.changes.(instrument_name).(interval)" }, "description": "Send a subscription request to receive isolated state change updates for a specific instrument and interval", "messages": [ { "$ref": "#/channels/user.isolated.changes.(instrument_name).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for isolated state change updates by instrument", "tags": [ { "name": "Trading" }, { "name": "Private" } ], "title": "Send subscribe request for isolated changes by instrument" }, "send_subscribe_user_isolated_changes_kind_currency_interval": { "action": "send", "channel": { "$ref": "#/channels/user.isolated.changes.(kind).(currency).(interval)" }, "description": "Send a subscription request to receive isolated state change updates for a specific kind, currency, and interval", "messages": [ { "$ref": "#/channels/user.isolated.changes.(kind).(currency).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for isolated state change updates by kind and currency", "tags": [ { "name": "Trading" }, { "name": "Private" } ], "title": "Send subscribe request for isolated changes by kind and currency" }, "send_subscribe_user_isolated_liquidation": { "action": "send", "channel": { "$ref": "#/channels/user.isolated.liquidation" }, "description": "Send a subscription request to receive user notifications. This channel does not require any additional parameters.", "messages": [ { "$ref": "#/channels/user.isolated.liquidation/messages/subscription_message" } ], "summary": "Client sends subscription request for user", "tags": [ { "name": "User" }, { "name": "Lsp" }, { "name": "Private" } ], "title": "Send subscribe request" }, "send_subscribe_user_isolated_orders_instrument_name_interval": { "action": "send", "channel": { "$ref": "#/channels/user.isolated.orders.(instrument_name).(interval)" }, "description": "Send a subscription request to receive isolated order updates for a specific instrument and interval", "messages": [ { "$ref": "#/channels/user.isolated.orders.(instrument_name).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for isolated order updates by instrument", "tags": [ { "name": "Trading" }, { "name": "Private" } ], "title": "Send subscribe request for isolated orders by instrument" }, "send_subscribe_user_isolated_orders_kind_currency_interval": { "action": "send", "channel": { "$ref": "#/channels/user.isolated.orders.(kind).(currency).(interval)" }, "description": "Send a subscription request to receive isolated order updates for a specific kind, currency, and interval", "messages": [ { "$ref": "#/channels/user.isolated.orders.(kind).(currency).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for isolated order updates by kind and currency", "tags": [ { "name": "Trading" }, { "name": "Private" } ], "title": "Send subscribe request for isolated orders by kind and currency" }, "send_subscribe_user_isolated_portfolio_currency": { "action": "send", "channel": { "$ref": "#/channels/user.isolated.portfolio.(currency)" }, "description": "Send a subscription request to receive isolated portfolio notifications for a specific currency", "messages": [ { "$ref": "#/channels/user.isolated.portfolio.(currency)/messages/subscription_message" } ], "summary": "Client sends subscription request for isolated portfolio updates", "tags": [ { "name": "Account Management" }, { "name": "Private" } ], "title": "Send subscribe request for isolated portfolio" }, "send_subscribe_user_isolated_trades_instrument_name_interval": { "action": "send", "channel": { "$ref": "#/channels/user.isolated.trades.(instrument_name).(interval)" }, "description": "Send a subscription request to receive isolated trade updates for a specific instrument and interval", "messages": [ { "$ref": "#/channels/user.isolated.trades.(instrument_name).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for isolated trade updates by instrument", "tags": [ { "name": "Trading" }, { "name": "Private" } ], "title": "Send subscribe request for isolated trades by instrument" }, "send_subscribe_user_isolated_trades_kind_currency_interval": { "action": "send", "channel": { "$ref": "#/channels/user.isolated.trades.(kind).(currency).(interval)" }, "description": "Send a subscription request to receive isolated trade updates for a specific kind, currency, and interval", "messages": [ { "$ref": "#/channels/user.isolated.trades.(kind).(currency).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for isolated trade updates by kind and currency", "tags": [ { "name": "Trading" }, { "name": "Private" } ], "title": "Send subscribe request for isolated trade updates by kind and currency" }, "send_subscribe_user_lock": { "action": "send", "channel": { "$ref": "#/channels/user.lock" }, "description": "Send a subscription request to receive user notifications. This channel does not require any additional parameters.", "messages": [ { "$ref": "#/channels/user.lock/messages/subscription_message" } ], "summary": "Client sends subscription request for user", "tags": [ { "name": "User" }, { "name": "Private" } ], "title": "Send subscribe request" }, "send_subscribe_user_orders_instrument_name_interval": { "action": "send", "channel": { "$ref": "#/channels/user.orders.(instrument_name).(interval)" }, "description": "Send a subscription request to receive user updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/user.orders.(instrument_name).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for user updates", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Orders" } ], "title": "Send subscribe request for user" }, "send_subscribe_user_orders_instrument_name_raw": { "action": "send", "channel": { "$ref": "#/channels/user.orders.(instrument_name).raw" }, "description": "Send a subscription request to receive user updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/user.orders.(instrument_name).raw/messages/subscription_message" } ], "summary": "Client sends subscription request for user updates", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Orders" } ], "title": "Send subscribe request for user" }, "send_subscribe_user_orders_kind_currency_interval": { "action": "send", "channel": { "$ref": "#/channels/user.orders.(kind).(currency).(interval)" }, "description": "Send a subscription request to receive user updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/user.orders.(kind).(currency).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for user updates", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Orders" } ], "title": "Send subscribe request for user" }, "send_subscribe_user_orders_kind_currency_raw": { "action": "send", "channel": { "$ref": "#/channels/user.orders.(kind).(currency).raw" }, "description": "Send a subscription request to receive user updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/user.orders.(kind).(currency).raw/messages/subscription_message" } ], "summary": "Client sends subscription request for user updates", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Orders" } ], "title": "Send subscribe request for user" }, "send_subscribe_user_portfolio_currency": { "action": "send", "channel": { "$ref": "#/channels/user.portfolio.(currency)" }, "description": "Send a subscription request to receive user updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/user.portfolio.(currency)/messages/subscription_message" } ], "summary": "Client sends subscription request for user updates", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Portfolio" } ], "title": "Send subscribe request for user" }, "send_subscribe_user_position_lock": { "action": "send", "channel": { "$ref": "#/channels/user.position_lock" }, "description": "Send a subscription request to receive position lock notifications", "messages": [ { "$ref": "#/channels/user.position_lock/messages/subscription_message" } ], "summary": "Client sends subscription request for user position lock", "tags": [ { "name": "User" }, { "name": "Private" } ], "title": "Send subscribe request for position lock" }, "send_subscribe_user_trades_instrument_name_interval": { "action": "send", "channel": { "$ref": "#/channels/user.trades.(instrument_name).(interval)" }, "description": "Send a subscription request to receive user updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/user.trades.(instrument_name).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for user updates", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Trades" } ], "title": "Send subscribe request for user" }, "send_subscribe_user_trades_kind_currency_interval": { "action": "send", "channel": { "$ref": "#/channels/user.trades.(kind).(currency).(interval)" }, "description": "Send a subscription request to receive user updates for a specific instrument with specified interval", "messages": [ { "$ref": "#/channels/user.trades.(kind).(currency).(interval)/messages/subscription_message" } ], "summary": "Client sends subscription request for user updates", "tags": [ { "name": "User" }, { "name": "Private" }, { "name": "Trades" } ], "title": "Send subscribe request for user" }, "send_subscribe_user_trailing_orders_trigger_price_currency": { "action": "send", "channel": { "$ref": "#/channels/user.trailing_orders.trigger_price.(currency)" }, "description": "Send a subscription request to receive trailing order trigger price updates for a specific currency", "messages": [ { "$ref": "#/channels/user.trailing_orders.trigger_price.(currency)/messages/subscription_message" } ], "summary": "Client sends subscription request for trailing order trigger price updates", "tags": [ { "name": "Trading" }, { "name": "Private" } ], "title": "Send subscribe request for trailing orders" } }, "servers": { "private": { "description": "Main WebSocket. HTTP methods, and after public/auth, private/subscribe for user channels.", "host": "drb.coinbase.com/ws/api/v2", "protocol": "wss" }, "public": { "description": "Public WebSocket. Unauthenticated public/subscribe only.", "host": "streams.drb.coinbase.com/ws/api/v2", "protocol": "wss" } } }