public/get_order_book_by_instrument_id

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

cURL

cURL

curl --request GET \
  --url https://test.deribit.com/api/v2/public/get_order_book_by_instrument_id

import requests

url = "https://test.deribit.com/api/v2/public/get_order_book_by_instrument_id"

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://test.deribit.com/api/v2/public/get_order_book_by_instrument_id', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://test.deribit.com/api/v2/public/get_order_book_by_instrument_id",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://test.deribit.com/api/v2/public/get_order_book_by_instrument_id"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://test.deribit.com/api/v2/public/get_order_book_by_instrument_id")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://test.deribit.com/api/v2/public/get_order_book_by_instrument_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

200

{
  "jsonrpc": "2.0",
  "id": 8772,
  "result": {
    "timestamp": 1550757626706,
    "stats": {
      "volume": 93.35589552,
      "price_change": 0.6913,
      "low": 3940.75,
      "high": 3976.25
    },
    "state": "open",
    "settlement_price": 3925.85,
    "open_interest": 45.27600333464605,
    "min_price": 3932.22,
    "max_price": 3971.74,
    "mark_price": 3931.97,
    "last_price": 3955.75,
    "instrument_name": "BTC-PERPETUAL",
    "index_price": 3910.46,
    "funding_8h": 0.00455263,
    "current_funding": 0.00500063,
    "change_id": 474988,
    "bids": [
      [
        3955.75,
        30
      ],
      [
        3940.75,
        102020
      ],
      [
        3423,
        42840
      ]
    ],
    "best_bid_price": 3955.75,
    "best_bid_amount": 30,
    "best_ask_price": 0,
    "best_ask_amount": 0,
    "asks": []
  }
}

Query Parameters

instrument_id · integer · required

The instrument ID for which to retrieve the order book, see public/get_instruments to obtain instrument IDs.

depth · enum<integer>

The number of entries to return for bids and asks, maximum - 10000.

Available options: 1, 5, 10, 20, 50, 100, 1000, 10000

Response

200 - application/json

Success response

jsonrpc · enum<string> · required

The JSON-RPC version (2.0)

Available options: 2.0

result · object · required

Hide child attributes

result. instrument_name · string · required

Unique instrument identifier

Example:

"BTC-PERPETUAL"

result. timestamp · integer · required

The timestamp (milliseconds since the Unix epoch)

Example:

1536569522277

result. state · enum<string> · required

The state of the order book. Represents the current lifecycle stage of the instrument.

State Lifecycle and Meanings:

• open: Default state for running books. In this state book is accepting new orders, edits, cancels; prices should be updated, trading is live.
• 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.
• 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.
• 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.
• 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.
• 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.
• archivized: Set when instrument is moved to expired_instruments table, final state.

Available options: open, settlement, delivered, inactive, locked, halted, archivized

result. stats · object · required

Hide child attributes

result.stats. volume · number · required

Volume during last 24h in base currency

result.stats. low · number · required

Lowest price during 24h

result.stats. high · number · required

Highest price during 24h

result.stats. price_change · number

24-hour price change expressed as a percentage, null if there weren't any trades

Example:

10.23

result.stats. volume_usd · number

Volume in usd (futures only)

result. open_interest · number · required

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.

result. best_bid_price · number | null · required

The current best bid price, null if there aren't any bids

result. best_bid_amount · number | null · required

It represents the requested order size of all best bids

result. best_ask_price · number | null · required

The current best ask price, null if there aren't any asks

result. best_ask_amount · number | null · required

It represents the requested order size of all best asks

result. index_price · number · required

Current index price

Example:

8247.27

result. min_price · number · required

The minimum price for the future. Any sell orders you submit lower than this price will be clamped to this minimum.

result. max_price · number · required

The maximum price for the future. Any buy orders you submit higher than this price, will be clamped to this maximum.

result. mark_price · number · required

The mark price for the instrument

result. last_price · number | null · required

The price for the last trade

result. bids · number[][] · required

List of bids (price-amount pairs)

Required array length: 2 elements

result. asks · number[][] · required

List of asks (price-amount pairs)

Required array length: 2 elements

result. underlying_price · number

Underlying price for implied volatility calculations (options only)

result. underlying_index · number

Name of the underlying future, or index_price (options only)

result. interest_rate · number

Interest rate used in implied volatility calculations (options only)

result. bid_iv · number

(Only for option) implied volatility for best bid

result. ask_iv · number

(Only for option) implied volatility for best ask

result. mark_iv · number

(Only for option) implied volatility for mark price

result. greeks · object

Only for options. Greeks are risk measures that describe how the option's price changes with respect to various factors.

Delta (Δ)

Deribit uses two different Deltas:

• DeltaTotal in the account summary uses the Net Transaction Delta (NTD)
• Delta for individual option expiries is the Black Scholes Delta

In the settings section you can toggle Net Transaction Delta instead.

What is DeltaTotal in the account summary? DeltaTotal = Net Transaction Delta of options + BTC Position of Futures

What is Net Transaction Delta? Net Transaction Delta = Black Scholes Delta - Mark Price of Options

Why do we use a Net Transaction Delta? The 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.

You should actually treat your delta as Equity + Delta Total if you want to have less risk for your USD PnL.

Example: Consider a call option with strike 0, which has a Black Scholes Delta of 1 and Net Transaction Delta = 0.

Imagine 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.

Now let's say you buy one call with strike 0. The question is if you should sell another future?

The 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.

⚠️ During the 30 minute settlement period we decay your Delta. See Delta decay during settlement for more details.

Theta (Θ)

The 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.

Vega, Gamma, and Rho

Vega (not actually a Greek symbol), Gamma, Theta and Rho values shown on Deribit are calculated using standard Black Scholes without adjustments.

Hide child attributes

result.greeks. delta · number · required

(Only for option) The delta value for the option. This is the Black Scholes Delta for individual option expiries.

Note that DeltaTotal in account summary uses Net Transaction Delta instead. See the greeks object description for more details.

result.greeks. gamma · number · required

(Only for option) The gamma value for the option. Calculated using standard Black Scholes without adjustments.

Gamma measures the rate of change of delta with respect to changes in the underlying asset price.

result.greeks. rho · number · required

(Only for option) The rho value for the option. Calculated using standard Black Scholes without adjustments.

Rho measures the sensitivity of the option price to changes in the risk-free interest rate.

result.greeks. theta · number · required

(Only for option) The theta value for the option. Deribit uses 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.

Theta measures the rate of change of the option price with respect to time decay.

result.greeks. vega · number · required

(Only for option) The vega value for the option. Calculated using standard Black Scholes without adjustments.

Vega (not actually a Greek symbol) measures the sensitivity of the option price to changes in implied volatility.

result. funding_8h · number

Funding 8h (perpetual only)

result. current_funding · number

Current funding (perpetual only)

result. delivery_price · number

The settlement price for the instrument. Only when state = closed

result. settlement_price · number

Optional (not added for spot). The settlement price for the instrument. Only when state = open

id · integer

The id that was sent in the request