NAV Navbar
shell java python php node.js javascript

Introduction

Coinscious Data Service - Backtesting API: The Coinscious Backtesting API is a suite of RESTful JSON endpoints for testing user-defined strategies on historical Coinsicous cryptocurrency and indicator data. We provide Backtesting API and Callback API

Backtesting API

Requests to the the Backtesting API can test the status of the application and start a backtest with user-specified parameters.

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Heartbeat

Returns the status of the application.

GET /heartbeat

Example responses

200 Response

{
  "status": "string"
}

Responses

Status Meaning Description Schema
200 It's All Good. Returned the status successfully. response
400 Unexpected Error Refer to the list of Error Codes we provide.
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
429 Too Many Requests
500 Internal Server Error

Response Schema

Status Code 200

Name Type Required Description
status string indicating the status

Enumerated Values

Property Value
status alive

Backtest

Runs a backtest with the user specified parameters from the request body. Also subscribes a client to receive data at each simulated historical timestep during the backtest.

POST /backtest

Body parameter

{
  "start": 0,
  "end": 0,
  "callback_url": "http://example.com",
  "data_freq": "1m",
  "trading_pairs": [
    "string"
  ],
  "indicators": [
    {
      "indicator_name": "SMA",
      "parameters": [
        {
          "parameter_name": "string",
          "parameter_value": 0
        }
      ]
    }
  ],
  "exchanges": [
    {
      "exchange_name": "string",
      "exchange_fee_structure": {
        "percent_fee": 0,
        "fee_unit": "string"
      }
    }
  ],
  "initial_portfolio": [
    {
      "exchange_name": "string",
      "assets": [
        {
          "asset_ticker": "string",
          "asset_amount": 0
        }
      ]
    }
  ],
  "execution_params": {
    "simple_market_order_at": "OPEN"
  },
  "report_params": {
    "risk_free_rate": 0,
    "benchmark": "string",
    "rolling_window_days": 0,
    "report_unit": "usd"
  }
}

Parameters

Name In Type Required Description
body body Backtest true Parameters for backtest.

Example responses

200 Response

{
  "report_link": "string"
}

Responses

Status Meaning Description Schema
200 It's All Good. Backtest results are available as a tearsheet at the given url. response
400 Unexpected Error Refer to the list of Error Codes we provide.
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
429 Too Many Requests
500 Internal Server Error

Response Schema

Status Code 200

Name Type Required Description
report_link string(url) tearsheet url

Callback API

This API should be implemented by clients in order to communicate with the Coinscious Backtesting server. The client server url should be the same as the "callback_url" parameter used when starting the backtest.

Trade Strategy

POST /tradestrategy

Body parameter

{
  "trading_pairs_data": [
    {
      "trading_pair": "string",
      "indicators": [
        {
          "indicator_name": "string",
          "indicator_value": 0
        }
      ]
    }
  ],
  "current_portfolio": [
    {
      "exchange_name": "string",
      "assets": [
        {
          "asset_ticker": "string",
          "asset_amount": 0
        }
      ]
    }
  ],
  "timeindex": 0
}

Parameters

Name In Type Required Description
body body StrategyInput false

Example responses

202 Response

{
  "signals": [
    {
      "trading_pair": "string",
      "quantity": 0,
      "signal_type": "BUY"
    }
  ]
}

Responses

Status Meaning Description Schema
200 It's All Good. Client servers should implement this response if the data was received successfully. The returned payload should contain signals specifying the desired trading pair, trade size, and direction. StrategyOutput
400 Unexpected Error Refer to the list of Error Codes we provide.
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
429 Too Many Requests
500 Internal Server Error

Schemas

Backtest

