openapi: 3.0.0
info:
title: Deribit Account Management Matching Engine API
version: 2.1.1
servers:
- url: https://test.deribit.com/api/v2
tags:
- name: Matching Engine
paths:
/private/simulate_block_trade:
get:
parameters:
- in: query
name: role
required: false
schema:
$ref: '#/components/schemas/role'
description: Describes if user wants to be maker or taker of trades
- in: query
name: trades
required: true
schema:
type: array
items:
type: object
properties:
instrument_name:
$ref: '#/components/schemas/instrument_name'
description: Instrument name
price:
type: number
description: Price for trade
amount:
$ref: '#/components/schemas/amount'
description: It represents the requested trade size. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.
direction:
$ref: '#/components/schemas/direction'
description: Direction of trade from the maker perspective
description: List of trades for block trade
style: form
explode: true
responses:
'200':
$ref: '#/components/responses/PrivateSimulateBlockTradeResponse'
tags:
- Matching Engine
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 1
method: private/simulate_block_trade
params:
role: maker
trades:
- instrument_name: BTC-PERPETUAL
direction: buy
price: 11624
amount: 40
- instrument_name: BTC-9AUG19-10250-P
direction: buy
amount: 1.2
price: 0.0707
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Checks if a block trade can be executed without actually executing it. Use this method to verify that a block trade will succeed before proceeding with the actual execution.
**📖 Related Article:** [Block Trading](https://docs.deribit.com/articles/block-trading-api)
**Scope:** `block_trade:read`
[Try in API console](https://test.deribit.com/api_console?method=%2Fprivate%2Fsimulate_block_trade)
'
x-mint:
metadata:
title: private/simulate_block_trade
og:title: private/simulate_block_trade
keywords:
- private/simulate_block_trade
- role
- trades
href: /api-reference/block-trade/private-simulate_block_trade
/private/verify_block_trade:
get:
parameters:
- in: query
name: timestamp
required: true
schema:
$ref: '#/components/schemas/timestamp'
description: Timestamp, shared with other party (milliseconds since the UNIX epoch)
- in: query
name: nonce
required: true
schema:
$ref: '#/components/schemas/nonce'
description: Nonce, shared with other party
- in: query
name: role
required: true
schema:
$ref: '#/components/schemas/role'
description: Describes if user wants to be maker or taker of trades
- in: query
name: trades
required: true
schema:
type: array
items:
type: object
properties:
instrument_name:
$ref: '#/components/schemas/instrument_name'
description: Instrument name
price:
type: number
description: Price for trade
amount:
$ref: '#/components/schemas/amount'
description: It represents the requested trade size. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.
direction:
$ref: '#/components/schemas/direction'
description: Direction of trade from the maker perspective
description: List of trades for block trade
style: form
explode: true
responses:
'200':
$ref: '#/components/responses/PrivateVerifyBlockTradeResponse'
tags:
- Matching Engine
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 1
method: private/verify_block_trade
params:
nonce: okpdjkdo
timestamp: 1565172650935
role: maker
trades:
- instrument_name: BTC-PERPETUAL
direction: buy
price: 11624
amount: 40
- instrument_name: BTC-9AUG19-10250-P
direction: buy
amount: 1.2
price: 0.0707
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Verifies and creates a block trade signature. This is the first step in the block trade workflow - the first party calls this method to generate a signature that must be shared with the second party.
**Note:** In the API, the `direction` field is always expressed from the maker''s perspective. This means that when you accept a block trade as a taker, the direction shown in the API represents the opposite side of your trade. For example, if you are buying puts as a taker, the API will show the operation as a "sell put" (maker''s perspective), and you will be verifying and accepting a "sell put" block trade.
**📖 Related Article:** [Block Trading](https://docs.deribit.com/articles/block-trading-api)
**Scope:** `block_trade:read`
[Try in API console](https://test.deribit.com/api_console?method=%2Fprivate%2Fverify_block_trade)
'
x-mint:
metadata:
title: private/verify_block_trade
og:title: private/verify_block_trade
keywords:
- private/verify_block_trade
- timestamp
- nonce
- role
- trades
- signature
href: /api-reference/block-trade/private-verify_block_trade
/private/execute_block_trade:
get:
parameters:
- in: query
name: timestamp
required: true
schema:
$ref: '#/components/schemas/timestamp'
description: Timestamp, shared with other party (milliseconds since the UNIX epoch)
- in: query
name: nonce
required: true
schema:
$ref: '#/components/schemas/nonce'
description: Nonce, shared with other party
- in: query
name: role
required: true
schema:
$ref: '#/components/schemas/role'
description: Describes if user wants to be maker or taker of trades
- in: query
name: trades
required: true
schema:
type: array
items:
type: object
properties:
instrument_name:
$ref: '#/components/schemas/instrument_name'
description: Instrument name
price:
type: number
description: Price for trade
amount:
$ref: '#/components/schemas/amount'
description: It represents the requested trade size. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.
direction:
$ref: '#/components/schemas/direction'
description: Direction of trade from the maker perspective
description: List of trades for block trade
style: form
explode: true
- in: query
name: counterparty_signature
required: true
schema:
$ref: '#/components/schemas/block_trade_signature'
description: Signature of block trade generated by `private/verify_block_trade_method`
responses:
'200':
$ref: '#/components/responses/PrivateGetBlockTradeResponse'
tags:
- Matching Engine
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 1
method: private/execute_block_trade
params:
nonce: bszyprbq
timestamp: 1590485535899
role: maker
trades:
- instrument_name: BTC-PERPETUAL
direction: sell
price: 8900
amount: 200000
- instrument_name: BTC-28MAY20-9000-C
direction: sell
amount: 5
price: 0.0133
counterparty_signature: 1590485595899.1Mn52L_Q.lNyNBzXXo-_QBT_wDuMgnhA7uS9tBqdQ5TLN6rxbuoAiQhyaJYGJrm5IV_9enp9niY_x8D60AJLm3yEKPUY1Dv3T0TW0n5-ADPpJF7Fpj0eVDZpZ6QCdX8snBWrSJ0TtqevnO64RCBlN1dIm2T70PP9dlhiqPDAUYI4fpB1vLYI
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Executes a block trade. This is the second step in the block trade workflow - the second party calls this method with the signature received from the first party to execute the trade.
The whole request must be exactly the same as in [private/verify_block_trade](https://docs.deribit.com/api-reference/block-trade/private-verify_block_trade), only the `role` field should be set appropriately - this means that both sides have to agree on the same `timestamp`, `nonce`, and `trades` fields, and the server will ensure that the `role` field is different between sides (each party accepts their own role).
Using the same `timestamp` and `nonce` by both sides in [private/verify_block_trade](https://docs.deribit.com/api-reference/block-trade/private-verify_block_trade) ensures that even if unintentionally both sides execute the given block trade with a valid `counterparty_signature`, the block trade will be executed only once.
**Note:** In the API, the `direction` field is always expressed from the maker''s perspective. This means that when you accept a block trade as a taker, the direction shown in the API represents the opposite side of your trade. For example, if you are buying puts as a taker, the API will show the operation as a "sell put" (maker''s perspective), and you will be verifying and accepting a "sell put" block trade.
**📖 Related Article:** [Block Trading](https://docs.deribit.com/articles/block-trading-api)
**Scope:** `block_trade:read_write`
[Try in API console](https://test.deribit.com/api_console?method=%2Fprivate%2Fexecute_block_trade)
'
x-mint:
metadata:
title: private/execute_block_trade
og:title: private/execute_block_trade
keywords:
- private/execute_block_trade
- timestamp
- nonce
- role
- trades
- counterparty_signature
- app_name
- broker_code
- broker_name
- trade_id
- trade_seq
- instrument_name
- order_type
- advanced
- order_id
- matching_id
- direction
- tick_direction
- index_price
- price
- amount
- contracts
- iv
- underlying_price
- liquidation
- liquidity
- fee
- fee_currency
- label
- state
- block_trade_id
- block_rfq_id
- block_rfq_quote_id
- reduce_only
- post_only
- mmp
- risk_reducing
- api
- profit_loss
- mark_price
- legs
- combo_id
- combo_trade_id
- quote_set_id
- quote_id
- trade_allocations
- user_id
- client_info
- client_id
- client_link_id
- name
href: /api-reference/block-trade/private-execute_block_trade
/private/create_combo:
get:
parameters:
- in: query
name: trades
required: true
schema:
type: array
items:
type: object
properties:
instrument_name:
$ref: '#/components/schemas/instrument_name'
amount:
$ref: '#/components/schemas/amount'
direction:
$ref: '#/components/schemas/direction'
description: List of trades used to create a combo
style: form
explode: true
responses:
'200':
$ref: '#/components/responses/PrivateCreateComboResponse'
tags:
- Matching Engine
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 6
method: private/create_combo
params:
trades:
- instrument_name: BTC-29APR22-37500-C
amount: '1'
direction: buy
- instrument_name: BTC-29APR22-37500-P
amount: '1'
direction: sell
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Verifies and creates a combo book or returns an existing combo matching the given trades. Combos allow trading on multiple instruments (futures and options) simultaneously as a single strategy.
If a combo matching the provided trades already exists, this method returns the existing combo. Otherwise, it creates a new combo book with the specified leg structure.
**Scope:** `trade:read_write`
[Try in API console](https://test.deribit.com/api_console?method=%2Fprivate%2Fcreate_combo)
'
x-mint:
metadata:
title: private/create_combo
og:title: private/create_combo
keywords:
- private/create_combo
- trades
- instrument_id
- state
- state_timestamp
- creation_timestamp
- legs
- instrument_name
- amount
href: /api-reference/combo-books/private-create_combo
/private/cancel_all:
get:
parameters:
- name: detailed
required: false
in: query
schema:
type: boolean
description: 'When `detailed` is set to `true`, the output format is changed to include a list of all cancelled orders.
**📖 Related Article:** [Detailed Response for Cancel Methods](https://docs.deribit.com/articles/json-rpc-overview#detailed-response-for-cancel-methods)
Default: `false`
'
- name: freeze_quotes
required: false
in: query
schema:
type: boolean
description: Whether or not to reject incoming quotes for 1 second after cancelling (`false` by default). Related to `private/mass_quote` request.
responses:
'200':
$ref: '#/components/responses/PrivateCancelAllResponse'
tags:
- Matching Engine
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 8748
method: private/cancel_all
params: {}
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Cancels all open orders and trigger orders for the authenticated account across all currencies and instrument kinds. This is a bulk cancellation operation useful for quickly clearing all active orders.
Use the `detailed` parameter to receive a list of all cancelled orders. The `freeze_quotes` parameter can be used to freeze quotes instead of cancelling them.
**Note:** This operation cannot be undone. All open orders will be permanently cancelled.
**Scope:** `trade:read_write`
[Try in API console](https://test.deribit.com/api_console?method=%2Fprivate%2Fcancel_all)
'
x-mint:
metadata:
title: private/cancel_all
og:title: private/cancel_all
keywords:
- private/cancel_all
- detailed
- freeze_quotes
href: /api-reference/trading/private-cancel_all
/private/cancel_all_by_instrument:
get:
parameters:
- name: instrument_name
required: true
in: query
schema:
$ref: '#/components/schemas/instrument_name'
description: Instrument name
- name: type
required: false
in: query
schema:
$ref: '#/components/schemas/simple_order_type'
description: Order type - `limit`, `stop`, `take`, `trigger_all` or `all`, default - `all`
- name: detailed
required: false
in: query
schema:
type: boolean
description: 'When `detailed` is set to `true`, the output format is changed to include a list of all cancelled orders.
**📖 Related Article:** [Detailed Response for Cancel Methods](https://docs.deribit.com/articles/json-rpc-overview#detailed-response-for-cancel-methods)
Default: `false`
'
- name: include_combos
required: false
in: query
schema:
type: boolean
description: 'When set to `true` orders in combo instruments affecting a given position will also be cancelled. Default: `false`'
- name: freeze_quotes
required: false
in: query
schema:
type: boolean
description: Whether or not to reject incoming quotes for 1 second after cancelling (`false` by default). Related to `private/mass_quote` request.
responses:
'200':
$ref: '#/components/responses/PrivateCancelAllResponse'
tags:
- Matching Engine
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 4122
method: private/cancel_all_by_instrument
params:
instrument_name: ETH-22FEB19-120-P
type: all
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Cancels all open orders for a specific instrument. This is useful for quickly clearing all orders for a single instrument.
Orders can be optionally filtered by order type (limit, market, stop, etc.). Use the `detailed` parameter to receive a list of all cancelled orders. The `include_combos` parameter can be used to include combo orders in the cancellation.
**Scope:** `trade:read_write`
[Try in API console](https://test.deribit.com/api_console?method=%2Fprivate%2Fcancel_all_by_instrument)
'
x-mint:
metadata:
title: private/cancel_all_by_instrument
og:title: private/cancel_all_by_instrument
keywords:
- private/cancel_all_by_instrument
- instrument_name
- type
- detailed
- include_combos
- freeze_quotes
href: /api-reference/trading/private-cancel_all_by_instrument
/private/cancel_all_by_currency:
get:
parameters:
- name: currency
required: true
in: query
schema:
$ref: '#/components/schemas/currency'
description: The currency symbol
- name: kind
required: false
in: query
schema:
$ref: '#/components/schemas/kind_with_combo_all'
description: Instrument kind, `"combo"` for any combo or `"any"` for all. If not provided instruments of all kinds are considered
- name: type
required: false
in: query
schema:
$ref: '#/components/schemas/simple_order_type'
description: Order type - `limit`, `stop`, `take`, `trigger_all` or `all`, default - `all`
- name: detailed
required: false
in: query
schema:
type: boolean
description: 'When `detailed` is set to `true`, the output format is changed to include a list of all cancelled orders.
**📖 Related Article:** [Detailed Response for Cancel Methods](https://docs.deribit.com/articles/json-rpc-overview#detailed-response-for-cancel-methods)
Default: `false`
'
- name: freeze_quotes
required: false
in: query
schema:
type: boolean
description: Whether or not to reject incoming quotes for 1 second after cancelling (`false` by default). Related to `private/mass_quote` request.
responses:
'200':
$ref: '#/components/responses/PrivateCancelAllResponse'
tags:
- Matching Engine
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 5663
method: private/cancel_all_by_currency
params:
currency: BTC
kind: option
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Cancels all open orders for a specific currency. This is useful for quickly clearing all orders across multiple instruments in a currency.
Orders can be optionally filtered by instrument kind (future, option, etc.) and/or order type (limit, market, stop, etc.). Use the `detailed` parameter to receive a list of all cancelled orders.
**Scope:** `trade:read_write`
[Try in API console](https://test.deribit.com/api_console?method=%2Fprivate%2Fcancel_all_by_currency)
'
x-mint:
metadata:
title: private/cancel_all_by_currency
og:title: private/cancel_all_by_currency
keywords:
- private/cancel_all_by_currency
- currency
- kind
- type
- detailed
- freeze_quotes
href: /api-reference/trading/private-cancel_all_by_currency
/private/cancel_all_by_currency_pair:
get:
parameters:
- name: currency_pair
required: true
in: query
schema:
$ref: '#/components/schemas/index_name'
description: The currency pair symbol
- name: kind
required: false
in: query
schema:
$ref: '#/components/schemas/kind_with_combo_all'
description: Instrument kind, `"combo"` for any combo or `"any"` for all. If not provided instruments of all kinds are considered
- name: type
required: false
in: query
schema:
$ref: '#/components/schemas/simple_order_type'
description: Order type - `limit`, `stop`, `take`, `trigger_all` or `all`, default - `all`
- name: detailed
required: false
in: query
schema:
type: boolean
description: 'When `detailed` is set to `true`, the output format is changed to include a list of all cancelled orders.
**📖 Related Article:** [Detailed Response for Cancel Methods](https://docs.deribit.com/articles/json-rpc-overview#detailed-response-for-cancel-methods)
Default: `false`
'
- name: freeze_quotes
required: false
in: query
schema:
type: boolean
description: Whether or not to reject incoming quotes for 1 second after cancelling (`false` by default). Related to `private/mass_quote` request.
responses:
'200':
$ref: '#/components/responses/PrivateCancelAllResponse'
tags:
- Matching Engine
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 5663
method: private/cancel_all_by_currency_pair
params:
currency_pair: BTC_USD
kind: option
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Cancels all open orders for a specific currency pair. This is useful for quickly clearing all orders across instruments in a currency pair.
Orders can be optionally filtered by instrument kind (future, option, etc.) and/or order type (limit, market, stop, etc.). Use the `detailed` parameter to receive a list of all cancelled orders.
**Scope:** `trade:read_write`
[Try in API console](https://test.deribit.com/api_console?method=%2Fprivate%2Fcancel_all_by_currency_pair)
'
x-mint:
metadata:
title: private/cancel_all_by_currency_pair
og:title: private/cancel_all_by_currency_pair
keywords:
- private/cancel_all_by_currency_pair
- currency_pair
- kind
- type
- detailed
- freeze_quotes
href: /api-reference/trading/private-cancel_all_by_currency_pair
/private/cancel_all_by_kind_or_type:
get:
parameters:
- name: currency
required: true
in: query
schema:
$ref: '#/components/schemas/currency_with_any_and_list'
description: The currency symbol, list of currency symbols or `"any"` for all
- name: kind
required: false
in: query
schema:
$ref: '#/components/schemas/kind_with_combo_all'
description: Instrument kind, `"combo"` for any combo or `"any"` for all. If not provided instruments of all kinds are considered
- name: type
required: false
in: query
schema:
$ref: '#/components/schemas/simple_order_type'
description: Order type - `limit`, `stop`, `take`, `trigger_all` or `all`, default - `all`
- name: detailed
required: false
in: query
schema:
type: boolean
description: 'When `detailed` is set to `true`, the output format is changed to include a list of all cancelled orders.
**📖 Related Article:** [Detailed Response for Cancel Methods](https://docs.deribit.com/articles/json-rpc-overview#detailed-response-for-cancel-methods)
Default: `false`
'
- name: freeze_quotes
required: false
in: query
schema:
type: boolean
description: Whether or not to reject incoming quotes for 1 second after cancelling (`false` by default). Related to `private/mass_quote` request.
responses:
'200':
$ref: '#/components/responses/PrivateCancelAllResponse'
tags:
- Matching Engine
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 2
method: private/cancel_all_by_kind_or_type
params:
currency:
- BTC
- ETH
kind: future
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Cancels all open orders in one or more currencies, optionally filtered by instrument kind and/or order type. This provides flexible bulk cancellation across multiple currencies.
Specify one or more currencies, and optionally filter by instrument kind (future, option, etc.) and/or order type (limit, market, stop, etc.). Use the `detailed` parameter to receive a list of all cancelled orders.
**Scope:** `trade:read_write`
[Try in API console](https://test.deribit.com/api_console?method=%2Fprivate%2Fcancel_all_by_kind_or_type)
'
x-mint:
metadata:
title: private/cancel_all_by_kind_or_type
og:title: private/cancel_all_by_kind_or_type
keywords:
- private/cancel_all_by_kind_or_type
- currency
- kind
- type
- detailed
- freeze_quotes
href: /api-reference/trading/private-cancel_all_by_kind_or_type
/private/cancel_by_label:
get:
parameters:
- name: label
in: query
schema:
type: string
required: true
description: user defined label for the order (maximum 64 characters)
- in: query
name: currency
required: false
schema:
$ref: '#/components/schemas/currency'
description: The currency symbol
responses:
'200':
$ref: '#/components/responses/PrivateCancelAllResponse'
tags:
- Matching Engine
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 47
method: private/cancel_by_label
params:
label: label
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Cancels all orders (including trigger orders) that have a specific label. This is useful for managing groups of related orders that share the same label.
Orders can be cancelled across all currencies or filtered to a specific currency. When cancelling by currency, the currency queue is used for processing.
**Rate Limits:** When called without the `currency` parameter, this method is subject to `cancel_all` rate limits. Different rate limit values may apply for per-currency cancels versus calls without providing the currency parameter.
**Scope:** `trade:read_write`
[Try in API console](https://test.deribit.com/api_console?method=%2Fprivate%2Fcancel_by_label)
'
x-mint:
metadata:
title: private/cancel_by_label
og:title: private/cancel_by_label
keywords:
- private/cancel_by_label
- label
- currency
href: /api-reference/trading/private-cancel_by_label
/private/cancel_quotes:
get:
parameters:
- name: detailed
required: false
in: query
schema:
type: boolean
description: 'When `detailed` is set to `true`, the output format is changed to include a list of all cancelled orders.
**📖 Related Article:** [Detailed Response for Cancel Methods](https://docs.deribit.com/articles/json-rpc-overview#detailed-response-for-cancel-methods)
Default: `false`
'
- name: freeze_quotes
required: false
in: query
schema:
type: boolean
description: Whether or not to reject incoming quotes for 1 second after cancelling (`false` by default). Related to `private/mass_quote` request.
- name: cancel_type
in: query
schema:
enum:
- delta
- quote_set_id
- instrument
- instrument_kind
- currency
- currency_pair
- all
type: string
example: delta
required: true
description: Type of cancel criteria.
- name: min_delta
in: query
schema:
type: number
example: 0.4
required: false
description: 'Min delta to cancel by delta (for `cancel_type`: `delta`).'
- name: max_delta
in: query
schema:
type: number
example: 0.6
required: false
description: 'Max delta to cancel by delta (for `cancel_typ
# --- truncated at 32 KB (181 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/deribit/refs/heads/main/openapi/deribit-matching-engine-api-openapi.yml