openapi: 3.0.0
info:
  title: Deribit Account Management Combo Books API
  version: 2.1.1
servers:
- url: https://test.deribit.com/api/v2
tags:
- name: Combo Books
paths:
  /public/get_combos:
    get:
      tags:
      - Combo Books
      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:
      - Combo Books
      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:
      - Combo Books
      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
  /private/create_combo:
    get:
      parameters:
      - in: query
        name: trades
        required: true
        schema:
          type: array
          items:
            type: object
            properties:
              instrument_name:
                $ref: '#/components/schemas/instrument_name'
              amount:
                $ref: '#/components/schemas/amount'
              direction:
                $ref: '#/components/schemas/direction'
        description: List of trades used to create a combo
        style: form
        explode: true
      responses:
        '200':
          $ref: '#/components/responses/PrivateCreateComboResponse'
      tags:
      - Combo Books
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 6
                  method: private/create_combo
                  params:
                    trades:
                    - instrument_name: BTC-29APR22-37500-C
                      amount: '1'
                      direction: buy
                    - instrument_name: BTC-29APR22-37500-P
                      amount: '1'
                      direction: sell
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Verifies and creates a combo book or returns an existing combo matching the given trades. Combos allow trading on multiple instruments (futures and options) simultaneously as a single strategy.


        If a combo matching the provided trades already exists, this method returns the existing combo. Otherwise, it creates a new combo book with the specified leg structure.


        **Scope:** `trade:read_write`


        [Try in API console](https://test.deribit.com/api_console?method=%2Fprivate%2Fcreate_combo)


        '
      x-mint:
        metadata:
          title: private/create_combo
          og:title: private/create_combo
          keywords:
          - private/create_combo
          - trades
          - instrument_id
          - state
          - state_timestamp
          - creation_timestamp
          - legs
          - instrument_name
          - amount
        href: /api-reference/combo-books/private-create_combo
  /private/get_leg_prices:
    get:
      parameters:
      - in: query
        name: legs
        required: true
        schema:
          type: array
          items:
            type: object
            properties:
              instrument_name:
                $ref: '#/components/schemas/instrument_name'
                description: Instrument name
              amount:
                $ref: '#/components/schemas/amount'
                description: It represents the requested trade size. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.
              direction:
                $ref: '#/components/schemas/direction'
                description: Direction of selected leg
        description: List of legs for which the prices will be calculated
        style: form
        explode: true
      - name: price
        in: query
        schema:
          type: number
        required: true
        description: Price for the whole leg structure
      responses:
        '200':
          $ref: '#/components/responses/PrivateGetLegPricesResponse'
      tags:
      - Combo Books
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: private/get_leg_prices
                  params:
                    price: 0.6
                    legs:
                    - instrument_name: BTC-1NOV24-67000-C
                      direction: buy
                      amount: 2
                    - instrument_name: BTC-1NOV24-66000-C
                      direction: sell
                      amount: 2
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Returns individual leg prices for a given combo structure based on an aggregated price of the strategy and the mark prices of the individual legs.


        **Note:** Leg prices change dynamically with mark price fluctuations, and the algorithm is calibrated only for conventional option structures and future spreads. This method supports both inverse strategies and known linear structures within a single currency pair.


        [Try in API console](https://test.deribit.com/api_console?method=%2Fprivate%2Fget_leg_prices)


        '
      x-mint:
        metadata:
          title: private/get_leg_prices
          og:title: private/get_leg_prices
          keywords:
          - private/get_leg_prices
          - legs
          - price
          - amount
          - ratio
          - instrument_name
          - direction
        href: /api-reference/combo-books/private-get_leg_prices
components:
  responses:
    PublicGetComboDetailsResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicGetComboDetailsResponse'
          examples:
            response:
              value:
                jsonrpc: '2.0'
                id: 3
                result:
                  state_timestamp: 1650620605150
                  state: active
                  legs:
                  - instrument_name: BTC-PERPETUAL
                    amount: -1
                  - instrument_name: BTC-29APR22
                    amount: 1
                  id: BTC-FS-29APR22_PERP
                  instrument_id: 27
                  creation_timestamp: 1650620575000
              description: Response example
      description: Success response
    PrivateCreateComboResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrivateCreateComboResponse'
          examples:
            response:
              value:
                jsonrpc: '2.0'
                id: 6
                result:
                  state_timestamp: 1650960943922
                  state: active
                  legs:
                  - instrument_name: BTC-29APR22-37500-C
                    amount: 1
                  - instrument_name: BTC-29APR22-37500-P
                    amount: -1
                  id: BTC-REV-29APR22-37500
                  instrument_id: 52
                  creation_timestamp: 1650960943000
              description: Response example
      description: Success response
    PrivateGetLegPricesResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrivateGetLegPricesResponse'
          examples:
            response:
              value:
                jsonrpc: '2.0'
                id: 1
                result:
                  legs:
                  - ratio: 1
                    instrument_name: BTC-1NOV24-67000-C
                    price: 0.6001
                    direction: buy
                  - ratio: 1
                    instrument_name: BTC-1NOV24-66000-C
                    price: 0.0001
                    direction: sell
                  amount: 2
              description: Response example
      description: Success response
    PublicGetComboIdsResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicGetComboIdsResponse'
          examples:
            response:
              value:
                jsonrpc: '2.0'
                id: 1
                result:
                - BTC-CS-29APR22-39300_39600
                - BTC-FS-29APR22_PERP
              description: Response example
      description: Success response
    PublicGetCombosResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicGetCombosResponse'
          examples:
            response:
              value:
                jsonrpc: '2.0'
                id: 2
                result:
                - state_timestamp: 1650636265101
                  state: active
                  legs:
                  - instrument_name: BTC-29APR22-39300-C
                    amount: 1
                  - instrument_name: BTC-29APR22-39600-C
                    amount: -1
                  id: BTC-CS-29APR22-39300_39600
                  instrument_id: 28
                  creation_timestamp: 1650636235000
                - state_timestamp: 1650620605150
                  state: active
                  legs:
                  - instrument_name: BTC-PERPETUAL
                    amount: -1
                  - instrument_name: BTC-29APR22
                    amount: 1
                  id: BTC-FS-29APR22_PERP
                  instrument_id: 27
                  creation_timestamp: 1650620575000
              description: Response example
      description: Success response
  schemas:
    combo_leg:
      properties:
        instrument_name:
          $ref: '#/components/schemas/instrument_name'
        amount:
          $ref: '#/components/schemas/combo_leg_amount'
      type: object
    PublicGetComboIdsResponse:
      properties:
        jsonrpc:
          type: string
          enum:
          - '2.0'
          description: The JSON-RPC version (2.0)
        id:
          type: integer
          description: The id that was sent in the request
        result:
          type: array
          items:
            $ref: '#/components/schemas/combo_id'
      required:
      - jsonrpc
      - result
      type: object
    PrivateCreateComboResponse:
      properties:
        jsonrpc:
          type: string
          enum:
          - '2.0'
          description: The JSON-RPC version (2.0)
        id:
          type: integer
          description: The id that was sent in the request
        result:
          $ref: '#/components/schemas/combo'
      required:
      - jsonrpc
      - result
      type: object
    timestamp:
      example: 1536569522277
      type: integer
      description: The timestamp (milliseconds since the Unix epoch)
    PublicGetComboDetailsResponse:
      properties:
        jsonrpc:
          type: string
          enum:
          - '2.0'
          description: The JSON-RPC version (2.0)
        id:
          type: integer
          description: The id that was sent in the request
        result:
          $ref: '#/components/schemas/combo'
      required:
      - jsonrpc
      - result
      type: object
    combo:
      properties:
        id:
          $ref: '#/components/schemas/combo_id'
        instrument_id:
          $ref: '#/components/schemas/instrument_id'
        state:
          $ref: '#/components/schemas/combo_state'
        state_timestamp:
          $ref: '#/components/schemas/timestamp'
        creation_timestamp:
          $ref: '#/components/schemas/timestamp'
        legs:
          type: array
          items:
            $ref: '#/components/schemas/combo_leg'
      type: object
    instrument_id:
      type: integer
      description: Instrument ID
    combo_leg_amount:
      example: -1
      type: integer
      description: Size multiplier of a leg. A negative value indicates that the trades on given leg are in opposite direction to the combo trades they originate from
    combo_id:
      example: BTC-FS-31DEC21-PERP
      type: string
      description: Unique combo identifier
    currency:
      enum:
      - BTC
      - ETH
      - USDC
      - USDT
      - EURR
      type: string
      description: Currency, i.e `"BTC"`, `"ETH"`, `"USDC"`
    amount:
      type: number
      description: It represents the requested order size. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.
    PrivateGetLegPricesResponse:
      properties:
        jsonrpc:
          type: string
          enum:
          - '2.0'
          description: The JSON-RPC version (2.0)
        id:
          type: integer
          description: The id that was sent in the request
        result:
          properties:
            legs:
              $ref: '#/components/schemas/leg_structure'
            amount:
              type: number
              description: This value multiplied by the ratio of a leg gives trade size on that leg.
          type: object
      required:
      - jsonrpc
      - result
      type: object
    direction:
      enum:
      - buy
      - sell
      type: string
      description: 'Direction: `buy`, or `sell`'
    PublicGetCombosResponse:
      properties:
        jsonrpc:
          type: string
          enum:
          - '2.0'
          description: The JSON-RPC version (2.0)
        id:
          type: integer
          description: The id that was sent in the request
        result:
          type: array
          items:
            $ref: '#/components/schemas/combo'
      required:
      - jsonrpc
      - result
      type: object
    currency_with_any:
      enum:
      - BTC
      - ETH
      - USDC
      - USDT
      - EURR
      - any
      type: string
      description: Currency name or `"any"` if don't care
    leg_structure:
      items:
        properties:
          ratio:
            type: integer
            description: Ratio of amount between legs
          instrument_name:
            type: string
            example: BTC-PERPETUAL
            description: Unique instrument identifier
          direction:
            type: string
            enum:
            - buy
            - sell
            description: 'Direction: `buy`, or `sell`'
          price:
            type: number
            description: Price for a leg
        type: object
      type: array
    combo_state:
      enum:
      - active
      - inactive
      type: string
      description: 'Combo state: `"active"`, "`inactive`"'
    instrument_name:
      example: BTC-PERPETUAL
      type: string
      description: Unique instrument identifier