Darwinex API Walkthrough

Darwinex APIs enable you to create their your own metrics, applications or bots to trade DARWINs.

Table of contents

1. Overview
2. Documentation and usage
3. Refresh Token Grant Flow
4. API Throttling
5. Generic API Handlers error codes
6. Frequently Asked Questions
   1. What is the difference between Product and DARWIN?
   2. Which product name should be used in the API?
   3. Where can I find my Investor Account ID?
   4. How can I revoke an access token?
   5. I’m using the API Portal to test the APIs but all I get is “no response from server”
   6. “OAuth application is not in active state” / “invalid_client” messages are shown when trying to get an OAuth token for the user

1. Overview

Darwinex APIs enable users to create their own trading applications or bots to trade DARWINs at Darwinex.

At the present time, our offering consists of the following APIs:

1. Darwin Info API: provides both the latest snapshot and historical time series for DARWIN Quotes and Investment Attributes.
2. Product Quotes API: Access to product quotes in real time through a REST API.
3. Product Websockets API: Subscription to a WebSocket whereby all product quote updates can be retrieved  in real-time.
4. Investor Account Info API: retrieves information from your investor account such as: current status, current and past investments, open/closed trades, executed/rejected/cancelled conditional orders, etc.
5. Darwin Trading API: provides an interface to manage your DARWIN investments: buy/sell DARWINs, configure conditional orders, modify account leverage, etc.

2. API Documentation and Usage

To use any of the available Darwinex APIs, clients must first obtain a valid Access Token. Once obtained, it must be embedded in  an “Authorization” header to perform calls to any API successfully. Such an Authorization header typically looks like:

{“Authorization”: “Bearer <your-access-token-string>”}

Access tokens can be obtained at darwinex.com/data/darwin-api. Two options are offered for obtaining an access token.

1. Access to the 3 DARWIN data APIs (DARWIN Info API, DARWIN Quotes API, Quote Web Socket API) only. This access token will be valid for several months or until the token is revoked or regenerated.
2. Request credentials to all APIs, with the 2 Investor APIs (Investor Account API, DARWIN Trading API) accessing either your DEMO or your LIVE investment accounts. With these credentials, all APIs will be accessible. The access token provided via this method will be valid for only one hour, but the refresh token grant flow can be used to renew this token.

Each API listing in the Store has an  “API Console” tab that lists and describes its available methods. The information displayed on the API Console tab is based on the swagger 2.0 specification.

There are two main environments: PRODUCTION and SANDBOX. Both environments show real information about DARWINs.

• The PRODUCTION environment allows access to LIVE investor accounts.
• The SANDBOX environment allows access to DEMO investor accounts.

Each API shows, on the first Overview tab, the URLs to use for Production and Sandbox environments respectively.

For example:

https://api.darwinex.com/darwininfo

https://api.darwinex.com/darwininfo/1.0

All listed APIs can also be used directly via the API Console tab. Enter your access token in the “Set Request Header” text field at the beginning of the page, select the method to use, fill the corresponding fields and click on “Try It Out!”.  

The execution report also provides an example of a request for the method using curl in a terminal.

Example:

curl -k -X GET "https://api.darwinex.com/darwininfo/1.5/products?status=ALL&page=0&per_page=50" -H "accept: application/json" -H "Authorization: Bearer <bearerToken>"

3. Refresh Token Grant Flow

To be able to use the DARWIN APIs during a longer time period, your Access Token needs to be renewed using the Refresh Token Grant flow.

The Access Token provided for accessing the full range of APIs is valid only for a short period of time. In order to be able to use the APIs for a longer time period, it is required to renew the token frequently using the Refresh Token Grant flow.

The POST request can be made using Postman, curl, python, R, Rust or the language of your choice.

Example in curl:

curl -k -d "grant_type=refresh_token&refresh_token=<refresh_token>" -H "Authorization: Basic Base64(<consumerKey>:<consumerSecret>)" -H "Content-Type: application/x-www-form-urlencoded" https://api.darwinex.com/token

The request must include the Refresh Token, the Consumer Key and the Consumer Secret.

These are provided on the Access Token generation page.

For example, for consumerKey:

6ZuXLMou7gtnfQwPW2PkVpnwNoMa

... and consumerSecret:

sYuBhpNtfIFaETYzYtEOfmurNi4a

... the encoded text is:

Nlp1WExNb3U3Z3RuZlF3UFcyUGtWcG53Tm9NYTpzWXVCaHBOdGZJRmFFVFl6WXRFT2ZtdXJOaTRh

Following up on our curl example, the request would be as follows:

curl -k -d "grant_type=refresh_token&refresh_token=bc8232b9-934f-374f-a61f-b331aa5c8e96" -H "Authorization: Basic Nlp1WExNb3U3Z3RuZlF3UFcyUGtWcG53Tm9NYTpzWXVCaHBOdGZJRmFFVFl6WXRFT2ZtdXJOaTRh” -H "Content-Type: application/x-www-form-urlencoded" https://api.darwinex.com/token

And here's an example of response:

