1. Darwinex Docs
  2. Algorithmic Trading
  3. Algorithmic Trading & Investing with the DARWIN API

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.

The APIs can be used in any programming language, subject to it supporting connection to and authentication via a RESTful web service.

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.

API Store Listing

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.

Documentation detailing the technical specification of each API in our offering can be found on the Darwinex API Store - the central hub of information for developers using the API.

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.

Screenshot 2019-06-07 at 13.33.23

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

The latest version of any API will usually contain the default URL (without a version number), as well as the URL containing the version number. In the advent of updates to any API, the version number will be incremented. Consequently, existing access tokens may not remain valid for newer API versions and you may need to request new access tokens for the same. To prevent unexpected issues while using the API it is recommended to use the URL with the version for which the application is prepared.

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!”.  

Clicking on “Try It Out!” on this page after entering your access token is actually sending the request LIVE (it’s not just a test).

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

Screenshot 2019-06-07 at 14.10.28-1

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.

access-token-real

Notice that the Consumer Key and the Consumer Secret have to be sent encoded in base64. The text to encode should be: consumerKey:consumerSecret.

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.

Nevertheless, it is highly recommended to use the long version of the product name (example: “ULI.4.2”).

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):

search-button

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

search-button-uli

darwin-url

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.

investor-account-id-1

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

If you're using the Direct Access Token authentication type, please contact our Support Team (info@darwinex.com) to revoke the concerned access token and generate a new one.

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.

If you are still having problems, please, contact our Support Team (info@darwinex.com).

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.