API guide

App registration

Register your app before using our API. Here’s how:

1. Open a Deriv account (either a demo or real account).
2. Create a new token using the admin scope.
3. Register your app to obtain yourapp_id .

Client authentication

Some API calls require client authentication (e.g. portfolio) while others don’t (e.g. ticks).

There are 2 ways to authenticate clients:

1. Client authentication by app-specific API tokens

Clients can generate API tokens by logging to their Deriv account and going to Security & Limits > API token.

2. Client authentication by OAuth

Send clients to:

https://oauth.binary.com/oauth2/authorize?app_id=[..insert app_id..]
Copied to clipboard
Copy

Our system will authenticate the client and send them to the redirect URL you gave us during app registration. A valid token will be returned in the token parameter of the URL.

To display the authentication form in another language, add the language code to the OAuth URL as follows:

https://oauth.binary.com/oauth2/authorize?app_id=[..insert app_id..]&l=ZH_CN
Copied to clipboard
Copy

Complete the authentication by calling authorize using clients’ API token.

Token scopes

Each token can have one or more of these scopes:

• read - for calls that only read client’s data
• trade - for calls that can create trades
• trading_information - for calls that can read information on client’s trades
• payments - for calls that can access the cashier (for deposits and withdrawals)
• admin - for calls that can change client’s settings

Explore our API playground to learn about the required scope for all our API calls.

Opening Deriv accounts

To open accounts via our API, you'll first need to verify the client's email address using verify_email to

To open a virtual account, use new_virtual_account and then topup_virtual to top-up the new account with virtual money.

To open a real account, use residence_list and states_list to get the information needed for the account opening form. Once you have all the necessary information, use new_account_real.

If you are a registered affiliate, remember to include the affiliate_token parameter. You’ll earn commission for every new account.

Based on the client’s country of residence, use landing_company to determine which landing company the account will be opened with. Use landing_company_details to get information about the landing company.

Accounting functionalites

You may get a client's portfolio, statement, profit_table, and their account balance. You may also sell an expired contract with sell_expired, or generate a real time stream of transactions.

Option prices

• To price an option, callproposal.
• To price options that are open in a client's portfolio, use paymentagent_transfer.

Payment agents

• Clients may withdraw via a payment agent using paymentagent_withdraw.
• Payment agents may credit clients’ accounts usingpaymentagent_transfer.

Utility calls

• To keep the connection alive, use ping.
• Get the server time with time.
• Get the status of the website with website_status.

Streams

Some functions generate streams of data (e.g. ticks) while others don’t. Use forget to cancel an outstanding stream.