Quickstart Guide

Get started with the Deribit API — environment setup, first authenticated request, and key endpoints for placing your first order 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
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
   }));