{
  "start": 0,
  "end": 0,
  "callback_url": "http://example.com",
  "data_freq": "1m",
  "trading_pairs": [
    "string"
  ],
  "indicators": [
    {
      "indicator_name": "SMA",
      "parameters": [
        {
          "parameter_name": "string",
          "parameter_value": 0
        }
      ]
    }
  ],
  "exchanges": [
    {
      "exchange_name": "string",
      "exchange_fee_structure": {
        "percent_fee": 0,
        "fee_unit": "string"
      }
    }
  ],
  "initial_portfolio": [
    {
      "exchange_name": "string",
      "assets": [
        {
          "asset_ticker": "string",
          "asset_amount": 0
        }
      ]
    }
  ],
  "execution_params": {
    "simple_market_order_at": "OPEN"
  },
  "report_params": {
    "risk_free_rate": 0,
    "benchmark": "string",
    "rolling_window_days": 0,
    "unit": "usd"
  }
}

Properties

Name Type Required Description
start integer true Unix timestamp for the start of the backtest period.
end integer true Unix timestamp for the end of the backtest period.
callback_url string(uri) true The client endpoint where data from the server will be sent at each timestep of the historical backtest simulation. Users are required to implement this endpoint in order to accept a payload structured as described in the StrategyInput schema of the callback API, and return a payload structured as described in the StrategyOutput schema of the callback API to the server.
data_freq string true Length of data represented by each timestep. Clients will receive data and will be able to generate signals to place orders with this frequency at each simulated historical timestep during the backtest.
trading_pairs [string] true An array of trading pairs.
indicators [Indicators] false An array of objects with information about the indicators and their parameters to be sent to clients at each simulated historical timestep during the backtest.
exchanges [Exchanges] true An array of objects with information about the exchanges where trading will occur and their fee structure.
initial_portfolio [object] true An array of objects the amount of assets when starting the backtest, grouped by the exchange they are located in.
» exchange_name string false Exchanges where trading will occur. Please see exchange-list for how to get the list of allowable exchanges.
» assets [object] false An array of objects specifying the name and the amount of assets in the exchange at the start of the backtest. Please see token-list for how to get the list of allowable coins/tokens to be used as assets.
»» asset_ticker string false The ticker identifying the asset e.g. btc stands for bitcoin.
»» asset_amount number false The number of units of the asset asset.
» execution_params ExecutionParams false Parameters to control order execution.
» report_params ReportParams false Parameters to control calculations when comparing and reporting backtest performance.

Enumerated Values

Property Value
data_freq 1m
data_freq 5m
data_freq 15m
data_freq 30m
data_freq 1h
data_freq 2h
data_freq 4h
data_freq 6h
data_freq 12h
data_freq 1d

Indicators

{
  "indicator_name": "SMA",
  "parameters": [
    {
      "parameter_name": "string",
      "parameter_value": 0
    }
  ]
}

Properties

Name Type Required Description
indicator_name string true The name of the indicator.
parameters [object] false An array of objects with the name and values of the parameters used in indicator calculations. Required parameters differ between indicators. Please see additional documentation on parameters and calculation methodology.
» parameter_name string false
» parameter_value number false

Enumerated Values

Property Value
indicator_name SMA
indicator_name EMA
indicator_name RSI
indicator_name MACD
indicator_name BOLLINGER_BANDS

Exchanges

{
  "exchange_name": "string",
  "exchange_fee_structure": {
    "percent_fee": 0,
    "fee_unit": "string"
  }
}

Properties

Name Type Required Description
exchange_name string false Exchanges where trading will occur. Please see exchange-list for how to get the list of allowable exchanges.
exchange_fee_structure object false An object describing how fees will be calculated and applied when trading on this exchange.

oneOf

Name Type Required Description
» anonymous object false
»» percent_fee number false The fee paid per trade, applied as a percentage of the total value of transacted.
»» percent_fee_unit string false The asset to deduct the percent fee from.

xor

Name Type Required Description
» anonymous object false
»» flat_fee number false The fee paid per trade, applied to the asset in the portfolio specified by the fee_unit parameter.
»» fee_unit string false The asset to deduct the flat fee from.

ExecutionParams

{
  "simple_market_order_at": "OPEN"
}

Parameters to control order execution.

Properties

