API guide

App registration

Before using the API, you must register your application:

Open an account at Binary.com (either a Virtual Account or a Real Account).
Go to Security & Limits, select API token and create a new token with the admin scope.

Client authentication

Certain API calls require client authentication (e.g. portfolio) whilst other calls do not (e.g. ticks).

There are 2 ways to do client authentication:

Client authentication by app-specific API tokens - Binary.com users can generate tokens by logging into their accounts and navigate to the API token page under Security & Limits.
Client authentication by OAuth - To use OAuth, get your app_id (see instructions above):
To authenticate your users, navigate them to Binary.com OAuth URL:
```
https://oauth.binary.com/oauth2/authorize?app_id=[..insert app_id..]
```
Our system will authenticate the user, and redirect him to the redirect URI specified during app registration, with a valid token returned in the URL in the token parameter.

To display the authentication form in another language, append the language code to the OAuth URL as follows:
```
https://oauth.binary.com/oauth2/authorize?app_id=[..insert app_id..]&l=ZH_CN
```

With a user's API token (either a per-app token, or a token obtained via OAuth), you may call authorize.

Token scopes

Tokens can possess one or more of these scopes:

read - for API calls that only read client data
trade - for API calls that can create trades in the client account
payments - for API calls that can access the cashier (deposits and withdrawals)
admin - for API calls that change client settings

The drop-down list in the API playground indicates which call needs which scope.

Binary.com accounts opening

To open Binary.com accounts via the API, start by verifying the user's email address using verify_email.

To open a Virtual Account, you may call new_account_virtual. Then, you may call topup_virtual to top-up virtual-money fund.

To open a Real Account, you may use residence_list and states_list to retrieve data to create the account opening form. Once you have the required data from the user, call new_account_real.

If you are a registered affiliate, remember to pass in the affiliate_token parameter, so that you may earn affiliate commissions for the new account. You can determine which Landing Company (i.e counter-party) the account will be opened with, based on the user's jurisdiction, using landing_company, and you can find out details about that landing company using landing_company_details.

Accounting functionalites

You may generate a user's portfolio, statement and profit_table, as well as retrieve his account balance. You may also sell expired contract with sell_expired, and generate a realtime stream of transactions.

Option prices

To price an option, call proposal
To price options which are open in a user's portfolio, call proposal_open_contract

Payment agents

Clients may withdraw to a payment agent using paymentagent_withdraw
Payment agents may credit a client account using paymentagent_transfer

Utility calls

To keep the connection alive, use ping
You can get the server time with time
You can also get the status of the website with website_status

Streams

Note: Certain functions generate streams (e.g. ticks) whilst other functions do not. Please use forget to cancel an outstanding stream.