> ## Documentation Index
> Fetch the complete documentation index at: https://docs.derive.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# private/get_option_settlement_history

> Returns option settlement (expiry) events for a single subaccount or an entire wallet (specify exactly one). Each settlement includes the reconstructed option instrument name, the settled amount and value for that expired position, and the realized settlement PnL against the position's cost basis, with and without trading fees.



## OpenAPI

````yaml /openapi.json post /private/get_option_settlement_history
openapi: 3.1.0
info:
  title: Derive v3 API
  version: 0.2.0
  description: JSON-RPC 2.0 methods, served over WebSocket and HTTP POST.
servers:
  - url: https://api.derive.xyz/v3
    description: Production (HTTP POST base)
  - url: https://testnet.api.derive.xyz/v3
    description: Testnet (HTTP POST base)
security: []
tags:
  - name: Subaccounts
    description: >-
      List, inspect, and label subaccounts, portfolios, positions, and
      collateral.
  - name: Session Keys
    description: Register, edit, and list delegated signing keys.
  - name: Account
    description: Wallet-level account information and settings.
  - name: Orderbook
    description: Place, replace, cancel, and query orders, trigger orders, and algos.
  - name: RFQ
    description: 'Request-for-quote: send RFQs, quote, and execute block trades.'
  - name: Vault Shareholders
    description: >-
      Deposit into and withdraw from vaults, and track shares, requests, and
      performance.
  - name: Vault Curators
    description: >-
      Create and operate curated vaults: settle deposit and withdrawal requests,
      and manage vault metadata.
  - name: History
    description: >-
      Per-account historical records: orders, trades, transfers, and
      settlements.
  - name: Market Maker Protection
    description: Configure, read, and reset market-maker protection.
  - name: Transfers & Withdrawals
    description: Move collateral between subaccounts, to other wallets, and on-chain.
  - name: Onchain Actions
    description: >-
      L1 onchain actions submitted via OnchainActionManager: register deposit
      addresses, list pending deposits, and inspect onchain action history.
  - name: System
    description: Rate limits and transaction lookups.
  - name: Market Data
    description: Instruments, currencies, tickers, and market-wide feeds.
  - name: Referrals
    description: Referral codes and program performance.
  - name: Other
    description: Uncategorized.
paths:
  /private/get_option_settlement_history:
    post:
      tags:
        - History
      summary: private/get_option_settlement_history
      description: >-
        Returns option settlement (expiry) events for a single subaccount or an
        entire wallet (specify exactly one). Each settlement includes the
        reconstructed option instrument name, the settled amount and value for
        that expired position, and the realized settlement PnL against the
        position's cost basis, with and without trading fees.
      operationId: private_get_option_settlement_history
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetOptionSettlementHistoryParams'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptionSettlementHistoryResponse'
        default:
          description: JSON-RPC error (see Error Codes)
components:
  schemas:
    GetOptionSettlementHistoryParams:
      description: >-
        Parameters for `private/get_option_settlement_history`. One of `wallet`
        or `subaccount_id` must be provided; `wallet` returns every subaccount's
        settlements.
      type: object
      properties:
        subaccount_id:
          default: null
          type:
            - integer
            - 'null'
          format: uint64
          minimum: 0
        wallet:
          default: null
          type:
            - string
            - 'null'
    OptionSettlementHistoryResponse:
      type: object
      required:
        - settlements
      properties:
        settlements:
          type: array
          items:
            $ref: '#/components/schemas/OptionSettlementResponse'
    OptionSettlementResponse:
      description: One settled option position.
      type: object
      required:
        - amount
        - expiry
        - instrument_name
        - option_settlement_pnl
        - option_settlement_pnl_excl_fees
        - settlement_price
        - settlement_value
        - subaccount_id
      properties:
        amount:
          description: Settled balance (negative = short, positive = long).
          type: string
          format: decimal
        expiry:
          description: Expiry of the option, unix seconds.
          type: integer
          format: uint64
          minimum: 0
        instrument_name:
          type: string
        option_settlement_pnl:
          description: >-
            USD profit or loss from the settlement: settlement value minus the
            position's average cost including fees times amount. `null` when no
            closing balance row exists for the settlement (settled before
            balance history was recorded).
          type:
            - string
            - 'null'
          format: decimal
        option_settlement_pnl_excl_fees:
          description: >-
            Same as `option_settlement_pnl` but against the average price
            excluding fees.
          type:
            - string
            - 'null'
          format: decimal
        settlement_price:
          description: >-
            Decimal string of the human value (e.g. `"1.5"`), up to 12
            fractional digits; a string or JSON number is accepted
          type: string
          format: decimal
        settlement_value:
          description: Crystallized cash value = intrinsic value * amount.
          type: string
          format: decimal
        subaccount_id:
          type: integer
          format: uint64
          minimum: 0

````

## Related topics

- [Migration skill for your coding agent](/migrating/breaking-changes.md)
- [public/get_option_settlement_prices](/api-reference/market-data/publicget_option_settlement_prices.md)
- [private/get_funding_history](/api-reference/history/privateget_funding_history.md)