# Deriv API quickstart: token to first REST call

Independent and unofficial. Not affiliated with or endorsed by any broker or platform named here. Educational only: nothing here is advice, and nothing here recommends a broker or a trade.

This is the markdown version of https://openbrokerapi.com/brokers/deriv/quickstart, written from the same records as that page.

Risk warning: CFDs and spread bets are complex instruments and come with a high risk of losing money rapidly due to leverage. You can lose money on these products, and each provider publishes its own loss figure under FCA rules. You should consider whether you understand how they work and whether you can afford to take the high risk of losing your money. Automated and API trading can amplify losses through bugs, connectivity failures and runaway orders.

Make a first Deriv REST call: a health check with no credentials, then your Options accounts with a bearer token, in Python, JavaScript or curl. Deriv's trading and market data run over WebSocket and are not covered here. The samples were written from Deriv's documentation and have not been run against Deriv.

- Checked: 2026-10-12

Unverified: the code on this page was written from the documentation and has not yet been run on a demo account.

Demo accounts only. Credentials are read from environment variables on your own machine. No field on this site asks for a key, a username or a password.

## Steps

### 1. What this page covers, and what it does not

Deriv splits its API in two. REST, on https://api.derivws.com, handles account creation and management. Trading itself (proposals, buy and sell) and live market data run over WebSocket. This quickstart covers the REST calls only, so it stops at reading your accounts and does not show a trade. Deriv says each user receives a default demo account at signup, so there is a demo account to read without creating one. You need a Deriv login and one of Python 3 with the requests package, Node 18 or later, or curl.

