WebSockets

POST

Auth required

Get a WebSocket URL via OTP and connect for real-time Options trading

Endpoint

POST

/trading/v1/options/accounts/{accountId}/otp

Base URL: https://api.derivws.com

Request & Response

View Raw

Status Codes

200

OTP generated successfully — response contains the WebSocket URL

400

Bad request - Invalid account ID

401

Unauthorized - Invalid or missing Bearer token

500

Internal server error

Error Responses

The API returns structured error responses with detailed information about what went wrong.

400

Bad request

{
  "errors": [
    {
      "status": 400,
      "code": "ValidationError",
      "message": "Invalid account ID format"
    }
  ],
  "meta": {
    "endpoint": "/tenant/{tenant_id}/options/accounts/INVALID/otp",
    "method": "POST",
    "timing": 12
  }
}

401

Unauthorized

{
  "errors": [
    {
      "status": 401,
      "code": "Unauthorized",
      "message": "Invalid or missing authentication credentials"
    }
  ],
  "meta": {
    "endpoint": "/tenant/{tenant_id}/options/accounts/DOT90004580/otp",
    "method": "POST",
    "timing": 45
  }
}

500

Internal server error

{
  "errors": [
    {
      "status": 500,
      "code": "InternalError",
      "message": "Failed to generate OTP"
    }
  ],
  "meta": {
    "endpoint": "/tenant/{tenant_id}/options/accounts/DOT90004580/otp",
    "method": "POST",
    "timing": 234
  }
}

About websocket

The websocket endpoint get a websocket url via otp and connect for real-time options trading

Step 1: Get your WebSocket URL

Call the OTP endpoint with your Bearer token. The response contains a ready-to-use WebSocket URL that already includes the one-time password as a query parameter.

// Request OTP — returns a WebSocket URL
const response = await fetch(
  'https://api.derivws.com/trading/v1/options/accounts/DOT90004580/otp',
  {
    method: 'POST',
    headers: {
      'Deriv-App-ID': 'YOUR_APP_ID',
      'Authorization': 'Bearer YOUR_AUTH_TOKEN',
    },
  }
);
const { data } = await response.json();
// data.url === "wss://api.derivws.com/trading/v1/options/ws/demo?otp=abc123xyz789"

Step 2: Connect to the WebSocket

Use the URL returned in the previous step directly as your WebSocket endpoint. No additional authentication headers are needed — the OTP in the URL handles authentication.

// Connect using the URL from the OTP response
const ws = new WebSocket(data.url);

ws.onopen = () => {
  console.log('Connected to Options trading WebSocket');
  // You can now send trading commands
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('Received:', message);
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

OTP Lifetime

OTP tokens are short-lived and must be used immediately after generation. If the token expires before you connect, request a new one by calling the OTP endpoint again.

Public WebSocket (no auth)

For read-only public market data, you can connect to wss://api.derivws.com/trading/v1/options/ws/public directly without any authentication or OTP.