Technical Migration Guide

​

HTTP API

• Envelope. Responses follow JSON-RPC: a top-level result or error object plus the request ID, not a bare REST body.
• Numeric values. Send prices and sizes as JSON numbers, and expect them back as JSON numbers. This differs from the Coinbase spot API, which encodes decimals as decimal strings.
• Order size. amount is in the base coin for spot, options, and linear instruments — including the USDC-settled perpetuals used here, so amount: 0.001 is 0.001 of the base coin. It is in USD only for inverse futures and inverse perpetuals. Pass contracts instead to specify contract units.
• Client order ID. Carried in the label field, not a dedicated client-order-ID field. Unlike client_order_id today, label is not guaranteed unique, so don’t rely on it as an idempotency key.
• Instrument names. Instrument names replace the old symbol field and use a new format (see below).

​

WebSocket API

• Two hosts. Public market data is public/subscribe on the streams host. HTTP methods and authenticated order flow are on the main WebSocket. Authenticate by calling public/auth after connecting; the socket then stays authenticated, and you re-send public/auth on it before the session expires.
• Subscriptions. Subscribe to channels by name. Market-data channels cover the order book, ticker, trades, and charts; private channels cover your orders, position changes, and portfolio.
• Cancel on Disconnect (CoD). An opt-in safety mechanism: your orders auto-cancel if the connection drops.
• Heartbeats. The server sends periodic test requests that your client must answer to keep the connection alive. You set the heartbeat interval from public/set_heartbeat.

​

Symbology

​

Authentication

​

Auth example

// public/auth — exchange your CDP key for an access token
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "public/auth",
  "params": { "grant_type": "coinbase_cdp", "token": "<signed_cdp_jwt>" }
}

// To trade, send the returned access token in the Authorization: Bearer <access_token> header
// (for websockets the channel is authenticated, see below)
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "private/buy",
  "params": {
    "instrument_name": "BTC_USDC-PERPETUAL",
    "amount": 0.001,
    "type": "limit",
    "price": 65000.5
  }
}

• HTTP
• WebSocket

• You create a JWT, no round-trip to Coinbase. See creating a JWT.
• It lasts only ~120s, use a fresh JWT for every public/auth call.
• You need to provide the Deribit access token on each private method call.
• Refresh the Deribit access token every 15 minutes.

• You create a JWT, no round-trip to Coinbase. See creating a JWT.
• It lasts only ~120s, use a fresh JWT for every public/auth call.
• When you call public/auth that authorizes the websocket session, no return token is needed to access private methods.
• Refresh the websockets authentication before it expires (~50 minutes).

​

Attaching a Take Profit / Stop Loss (OTOCO)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "private/buy",
  "params": {
    "instrument_name": "BTC_USDC-PERPETUAL",
    "amount": 0.1,
    "type": "limit",
    "price": 60000,
    "linked_order_type": "one_triggers_one_cancels_other",
    "otoco_config": [
      { "type": "take_limit",  "direction": "sell", "amount": 0.1, "price": 65000, "trigger": "last_price" },
      { "type": "stop_market", "direction": "sell", "amount": 0.1, "trigger_price": 55000, "trigger": "mark_price" }
    ]
  }
}

​

Endpoint mapping

​

FAQ