Status: verified. Source: [developers.deriv.com](https://developers.deriv.com/docs/intro/api-overview/), checked 2026-10-12.

### 2. A call with no credentials: the health check

GET /v1/health needs no authentication, no parameters and no body, so it tells you that your machine can reach Deriv's REST gateway before any token is involved. Deriv's page gives 200 as the reply status. The fields in the reply body were not read for this page, so the samples print the status and the raw body and nothing more.

Python:

```python
# No credentials are needed for this call.
# Written from Deriv's documentation. Not run against Deriv.
import requests

BASE_URL = "https://api.derivws.com"

resp = requests.get(BASE_URL + "/v1/health", timeout=10)
print("HTTP", resp.status_code)
print(resp.text)
```

JavaScript:

```javascript
// No credentials are needed for this call.
// Written from Deriv's documentation. Not run against Deriv.
// Node 18 or later. Save as a .mjs file so top level await works.
const BASE_URL = "https://api.derivws.com";

const res = await fetch(`${BASE_URL}/v1/health`, { method: "GET" });
console.log("HTTP", res.status);
console.log(await res.text());
```

curl:

```bash
# No credentials are needed for this call.
# Written from Deriv's documentation. Not run against Deriv.
curl -i "https://api.derivws.com/v1/health"
```

Status: verified. Source: [developers.deriv.com](https://developers.deriv.com/llms/health.md), checked 2026-10-12.

### 3. Choose how you will get a token

Deriv describes two routes. An OAuth 2.0 app sends the user to Deriv's sign in page and receives an access token without ever seeing a password. A Personal Access Token app has the user generate a token in Deriv and enter it into the application by hand. For a script that only you run, the Personal Access Token is the shorter route. The page opened for this step does not say where in Deriv the token is generated or where the application ID comes from, so those clicks are not given here: this site has not verified them. Whichever route you use, keep the token in an environment variable. The first authenticated call below needs a token carrying the trade scope.

Status: verified. Source: [developers.deriv.com](https://developers.deriv.com/docs/intro/authentication/), checked 2026-10-12.

### 4. Send the token as a bearer header

Every authenticated REST request carries Authorization: Bearer followed by the token, which may be an OAuth 2.0 access token or a Personal Access Token. With a Personal Access Token you must also send a Deriv-App-ID header holding your application ID. Leave it out and Deriv answers 401 with the message Deriv-App-ID header is required for PAT tokens. With an OAuth 2.0 token the header is not needed, because the token already identifies the application. Deriv names four scopes: trade, account_manage, payment and application_read. The samples read the token from DERIV_TOKEN and the application ID from DERIV_APP_ID.

Status: verified. Source: [developers.deriv.com](https://developers.deriv.com/llms/authentication.md), checked 2026-10-12.

### 5. First real call: list your Options accounts

GET /trading/v1/options/accounts lists your Options trading accounts. It is read only and Deriv lists the scope it needs as trade. The samples send both headers, which is what a Personal Access Token needs. If you are using an OAuth 2.0 token, remove the Deriv-App-ID line.

Python:

```python
# Set DERIV_TOKEN and DERIV_APP_ID as environment variables first. Never paste real values into code or into this site.
# Written from Deriv's documentation. Not run against Deriv.
import os
import requests

BASE_URL = "https://api.derivws.com"
headers = {
    "Authorization": "Bearer " + os.environ["DERIV_TOKEN"],
    "Deriv-App-ID": os.environ["DERIV_APP_ID"],  # needed with a Personal Access Token
}

resp = requests.get(BASE_URL + "/trading/v1/options/accounts", headers=headers, timeout=10)
print("HTTP", resp.status_code)
resp.raise_for_status()
for account in resp.json()["data"]:
    print(account["account_id"], account["account_type"], account["balance"], account["currency"], account["status"])
```

JavaScript:

```javascript
// Set DERIV_TOKEN and DERIV_APP_ID as environment variables first. Never paste real values into code or into this site.
// Written from Deriv's documentation. Not run against Deriv.
// Node 18 or later. Save as a .mjs file so top level await works.
const BASE_URL = "https://api.derivws.com";

const res = await fetch(`${BASE_URL}/trading/v1/options/accounts`, {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.DERIV_TOKEN}`,
    "Deriv-App-ID": process.env.DERIV_APP_ID // needed with a Personal Access Token
  }
});
console.log("HTTP", res.status);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const body = await res.json();
for (const account of body.data) {
  console.log(account.account_id, account.account_type, account.balance, account.currency, account.status);
}
```

curl:

```bash
# Set DERIV_TOKEN and DERIV_APP_ID as environment variables first. Never paste real values into code or into this site.
# Written from Deriv's documentation. Not run against Deriv.
# The Deriv-App-ID header is needed with a Personal Access Token.
curl -s "https://api.derivws.com/trading/v1/options/accounts" \
  -H "Authorization: Bearer $DERIV_TOKEN" \
  -H "Deriv-App-ID: $DERIV_APP_ID"
```

Status: verified. Source: [developers.deriv.com](https://developers.deriv.com/llms/get-accounts.md), checked 2026-10-12.

### 6. Read the reply

The reply is an object with two parts. data is a list, one entry per account, each with account_id, balance, currency, group, status (active or inactive) and account_type, which is demo or real. meta repeats the endpoint and the method and gives a timing figure. The field to read first is account_type: anything you do next should use the account_id of an entry whose account_type is demo. A token can see real accounts as well as demo ones, and no host name stands between the two on REST, so your code has to check.

Status: verified. Source: [developers.deriv.com](https://developers.deriv.com/llms/get-accounts.md), checked 2026-10-12.

### 7. The limits to respect

Deriv's limits page gives three REST figures: 300 requests a minute and 1,000 requests in 10 minutes per IP address, and 80 requests a minute per logged in user. Deriv says that once you are logged in you reach the 80 a minute limit first, and that spreading requests across several IP addresses does not raise it. The page opened does not say what reply comes back when a limit is passed. WebSocket calls have their own budgets, counted per connection, on the same page. This site's limits register holds one Deriv row, 80 a minute per logged in user on REST, with the status verified and a check date of 22 September 2026: it is in the table below this list.

Status: verified. Source: [developers.deriv.com](https://developers.deriv.com/docs/limits), checked 2026-10-12.

### 8. The errors you are likely to meet first

A REST error arrives as an object with an errors list and the same meta block as a success. Each entry in errors has a status, a code and a message, so print all three. Deriv's page gives 401 for a missing or invalid token or a missing Deriv-App-ID header, 403 for a valid token that lacks the scope, 400 for a request that fails validation and 429 for too many requests. The codes it lists include InvalidToken, Unauthorized, ValidationError, NotFound and RateLimit. Deriv's advice is to retry read only GET calls with a growing delay between attempts and not to retry trades blindly. This site keeps a page for each recorded Deriv code under /errors/deriv, linked in the block at the foot of this page.

Status: verified. Source: [developers.deriv.com](https://developers.deriv.com/llms/errors.md), checked 2026-10-12.

### 9. What to read next: the step to WebSocket

The bridge from REST to trading is POST /trading/v1/options/accounts/{accountId}/otp. It exchanges your bearer token for a one time WebSocket address for one account, with the one time password already in the address. Deriv's overview gives separate demo and real WebSocket endpoints, and the address you receive follows the account you asked for, which is one more reason to pass a demo account_id. How long the address stays usable was not on the page opened. What you send once connected and what arrives, from ticks and proposal to buy, sell, portfolio and balance, is recorded message by message on this site at /brokers/deriv/messages, so read those pages beside Deriv's own and keep to the demo account while you do.

Status: verified. Source: [developers.deriv.com](https://developers.deriv.com/llms/websocket.md), checked 2026-10-12.

## Sources

- Status: verified. Source: [Deriv API: API overview](https://developers.deriv.com/docs/intro/api-overview/), checked 2026-10-12.
- Status: verified. Source: [Deriv API: health check](https://developers.deriv.com/llms/health.md), checked 2026-10-12.
- Status: verified. Source: [Deriv API: authentication](https://developers.deriv.com/docs/intro/authentication/), checked 2026-10-12.
- Status: verified. Source: [Deriv API: authentication reference](https://developers.deriv.com/llms/authentication.md), checked 2026-10-12.
- Status: verified. Source: [Deriv API: get accounts](https://developers.deriv.com/llms/get-accounts.md), checked 2026-10-12.
- Status: verified. Source: [Deriv API: limits](https://developers.deriv.com/docs/limits), checked 2026-10-12.
- Status: verified. Source: [Deriv API: errors](https://developers.deriv.com/llms/errors.md), checked 2026-10-12.
- Status: verified. Source: [Deriv API: WebSocket and the one time password call](https://developers.deriv.com/llms/websocket.md), checked 2026-10-12.

## Deriv limits to pace against

- Headline limit: 80/min per logged in user (REST)
  - Scope: user, REST
  - Sources conflict: [developers.deriv.com](https://developers.deriv.com/llms/api-overview.md) states 60 REST requests per minute per token, checked 2026-10-12. Deriv's API overview in the text form it publishes for AI tools gives REST 60 requests a minute per token, where its Limits page gives 80 a minute per logged in user. The same overview also gives 100 WebSocket requests a second per connection, 100 active subscriptions per connection and 5 concurrent WebSocket connections per user, none of which the Limits page mentions. Deriv's own pages disagree; the conflict is labelled, not resolved. Pace against 60.
  - Status: conflicting. Source: [developers.deriv.com](https://developers.deriv.com/docs/limits/), checked 2026-10-12.
  - Note: From the Limits page: REST is also capped at 300 a minute and 1,000 per ten minutes per IP address. WebSocket budgets, each shared by the calls in its row, a minute and an hour: proposal, proposal_open_contract, buy and sell 360 and 14,400; balance and statement 100 and 2,000; portfolio and profit table 30 and 1,500; all other calls 220 and 14,400. ping sits outside these budgets at 10 a second per connection.

## Next on the Deriv API

- [Deriv API error codes](https://openbrokerapi.com/errors/deriv): 10 decoded, each with what it means, and the fix where the source gives one.
- [Deriv API endpoints](https://openbrokerapi.com/brokers/deriv/endpoints): 5 documented, each with its method, path, parameters and source.
- [Deriv messages](https://openbrokerapi.com/brokers/deriv/messages): 19 documented, each with its fields and source.
- [Deriv API page](https://openbrokerapi.com/brokers/deriv): The full record: access, authentication, limits and the source for each.

## Licence and how to cite

The records behind this page are all rights reserved. This file is the page itself, at its own address, in another format. It is not part of the CC BY 4.0 downloads listed at https://openbrokerapi.com/data. Quote from it with a link to the page.

Cite as: Deriv API quickstart: token to first REST call. Broker API Hub, https://openbrokerapi.com/brokers/deriv/quickstart, newest check 2026-10-12.

Where you rely on a single figure, cite the source and the checked date printed beside it as well. Where this page and a broker's own documentation differ, the documentation wins.