Deriv API

Complete Workflows

End-to-end examples of common trading workflows using the Deriv API

Authentication Workflow

Steps:

  1. Connect to WebSocket endpoint
  2. Send get_session_token request with one-time token
  3. Receive session token in response
  4. Send authorize request with session token
  5. Receive authorization confirmation
  6. Connection is now authorized for trading operations
authentication.js
javascript
1const ws = new WebSocket('wss://ws.binaryws.com/websockets/v3');
2
3ws.onopen = () => {
4  // Step 1: Get session token
5  ws.send(JSON.stringify({
6    get_session_token: "YOUR_ONE_TIME_TOKEN",
7    req_id: 1
8  }));
9};
10
11ws.onmessage = (msg) => {
12  const data = JSON.parse(msg.data);
13  
14  // Step 2: Authorize with session token
15  if (data.msg_type === 'get_session_token') {
16    ws.send(JSON.stringify({
17      authorize: data.get_session_token.token,
18      req_id: 2
19    }));
20  }
21  
22  // Step 3: Now authenticated!
23  if (data.msg_type === 'authorize') {
24    console.log('Authenticated:', data.authorize.loginid);
25    // Ready to make authenticated requests
26  }
27};

Complete Trading Workflow

Steps:

  1. Establish connection and authenticate
  2. Get active symbols using active_symbols
  3. Subscribe to tick stream for chosen symbol using ticks
  4. Get contract proposal using proposal (with subscribe)
  5. Monitor real-time price updates
  6. When ready, buy contract using buy
  7. Subscribe to contract updates using proposal_open_contract
  8. Monitor contract status in real-time
  9. Optionally sell early using sell
  10. Check portfolio using portfolio
trading-workflow.js
javascript
1// After authentication...
2
3// 1. Get active symbols
4ws.send(JSON.stringify({
5  active_symbols: "brief",
6  req_id: 3
7}));
8
9// 2. Subscribe to ticks
10ws.send(JSON.stringify({
11  ticks: "1HZ100V",
12  subscribe: 1,
13  req_id: 4
14}));
15
16// 3. Get price proposal
17ws.send(JSON.stringify({
18  proposal: 1,
19  amount: 10,
20  basis: "stake",
21  contract_type: "MULTDOWN",
22  currency: "USD",
23  duration_unit: "s",
24  multiplier: 10,
25  underlying_symbol: "1HZ100V",
26  subscribe: 1,
27  req_id: 5
28}));
29
30// 4. Buy the contract (when ready)
31// Use proposal ID from previous response
32ws.send(JSON.stringify({
33  buy: "PROPOSAL_ID_HERE",
34  price: 100,
35  req_id: 6
36}));
37
38// 5. Monitor contract status
39ws.send(JSON.stringify({
40  proposal_open_contract: 1,
41  contract_id: CONTRACT_ID,
42  subscribe: 1,
43  req_id: 7
44}));

Market Data Workflow

Steps:

  1. Connect to WebSocket (no auth needed)
  2. Request active_symbols to see available markets
  3. Subscribe to ticks for real-time price updates
  4. Optionally get ticks_history for historical data
  5. Use contracts_for to see available contract types
  6. Stream continues until forget or disconnect
market-data.js
javascript
1const ws = new WebSocket('wss://ws.binaryws.com/websockets/v3');
2
3ws.onopen = () => {
4  // Get available symbols
5  ws.send(JSON.stringify({
6    active_symbols: "brief",
7    product_type: "basic",
8    req_id: 1
9  }));
10  
11  // Subscribe to tick stream
12  ws.send(JSON.stringify({
13    ticks: "1HZ100V",
14    subscribe: 1,
15    req_id: 2
16  }));
17  
18  // Get historical data
19  ws.send(JSON.stringify({
20    ticks_history: "1HZ100V",
21    count: 100,
22    end: "latest",
23    style: "ticks",
24    req_id: 3
25  }));
26};
27
28ws.onmessage = (msg) => {
29  const data = JSON.parse(msg.data);
30  
31  if (data.msg_type === 'active_symbols') {
32    console.log('Available symbols:', data.active_symbols);
33  }
34  
35  if (data.msg_type === 'tick') {
36    console.log('Current price:', data.tick.quote);
37    // Update your chart here
38  }
39  
40  if (data.msg_type === 'history') {
41    console.log('Historical data:', data.history);
42    // Initialize your chart here
43  }
44};

Common Patterns

Subscription Management
How to manage WebSocket subscriptions effectively
  • Always store subscription IDs
  • Use forget to unsubscribe
  • Use forget_all to clear all
  • Clean up subscriptions before disconnect
Error Handling
Best practices for handling API errors
  • Always check for error field
  • Implement exponential backoff for retries
  • Log errors with context
  • Handle network disconnections gracefully
Request IDs
How to track requests and responses
  • Use unique req_id for each request
  • Match responses using req_id
  • Helps with concurrent requests
  • Essential for debugging
Connection Lifecycle
Managing WebSocket connection state
  • Handle onopen, onclose, onerror
  • Implement auto-reconnect logic
  • Re-authenticate after reconnect
  • Restore subscriptions on reconnect