Quickstart Guide

Deribit provides three different interfaces to access the API:

JSON-RPC over WebSocket (recommended) - Real-time, bidirectional communication
JSON-RPC over HTTP - Simple REST-like interface
FIX API - Financial Information eXchange protocol for institutional trading

All examples in this documentation use the test environment (test.deribit.com). To use production, change the URLs to www.deribit.com. Test and production environments are separate and require different accounts and API keys.

Get API Credentials

Log in to your Deribit account at www.deribit.com or test.deribit.com for testing
Navigate to Account → API
Create a new API key with appropriate permissions
Save your Client ID and Client Secret securely

Never share your API credentials or commit them to version control. The client secret is only shown once and cannot be retrieved later.

Creating API Keys

Step-by-step guide to creating API keys

Asymmetric API Keys

Using Ed25519 or RSA key pairs for enhanced security

Choose Your Interface

HTTP (Simplest)
WebSocket (Recommended)
FIX API

Best for: Simple scripts, one-off requests, testing

# Get market data (no authentication required)
curl -X GET "https://test.deribit.com/api/v2/public/get_instruments?currency=BTC&kind=future"

Best for: Real-time data, subscriptions, trading bots

const WebSocket = require('ws');
const ws = new WebSocket('wss://test.deribit.com/ws/api/v2');

ws.on('open', function open() {
  // Subscribe to order book updates
  ws.send(JSON.stringify({
    "jsonrpc": "2.0",
    "method": "public/subscribe",
    "params": {
      "channels": ["book.BTC-PERPETUAL.100ms"]
    },
    "id": 1
  }));
});

ws.on('message', function incoming(data) {
  console.log(JSON.parse(data));
});

Authenticate

For private methods, you need to authenticate. Deribit supports multiple authentication methods:

Client Credentials - Standard OAuth 2.0 flow
Client Signature - User generated signature
Refresh Token - Token renewal

HTTP Authentication
WebSocket Authentication

# Get access token using Client Credentials
curl -X GET "https://test.deribit.com/api/v2/public/auth" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "expires_in": 31536000,
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "scope": "account:read trade:read",
    "token_type": "bearer"
  }
}

const WebSocket = require('ws');
const ws = new WebSocket('wss://test.deribit.com/ws/api/v2');

ws.on('open', function open() {
  // Authenticate
  ws.send(JSON.stringify({
    "jsonrpc": "2.0",
    "method": "public/auth",
    "params": {
      "grant_type": "client_credentials",
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET"
    },
    "id": 1
  }));
});

ws.on('message', function incoming(data) {
  const response = JSON.parse(data);
  if (response.result && response.result.access_token) {
    console.log('Authenticated! Access token:', response.result.access_token);
    // Now you can make private method calls
  }
});

Access Scopes

Learn more about API permissions and access scopes

Make Your First Requests

Public Data (No Auth)
Private Data (Auth Required)
WebSocket Subscriptions

Get Market Data

# Get all BTC futures
curl -X GET "https://test.deribit.com/api/v2/public/get_instruments?currency=BTC&kind=future"

# Get ticker for BTC-PERPETUAL
curl -X GET "https://test.deribit.com/api/v2/public/ticker?instrument_name=BTC-PERPETUAL"

# Get order book
curl -X GET "https://test.deribit.com/api/v2/public/get_order_book?instrument_name=BTC-PERPETUAL&depth=5"

Get Account Information

# Get account summary
curl -X GET "https://test.deribit.com/api/v2/private/get_account_summary?currency=BTC" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get open orders
curl -X GET "https://test.deribit.com/api/v2/private/get_open_orders?currency=BTC" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Subscribe to Real-Time Data

const WebSocket = require('ws');
const ws = new WebSocket('wss://test.deribit.com/ws/api/v2');

ws.on('open', function open() {
  // Subscribe to multiple channels
  ws.send(JSON.stringify({
    "jsonrpc": "2.0",
    "method": "public/subscribe",
    "params": {
      "channels": [
        "book.BTC-PERPETUAL.100ms",
        "ticker.BTC-PERPETUAL.100ms",
        "trades.BTC-PERPETUAL.100ms"
      ]
    },
    "id": 1
  }));
});

ws.on('message', function incoming(data) {
  const message = JSON.parse(data);
  if (message.method === 'subscription') {
    console.log('Update:', message.params.channel, message.params.data);
  }
});

Place a Test Order (Testnet Only)

Only use test.deribit.com for testing. Never test with real funds on production.

HTTP
WebSocket

# Place a limit buy order (testnet)
curl -X GET "https://test.deribit.com/api/v2/private/buy" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d "instrument_name=BTC-PERPETUAL" \
  -d "amount=10" \
  -d "type=limit" \
  -d "price=50000"

ws.send(JSON.stringify({
  "jsonrpc": "2.0",
  "method": "private/buy",
  "params": {
    "instrument_name": "BTC-PERPETUAL",
    "amount": 10,
    "type": "limit",
    "price": 50000,
    "access_token": "YOUR_ACCESS_TOKEN"
  },
  "id": 2
}));

Introduction

Authentication

Technical Information

Best Practices

Guides

Creating API Keys

Asymmetric API Keys

Access Scopes