Quickstart Guide

Welcome to the Deribit API! This guide will help you make your first API call in minutes.

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.

1. Get API Credentials

   1. Log in to your Deribit account at www.deribit.com or test.deribit.com for testing
   2. Navigate to Account → API
   3. Create a new API key with appropriate permissions
   4. 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

2. Choose Your Interface

   HTTP (Simplest)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"
   

   WebSocket (Recommended)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));
   });
   

   FIX APIBest for: Institutional trading, high-frequency trading

   See the FIX API documentation for details.

3. 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

   # 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"
     }
   }
   

   WebSocket Authentication

   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

4. Make Your First Requests

   Public Data (No Auth)

   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"
   

   Private Data (Auth Required)

   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"
   

   WebSocket Subscriptions

   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);
     }
   });
   
5. Place a Test Order (Testnet Only)

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

   HTTP

   # 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"
   

   WebSocket

   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
   }));