Deriv Api Integration Guide: Setup, Endpoints, And Code

Building custom trading applications or automated bots on top of retail broker infrastructure requires direct programmatic access. The Deriv API lets developers connect third-party software, mobile apps, or web platforms directly to Deriv's trading engine using WebSockets and JSON-RPC. You can fetch live asset pricing, execute trades across forex, synthetic indices, and commodities, and manage user accounts programmatically without using the default web terminal.

Getting started requires understanding authentication flows, subscription patterns, and handling real-time data streams correctly. This breakdown covers setup, request architecture, practical implementation, and common integration pitfalls.

Getting Started With Deriv API Credentials

Before writing code, you need an account and an API token. Deriv manages programmatic access through token-based authentication tied to specific permission scopes (read, trade, payments, admin).

1. Log into your real or demo Deriv account.
2. Navigate to account settings and select API token.
3. Generate a token by checking the specific scopes your app requires. For a standard trading bot, you'll need read and trade permissions.
4. Copy the token string immediately. Store it securely in environment variables (.env) rather than hardcoding it into your repository.

Never expose tokens with payment or trade scopes in client-side front-end code. Route sensitive operations through a secure backend server. For another look on this event, check out the latest coverage from Reuters.

Understanding the WebSocket Protocol

Unlike traditional REST architectures that rely on HTTP request-response cycles for every data point, the Deriv API operates primarily over a persistent WebSocket connection. This protocol enables bi-directional communication, meaning the server can push price ticks and trade execution updates instantly to your application.

The base WebSocket endpoint for Deriv is:

wss://ws.derivws.com/websockets/v3?app_id=YOUR_APP_ID

You must obtain a registered app_id from your Deriv dashboard, though testing can often begin with default placeholder IDs provided in developer documentation. Every message sent to the server must be a JSON string formatted as a JSON-RPC request, containing a msg_type and optional parameters.

Basic Connection and Authorization Example

Here is how a standard connection handshake works in Node.js or browser environments:

const WebSocket = require('ws');
const ws = new WebSocket('wss://ws.derivws.com/websockets/v3?app_id=1089');

ws.on('open', function open() {
    // Send authorization request right after opening connection
    const authRequest = {
        authorize: "YOUR_API_TOKEN_HERE"
    };
    ws.send(JSON.stringify(authRequest));
});

ws.on('message', function incoming(data) {
    const response = JSON.parse(data);
    
    if (response.msg_type === 'authorize') {
        if (response.error) {
            console.error("Authorization failed:", response.error.message);
        } else {
            console.log("Successfully logged in as:", response.authorize.email);
            subscribeToTicks(ws);
        }
    }
});

Core API Endpoints and Subscriptions

The Deriv API uses command-based message requests rather than traditional URL paths. You send a JSON object with a specific command key, and the server replies with a matching message type.

1. Streaming Real-Time Price Ticks

To receive live price updates for an asset (like Volatility 75 Index or EUR/USD), send a subscription request. Adding "subscribe": 1 tells the server to push updates every time a new tick occurs.

{
    "ticks": "R_75",
    "subscribe": 1
}

To stop receiving updates, take the id returned in the subscription response and send a forget request:

{
    "forget": "12345678-abcd-1234-ef00-123456789abc"
}

2. Executing Trades

Placing a contract programmatically involves sending the buy command along with parameters defining the contract type, stake amount, currency, and duration.

{
    "buy": 1,
    "price": 10,
    "parameters": {
        "amount": 10,
        "basis": "stake",
        "currency": "USD",
        "duration": 5,
        "duration_unit": "m",
        "symbol": "R_75",
        "contract_type": "CALL"
    }
}

Common Integration Mistakes to Avoid

• Ignoring Connection Drops: WebSockets drop due to network jitter or server timeouts. Always implement automatic reconnection logic with exponential backoff.
• Hardcoding App IDs and Tokens: Committing API secrets to public version control repositories leads to compromised accounts. Use environment configuration managers.
• Failing to Handle Rate Limits: Sending dozens of requests per second without throttling will trigger API bans. Check response headers and implement local queue management for high-frequency scripts.
• Assuming Synchronous Execution: Because ticks and trade confirmations arrive asynchronously, don't write blocking sequential code expecting immediate return values. Use async/await patterns tied to message IDs.

Frequently Asked Questions

Can I use Deriv API with Python?

Yes. You can use standard libraries like websockets or asyncio to establish persistent connections, authorize your account, and parse incoming JSON streams.

Is there a sandbox environment for testing?

Yes. You can register a free demo account on Deriv, generate a demo API token, and test all trading operations without risking real capital.

What is the maximum request rate allowed?

Deriv enforces rate limits per IP address and app ID to prevent system abuse. Exceeding these limits results in temporary connection throttling or IP blacklisting.

Do I need a web server to use the API?

Not necessarily for client-side web apps, but building automated trading bots or background workers is much safer when run on a dedicated backend server or cloud instance.