openapi: 3.0.0
info:
title: Deribit Account Management Public API
version: 2.1.1
description: Public methods can be used without authentication.
servers:
- url: https://test.deribit.com/api/v2
tags:
- name: Public
description: Public methods can be used without authentication.
paths:
/public/get_announcements:
get:
parameters:
- name: start_timestamp
in: query
schema:
$ref: '#/components/schemas/timestamp'
default: Current time
description: The most recent timestamp to return the results for (milliseconds since the UNIX epoch)
required: false
- name: count
in: query
schema:
type: integer
default: 5
example: 10
maximum: 50
minimum: 1
description: Maximum count of returned announcements, default - `5`, maximum - `50`
required: false
responses:
'200':
$ref: '#/components/responses/PublicGetAnnouncementsResponse'
tags:
- Public
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 7661
method: public/get_announcements
params: {}
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Retrieves platform announcements and important notices. Announcements include system updates, maintenance schedules, new features, policy changes, and other important information.
Results are returned in reverse chronological order (newest first). The default `start_timestamp` is the current time, and the `count` parameter must be between 1 and 50 (default is 5).
[Try in API console](https://test.deribit.com/api_console?method=%2Fpublic%2Fget_announcements)
'
x-mint:
metadata:
title: public/get_announcements
og:title: public/get_announcements
keywords:
- public/get_announcements
- start_timestamp
- count
- body
- publication_timestamp
- important
- confirmation
- title
href: /api-reference/account-management/public-get_announcements
/public/auth:
get:
tags:
- Public
parameters:
- name: grant_type
in: query
schema:
type: string
enum:
- client_credentials
- client_signature
- refresh_token
example: client_credentials
required: true
description: Method of authentication
- name: client_id
in: query
schema:
type: string
example: fo7WAPRm4P
required: true
description: Required for grant type `` `client_credentials` `` and `` `client_signature` ``
- name: client_secret
in: query
schema:
type: string
example: W0H6FJW4IRPZ1MOQ8FP6KMC5RZDUUKXS
required: true
description: Required for grant type `` `client_credentials` ``
- name: refresh_token
in: query
schema:
type: string
required: true
description: Required for grant type `` `refresh_token` ``
- name: timestamp
in: query
schema:
type: integer
required: true
description: 'Required for grant type `` `client_signature` ``.
Provides time when request has been generated (milliseconds since the UNIX epoch).
'
- name: signature
in: query
schema:
type: string
required: true
description: 'Required for grant type `` `client_signature` ``.
It''s a cryptographic signature calculated over provided fields using user **secret key**. The signature should be calculated as an HMAC (Hash-based Message Authentication Code) with `` `SHA256` `` hash algorithm.
'
- name: nonce
in: query
schema:
type: string
description: 'Optional for grant type `` `client_signature` ``.
Delivers user generated initialization vector for the server token.
'
required: false
- name: data
in: query
schema:
type: string
description: 'Optional for grant type `` `client_signature` ``.
Contains any user specific value.
'
required: false
- name: state
in: query
schema:
type: string
description: Will be passed back in the response.
required: false
- name: scope
in: query
schema:
type: string
example: connection
description: 'Describes type of the access for assigned token.
**Possible values:**
- `` `connection` ``
- `` `session:name` ``
- `` `trade:[read, read_write, none]` ``
- `` `wallet:[read, read_write, none]` ``
- `` `account:[read, read_write, none]` ``
- `` `expires:NUMBER` ``
- `` `ip:ADDR` ``
Details are elucidated in [Access scope](https://docs.deribit.com/articles/access-scope)
'
required: false
responses:
'200':
$ref: '#/components/responses/PublicAuthResponse'
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 9929
method: public/auth
params:
grant_type: client_credentials
client_id: fo7WAPRm4P
client_secret: W0H6FJW4IRPZ1MOQ8FP6KMC5RZDUUKXS
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Retrieve an OAuth access token, to be used for authentication of ''private'' requests.
**📖 Related Article:** [Authentication](https://docs.deribit.com/articles/authentication)
**Authentication Methods:**
Three methods of authentication are supported:
- ``client_credentials`` - Using the client id and client secret that can be found on the API page on the website. This is the simplest method, suitable for server-to-server applications and quick setup.
- ``client_signature`` - Enhanced security method that uses a cryptographic signature instead of sending the client secret directly. You generate an HMAC-SHA256 signature of a string containing a timestamp, a random nonce, and optional data, using your Client Secret as the key. This method requires `` `client_id` ``, `` `timestamp` `` (current time in milliseconds), `` `nonce` ``, `` `signature` ``, and optionally a `` `data` `` field. Deribit verifies the signature instead of requiring the raw secret. Best for enhanced security, asymmetric key pairs, and avoiding secret transmission. See the [Client Signature (WebSocket) guide](https://docs.deribit.com/articles/authentication#client-signature-websocket) for detailed signature calculation instructions.
- ``refresh_token`` - Using a refresh token that was received from an earlier invocation. This allows you to obtain a new access token without re-supplying your Client ID and Client Secret. Best for long-lived sessions, token renewal, and avoiding re-authentication.
**Response:**
The response will contain an access token, expiration period (number of seconds that the token is valid) and a refresh token that can be used to get a new set of tokens.
[Try in API console](https://test.deribit.com/api_console?method=%2Fpublic%2Fauth)
'
x-mint:
metadata:
title: public/auth
og:title: public/auth
keywords:
- public/auth
- grant_type
- client_id
- client_secret
- refresh_token
- timestamp
- signature
- nonce
- data
- state
- scope
- access_token
- token_type
- expires_in
- sid
- enabled_features
- mandatory_tfa_status
- google_login
href: /api-reference/authentication/public-auth
/public/exchange_token:
get:
tags:
- Public
parameters:
- name: refresh_token
in: query
schema:
type: string
example: 1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ
required: true
description: Refresh token
- name: subject_id
in: query
schema:
type: integer
example: 10
required: true
description: New subject id
- name: scope
in: query
schema:
type: string
required: false
description: Optional scope override for the new session. Cannot exceed caller's permissions. Supports `session` scope for direct session creation during token exchange.
responses:
'200':
$ref: '#/components/responses/PublicTokenResponse'
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 7619
method: public/exchange_token
params:
refresh_token: 1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ
subject_id: 10
description: JSON-RPC Request Example
description: JSON-RPC request body
description: "Generates a token for a new subject id. This method can be used to switch between subaccounts.\n\n**\U0001F4D6 Related Articles:** \n- [Fork and Exchange Tokens](https://docs.deribit.com/articles/authentication#fork-and-exchange-tokens)\n- [Managing Subaccounts](https://docs.deribit.com/articles/managing-subaccounts-api)\n\n[Try in API console](https://test.deribit.com/api_console?method=%2Fpublic%2Fexchange_token)\n\n"
x-mint:
metadata:
title: public/exchange_token
og:title: public/exchange_token
keywords:
- public/exchange_token
- refresh_token
- subject_id
- scope
- access_token
- token_type
- expires_in
- sid
href: /api-reference/authentication/public-exchange_token
/public/fork_token:
get:
tags:
- Public
parameters:
- name: refresh_token
in: query
schema:
type: string
example: 1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ
required: true
description: Refresh token
- name: session_name
in: query
schema:
type: string
example: forked_session_name
required: true
description: New session name
responses:
'200':
$ref: '#/components/responses/PublicTokenResponse'
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 7620
method: public/fork_token
params:
refresh_token: 1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ
session_name: forked_session_name
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Generates a token for a new named session. This method can be used only with session scoped tokens.
**📖 More Details:** [Fork and Exchange Tokens](https://docs.deribit.com/articles/authentication#fork-and-exchange-tokens)
[Try in API console](https://test.deribit.com/api_console?method=%2Fpublic%2Ffork_token)
'
x-mint:
metadata:
title: public/fork_token
og:title: public/fork_token
keywords:
- public/fork_token
- refresh_token
- session_name
- access_token
- token_type
- expires_in
- scope
- sid
href: /api-reference/authentication/public-fork_token
/public/get_block_rfq_trades:
get:
parameters:
- name: currency
required: true
in: query
schema:
$ref: '#/components/schemas/currency_with_any'
description: The currency symbol or `"any"` for all
- name: continuation
in: query
required: false
schema:
type: string
example: 1738050297271:103
description: Continuation token for pagination. Consists of `timestamp` and `block_rfq_id`.
- name: count
in: query
required: false
schema:
type: integer
maximum: 1000
minimum: 1
description: Count of Block RFQs returned, maximum - `1000`
responses:
'200':
$ref: '#/components/responses/PublicGetBlockRfqTradesResponse'
tags:
- Public
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 1
method: public/get_block_rfq_trades
params:
currency: BTC
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Returns a list of recent Block RFQ trades. Can be optionally filtered by currency.
This is a public method that provides market data about completed Block RFQ trades. For private Block RFQ information, use [private/get_block_rfqs](https://docs.deribit.com/api-reference/block-rfq/private-get_block_rfqs).
**📖 Related Article:** [Deribit Block RFQ API walkthrough](https://docs.deribit.com/articles/block-rfq-api-walkthrough)
[Try in API console](https://test.deribit.com/api_console?method=%2Fpublic%2Fget_block_rfq_trades)
'
x-mint:
metadata:
title: public/get_block_rfq_trades
og:title: public/get_block_rfq_trades
keywords:
- public/get_block_rfq_trades
- currency
- continuation
- count
- block_rfqs
- timestamp
- direction
- amount
- mark_price
- legs
- combo_id
- hedge
- index_prices
- trades
- ratio
- instrument_name
- price
- hedge_amount
href: /api-reference/block-rfq/public-get_block_rfq_trades
/public/get_combos:
get:
tags:
- Public
parameters:
- name: currency
required: true
in: query
schema:
$ref: '#/components/schemas/currency_with_any'
description: The currency symbol or `"any"` for all
responses:
'200':
$ref: '#/components/responses/PublicGetCombosResponse'
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 2
method: public/get_combos
params:
currency: BTC
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Retrieves information about active combos for the specified currency. Returns detailed information including leg structures and combo properties.
For a list of combo IDs only, use [public/get_combo_ids](https://docs.deribit.com/api-reference/combo-books/public-get_combo_ids). For details about a specific combo, use [public/get_combo_details](https://docs.deribit.com/api-reference/combo-books/public-get_combo_details).
[Try in API console](https://test.deribit.com/api_console?method=%2Fpublic%2Fget_combos)
'
x-mint:
metadata:
title: public/get_combos
og:title: public/get_combos
keywords:
- public/get_combos
- currency
- instrument_id
- state
- state_timestamp
- creation_timestamp
- legs
- instrument_name
- amount
href: /api-reference/combo-books/public-get_combos
/public/get_combo_ids:
get:
tags:
- Public
parameters:
- name: currency
required: true
in: query
schema:
$ref: '#/components/schemas/currency'
description: The currency symbol
- name: state
required: false
in: query
schema:
$ref: '#/components/schemas/combo_state'
description: Combo state, if not provided combos of all states are considered
responses:
'200':
$ref: '#/components/responses/PublicGetComboIdsResponse'
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 1
method: public/get_combo_ids
params:
currency: BTC
state: active
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Retrieves available combo IDs. This method can be used to get the list of all combos, or only the list of combos in the given state.
Use [public/get_combo_details](https://docs.deribit.com/api-reference/combo-books/public-get_combo_details) to retrieve detailed information about a specific combo.
[Try in API console](https://test.deribit.com/api_console?method=%2Fpublic%2Fget_combo_ids)
'
x-mint:
metadata:
title: public/get_combo_ids
og:title: public/get_combo_ids
keywords:
- public/get_combo_ids
- currency
- state
href: /api-reference/combo-books/public-get_combo_ids
/public/get_combo_details:
get:
tags:
- Public
parameters:
- name: combo_id
required: true
in: query
schema:
$ref: '#/components/schemas/combo_id'
description: Combo ID
responses:
'200':
$ref: '#/components/responses/PublicGetComboDetailsResponse'
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 3
method: public/get_combo_details
params:
combo_id: BTC-FS-29APR22_PERP
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Retrieves detailed information about a specific combo, including its leg structure, state, and other properties.
Use [public/get_combo_ids](https://docs.deribit.com/api-reference/combo-books/public-get_combo_ids) to get a list of available combo IDs.
[Try in API console](https://test.deribit.com/api_console?method=%2Fpublic%2Fget_combo_details)
'
x-mint:
metadata:
title: public/get_combo_details
og:title: public/get_combo_details
keywords:
- public/get_combo_details
- combo_id
- instrument_id
- state
- state_timestamp
- creation_timestamp
- legs
- instrument_name
- amount
href: /api-reference/combo-books/public-get_combo_details
/public/get_order_book:
get:
parameters:
- in: query
name: instrument_name
required: true
schema:
type: string
example: BTC-PERPETUAL
description: The instrument name for which to retrieve the order book, see [`public/get_instruments`](#public-get_instruments) to obtain instrument names.
- in: query
name: depth
required: false
schema:
type: integer
enum:
- 1
- 5
- 10
- 20
- 50
- 100
- 1000
- 10000
example: 5
description: The number of entries to return for bids and asks, maximum - `10000`.
responses:
'200':
$ref: '#/components/responses/PublicGetOrderBookResponse'
tags:
- Public
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 8772
method: public/get_order_book
params:
instrument_name: BTC-PERPETUAL
depth: 5
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Retrieves the order book (bids and asks) for a given instrument, along with other market values such as best bid/ask prices, last trade price, mark price, and index price.
The order book depth can be controlled using the `depth` parameter, which accepts values from 1 to 10000. The response includes price levels sorted by price (bids descending, asks ascending).
[Try in API console](https://test.deribit.com/api_console?method=%2Fpublic%2Fget_order_book)
'
x-mint:
metadata:
title: public/get_order_book
og:title: public/get_order_book
keywords:
- public/get_order_book
- instrument_name
- depth
- timestamp
- state
- stats
- open_interest
- best_bid_price
- best_bid_amount
- best_ask_price
- best_ask_amount
- index_price
- min_price
- max_price
- mark_price
- last_price
- underlying_price
- underlying_index
- interest_rate
- bid_iv
- ask_iv
- mark_iv
- greeks
- funding_8h
- current_funding
- delivery_price
- settlement_price
- bids
- asks
- volume
- low
- high
- price_change
- volume_usd
- delta
- gamma
- rho
- theta
- vega
href: /api-reference/market-data/public-get_order_book
/public/get_order_book_by_instrument_id:
get:
parameters:
- in: query
name: instrument_id
required: true
schema:
type: integer
description: The instrument ID for which to retrieve the order book, see [`public/get_instruments`](#public-get_instruments) to obtain instrument IDs.
- in: query
name: depth
required: false
schema:
type: integer
enum:
- 1
- 5
- 10
- 20
- 50
- 100
- 1000
- 10000
description: The number of entries to return for bids and asks, maximum - `10000`.
responses:
'200':
$ref: '#/components/responses/PublicGetOrderBookResponse'
tags:
- Public
description: 'Retrieves the order book (bids and asks) for a given instrument ID, along with other market values such as best bid/ask prices, last trade price, mark price, and index price.
This method is similar to `get_order_book` but uses instrument ID instead of instrument name. The order book depth can be controlled using the `depth` parameter, which accepts values from 1 to 10000.
[Try in API console](https://test.deribit.com/api_console?method=%2Fpublic%2Fget_order_book_by_instrument_id)
'
x-mint:
metadata:
title: public/get_order_book_by_instrument_id
og:title: public/get_order_book_by_instrument_id
keywords:
- public/get_order_book_by_instrument_id
- instrument_id
- depth
- instrument_name
- timestamp
- state
- stats
- open_interest
- best_bid_price
- best_bid_amount
- best_ask_price
- best_ask_amount
- index_price
- min_price
- max_price
- mark_price
- last_price
- underlying_price
- underlying_index
- interest_rate
- bid_iv
- ask_iv
- mark_iv
- greeks
- funding_8h
- current_funding
- delivery_price
- settlement_price
- bids
- asks
- volume
- low
- high
- price_change
- volume_usd
- delta
- gamma
- rho
- theta
- vega
href: /api-reference/market-data/public-get_order_book_by_instrument_id
/public/get_last_settlements_by_currency:
get:
parameters:
- name: currency
required: true
in: query
schema:
$ref: '#/components/schemas/currency'
description: The currency symbol
- in: query
name: type
required: false
schema:
$ref: '#/components/schemas/settlement_type'
description: Settlement type
- name: count
required: false
in: query
schema:
type: integer
maximum: 1000
minimum: 1
description: Number of requested items, default - `20`, maximum - `1000`
- name: continuation
in: query
required: false
schema:
type: string
example: xY7T6cutS3t2B9YtaDkE6TS379oKnkzTvmEDUnEUP2Msa9xKWNNaT
description: Continuation token for pagination
- in: query
name: search_start_timestamp
required: false
schema:
$ref: '#/components/schemas/timestamp'
description: The latest timestamp to return result from (milliseconds since the UNIX epoch)
responses:
'200':
$ref: '#/components/responses/PublicSettlementResponse'
tags:
- Public
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 4497
method: public/get_last_settlements_by_currency
params:
currency: BTC
type: delivery
count: 2
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Retrieves historical settlement, delivery, and bankruptcy events from all instruments within a given currency. Settlements occur when futures or options contracts expire and are settled at the delivery price.
Results can be filtered by settlement type and timestamp. Use pagination parameters (`count` and `continuation`) to retrieve large settlement histories. This data is useful for analyzing historical contract settlements and understanding market events.
[Try in API console](https://test.deribit.com/api_console?method=%2Fpublic%2Fget_last_settlements_by_currency)
'
x-mint:
metadata:
title: public/get_last_settlements_by_currency
og:title: public/get_last_settlements_by_currency
keywords:
- public/get_last_settlements_by_currency
- currency
- type
- count
- continuation
- search_start_timestamp
- settlements
- funding
- funded
- index_price
- instrument_name
- mark_price
- position
- profit_loss
- session_bankruptcy
- session_profit_loss
- session_tax
- session_tax_rate
- socialized
- timestamp
href: /api-reference/market-data/public-get_last_settlements_by_currency
/public/get_book_summary_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'
description: Instrument kind, if not provided instruments of all kinds are considered
responses:
'200':
$ref: '#/components/responses/PublicGetBookSummaryResponse'
tags:
- Public
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 9344
method: public/get_book_summary_by_currency
params:
currency: BTC
kind: future
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Retrieves summary information such as open interest, 24-hour volume, best bid/ask prices, last trade price, and other market statistics for all instruments in a given currency.
Results can be filtered by instrument kind (future, option, etc.). This method provides a quick overview of market activity across all instruments for a currency.
**Note:** For real-time updates, we recommend using the WebSocket subscription to `ticker.{instrument_name}.{interval}` instead of polling this endpoint.
[Try in API console](https://test.deribit.com/api_console?method=%2Fpublic%2Fget_book_summary_by_currency)
'
x-mint:
metadata:
title: public/get_book_summary_by_currency
og:title: public/get_book_summary_by_currency
keywords:
- public/get_book_summary_by_currency
- currency
- kind
- instrument_name
- high
- low
- base_currency
- quote_currency
- volume
- bid_price
- ask_price
- mid_price
- mark_price
- last
- open_interest
- creation_timestamp
- estimated_delivery_price
- volume_usd
- volume_notional
- current_funding
- funding_8h
- mark_iv
- interest_rate
- underlying_index
- underlying_price
- price_change
href: /api-reference/market-data/public-get_book_summary_by_currency
/public/get_book_summary_by_instrument:
get:
parameters:
- name: instrument_name
required: true
in: query
schema:
$ref: '#/components/schemas/instrument_name'
description: Instrument name
responses:
'200':
$ref: '#/components/responses/PublicGetBookSummaryResponse'
tags:
- Public
requestBody:
content:
application/json:
examples:
request:
value:
jsonrpc: '2.0'
id: 3659
method: public/get_book_summary_by_instrument
params:
instrument_name: ETH-22FEB19-140-P
description: JSON-RPC Request Example
description: JSON-RPC request body
description: 'Retrieves summary information such as open interest, 24-hour volume, best bid/ask prices, last trade price, mark price, and other market statistics for a specific instrument.
This method provides a quick overview of current market activity and liquidity for a single instrument.
[Try in API console](https://test.deribit.com/api_con
# --- truncated at 32 KB (199 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/deribit/refs/heads/main/openapi/deribit-public-api-openapi.yml