API Reference
We propose a RESTful API that comforms to the REST architectural style. All endpoints proposed accept GET parameters and return JSON-encoded response, use standard HTTP response codes and authentication.
We propose different examples of how to use the API in your favorate programming language to automate your trading stategy. Just copy the code in your editor, and test it by yourself.
Have any question regarding the API ? Contact us and we will always reply back.
Choose Your Language
Ruby
Python
PHP
Node.js
BASE URL
https://qtamr.com/api/API Authentification
The API uses API keys to authenticate requests. You can view and manage your API keys in API management page. We use OAuth 2.0 authentication protocole. To create an access token (API key) you will need to generate your Client Secret Key first.
From API management page, you can generate or refresh your API key. Each key is valid for 1 Day. When integrating this API in your trading system or strategy, you can used you Client Secret to automatically generate new key if the previous one expired. The example show you how to generate a new key with your Client Secret.
To call an API endpoint, the API key should be passed in the HTTP request header parameter "Authorization" as Bearer Token.
Always keep your Client Secret and API keys safe. If you feel your keys have been exposed to anyone, generate a new Client secret and API keys.
Access Token
import requests, json
client_secret = "YOUR_CLIENT_SECRET_FROM_API_GATEWAY"
url = BASE_URL+"oauth/v2/token"
r = requests.get(url,headers={"Content-Type":"application/json"},
params={'client_secret':client_secret})
response = json.loads(r.content) $client_secret = "YOUR_CLIENT_SECRET_FROM_API_GATEWAY"
$url = $BASE_URL."oauth/v2/token";
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query([
"client_secret" => $client_secret
]));
$response = curl_exec($curl); RESPONSE
{
"access_token": "YOUR_ACCESS_TOKEN_GENERATED",
"expires_in": 86400,
"token_type": "bearer",
"scope": "client"
} API Asset Forecast
We provide forecasts for assets in the folowing asset classes: equity, currency, commodity and cryptocurrency. Forecasts are also provided for some global market indices. There is an API endpoint for each asset class as provided below. You can get the list of assets handled by this platform/API by following this link: Assets List.
Forecasts are done for mainly short term investment from 1 Day to 4 weeks.
Parameters
There is 1 parameter required ticker to use the API endPoints and one optional parameter date.| Parameter | Description | Value | Example |
|---|---|---|---|
| ticker | The symbol/identifiant of the asset | The list of assets: Assets List | AAPL |
| date | The date from when you want the forecast. When empty, the current forecast is provided. | Any date in format: yyyy-mm-ddTH:I:S.0000 | See the example code. |
Response Detail
When the parameter date is not provided, the default date is the current date(time) and the response is the latest forecast done for that specific asset.| Key | Description |
|---|---|
| direction | The recommended position direction to take on the asset |
| signal_strength | The strength of the signal from Strong Sell to strong Buy |
| signal_strength_code | 1=strong sell, 2=sell, 3=neutral,4=buy,5=strong buy. |
| start_date_current_forecast | The date when the current recommended direction(forecast) was first initiated. |
| previous_close_price | The close price of the previous period |
| stop_loss | Gives the level of stop loss (based on the previous_close_price) for different level of risk. |
| previous_bar_data | The previous period bar data |
Endpoints - GET
| Equities | /forecasts/stock/{ticker}/ |
| Currencies | /forecasts/currency/{ticker}/ |
| Commodities | /forecasts/commodity/{ticker}/ |
| Cryptocurrencies | /forecasts/cryptocurrency/{ticker}/ |
| Cross Assets | /forecasts/asset/{ticker}/ |
| Equity Indices | /forecasts/index/{ticker}/ |
The example below provides forecast for CPE stock (Callon Petroleum Company). You can use the equity or the cross asset endpoints.
Asset Forecast
access_token = 'YOUR_ACCESS_TOKEN_GENERATED'
bearer_token = 'Bearer ' + access_token
ticker = "CPE"
date = "2021-03-01T12:58:55.0000" #optional
url = BASE_URL+"forecasts/stock/%s/" % ticker
r = requests.get(url,headers={'Authorization': bearer_token,
"Content-Type":"application/json"},params={'date':date})
response = json.loads(r.content) $access_token = 'YOUR_ACCESS_TOKEN_GENERATED';
$bearer_token = 'Bearer ' . $access_token;
$ticker = "CPE";
$date = "2021-03-01T12:58:55.0000"; #optional
$url = $BASE_URL."forecasts/stock/". $ticker ."/?";
$curl = curl_init($url.http_build_query(["date" => $date]));
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json',
'Authorization: '.$bearer_token ));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($curl); RESPONSE
{
"id": "CPE",
"symbol": "CPE",
"description": "Callon Petroleum Company",
"direction": "buy",
"signal_strength": "buy",
"signal_strength_code": 4,
"date": "2021-03-01 00:00:00",
"start_date_current_forecast": "2021-09-07 00:00:00",
"previous_close_price": 27.09,
"stop_loss": {
"loss_2_pct": 26.548,
"loss_5_pct": 25.736,
"loss_7_pct": 25.194,
"loss_10_pct": 24.381,
"loss_15_pct": 23.027,
"loss_20_pct": 21.672
},
"previous_bar_data": {
"open": 27.09,
"high": 27.09,
"low": 27.09,
"close": 27.09,
"date": "2021-03-01 00:00:00"
}
} API Best Assets
The API endpoints here provide the best assets to buy or sell among the group of assets selected according to your parametrization.
Parameters
The parameters below are send to the request via the method GET (URL parameters). Regarding the Sectors, Industry_groups and Industries parameters below, the possible values are given by the Global Industry Classification Standard. The possible values of the parameter countries are given by ISO 3166-1 alpha-2 standard.| Parameter | Description | Value | Example |
|---|---|---|---|
| date | The date from when you want the forecast. When empty, the current forecast is provided. | Any date in format: yyyy-mm-ddTH:I:S.0000 | See the example code. |
| direction | Which position direction to take (L=buy,S=sell,LS=both) | L,S or LS | L |
| asset_classes | Help to restrict the asset classes | EQ,IND,CO,FX,CC | EQ,FX |
| algorithms | Which algorithms to use in the forecasting process | SR-*,ML-*,STA-*. * is the level of risk associated (1=Less Risk,2 or 3). | SR-3,ML-2 |
| continents | Used to select stocks in specific continents | Continent 2 letters code | NA,EU |
| countries | Used to select stocks in specific countries | Countires 2 letters code | US |
| capitalization | Used to select stocks with specific capitalization | Mid, Large, Mega, Small, Micro or Nano Cap | mid,small |
| sectors | Used to select stocks in specific sectors | Sector ID GICS standard | 10,20 |
| industry_groups | Used to select stocks in specific industry groups | Group ID GICS standard | 1010 |
| industries | Used to select stocks in specific industries | Industry ID GICS standard | 251020 |
| active_currency | Used to filter only active currencies | Boolean 0 and 1 | 1 |
| active_cryptocurrency | Used to filter only active cryptocurrencies | Boolean 0 and 1 | 1 |
| categories | Used to select commodities in specific categories | EN=Energy,PM=Precious Metals,BM=Base Metals,LI=Livestock and Meat,AG=Agricultural | PM,LI |
| min_price | The minimum price of assets to include | Any positive value | 10 |
| max_price | The maximum price of assets to include | Any positive value | 25 |
| asset_details | It gives you the forecast detail of each asset in the top selected | Boolean 0 or 1 | 0 |
Response Detail
Details in the table below.| Key | Description |
|---|---|
| top_assets | Gives the list of the top best assets according to the criteria chosen |
| query_params | Highlight the input parameters |
Endpoints - GET
| Equities | /forecasts/best-stocks/ |
| Currencies | /forecasts/best-currencies/ |
| Commodities | /forecasts/best-commodities/ |
| Cryptocurrencies | /forecasts/best-cryptocurrencies/ |
| Cross Assets | /forecasts/best-assets/ |
| Equity Indices | /forecasts/best-indices/ |
The example below provides the top 5 stocks to buy. Use the cross assets endpoint to get the best assets regardless the asset classes.
Best Assets
bearer_token = 'Bearer ' + access_token
date = "2021-03-01T12:58:55.0000"
direction = "L" # only buy positions
top = 3
url = BASE_URL+"forecasts/best-stocks/"
r = requests.get(url,headers={'Authorization': bearer_token,
"Content-Type":"application/json"},
params={'date':date,'top':5,'direction':direction})
response = json.loads(r.content) $bearer_token = 'Bearer ' . $access_token;
$date = "2021-03-01T12:58:55.0000";
$direction = "L"; # only buy positions
$top = 3;
$url = $BASE_URL."forecasts/best-stocks/?";
$curl = curl_init($url.http_build_query(["date" => $date,"top"=>$top,"direction"=>$direction]));
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json',
'Authorization: '.$bearer_token ));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($curl); RESPONSE
{
"top": 3,
"top_assets": [
"LBRDK",
"THETAUSD",
"TWLO",
"VG"
],
"date": "2021-03-01 00:00:00",
"query_params": {
"investorType": "1",
"direction": "L",
"top": "3",
"min_price": "0",
"max_price": "100000",
"asset_details": "0",
"date": "2021-03-01 00:00:00",
"algorithms": [
"SR-3"
]
}
} API Assets Allocation
The endpoints provided here perform two tasks. Firstly it select the best assets according to your chosen criteria and secondly it applies the allocation algothm that provides weights for each assets.
Parameters
All the previous parameters on Best Assets sections are still applicable here to select the best assets. Below are the allocation related parameters.| Parameter | Description | Value | Example |
|---|---|---|---|
| min_weight | The minimum weight allocated to each asset | Value between 0 and 1 | 0 |
| max_weight | The maximum weight allocated to each asset | Value between 0 and 1 | 1 |
| allocation_type | This indicates the allocation methodology | EQ(equally weighted),OPT(optimal allocation) | OPT |
| risk_aversion | Indicates the investor risk aversion level | Value between 0 and 1 | 1 |
Response Detail
The sum of weights should be equal to 1.| Key | Description |
|---|---|
| weights | The weight allocated for each asset selected |
| constraints | Highlight the inputs constraints given |
| top_assets_details | Give the detail on the best assets selected be the algorithm |
Endpoints - GET
| Equities | /stocks-allocation/ |
| Currencies | /currencies-allocation/ |
| Commodities | /commodities-allocation/ |
| Cryptocurrencies | /cryptocurrencies-allocation/ |
| Cross Assets | /assets-allocation/ |
| Equity Indices | /indices-allocation/ |
The example below provides the allocation for the top 3 stocks to buy. Use the cross assets endpoint to get the best assets regardless the asset classes.
Asset Allocation
bearer_token = 'Bearer ' + access_token
date = "2021-03-01T12:58:55.0000"
direction = "L" # only buy positions
top = 3
url = BASE_URL+"stocks-allocation/"
r = requests.get(url,headers={'Authorization': bearer_token,
"Content-Type":"application/json"},
params={'date':date,'top':5,'direction':direction})
response = json.loads(r.content) $bearer_token = 'Bearer ' . $access_token;
$date = "2021-03-01T12:58:55.0000";
$direction = "L"; # only buy positions
$top = 3;
$url = $BASE_URL."stocks-allocation/?";
$curl = curl_init($url.http_build_query(["date" => $date,"top"=>$top,"direction"=>$direction]));
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json',
'Authorization: '.$bearer_token ));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($curl); RESPONSE
{
"date": "2021-03-01 00:00:00",
"weights": {
"LBRDK": 0.48624,
"TWLO": 0.21365,
"VG": 0.30011
},
"constraints": {
"min_weight": "0",
"max_weight": "1",
"allocation_type": "OPT",
"target_value": "0.1",
"risk_aversion": "1"
},
"top_assets_details": {
"top": 3,
"top_assets": [
"LBRDK",
"TWLO",
"VG"
],
"date": "2021-03-01 00:00:00",
"query_params": {
"investorType": "1",
"direction": "L",
"top": "3",
"min_price": "0",
"max_price": "100000",
"asset_details": "0",
"date": "2021-03-01 00:00:00",
"algorithms": [
"SR-3"
],
"asset_classes": [
"EQ"
]
}
}
} API Portfolios
The API endpoints here provide portfolio current composition with weights and performance over a specific period of time.
The second endPoint can provide the portfolio value compared against a market benchmark over 1 year for a base value of 100.
Parameters
There is 1 parameter required id_portfolio to use the API endPoints. The list of portfolio and performance are available Here| Parameter | Description | Value | Example |
|---|---|---|---|
| id_portfolio | The reference of the portfolio | The list of portfolios with reference are available here: Portfolios List | PTFHS1 |
Response Detail
Details in the table below.| Key | Description |
|---|---|
| direction | The recommended position direction to take on the asset |
| valuation_frequency | The frequency at which the portfolio is rebalanced (changing composition if needed) and the performance are recalculated |
| last_calculation_time | The exact date and time the calculation above is done (UTC time) |
| launch_date | The date when the portfolio was launched |
| first_valuation_date | The date when the portfolio composition was processed. Generally before the launch date |
| risk_level | This tell you on a scale of 5 the level of risk of the portfolio |
| difficulty_level | This is related to the difficulty of using the portfolio when investing. Some portfolios have long and short positions and some portfolios are rebalanced more frequently than others. |
| returns | This variable provide the portfolio performance or return over the latest period of time (1D, 1M, 3M,etc.) |
| current_composition | This field gives you the exact current composition (assets) in your portfolio as well as the allocation of your capital that minimizes risk and maximizes the return. |
| assets_added | The list of assets added to portfolio if any during the last valuation time |
| assets_removed | The list of assets removed from the portfolio if any during the last valuation time. The return gives you the performance of the asset since it was added in the portfolio |
Endpoints - GET
| Portfolio Composition | /portfolio/{id_portfolio}/ |
| Portfolio Performance | /portfolio/performance/{id_portfolio}/ |
The example below provides the current composition for the portfolio PTFHS1.
Portfolio Composition
bearer_token = 'Bearer ' + access_token
idPortfolio = "PTFHS1"
url = BASE_URL+"portfolio/%s/" % idPortfolio
r = requests.get(url,headers={'Authorization': bearer_token,
"Content-Type":"application/json"})
response = json.loads(r.content) $bearer_token = 'Bearer ' . $access_token;
$idPortfolio = "PTFHS1";
$url = $BASE_URL."portfolio/". $idPortfolio ."/";
$curl = curl_init($url.http_build_query([]));
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json',
'Authorization: '.$bearer_token ));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($curl); RESPONSE
{
"id": "PTFHS1",
"direction": "L",
"asset_class": "CC",
"valuation_frequency": "daily",
"last_calculation_time": "2021-11-12 15:25:48",
"launch_date": "2021-10-26 00:00:00",
"first_valuation_date": "2021-01-01 00:00:00",
"risk_level": 3.4,
"difficulty_level": 2.5,
"returns": {
"2W": "8.12%",
"1M": "30.83%",
"3M": "51.47%",
"6M": "75.55%",
"9M": "104.44%",
"1Y": "NA"
},
"current_composition": {
"portfolio_id": "PTFHS1",
"date": "2021-11-11 00:00:00",
"composition": {
"TRXUSD": {
"ticker": "TRXUSD",
"weight": "16.51%",
"direction": "L",
"dateIn": "2021-11-11 00:00:00",
"name": "TRON / US Dollar",
"asset_class": "CC"
},
"ETHUSD": {
"ticker": "ETHUSD",
"weight": "25.41%",
"direction": "L",
"dateIn": "2021-11-10 00:00:00",
"name": "Ether / US dollar",
"asset_class": "CC"
},
"MIOTAUSD": {
"ticker": "MIOTAUSD",
"weight": "20.48%",
"direction": "L",
"dateIn": "2021-11-09 00:00:00",
"name": "IOTA / US Dollar",
"asset_class": "CC"
}
},
"assets_added": [
"TRXUSD"
],
"assets_removed": [
{
"ticker": "ALGOUSD",
"direction": "L",
"return": "-1.1%"
},
{
"ticker": "LTCUSD",
"direction": "L",
"return": "15.04%"
}
]
}
} API Backtesting Strategy
For the backtesting part, at each rebalancing date, the best assets have to be selected, and then allocated before the position orders are defined and executed.
Parameters
All the previous parameters on Best Assets and Asset Allocation sections are still relevant here. Below are the details for parameters related only to backtesting.| Parameter | Description | Value | Example |
|---|---|---|---|
| start_date | The start date of backtesting period | Any date in format: yyyy-mm-ddTH:I:S.0000 | See the example code |
| end_date | The end date of backtesting period | Any date in format: yyyy-mm-ddTH:I:S.0000 | See the example code |
| benchmark | The benchmark asset used to asset the strategy performance | The list of assets: Assets List | SP500 |
| commission | The commission cost | Value between 0 and 1 | 0.002 |
| slippage | The slippage cost | Value between 0 and 1 | 0.005 |
| start_cash | The initial capital for the strategy | Any positive value | 30000 |
| risk_management | Indicates whether to activate risk management (taking into account stop loss and take profit positions). | Boolean 0 and 1 | 1 |
| stop_loss | The stop loss percentageused to get the stop loss price | Any positive value | 0.02 |
| reserved_cash | The amount of cash not allocated | Value between 0 and 1 | 0.05 |
| period_in_portfolio | The maximum number of days an asset can stay in the portfolio | value between 1 and 90 | 30 |
| report_detail | To get more detail (weights at each rebalancing date, trades journal, portfolio value evolution) | Boolean 0 and 1 | 0 |
Response Detail
Details given in the table below.| Key | Description |
|---|---|
| rebalancing | The frequency at which the portfolio composition could change |
| pnl | Profit and Loss of the strategy |
| pnl_benchmark | Profit and Loss of buy and hold of the benchmark |
| commission | The total loss due to commission |
| initial_capital | The initial capital in the strategy |
| ending_capital | The final portfolio value |
| net_return | The return over the backtesting period |
| net_annual_return | The corresponding annual return |
| risk_adjusted_return | The risk adjusted return (sharp ratio) |
| config | Highlight the inputs backtesting parameters given |
Endpoints - GET
| Equities | /stocks-backtest-strategy/ |
| Currencies | /currencies-backtest-strategy/ |
| Commodities | /commodities-backtest-strategy/ |
| Cryptocurrencies | /cryptocurrencies-backtest-strategy/ |
| Cross Assets | /assets-backtest-strategy/ |
| Equity Indices | /indices-backtest-strategy/ |
The example below provides the backtest result for the top 5 assets with daily rebalancing.
Backtest Strategy
bearer_token = 'Bearer ' + access_token
start_date = '2021-05-14T00:00:00.0000'
end_date = '2021-11-14T00:00:00.0000'
direction = "L"
benchmark = 'SP500'
asset_classes = "EQ,CC,CO,FX"
top = 5
url = BASE_URL+"assets-backtest-strategy/"
r = requests.get(url,headers={'Authorization': bearer_token,
"Content-Type":"application/json"},
params={'start_date':start_date,'end_date':end_date,'top':top,
'direction':direction,'benchmark': benchmark,
'asset_classes':asset_classes})
response = json.loads(r.content) $bearer_token = 'Bearer ' . $access_token;
$start_date = '2021-05-14T00:00:00.0000';
$end_date = '2021-11-14T00:00:00.0000';
$direction = "L"; # only buy positions
$benchmark = 'SP500';
$asset_classes = "EQ,CC,CO,FX";
$top = 5;
$url = $BASE_URL."assets-backtest-strategy/?";
$curl = curl_init($url.http_build_query(
['start_date'=>$start_date,'end_date'=>$end_date,'top'=>$top,
'direction'=>$direction,'benchmark'=>$benchmark,
'asset_classes'=>$asset_classes]));
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json',
'Authorization: '.$bearer_token ));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($curl); RESPONSE
{
"pnl": 4355.809,
"pnl_benchmark": 1219.454,
"commission": 0.0,
"initial_capital": 10000,
"ending_capital": 14355.809,
"net_return": "43.56%",
"net_annual_return": "109.02%",
"risk_adjusted_return": "10.75%",
"algorithms": "SR-3",
"config": {
"start_date": "2021-05-14 00:00:00",
"end_date": "2021-11-14 00:00:00",
"benchmark": "SPY",
"commission": "0",
"slippage": "0",
"start_cash": "10000",
"stop_loss": "0.05",
"period_in_portfolio": "90",
"risk_management": "0",
"reserved_cash": "0.02",
"report_detail": "0",
"top": "5",
"investorType": "1",
"direction": "L",
"algorithms": [
"SR-3"
]
},
"weights": [],
"portfolio": [],
"log": []
} API HTTP Status Code
HTTP Code Status
200 - OK
Everything worked as expected
400 - Bad Request
The request was unacceptable, often due to parameters that don't match requirements.
401 - Unauthorized
No valid API key provided or API has expired or the client secret is not valid.
403 - Forbidden
The API key doesn't have permissions to perform the request. Often endpoints that required subscription.
404 - Not Found
The requested resource doesn't exist.
500, 502, 503, 504 - Server Errors
Something went wrong on server end.