private/get_settlement_history_by_instrument

Retrieves settlement, delivery, and bankruptcy events for a specific instrument that have affected your account. 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 method is useful for tracking settlement events for a specific instrument.

Scope: trade:read

Try in API console

cURL

cURL

curl --request GET \
  --url https://test.deribit.com/api/v2/private/get_settlement_history_by_instrument \
  --header 'Content-Type: application/json' \
  --data '
{
  "jsonrpc": "2.0",
  "id": 2192,
  "method": "private/get_settlement_history_by_instrument",
  "params": {
    "instrument_name": "ETH-22FEB19",
    "type": "settlement",
    "count": 1
  }
}
'

import requests

url = "https://test.deribit.com/api/v2/private/get_settlement_history_by_instrument"

payload = {
    "jsonrpc": "2.0",
    "id": 2192,
    "method": "private/get_settlement_history_by_instrument",
    "params": {
        "instrument_name": "ETH-22FEB19",
        "type": "settlement",
        "count": 1
    }
}
headers = {"Content-Type": "application/json"}

response = requests.get(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 2192,
    method: 'private/get_settlement_history_by_instrument',
    params: {instrument_name: 'ETH-22FEB19', type: 'settlement', count: 1}
  })
};

fetch('https://test.deribit.com/api/v2/private/get_settlement_history_by_instrument', 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/private/get_settlement_history_by_instrument",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => json_encode([
    'jsonrpc' => '2.0',
    'id' => 2192,
    'method' => 'private/get_settlement_history_by_instrument',
    'params' => [
        'instrument_name' => 'ETH-22FEB19',
        'type' => 'settlement',
        'count' => 1
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://test.deribit.com/api/v2/private/get_settlement_history_by_instrument"

	payload := strings.NewReader("{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 2192,\n  \"method\": \"private/get_settlement_history_by_instrument\",\n  \"params\": {\n    \"instrument_name\": \"ETH-22FEB19\",\n    \"type\": \"settlement\",\n    \"count\": 1\n  }\n}")

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

	req.Header.Add("Content-Type", "application/json")

	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/private/get_settlement_history_by_instrument")
  .header("Content-Type", "application/json")
  .body("{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 2192,\n  \"method\": \"private/get_settlement_history_by_instrument\",\n  \"params\": {\n    \"instrument_name\": \"ETH-22FEB19\",\n    \"type\": \"settlement\",\n    \"count\": 1\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://test.deribit.com/api/v2/private/get_settlement_history_by_instrument")

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

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 2192,\n  \"method\": \"private/get_settlement_history_by_instrument\",\n  \"params\": {\n    \"instrument_name\": \"ETH-22FEB19\",\n    \"type\": \"settlement\",\n    \"count\": 1\n  }\n}"

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

200

{
  "jsonrpc": "2.0",
  "id": 2192,
  "result": {
    "settlements": [
      {
        "type": "settlement",
        "timestamp": 1550475692526,
        "session_profit_loss": 0.038358299,
        "profit_loss": -0.001783937,
        "position": -66,
        "mark_price": 121.67,
        "instrument_name": "ETH-22FEB19",
        "index_price": 119.8
      }
    ],
    "continuation": "xY7T6cusbMBNpH9SNmKb94jXSBxUPojJEdCPL4YociHBUgAhWQvEP"
  }
}

Query Parameters

instrument_name · string · required

Instrument name Unique instrument identifier

Example:

"BTC-PERPETUAL"

type · enum<string>

Settlement type The type of settlement. settlement, delivery or bankruptcy.

Available options: settlement, delivery, bankruptcy

count · integer

Number of requested items, default - 20, maximum - 1000

Required range: 1 <= x <= 1000

continuation · string

Continuation token for pagination

Example:

"xY7T6cutS3t2B9YtaDkE6TS379oKnkzTvmEDUnEUP2Msa9xKWNNaT"

search_start_timestamp · integer

The latest timestamp to return result from (milliseconds since the UNIX epoch) The timestamp (milliseconds since the Unix epoch)

Example:

1536569522277

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. continuation · string · required

Continuation token for pagination.

Example:

"xY7T6cutS3t2B9YtaDkE6TS379oKnkzTvmEDUnEUP2Msa9xKWNNaT"

result. settlements · object[] · required

Hide child attributes

result.settlements. funding · number · required

funding (in base currency ; settlement for perpetual product only)

Example:

-0.000002511

result.settlements. index_price · number · required

underlying index price at time of event (in quote currency; settlement and delivery only)

Example:

11008.37

result.settlements. instrument_name · string · required

instrument name (settlement and delivery only)

Example:

"BTC-30MAR18"

result.settlements. position · number · required

position size (in quote currency; settlement and delivery only)

Example:

1000

result.settlements. session_profit_loss · number · required

total value of session profit and losses (in base currency)

Example:

0.001160788

result.settlements. timestamp · integer · required

The timestamp (milliseconds since the Unix epoch)

Example:

1536569522277

result.settlements. type · enum<string> · required

The type of settlement. settlement, delivery or bankruptcy.

Available options: settlement, delivery, bankruptcy

result.settlements. funded · number

funded amount (bankruptcy only)

Example:

0

result.settlements. mark_price · number

mark price for at the settlement time (in quote currency; settlement and delivery only)

Example:

11000

result.settlements. profit_loss · number

profit and loss (in base currency; settlement and delivery only)

Example:

0

result.settlements. session_bankruptcy · number

value of session bankruptcy (in base currency; bankruptcy only)

Example:

0.001160788

result.settlements. session_tax · number

total amount of paid taxes/fees (in base currency; bankruptcy only)

Example:

-0.001160788

result.settlements. session_tax_rate · number

rate of paid taxes/fees (in base currency; bankruptcy only)

Example:

0.000103333

result.settlements. socialized · number

the amount of the socialized losses (in base currency; bankruptcy only)

Example:

-0.001160788

id · integer

The id that was sent in the request