{"access_token":"cf61ef76-222e-3359-b940-d8d474d6a160","refresh_token":"a5f17ab4-442f-335a-ae96-cdf356a0d97c","scope":"openid",...,"token_type":"Bearer","expires_in":3600}

4. API Throttling

The following restrictions apply to the API usage, although these limits are subject to change over time. In case of reaching any of the limits, the following requests until the following minute will be rejected:

Per User	Each user is allowed to 50 requests / minute in total.
DARWIN Info API	10 requests / minute
DARWIN Quotes API	1 request / minute
DARWIN Trading API	20 requests / minute
Investor Account Info API	20 requests / minute

 

In addition there are some additional global restrictions that might be reached by the usage of many different endpoints/users at the same time.

5. Generic API Handlers error codes

The following generic error codes might be returned by our API Manager while trying to use the API. The details and format of these errors will be provided in JSON or in XML format depending on the "accept" header provided in the request. (Example: "accept: application/json").

Error Code	Error	Description
700700	API Blocked	This API has been blocked temporarily. Please try again later or contact info@darwinex.com.
900800	Message throttled out	The maximum number of requests that can be made to the API within a designated time period is reached and the API is throttled for the user.
900801	Hard limit exceeded	Hard throttle limit has been reached
900802	Resource level throttle out	Message is throttled out because resource level has exceeded
900803	Application level throttle out	Message is throttled out because application level is exceeded
900804	Subscription level throttled out	Message throttled out due to throttling limit reached for your account.
900805	Message blocked	Accessing an API which is blocked on user, IP, application, or API Context.
900806	Custom policy throttled out	Message throttled out due to exceeding the limit configured through one of our custom throttling policy rules.
900807	Message throttled out	Messaged throttled out because of exceeding the burst control/rate limit (requests per second) for your account.

900900	Unclassified authentication failure	An unspecified error has occurred
900901	Invalid credentials	Invalid authentication information provided.
900902	Missing credentials	No authentication information provided. Check the Authorization: Bearer header is provided in the request.
900905	Incorrect access token type is provided	The access token type used is not supported when invoking the API. The supported access token types are application and user accesses tokens.
900906	No matching resource found in the API for the given request	A resource with the name in the request can not be found in the API.
900907	The requested API is temporarily blocked	The access for your user might be blocked. Contact info@darwinex.com for info and request unblocking of the user.
900908	Resource forbidden	The user invoking the API has not been granted access to the required resource.
900909	The subscription to the API is inactive	The status of the API has changed to an inaccessible/unavailable state.
900910	The access token does not allow you to access the requested resource	Can not access the required resource with the provided access token. Check the valid resources that can be accessed with this token.
102511	Incomplete payload	The payload sent with the request is too large and the client is unable to keep the connection alive until the payload is completely transferred to the API Gateway

6. Frequently Asked Questions

a. What is the difference between Product and DARWIN?

At the present time, these terms can be used interchangeably and refer to the same thing: a DARWIN.

b. Which product name should be used in the API?

The short product name (example: “ULI”) can be used in most of the methods in the APIs.

This long version of the product name can be found in any DARWIN’s full listing URL.

For example, https://www.darwinex.com/darwin/LVS.4.20 where “LVS.4.20” is the full product name.

Steps to follow in order to get this URL for any DARWIN for which you have a short name (e.g. LVS):

• Log in into https://www.darwinex.com.
• Click on the Search button.

• Write the short name of the product and select the product from the list.

• The details about the DARWIN are displayed. On this page, get the long product name from the URL: https://www.darwinex.com/darwin/ULI.4.2  → ULI.4.2 is the long product name.

c. Where can I find my Investor Account ID?

The Investor Account ID identifies the account of the user that should be used for trading DARWINs. For instance, if a new Demo account is requested or reset, a new investor account ID for the demo account should be used. 

To retrieve your investor account ID, use the method GET /investoraccounts from the Investor Account Info API.

d. How can I revoke an access token?

There might be scenarios where an access token has been exposed insecurely or the access simply needs to be revoked.

For the token provided via the website, an option to revoke the token can be found under https://www.darwinex.com/data/darwin-api.

In case you are using OAuth 2.0 authentication, a request can be sent to revoke the access token, containing the consumer key and the consumer secret.

curl -X POST --basic -u "<consumer_key:consumer_secret>" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -k -d "token=<access_token>&token_type_hint=access_token" https://api.darwinex.com/oauth2/revoke

e. I’m using the API Portal to test the APIs but all I get is “no response from server”

First, ensure a valid Access Token has been provided in the input text field for authorization.

Next, try to open the URL appearing in the Curl section of the method after clicking on “Try It Out!”.

It should look something like https://api.darwinex.com/investoraccountinfo.  

Try to open this url in another tab of your web browser. There might be issues with the certificate used in the handshake of the connection, or issues with a firewall or antivirus installed.

f. “OAuth application is not in active state” / “invalid_client” messages are shown when trying to get an OAuth token for the user

The configuration for the application might need to be updated by our administrators.

Contact our team at info@darwinex.com.

The configuration for the application might need to be updated by our administrators.