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 your app_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
  2. Clients can generate API tokens by logging to their Deriv account and going to Security & Limits > API token.

  3. Client authentication by OAuth
  4. Send clients to:

    https://oauth.binary.com/oauth2/authorize?app_id=[..insert app_id..]
    copy code icon 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
    copy code icon 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 open a virtual account, use new_account_virtual 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

Payment agents

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.