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.
- Register your app to obtain your
app_id
.
Client authentication
Certain API calls require client authentication (e.g. portfolio
) whilst other calls do not (e.g. ticks
).
- 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 thetoken
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
- trading_information - for API calls that can read details about trades and related information 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.