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

Darwinex API Walkthrough

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

Table of contents

  1. Overview
  2. Documentation and usage
  3. Refresh Token Grant Flow
  4. 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. 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.