Skip to main content
Voice Broker Trading enables a licensed broker to execute block trades on behalf of two client counterparties in a single API call — no signature exchange between clients is required. Trades are block trades and appear with broker_name and broker_code fields in each client’s trade history.
Broker accounts must be enabled by Deribit staff. Authentication is required for all private methods — see the Authentication Guide.

​
Key Concepts

  • Broker Code — a unique string identifying a broker client (counterparty group). Multiple users from the same client group can link using the same code. Trades carry this code, allowing clients to filter their history by broker.
  • Client / Client Link — the broker identifies each side of a trade by client_id (counterparty group) and client_link_id (specific linked user).
  • Trade Confirmations — each client link has a confirmations_required flag. When true (the default), the trade is held pending until the client approves it via API. The window is 10 minutes; expiry or rejection cancels the trade.

​
Broker: Execute a Trade

private/execute_broker_trade — Scope: block_trade:read_write Submits both sides in one call. direction is always from the maker’s perspective. 
{
  "jsonrpc": "2.0",
  "method": "private/execute_broker_trade",
  "id": 1,
  "params": {
    "maker": { "client_id": 2, "client_link_id": 3 },
    "taker": { "client_id": 1, "client_link_id": 1 },
    "trades": [
      {
        "instrument_name": "BTC-PERPETUAL",
        "direction": "buy",
        "price": 102000.0,
        "amount": 100000
      }
    ]
  }
}
ParameterRequiredDescription
maker / takerNoClient info for each side. Omit to leave that side unregistered.
maker.client_id, taker.client_idYes (if side provided)Broker’s client ID.
maker.client_link_id, taker.client_link_idYes (if side provided)Specific linked user within that client.
trades[]YesUp to 20 legs. Each requires instrument_name, direction, price, amount.
If no confirmations are required, the response is a completed block trade with id, timestamp, trades[], and maker/taker objects containing client_id, client_link_id, client_name, client_link_name, confirmations_required, and an obscured user_id (e.g. ***123). If confirmations are required, the response is a pending trade request: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "timestamp": 1747239767111,
    "nonce": "3WqPoAsmde9aXCSEBVUmi2XxGkgA",
    "request_state": "pending",
    "expires_at": 1747240367111,
    "trades": [
      {
        "instrument_name": "BTC-PERPETUAL",
        "direction": "buy",
        "price": 102000.0,
        "amount": 100000
      }
    ],
    "maker": {
      "client_id": 2,
      "client_link_id": 3,
      "client_name": "Acme Capital",
      "client_link_name": "Acme Capital 1",
      "user_id": "***123",
      "confirmations_required": true,
      "state": { "value": "initial", "timestamp": 1747239767111 }
    },
    "taker": {
      "client_id": 1,
      "client_link_id": 1,
      "client_name": "Beta Fund",
      "client_link_name": "Beta Fund 1",
      "user_id": "***456",
      "confirmations_required": true,
      "state": { "value": "initial", "timestamp": 1747239767111 }
    }
  }
}
Side state.value: initial → approved / rejected. The trade executes once all required approvals are received.

​
Broker: Cancel a Pending Trade

private/cancel_broker_trade_request — Scope: block_trade:read_write Cancels a pending trade using the nonce and timestamp from the execute response. 
{
  "jsonrpc": "2.0",
  "method": "private/cancel_broker_trade_request",
  "id": 2,
  "params": {
    "timestamp": 1747239767111,
    "nonce": "3WqPoAsmde9aXCSEBVUmi2XxGkgA"
  }
}

​
Broker: Monitor Pending Requests

private/get_broker_trade_requests — Scope: block_trade:read Returns an array of all pending (and recently settled) broker trade requests with current per-side states. Takes no parameters. WebSocket: subscribe to broker.trade_requests.{currency} for real-time updates on every state change.

​
Broker: Trade History

private/get_broker_trades — Scope: block_trade:read 
{
  "jsonrpc": "2.0",
  "method": "private/get_broker_trades",
  "id": 3,
  "params": {
    "currency": "BTC",
    "count": 10
  }
}
ParameterDescription
currencyFilter by currency. Omit for all.
countResults per page (default 10, max 50).
start_id / end_idPaginate by block trade ID.
start_timestamp / end_timestampPaginate by time (ms). Cannot combine with ID pagination.
continuationOpaque token returned when using timestamp pagination.
Response: { "history": [...], "next_start_id": 41 }. Pass next_start_id as start_id for the next page (null = no more results). Each entry includes id, timestamp, trades[], and maker/taker with client info and obscured user_id.

​
Client: Approve or Reject a Pending Trade

When confirmations_required = true, the client is notified and must act within 10 minutes. Subscribe to block_trade_confirmations for real-time notifications. The notification data includes timestamp, nonce, role (maker or taker), broker_name, broker_code, trades[], and state. Poll pending trades with private/get_block_trade_requests — pass broker_code to filter broker-only requests.

​
Approve

{
  "jsonrpc": "2.0",
  "method": "private/approve_block_trade",
  "id": 4,
  "params": {
    "timestamp": 1747239767111,
    "nonce": "3WqPoAsmde9aXCSEBVUmi2XxGkgA",
    "role": "maker"
  }
}

​
Reject

{
  "jsonrpc": "2.0",
  "method": "private/reject_block_trade",
  "id": 5,
  "params": {
    "timestamp": 1747239767111,
    "nonce": "3WqPoAsmde9aXCSEBVUmi2XxGkgA",
    "role": "maker"
  }
}
If confirmations_shared = true on the client link, any sub-account in the same client group may approve or reject — not just the originally linked user.

​
Client: Trade History

Broker trades appear in regular block trade history. Filter by broker using the broker_code parameter on private/get_block_trades. Each broker trade includes broker_name and broker_code fields.

​
Notes

  • Obscured user IDs — brokers see only the last 3 digits of a client’s user ID (e.g. ***123).
  • Self-trading — the same Deribit user cannot be both maker and taker.
  • KYC — both clients must be verified for block trading.
  • Account locks / settlement proximity — trades fail if a client account is locked for the traded currency, or if the instrument is too close to expiry.

​
Common Errors

ErrorCause
user_not_a_brokerAccount is not enabled as a voice broker.
not_connectedClient link is not in connected state.
not_verifiedClient’s KYC level is insufficient for block trading.
not_a_clientclient_id does not exist or doesn’t belong to this broker.
same_client_id / self_tradeMaker and taker are the same client or user.
min_block_trade_limitAmount is below the minimum block trade size.
too_close_to_settlementInstrument expires too soon.
account_lockedClient account is locked for the traded currency.
Broker: private/execute_broker_trade · private/cancel_broker_trade_request · private/get_broker_trade_requests · private/get_broker_trades Client: private/get_block_trade_requests · private/approve_block_trade · private/reject_block_trade · private/get_block_trades WebSocket: block_trade_confirmations · broker.trade_requests.{currency}