Name Type Required Description
simple_market_order_at string false Trades are guaranteed to be filled at the price specified, either the open, high, low, or close price of the simulated historical timestep. Defaults to OPEN if not specified.

Enumerated Values

Property Value
simple_market_order_at OPEN
simple_market_order_at HIGH
simple_market_order_at LOW
simple_market_order_at CLOSE

ReportParams

{
  "risk_free_rate": 0,
  "benchmark": "string",
  "rolling_window_days": 0,
  "unit": "usd"
}

Parameters to control calculations when comparing and reporting backtest performance.

Properties

Name Type Required Description
risk_free_rate number false The annual risk-free rate. Defaults to 0.02 if not specified.
benchmark string true A benchmark to compare backtest performance against
rolling_window_days integer false The number of days in a sliding window when calculating rolling metrics like N-day rolling beta and rolling Sharpe ratio. Defaults to 30 if not specified.
unit string false The unit of currency to be used when reporting backtest performance. Defaults to usd if not specified.

Enumerated Values

Property Value
unit usd
unit usdt
unit btc

StrategyInput

{
  "trading_pairs_data": [
    {
      "trading_pair": "string",
      "indicators": [
        {
          "indicator_name": "string",
          "indicator_value": 0
        }
      ]
    }
  ],
  "current_portfolio": [
    {
      "exchange_name": "string",
      "assets": [
        {
          "asset_ticker": "string",
          "asset_amount": 0
        }
      ]
    }
  ],
  "timeindex": 0
}

Properties

Name Type Required Description
trading_pairs_data [object] false Data about trading pairs at the current simulated historical timestep during the backtest.
» trading_pair string false The trading pair e.g. binance_btc_usdt.
» indicators [object] false An array of indicator values at the current simulated historical timestep during the backtest.
»» indicator_name string false
»» indicator_value number false
» current_portfolio [object] true An array of objects with the name of the exchange and the amount of assets held at that location at the current simulated historical timestep during the backtest.
»» exchange_name string false The exchange where the asset is being held.
»» assets [object] false An array of objects specifying the name and the amount of assets in the exchange at the current simulated historical timestep during the backtest.
»»» asset_ticker string false The ticker identifying the asset e.g. btc stands for bitcoin.
»»» asset_amount number false The number of units of the asset.
»» timeindex integer true Unix timestamp indicating the start time of the current simulated historical timestep.

StrategyOutput

{
  "signals": [
    {
      "trading_pair": "string",
      "quantity": 0,
      "signal_type": "BUY"
    }
  ]
}

Properties

Name Type Required Description
signals [object] true An array of objects with information about user calculated signals.
» trading_pair string true The trading pair the signal applies to e.g. binance_btc_usdt. Must be one of the entries in pair_list specified when initializing the backtest.
» quantity number true The number of units of the trading pair that the signal dictates to trade.
» signal_type string true The type of signal. BUY is a signal to buy the trading pair. SELL is a signal to sell the trading pair. EXIT is a signal to make the portfolio's position of the trading pair 0, regardless of whether you are currently long or short.

Enumerated Values

Property Value
signal_type BUY
signal_type SELL
signal_type EXIT

Error Codes

Coinscious Data Services - Backtesting API uses the following error codes:

Error Code Meaning
1001 Invalid date range
1002 Data frequency not supported
1003 Pair not specified
1004 Pair not supported
1005 Indicator not supported
1006 Invalid indicator parameters
1007 Exchange not specified
1008 Exchange not supported
1009 Invalid exchange fee structure
1010 Invalid execution parameters
1101 Invalid risk free rate in report parameters
1102 Benchmark not specified in report parameters
1103 Benchmark not supported in report parameters
1104 Invalid number or days in the rolling window in report parameters
1105 Report unit not supported in report parameters
1201 Pair not specified in signals returned by client
1202 Pair not supported in signals returned by client
1203 Quantity not specified in signals returned by client
1204 Invalid quantity in signals returned by client
1205 Signal type not specified in signals returned by client
1206 Invalid signal type in signals returned by client
4001 Invalid WebSocket command.