> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cdp.coinbase.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:** `rat#view` or `wallet:transactions:read`
[Try in API console](https://test.deribit.com/api_console?method=%2Fprivate%2Fget_settlement_history_by_instrument)
## OpenAPI
````yaml /api-reference/coinbase-deribit-app-api/adv-starbase-openapi.json get /private/get_settlement_history_by_instrument
openapi: 3.0.0
info:
description: Coinbase Retail Advanced Trade API for derivatives trading.
title: Coinbase Retail Advanced Trade (Deribit) API
version: 2.1.1
servers:
- url: https://drb.coinbase.com/api/v2
security: []
tags:
- description: Can only be used over websockets.
name: WebSocket Only
- description: Public methods can be used without authentication.
name: Public
- description: >-
Private methods require authentication. All requests must include a
valid OAuth2 token.
A token can be requested using the /public/auth method.
When using the websockets protocol, the token must be included as a
parameter access_token in the message. When using REST (HTTP
GET), the token may also be passed in the Authorization
header.
name: Private
- name: Authentication
- name: Session Management
- description: >-
Subscription works as [notifications](#notifications), so users will
automatically (after subscribing) receive messages from the server.
Overview for each channel response format is described in
[subscriptions](#subscriptions) section.
name: Subscription Management
- name: Account Management
- name: Trading
- name: Market Data
paths:
/private/get_settlement_history_by_instrument:
get:
tags:
- Trading
- Private
description: >+
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:** `rat#view` or `wallet:transactions:read`
[Try in API
console](https://test.deribit.com/api_console?method=%2Fprivate%2Fget_settlement_history_by_instrument)
parameters:
- description: Instrument name
in: query
name: instrument_name
required: true
schema:
$ref: '#/components/schemas/instrument_name'
- description: Settlement type
in: query
name: type
required: false
schema:
$ref: '#/components/schemas/settlement_type'
- description: Number of requested items, default - `20`, maximum - `1000`
in: query
name: count
required: false
schema:
maximum: 1000
minimum: 1
type: integer
- description: Continuation token for pagination
in: query
name: continuation
required: false
schema:
example: xY7T6cutS3t2B9YtaDkE6TS379oKnkzTvmEDUnEUP2Msa9xKWNNaT
type: string
- description: >-
The latest timestamp to return result from (milliseconds since the
UNIX epoch)
in: query
name: search_start_timestamp
required: false
schema:
$ref: '#/components/schemas/timestamp'
requestBody:
content:
application/json:
examples:
request:
description: JSON-RPC Request Example
value:
id: 2192
jsonrpc: '2.0'
method: private/get_settlement_history_by_instrument
params:
count: 1
instrument_name: ETH-22FEB19
type: settlement
description: JSON-RPC request body
responses:
'200':
$ref: '#/components/responses/PrivateSettlementResponse'
components:
schemas:
instrument_name:
description: Unique instrument identifier
example: BTC-PERPETUAL
type: string
settlement_type:
description: The type of settlement. `settlement`, `delivery` or `bankruptcy`.
enum:
- settlement
- delivery
- bankruptcy
type: string
timestamp:
description: The timestamp (milliseconds since the Unix epoch)
example: 1536569522277
type: integer
PrivateSettlementResponse:
properties:
id:
description: The id that was sent in the request
type: integer
jsonrpc:
description: The JSON-RPC version (2.0)
enum:
- '2.0'
type: string
result:
properties:
continuation:
$ref: '#/components/schemas/continuation'
settlements:
items:
$ref: '#/components/schemas/settlement'
type: array
required:
- continuation
- settlements
type: object
required:
- jsonrpc
- result
type: object
continuation:
description: Continuation token for pagination.
example: xY7T6cutS3t2B9YtaDkE6TS379oKnkzTvmEDUnEUP2Msa9xKWNNaT
type: string
settlement:
properties:
funded:
description: funded amount (bankruptcy only)
example: 0
type: number
funding:
description: funding (in base currency ; settlement for perpetual product only)
example: -0.000002511
type: number
index_price:
description: >-
underlying index price at time of event (in quote currency;
settlement and delivery only)
example: 11008.37
type: number
instrument_name:
description: instrument name (settlement and delivery only)
example: BTC-30MAR18
type: string
mark_price:
description: >-
mark price for at the settlement time (in quote currency; settlement
and delivery only)
example: 11000
type: number
position:
description: position size (in quote currency; settlement and delivery only)
example: 1000
type: number
profit_loss:
description: profit and loss (in base currency; settlement and delivery only)
example: 0
type: number
session_bankruptcy:
description: value of session bankruptcy (in base currency; bankruptcy only)
example: 0.001160788
type: number
session_profit_loss:
description: total value of session profit and losses (in base currency)
example: 0.001160788
type: number
session_tax:
description: total amount of paid taxes/fees (in base currency; bankruptcy only)
example: -0.001160788
type: number
session_tax_rate:
description: rate of paid taxes/fees (in base currency; bankruptcy only)
example: 0.000103333
type: number
socialized:
description: >-
the amount of the socialized losses (in base currency; bankruptcy
only)
example: -0.001160788
type: number
timestamp:
$ref: '#/components/schemas/timestamp'
type:
$ref: '#/components/schemas/settlement_type'
required:
- type
- timestamp
- session_profit_loss
- position
- instrument_name
- index_price
- funding
type: object
responses:
PrivateSettlementResponse:
content:
application/json:
examples:
response:
description: Response example
value:
id: 2192
jsonrpc: '2.0'
result:
continuation: xY7T6cusbMBNpH9SNmKb94jXSBxUPojJEdCPL4YociHBUgAhWQvEP
settlements:
- index_price: 119.8
instrument_name: ETH-22FEB19
mark_price: 121.67
position: -66
profit_loss: -0.001783937
session_profit_loss: 0.038358299
timestamp: 1550475692526
type: settlement
schema:
$ref: '#/components/schemas/PrivateSettlementResponse'
description: Success response
````