openapi: 3.0.0
info:
  title: Deribit Account Management Block Trade API
  version: 2.1.1
servers:
- url: https://test.deribit.com/api/v2
tags:
- name: Block Trade
paths:
  /private/simulate_block_trade:
    get:
      parameters:
      - in: query
        name: role
        required: false
        schema:
          $ref: '#/components/schemas/role'
        description: Describes if user wants to be maker or taker of trades
      - in: query
        name: trades
        required: true
        schema:
          type: array
          items:
            type: object
            properties:
              instrument_name:
                $ref: '#/components/schemas/instrument_name'
                description: Instrument name
              price:
                type: number
                description: Price for trade
              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 trade from the maker perspective
        description: List of trades for block trade
        style: form
        explode: true
      responses:
        '200':
          $ref: '#/components/responses/PrivateSimulateBlockTradeResponse'
      tags:
      - Block Trade
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: private/simulate_block_trade
                  params:
                    role: maker
                    trades:
                    - instrument_name: BTC-PERPETUAL
                      direction: buy
                      price: 11624
                      amount: 40
                    - instrument_name: BTC-9AUG19-10250-P
                      direction: buy
                      amount: 1.2
                      price: 0.0707
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Checks if a block trade can be executed without actually executing it. Use this method to verify that a block trade will succeed before proceeding with the actual execution.


        **📖 Related Article:** [Block Trading](https://docs.deribit.com/articles/block-trading-api)


        **Scope:** `block_trade:read`


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


        '
      x-mint:
        metadata:
          title: private/simulate_block_trade
          og:title: private/simulate_block_trade
          keywords:
          - private/simulate_block_trade
          - role
          - trades
        href: /api-reference/block-trade/private-simulate_block_trade
  /private/verify_block_trade:
    get:
      parameters:
      - in: query
        name: timestamp
        required: true
        schema:
          $ref: '#/components/schemas/timestamp'
        description: Timestamp, shared with other party (milliseconds since the UNIX epoch)
      - in: query
        name: nonce
        required: true
        schema:
          $ref: '#/components/schemas/nonce'
        description: Nonce, shared with other party
      - in: query
        name: role
        required: true
        schema:
          $ref: '#/components/schemas/role'
        description: Describes if user wants to be maker or taker of trades
      - in: query
        name: trades
        required: true
        schema:
          type: array
          items:
            type: object
            properties:
              instrument_name:
                $ref: '#/components/schemas/instrument_name'
                description: Instrument name
              price:
                type: number
                description: Price for trade
              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 trade from the maker perspective
        description: List of trades for block trade
        style: form
        explode: true
      responses:
        '200':
          $ref: '#/components/responses/PrivateVerifyBlockTradeResponse'
      tags:
      - Block Trade
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: private/verify_block_trade
                  params:
                    nonce: okpdjkdo
                    timestamp: 1565172650935
                    role: maker
                    trades:
                    - instrument_name: BTC-PERPETUAL
                      direction: buy
                      price: 11624
                      amount: 40
                    - instrument_name: BTC-9AUG19-10250-P
                      direction: buy
                      amount: 1.2
                      price: 0.0707
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Verifies and creates a block trade signature. This is the first step in the block trade workflow - the first party calls this method to generate a signature that must be shared with the second party.


        **Note:** In the API, the `direction` field is always expressed from the maker''s perspective. This means that when you accept a block trade as a taker, the direction shown in the API represents the opposite side of your trade. For example, if you are buying puts as a taker, the API will show the operation as a "sell put" (maker''s perspective), and you will be verifying and accepting a "sell put" block trade.


        **📖 Related Article:** [Block Trading](https://docs.deribit.com/articles/block-trading-api)


        **Scope:** `block_trade:read`


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


        '
      x-mint:
        metadata:
          title: private/verify_block_trade
          og:title: private/verify_block_trade
          keywords:
          - private/verify_block_trade
          - timestamp
          - nonce
          - role
          - trades
          - signature
        href: /api-reference/block-trade/private-verify_block_trade
  /private/execute_block_trade:
    get:
      parameters:
      - in: query
        name: timestamp
        required: true
        schema:
          $ref: '#/components/schemas/timestamp'
        description: Timestamp, shared with other party (milliseconds since the UNIX epoch)
      - in: query
        name: nonce
        required: true
        schema:
          $ref: '#/components/schemas/nonce'
        description: Nonce, shared with other party
      - in: query
        name: role
        required: true
        schema:
          $ref: '#/components/schemas/role'
        description: Describes if user wants to be maker or taker of trades
      - in: query
        name: trades
        required: true
        schema:
          type: array
          items:
            type: object
            properties:
              instrument_name:
                $ref: '#/components/schemas/instrument_name'
                description: Instrument name
              price:
                type: number
                description: Price for trade
              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 trade from the maker perspective
        description: List of trades for block trade
        style: form
        explode: true
      - in: query
        name: counterparty_signature
        required: true
        schema:
          $ref: '#/components/schemas/block_trade_signature'
        description: Signature of block trade generated by `private/verify_block_trade_method`
      responses:
        '200':
          $ref: '#/components/responses/PrivateGetBlockTradeResponse'
      tags:
      - Block Trade
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: private/execute_block_trade
                  params:
                    nonce: bszyprbq
                    timestamp: 1590485535899
                    role: maker
                    trades:
                    - instrument_name: BTC-PERPETUAL
                      direction: sell
                      price: 8900
                      amount: 200000
                    - instrument_name: BTC-28MAY20-9000-C
                      direction: sell
                      amount: 5
                      price: 0.0133
                    counterparty_signature: 1590485595899.1Mn52L_Q.lNyNBzXXo-_QBT_wDuMgnhA7uS9tBqdQ5TLN6rxbuoAiQhyaJYGJrm5IV_9enp9niY_x8D60AJLm3yEKPUY1Dv3T0TW0n5-ADPpJF7Fpj0eVDZpZ6QCdX8snBWrSJ0TtqevnO64RCBlN1dIm2T70PP9dlhiqPDAUYI4fpB1vLYI
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Executes a block trade. This is the second step in the block trade workflow - the second party calls this method with the signature received from the first party to execute the trade.


        The whole request must be exactly the same as in [private/verify_block_trade](https://docs.deribit.com/api-reference/block-trade/private-verify_block_trade), only the `role` field should be set appropriately - this means that both sides have to agree on the same `timestamp`, `nonce`, and `trades` fields, and the server will ensure that the `role` field is different between sides (each party accepts their own role).


        Using the same `timestamp` and `nonce` by both sides in [private/verify_block_trade](https://docs.deribit.com/api-reference/block-trade/private-verify_block_trade) ensures that even if unintentionally both sides execute the given block trade with a valid `counterparty_signature`, the block trade will be executed only once.


        **Note:** In the API, the `direction` field is always expressed from the maker''s perspective. This means that when you accept a block trade as a taker, the direction shown in the API represents the opposite side of your trade. For example, if you are buying puts as a taker, the API will show the operation as a "sell put" (maker''s perspective), and you will be verifying and accepting a "sell put" block trade.


        **📖 Related Article:** [Block Trading](https://docs.deribit.com/articles/block-trading-api)


        **Scope:** `block_trade:read_write`


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


        '
      x-mint:
        metadata:
          title: private/execute_block_trade
          og:title: private/execute_block_trade
          keywords:
          - private/execute_block_trade
          - timestamp
          - nonce
          - role
          - trades
          - counterparty_signature
          - app_name
          - broker_code
          - broker_name
          - trade_id
          - trade_seq
          - instrument_name
          - order_type
          - advanced
          - order_id
          - matching_id
          - direction
          - tick_direction
          - index_price
          - price
          - amount
          - contracts
          - iv
          - underlying_price
          - liquidation
          - liquidity
          - fee
          - fee_currency
          - label
          - state
          - block_trade_id
          - block_rfq_id
          - block_rfq_quote_id
          - reduce_only
          - post_only
          - mmp
          - risk_reducing
          - api
          - profit_loss
          - mark_price
          - legs
          - combo_id
          - combo_trade_id
          - quote_set_id
          - quote_id
          - trade_allocations
          - user_id
          - client_info
          - client_id
          - client_link_id
          - name
        href: /api-reference/block-trade/private-execute_block_trade
  /private/invalidate_block_trade_signature:
    get:
      parameters:
      - in: query
        name: signature
        required: true
        schema:
          $ref: '#/components/schemas/block_trade_signature'
        description: Signature of block trade that will be invalidated
      responses:
        '200':
          $ref: '#/components/responses/OkResponse'
      tags:
      - Block Trade
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: private/invalidate_block_trade_signature
                  params:
                    signature: 1565173369982.1M9tO0Q-.z9n9WyZUU5op9pEz6Jtd2CI71QxQMMsCZAexnIfK9HQRT1pKH3clxeIbY7Bqm-yMcWIoE3IfCDPW5VEdiN-6oS0YkKUyXPD500MUf3ULKhfkmH81EZs
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Invalidates a block trade signature, effectively cancelling the block trade. This can be called at any time before [private/execute_block_trade](https://docs.deribit.com/api-reference/block-trade/private-execute_block_trade) is called.


        **📖 Related Article:** [Block Trading](https://docs.deribit.com/articles/block-trading-api)


        **Scope:** `block_trade:read_write`


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


        '
      x-mint:
        metadata:
          title: private/invalidate_block_trade_signature
          og:title: private/invalidate_block_trade_signature
          keywords:
          - private/invalidate_block_trade_signature
          - signature
        href: /api-reference/block-trade/private-invalidate_block_trade_signature
  /private/get_block_trade:
    get:
      parameters:
      - in: query
        name: id
        required: true
        schema:
          $ref: '#/components/schemas/block_trade_id'
        description: Block trade id
      responses:
        '200':
          $ref: '#/components/responses/PrivateGetBlockTradeResponse'
      tags:
      - Block Trade
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: private/get_block_trade
                  params:
                    id: '61'
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Returns information about a specific block trade identified by `block_trade_id`.


        **📖 Related Article:** [Block Trading](https://docs.deribit.com/articles/block-trading-api)


        **Scope:** `block_trade:read`


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


        '
      x-mint:
        metadata:
          title: private/get_block_trade
          og:title: private/get_block_trade
          keywords:
          - private/get_block_trade
          - id
          - timestamp
          - trades
          - app_name
          - broker_code
          - broker_name
          - trade_id
          - trade_seq
          - instrument_name
          - order_type
          - advanced
          - order_id
          - matching_id
          - direction
          - tick_direction
          - index_price
          - price
          - amount
          - contracts
          - iv
          - underlying_price
          - liquidation
          - liquidity
          - fee
          - fee_currency
          - label
          - state
          - block_trade_id
          - block_rfq_id
          - block_rfq_quote_id
          - reduce_only
          - post_only
          - mmp
          - risk_reducing
          - api
          - profit_loss
          - mark_price
          - legs
          - combo_id
          - combo_trade_id
          - quote_set_id
          - quote_id
          - trade_allocations
          - user_id
          - client_info
          - client_id
          - client_link_id
          - name
        href: /api-reference/block-trade/private-get_block_trade
  /private/get_block_trades:
    get:
      parameters:
      - in: query
        name: currency
        required: false
        schema:
          $ref: '#/components/schemas/currency'
        description: The currency symbol
      - name: count
        in: query
        required: false
        schema:
          type: integer
          maximum: 101
          minimum: 1
        description: Count of Block Trades returned, maximum - `101`
      - name: start_id
        required: false
        in: query
        schema:
          $ref: '#/components/schemas/block_trade_id'
        description: Response will contain block trades older than the one provided in this field
      - name: end_id
        required: false
        in: query
        schema:
          $ref: '#/components/schemas/block_trade_id'
        description: The id of the oldest block trade to be returned, `start_id` is required with `end_id`
      - name: block_rfq_id
        required: false
        in: query
        schema:
          type: integer
        description: ID of the Block RFQ
      - name: broker_code
        in: query
        required: false
        schema:
          type: string
          example: 2krM7sJsx
        description: Broker code to filter block trades. Only broker clients can use `broker_code` to filter broker block trades. Use `any` for all block trades.
      responses:
        '200':
          $ref: '#/components/responses/PrivateGetBlockTradesResponse'
      tags:
      - Block Trade
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: private/get_block_trades
                  params:
                    currency: BTC
                    count: 1
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Returns a list of the user''s block trades. If currency is not provided, returns block trades for all currencies. `block_rfq_id` can be provided to receive block trades related to that particular Block RFQ.


        **📖 Related Article:** [Block Trading](https://docs.deribit.com/articles/block-trading-api)


        **Scope:** `block_trade:read`


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


        '
      x-mint:
        metadata:
          title: private/get_block_trades
          og:title: private/get_block_trades
          keywords:
          - private/get_block_trades
          - currency
          - count
          - start_id
          - end_id
          - block_rfq_id
          - broker_code
          - timestamp
          - trades
          - app_name
          - broker_name
          - trade_id
          - trade_seq
          - instrument_name
          - order_type
          - advanced
          - order_id
          - matching_id
          - direction
          - tick_direction
          - index_price
          - price
          - amount
          - contracts
          - iv
          - underlying_price
          - liquidation
          - liquidity
          - fee
          - fee_currency
          - label
          - state
          - block_trade_id
          - block_rfq_quote_id
          - reduce_only
          - post_only
          - mmp
          - risk_reducing
          - api
          - profit_loss
          - mark_price
          - legs
          - combo_id
          - combo_trade_id
          - quote_set_id
          - quote_id
          - trade_allocations
          - user_id
          - client_info
          - client_id
          - client_link_id
          - name
        href: /api-reference/block-trade/private-get_block_trades
  /private/get_block_trade_requests:
    get:
      parameters:
      - name: broker_code
        in: query
        required: false
        schema:
          type: string
          example: jpqYKgg1
        description: Broker code to filter block trade requests. Only broker clients can use `broker_code` to query for their executed broker block trades.
      responses:
        '200':
          $ref: '#/components/responses/PrivateGetBlockTradeRequestsResponse'
      tags:
      - Block Trade
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: private/get_block_trade_requests
                  params:
                    broker_code: jpqYKgg1
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Provides a list of block trade requests including pending approvals, declined trades, and expired trades. `timestamp` and `nonce` received in response can be used with [private/approve_block_trade](https://docs.deribit.com/api-reference/block-trade/private-approve_block_trade) or [private/reject_block_trade](https://docs.deribit.com/api-reference/block-trade/private-reject_block_trade) to approve or reject the pending block trade.


        To use the block trade approval feature, an [additional API key setting feature](https://docs.deribit.com/articles/creating-api-key#block-trade-approval-feature) called `enabled_features: block_trade_approval` is required. This key has to be given to the broker/registered partner who performs the trades on behalf of the user for the feature to be active. If the user wants to approve the trade, they must approve it from a different API key that doesn''t have this feature enabled.


        Only broker clients can use `broker_code` to query for their broker block trade requests.


        **📖 Related Article:** [Block Trading](https://docs.deribit.com/articles/block-trading-api)


        **Scope:** `block_trade:read`


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


        '
      x-mint:
        metadata:
          title: private/get_block_trade_requests
          og:title: private/get_block_trade_requests
          keywords:
          - private/get_block_trade_requests
          - broker_code
          - nonce
          - timestamp
          - trades
          - app_name
          - username
          - role
          - user_id
          - broker_name
          - state
          - counterparty_state
          - combo_id
          - value
        href: /api-reference/block-trade/private-get_block_trade_requests
  /private/approve_block_trade:
    get:
      parameters:
      - in: query
        name: timestamp
        required: true
        schema:
          $ref: '#/components/schemas/timestamp'
        description: Timestamp, shared with other party (milliseconds since the UNIX epoch)
      - in: query
        name: nonce
        required: true
        schema:
          $ref: '#/components/schemas/nonce'
        description: Nonce, shared with other party
      - in: query
        name: role
        required: true
        schema:
          $ref: '#/components/schemas/role'
        description: Describes if user wants to be maker or taker of trades
      responses:
        '200':
          $ref: '#/components/responses/OkResponse'
      tags:
      - Block Trade
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: private/approve_block_trade
                  params:
                    timestamp: 1711468813551
                    nonce: bt-468nha
                    role: maker
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Approves a pending block trade. `nonce` and `timestamp` are used to identify the block trade while `role` should be opposite to the trading counterparty.


        Use [private/get_block_trade_requests](https://docs.deribit.com/api-reference/block-trade/private-get_block_trade_requests) to retrieve pending block trades that require approval.


        To use the block trade approval feature, an [additional API key setting feature](https://docs.deribit.com/articles/creating-api-key#block-trade-approval-feature) called `enabled_features: block_trade_approval` is required. This key has to be given to the broker/registered partner who performs the trades on behalf of the user for the feature to be active. If the user wants to approve the trade, they must approve it from a different API key that doesn''t have this feature enabled.


        **📖 Related Article:** [Block Trading](https://docs.deribit.com/articles/block-trading-api)


        **Scope:** `block_trade:read_write`


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


        '
      x-mint:
        metadata:
          title: private/approve_block_trade
          og:title: private/approve_block_trade
          keywords:
          - private/approve_block_trade
          - timestamp
          - nonce
          - role
        href: /api-reference/block-trade/private-approve_block_trade
  /private/reject_block_trade:
    get:
      parameters:
      - in: query
        name: timestamp
        required: true
        schema:
          $ref: '#/components/schemas/timestamp'
        description: Timestamp, shared with other party (milliseconds since the UNIX epoch)
      - in: query
        name: nonce
        required: true
        schema:
          $ref: '#/components/schemas/nonce'
        description: Nonce, shared with other party
      - in: query
        name: role
        required: true
        schema:
          $ref: '#/components/schemas/role'
        description: Describes if user wants to be maker or taker of trades
      responses:
        '200':
          $ref: '#/components/responses/OkResponse'
      tags:
      - Block Trade
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: private/reject_block_trade
                  params:
                    timestamp: 1711468813551
                    nonce: bt-468nha
                    role: maker
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Rejects a pending block trade. `nonce` and `timestamp` are used to identify the block trade while `role` should be opposite to the trading counterparty.


        Use [private/get_block_trade_requests](https://docs.deribit.com/api-reference/block-trade/private-get_block_trade_requests) to retrieve pending block trades that require approval.


        To use the block trade approval feature, an [additional API key setting feature](https://docs.deribit.com/articles/creating-api-key#block-trade-approval-feature) called `enabled_features: block_trade_approval` is required. This key has to be given to the broker/registered partner who performs the trades on behalf of the user for the feature to be active. If the user wants to approve the trade, they must approve it from a different API key that doesn''t have this feature enabled.


        **📖 Related Article:** [Block Trading](https://docs.deribit.com/articles/block-trading-api)


        **Scope:** `block_trade:read_write`


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


        '
      x-mint:
        metadata:
          title: private/reject_block_trade
          og:title: private/reject_block_trade
          keywords:
          - private/reject_block_trade
          - timestamp
          - nonce
          - role
        href: /api-reference/block-trade/private-reject_block_trade
  /private/get_broker_trades:
    get:
      parameters:
      - in: query
        name: currency
        required: false
        schema:
          $ref: '#/components/schemas/currency'
        description: The currency symbol
      - name: count
        required: false
        in: query
        schema:
          type: integer
          maximum: 1000
          minimum: 1
        description: Number of requested items, default - `20`, maximum - `1000`
      - name: start_id
        required: false
        in: query
        schema:
          $ref: '#/components/schemas/block_trade_id'
        description: Response will contain block trades older than the one provided in this field
      - name: end_id
        required: false
        in: query
        schema:
          $ref: '#/components/schemas/block_trade_id'
        description: The id of the oldest block trade to be returned, `start_id` is required with `end_id`
      responses:
        '200':
          $ref: '#/components/responses/PrivateGetBrokerTradesResponse'
      tags:
      - Block Trade
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: private/get_broker_trades
                  params:
                    currency: BTC
                    count: 1
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: '**Broker Method** Returns list of broker block trades. If currency is not provided, returns broker block trades for all currencies.


        **Scope:** `block_trade:read`


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


        '
      x-mint:
        metadata:
          title: private/get_broker_trades
          og:title: private/get_broker_trades
          keywords:
          - private/get_broker_trades
          - currency
          - count
          - start_id
          - end_id
          - history
          - next_start_id
          - timestamp
          - trades
          - maker
          - taker
          - app_name
          - broker_code
          - broker_name
          - trade_id
          - trade_seq
          - instrument_name
          - order_type
          - advanced
          - order_id
          - matching_id
          - direction
          - tick_direction
          - index_price
          - price
          - amount
          - contracts
          - iv
          - underlying_price
          - liquidation
          - liquidity
          - fee
          - fee_currency
          - label
          - state
          - block_trade_id
          - block_rfq_id
          - block_rfq_quote_id
          - reduce_only
          - post_only
          - mmp
          - risk_reducing
          - api
          - profit_loss
          - mark_price
          - legs
          - combo_id
          - combo_trade_id
          - quote_set_id
          - quote_id
          - trade_allocations
          - user_id
          - client_info
          - client_id
          - client_link_id
          - name
          - client_name
          - client_link_name
        href: /api-reference/block-trade/private-get_broker_trades
  /private/get_broker_trade_requests:
    get:
      responses:
        '200':
          $ref: '#/components/responses/PrivateGetBrokerTradeRequestsResponse'
      tags:
      - Block Trade
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 7
                  method: private/get_broker_trade_requests
                  params: {}
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: '**Broker Method** Provides a list of broker block trade requests including pending approvals, declined trades, and expired trades. `timestamp` and `nonce` received in response can be used to approve or reject the pending broker block trade. This method takes no parameters.


        **Scope:** `block_trade:read`


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


        '
      x-mint:
        metadata:
          title: private/get_broker_trade_requests
          og:title: private/get_broker_trade_requests
          keywords:
          - private/get_broker_trade_requests
          - timestamp
          - state
          - trades
          - maker
          - taker
          - nonce
          - amount
          - direction
          - price
          - instrument_name
          - client_id
          - user_id
          - client_name
          - client_link_name
          - client_link_id
        href: /api-reference/block-trade/private-get_broker_trade_requests
components:
  schemas:
    block_trade_id_in_result:
      example: '154'
      type: string
      description: Block trade id - when trade was part of a block trade
    pending_block_trade:
      properties:
        nonce:
          type: string
          example: bF1_gfgcsd
          description: Nonce that can be used to approve or reject pending block trade.
        timestamp:
          type: integer
          description: Timestamp that can be used to approve or reject pending block trade.
        trades:
          type: array
          items:
            $ref: '#/components/schemas/pending_block_trade'
        app_name:
          type: string
          example: Example Application
          description: The name of the application that executed the block trade on behalf of the user (optional).
        username:
          type: string
          example: Trader
          description: Username of the user who initiated the block trade.
        role:
          $ref: '#/components/schemas/role'
        user_id:
          $ref: '#/components/schemas/user_id'
        broker_code:
          type: string
          example: jpqYKgg1
          description: Broker code associated with the broker block trade.
        broker_name:
          type: string
          example: Test Broker
          description: Name of the broker associated with the block trade.
        state:
          type: object
          properties:
            value:
              type: string
              enum:
              - initial
              - accepted
              - rejected
              - executed
              description: State value.
            timestamp:
              type: integer
              description: State timestamp.
          required:
          - value
          - timestamp
          description: State of the pending block trade for current user.
        counterparty_state:
          type: object
          properties:
            value:
              type: string
              enum:
              - initial
              - accepted
              - rejected
              - executed
              description: State value.
            timestamp:
              type: integer
              description: State timestamp.
          required:
          - value
          - timestamp
          description: State of the pending block trade for the other party (optional).
        combo_id:
          type: string
          example: BTC-CS-27JUN25-80000_85000
          description: Combo instrument identifier
      required:
      - nonce
      - timestamp
      - trades
      - app_name
      - role
      - user_id
      - state
      type: object
    order_state_in_user_trade:
      enum:
      - open
      - filled
      - rejected
      - cancelled
      - untriggered
      - archive
      type: string
      description: 'Order state: `"open"`, `"filled"`, `"rejected"`, `"cancelled"`, `"untriggered"` or `"archive"` (if order was archived)'
    trade_id:
      type: string
      description: Unique (per currency) trade identifier
    PrivateGetBlockTradeRequestsResponse:
      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/pending_block_trade'
      required:
      - jsonrpc
      - result
      type: object
    timestamp:
      example: 1536569522277
      type: integer
      description: The timestamp (milliseconds since the Unix epoch)
    label_presentation:
      type: string
      description: User defined label (presented only when previously set for order by user)
    block_trade_id:
      example: '154'
      type: string
      description: Block trade id
    tick_direction:
      enum:
      - 0
      - 1
      - 2
      - 3
      type: integer
      description: Direction of the "tick" (`0` = Plus Tick, `1` = Zero-Plus Tick, `2` = Minus Tick, `3` = Zero-Minus Tick).
    profit_loss:
      type: number
      description: Profit and loss in base currency.
    currency:
      enum:
      - BTC
      - ETH
      - USDC
      - USDT
      - EURR
      type: string
      description: Currency, i.e `"BTC"`, `"ETH"`, `"USDC"`
    OkResponse:
      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: string
          enum:
          - ok
          description: Result of method execution. `ok` in case of success
      required:
      - jsonrpc
      - result
      type: object
    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.
    PrivateGetBrokerTradesResponse:
      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: object
          properties:
            history:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier of the block trade history entry.
                  timestamp:
                    type: integer
                    description: Timestamp of the block trade history entry (milliseconds since the UNIX epoch).
                  trades:
                    type: array
                    items:
                      $ref: '#/components/schemas/block_trade'
                  maker:
                    type: object
                    properties:
                      user_id:
                        type: integer
                        description: Obscured user id of the maker.
                      client_id:
                        type: integer
                        description: ID of a client; available to broker. Represents a group of users under a common name.
                      client_name:
                        type: string
                        description: Name of the client; available to broker.
                      client_link_name:
                        type: string
                        description: Name of the linked user within the client; available to broker.
                      client_link_id:
                        type: integer
                        description: ID assigned to a single user in a client; available to broker.
                  taker:
                    type: object
                    properties:
                      user_id:
                        type: integer
                        description: Obscured user id of the taker.
                      client_id:
                        type: integer
                        description: ID of a client; available to broker. Represents a group of users under a common name.
                      client_name:
                        type: string
                        description: Name of the client; available to broker.
                      client_link_name:
                        type: string
                        description: Name of the linked user within the client; available to broker.
                      client_link_id:
                        type: integer
                        description: ID assigned to a single user in a client; available to broker.
            next_start_id:
              type: integer
              description: The next start ID for pagination.
      required:
      - jsonrpc
      - result
      type: object
    user_id:
      example: 57874
      type: integer
      description: Unique user identifier
    direction:
      enum:
      - buy
      - sell
      type: string
      description: 'Direction: `buy`, or `sell`'
    trade_timestamp:
      example: 1517329113791
      type: integer
      description: The timestamp of the trade (milliseconds since the UNIX epoch)
    PrivateVerifyBlockTradeResponse:
      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: object
          properties:
            signature:
              $ref: '#/components/schemas/block_trade_signature'
          required:
          - signature
      required:
      - jsonrpc
      - result
      type: object
    PrivateGetBlockTradesResponse:
      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/block_trade'
      required:
      - jsonrpc
      - result
      type: object
    block_trade:
      properties:
        id:
          $ref: '#/components/schemas/block_trade_id'
        timestamp:
          $ref: '#/components/schemas/timestamp'
        trades:
          type: array
          items:
            $ref: '#/components/schemas/user_trade'
        app_name:
          type: string
          example: Example Application
          description: The name of the application that executed the block trade on behalf of the user (optional).
        broker_code:
          type: string
          example: 2krM7sJsx
          description: Broker code associated with the broker block trade.
        broker_name:
          type: string
          example: Test Broker
          description: Name of the broker associated with the block trade.
      required:
      - id
      - timestamp
      - trades
      type: object
    nonce:
      example: bF1_gfgcsd
      type: string
      description: Nonce
    PrivateGetBrokerTradeRequestsResponse:
      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:
            type: object
            properties:
              timestamp:
                type: integer
                description: Timestamp of the broker block trade request (milliseconds since the UNIX epoch).
              state:
                type: string
                description: State of the broker block trade request.
              trades:
                type: array
                items:
                  type: object
                  properties:
                    amount:
                      type: number
                      description: Trade amount.
                    direction:
                      type: string
                      description: Trade direction (buy or sell).
                    price:
                      type: number
                      description: Trade price.
                    instrument_name:
                      type: string
                      description: Name of the traded instrument.
              maker:
                type: object
                properties:
                  state:
                    type: string
                    description: 'State of the request from the maker side: `initial`, `approved`, or `rejected`.'
                  client_id:
                    type: integer
                    description: ID of a client; available to broker. Represents a group of users under a common name.
                  user_id:
                    type: string
                    description: Obscured user id of the maker.
                  client_name:
                    type: string
                    description: Name of the client; available to broker.
                  client_link_name:
                    type: string
                    description: Name of the linked user within the client; available to broker.
                  client_link_id:
                    type: integer
                    description: ID assigned to a single user in a client; available to broker.
              taker:
                type: object
                properties:
                  state:
                    type: string
                    description: 'State of the request from the taker side: `initial`, `approved`, or `rejected`.'
                  client_id:
                    type: integer
                    description: ID of a client; available to broker. Represents a group of users under a common name.
                  user_id:
                    type: string
                    description: Obscured user id of the taker.
                  client_name:
                    type: string
                    description: Name of the client; available to broker.
                  client_link_name:
                    type: string
                    description: Name of the linked user within the client; available to broker.
                  client_link_id:
                    type: integer
                    description: ID assigned to a single user in a client; available to broker.
              nonce:
                type: string
                description: Nonce for approving or rejecting the broker block trade request.
      required:
      - jsonrpc
      - result
      type: object
    block_trade_signature:
      example: 1565173369982.1M9tO0Q-.z9n9WyZUU5op9pEz6Jtd2CI71QxQMMsCZAexnIfK9HQRT1pKH3clxeIbY7Bqm-yMcWIoE3IfCDPW5VEdiN-6oS0YkKUyXPD500MUf3ULKhfkmH81EZs
      type: string
      description: Signature of block trade<br>It is valid only for 5 minutes around given timestamp
    price:
      type: number
      description: Price in base currency
    role:
      enum:
      - maker
      - taker
      type: string
      description: 'Trade role of the user: `maker` or `taker`'
    instrument_name:
      example: BTC-PERPETUAL
      type: string
      description: Unique instrument identifier
    PrivateSimulateBlockTradeResponse:
      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: boolean
          description: '`true` if block trade can be executed, `false` otherwise'
      required:
      - jsonrpc
      - result
      type: object
    PrivateGetBlockTradeResponse:
      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/block_trade'
      required:
      - jsonrpc
      - result
      type: object
    user_trade:
      properties:
        trade_id:
          $ref: '#/components/schemas/trade_id'
        trade_seq:
          $ref: '#/components/schemas/trade_seq'
        instrument_name:
          $ref: '#/components/schemas/instrument_name'
        timestamp:
          $ref: '#/components/schemas/trade_timestamp'
        order_type:
          type: string
          enum:
          - limit
          - market
          - liquidation
          description: 'Order type: `"limit`, `"market"`, or `"liquidation"`'
        advanced:
          type: string
          enum:
          - usd
          - implv
          description: 'Advanced type of user order: `"usd"` or `"implv"` (only for options; omitted if not applicable)'
        order_id:
          type: string
          description: Id of the user order (maker or taker), i.e. subscriber's order id that took part in the trade
        matching_id:
          type: string
          description: Always `null`
        direction:
          $ref: '#/components/schemas/direction'
          description: Trade direction of the taker
        tick_direction:
          $ref: '#/components/schemas/tick_direction'
        index_price:
          type: number
          description: Index Price at the moment of trade
        price:
          $ref: '#/components/schemas/price'
          description: The price of the trade
        amount:
          type: number
          description: Trade amount. For perpetual and inverse futures the amount is in USD units. For options and linear futures it is the underlying base currency coin.
        contracts:
          type: number
          description: Trade size in contract units (optional, may be absent in historical trades)
        iv:
          type: number
          description: Option implied volatility for the price (Option only)
        underlying_price:
          type: number
          description: Underlying price for implied volatility calculations (Options only)
        liquidation:
          type: string
          enum:
          - M
          - T
          - MT
          description: 'Optional field (only for trades caused by liquidation): `"M"` when maker side of trade was under liquidation, `"T"` when taker side was under liquidation, `"MT"` when both sides of trade were under liquidation'
        liquidity:
          type: string
          enum:
          - M
          - T
          description: 'Describes what was role of users order: `"M"` when it was maker order, `"T"` when it was taker order'
        fee:
          type: number
          description: User's fee in units of the specified `fee_currency`
        fee_currency:
          $ref: '#/components/schemas/currency'
        label:
          $ref: '#/components/schemas/label_presentation'
        state:
          $ref: '#/components/schemas/order_state_in_user_trade'
        block_trade_id:
          $ref: '#/components/schemas/block_trade_id_in_result'
        block_rfq_id:
          type: integer
          description: ID of the Block RFQ - when trade was part of the Block RFQ
        block_rfq_quote_id:
          type: integer
          description: ID of the Block RFQ quote - when trade was part of the Block RFQ
        reduce_only:
          type: string
          description: '`true` if user order is reduce-only'
        post_only:
          type: string
          description: '`true` if user order is post-only'
        mmp:
          type: boolean
          description: '`true` if user order is MMP'
        risk_reducing:
          type: boolean
          description: '`true` if user order is marked by the platform as a risk reducing order (can apply only to orders placed by PM users)'
        api:
          type: boolean
          description: '`true` if user order was created with API'
        profit_loss:
          $ref: '#/components/schemas/profit_loss'
        mark_price:
          type: number
          description: Mark Price at the moment of trade
        legs:
          type: array
          description: Optional field containing leg trades if trade is a combo trade (present when querying for **only** combo trades and in `combo_trades` events)
        combo_id:
          type: string
          description: Optional field containing combo instrument name if the trade is a combo trade
        combo_trade_id:
          type: number
          description: Optional field containing combo trade identifier if the trade is a combo trade
        quote_set_id:
          type: string
          description: QuoteSet of the user order (optional, present only for orders placed with `private/mass_quote`)
        quote_id:
          type: string
          description: QuoteID of the user order (optional, present only for orders placed with `private/mass_quote`)
        trade_allocations:
          type: array
          items:
            type: object
            properties:
              user_id:
                type: integer
                description: User ID to which part of the trade is allocated. For brokers the User ID is obstructed.
              amount:
                type: number
                description: Amount allocated to this user.
              fee:
                type: number
                description: Fee for the allocated part of the trade.
              client_info:
                type: object
                properties:
                  client_id:
                    type: integer
                    description: ID of a client; available to broker. Represents a group of users under a common name.
                  client_link_id:
                    type: integer
                    description: ID assigned to a single user in a client; available to broker.
                  name:
                    type: string
                    description: Name of the linked user within the client; available to broker.
                description: Optional client allocation info for brokers.
            required:
            - amount
            - fee
          description: List of allocations for Block RFQ pre-allocation. Each allocation specifies `user_id`, `amount`, and `fee` for the allocated part of the trade. For broker client allocations, a `client_info` object will be included.
      required:
      - trade_id
      - trade_seq
      - instrument_name
      - timestamp
      - order_id
      - matching_id
      - direction
      - tick_direction
      - index_price
      - price
      - amount
      - fee
      - fee_currency
      - state
      - mark_price
      type: object
    trade_seq:
      type: integer
      description: The sequence number of the trade within instrument
  responses:
    PrivateGetBlockTradesResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrivateGetBlockTradesResponse'
          examples:
            response:
              value:
                jsonrpc: '2.0'
                result:
                - trades:
                  - trade_seq: 4
                    trade_id: '92462'
                    timestamp: 1565093070164
                    tick_direction: 2
                    state: filled
                    price: 0.0151
                    order_type: limit
                    order_id: '343121'
                    matching_id: null
                    liquidity: M
                    iv: 72.38
                    instrument_name: BTC-9AUG19-11500-P
                    index_price: 11758.65
                    fee_currency: BTC
                    fee: 0
                    direction: sell
                    block_trade_id: '66'
                    amount: 2.3
                  - trade_seq: 41
                    trade_id: '92460'
                    timestamp: 1565093070164
                    tick_direction: 2
                    state: filled
                    price: 11753
                    order_type: limit
                    order_id: '343117'
                    matching_id: null
                    liquidity: M
                    instrument_name: BTC-9AUG19
                    index_price: 11758.65
                    fee_currency: BTC
                    fee: 0
                    direction: sell
                    block_trade_id: '66'
                    amount: 50
                  timestamp: 1565093070165
                  id: '66'
              description: Response example
      description: Success response
    PrivateGetBlockTradeRequestsResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrivateGetBlockTradeRequestsResponse'
          examples:
            response:
              value:
                jsonrpc: '2.0'
                id: 1
                result:
                - timestamp: 1742824052538
                  state:
                    timestamp: 1742824052539
                    value: initial
                  username: Trader
                  user_id: 8
                  role: taker
                  trades:
                  - amount: 100000
                    direction: buy
                    price: 87516.83
                    instrument_name: BTC-PERPETUAL
                  broker_code: jpqYKgg1
                  broker_name: Test Broker
                  counterparty_state:
                    timestamp: 1742824052538
                    value: approved
                  nonce: 29rKkuD3NSBPet4njrpNWEuHBm9s
              description: Response example
      description: Success response
    PrivateSimulateBlockTradeResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrivateSimulateBlockTradeResponse'
          examples:
            response:
              value:
                jsonrpc: '2.0'
                result: true
              description: Response example
      description: Success response
    PrivateGetBrokerTradesResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrivateGetBrokerTradesResponse'
          examples:
            response:
              value:
                jsonrpc: '2.0'
                id: 1
                result:
                  history:
                  - id: BLOCK-7
                    timestamp: 1747239767111
                    trades:
                    - timestamp: 1747239767111
                      amount: 100000
                      direction: buy
                      price: 102079.75
                      index_price: 102079.75
                      instrument_name: BTC-PERPETUAL
                      trade_seq: 7
                      mark_price: 102079.75
                      tick_direction: 1
                      contracts: 10000
                      trade_id: '7'
                      block_trade_id: BLOCK-7
                      block_trade_leg_count: 1
                    maker:
                      user_id: '****009'
                      client_id: 2
                      client_name: Test Client 2
                      client_link_name: Test Client 2 l
                      client_link_id: 2
                    taker:
                      user_id: '****008'
                      client_id: 1
                      client_name: Test Client 1
                      client_link_name: Test Client 1 l
                      client_link_id: 1
                  next_start_id: 6
              description: Response example
      description: Success response
    PrivateGetBlockTradeResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrivateGetBlockTradeResponse'
          examples:
            response:
              value:
                jsonrpc: '2.0'
                result:
                  trades:
                  - trade_seq: 37
                    trade_id: '92437'
                    timestamp: 1565089523719
                    tick_direction: 3
                    state: filled
                    price: 0.0001
                    order_type: limit
                    order_id: '343062'
                    matching_id: null
                    liquidity: T
                    iv: 0
                    instrument_name: BTC-9AUG19-10250-C
                    index_price: 11738
                    fee_currency: BTC
                    fee: 0.00025
                    direction: sell
                    block_trade_id: '61'
                    amount: 10
                  - trade_seq: 25350
                    trade_id: '92435'
                    timestamp: 1565089523719
                    tick_direction: 3
                    state: filled
                    price: 11590
                    order_type: limit
                    order_id: '343058'
                    matching_id: null
                    liquidity: T
                    instrument_name: BTC-PERPETUAL
                    index_price: 11737.98
                    fee_currency: BTC
                    fee: 1.64e-06
                    direction: buy
                    block_trade_id: '61'
                    amount: 190
                  timestamp: 1565089523720
                  id: '61'
              description: Response example
      description: Success response
    PrivateGetBrokerTradeRequestsResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrivateGetBrokerTradeRequestsResponse'
          examples:
            response:
              value:
                jsonrpc: '2.0'
                id: 7
                result:
                - timestamp: 1742824052547
                  state: activated
                  trades:
                  - amount: 100000
                    direction: buy
                    price: 87516.83
                    instrument_name: BTC-PERPETUAL
                  maker:
                    state: initial
                    client_id: 1
                    user_id: '***009'
                    client_name: Test Client
                    client_link_name: Test Client 2
                    client_link_id: 2
                  taker:
                    state: initial
                    client_id: 1
                    user_id: '***008'
                    client_name: Test Client
                    client_link_name: Test Client 1
                    client_link_id: 1
                  nonce: 3WqPoAsmde9aXCSEBVUmi2XxGkgA
                - timestamp: 1742824052538
                  state: activated
                  trades:
                  - amount: 100000
                    direction: buy
                    price: 87516.83
                    instrument_name: BTC-PERPETUAL
                  maker:
                    state: approved
                    client_id: 1
                    user_id: '***009'
                    client_name: Test Client
                    client_link_name: Test Client 2
                    client_link_id: 2
                  taker:
                    state: initial
                    client_id: 1
                    user_id: '***008'
                    client_name: Test Client
                    client_link_name: Test Client 1
                    client_link_id: 1
                  nonce: 29rKkuD3NSBPet4njrpNWEuHBm9s
              description: Response example
      description: Success response
    OkResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OkResponse'
          examples:
            response:
              value:
                jsonrpc: '2.0'
                id: 1569
                result: ok
              description: Response example
      description: Success response
    PrivateVerifyBlockTradeResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrivateVerifyBlockTradeResponse'
          examples:
            response:
              value:
                jsonrpc: '2.0'
                result:
                  signature: 1565172710935.1ESE83qh.g6fbgRd4VWagaJz7xdi2WaV-q-d3J0njoz1jZavuRudZJZif9uH8XdUAx1LHsu0E3e0ZG_xe1UPYlwo41xRVrkWU6OMgygDRafUkEmBuk9iLqjc9rh4
              description: Response example
      description: Success response