# API Reference
Backtest endpoint: https://api.orats.io/backtest
Examples shown use curl (opens new window).
You can download the latest version of curl here (opens new window) and see instructions of how to use curl here (opens new window).
Please use the latest version of curl (opens new window) in order for all the request examples to work.
# Submit a Backtest
- This endpoint submits a backtest to be added to a job queue.
- The backtest engine will be alerted to run the backtest in the queue.
- After the backtest has finished, it will change the status of the backtest as completed and call any callback url that has been set to alert that the backtest has completed.
POST | https://api.orats.io/backtest/submit
# Basic JSON postdata payload (IBM Long Call)
{
"general": {
"startDate": "2007-01-03",
"endDate": "2019-04-16",
"symbols": [{
"symbol": "IBM",
"weight": null,
"signals": null
}]
},
"entry": {
"options": [{
"ratio": 1,
"optionType": "call",
"leg": 1,
"opening": {
"dte": {
"target": 40,
"min": 30,
"max": 50
},
"strikeSelection": {
"type": "absDelta",
"value": {
"target": 0.35,
"min": 0.25,
"max": 0.45
}
}
}
}]
}
}
# Example request using curl
curl -d "@IBM_LongCallBasic.json" -H "Authorization: your-private-token" -X POST "https://api.orats.io/backtest/submit"
# JSON Response
{
"backtestId" : "hxo70n0kz9v2p0sg",
"status": "success"
}
TIP
For more details on JSON payload, see parameters
# Get Input Payload
To get the input json payload of your backtest.
GET | https://api.orats.io/backtest/input
# Example request using curl
curl -H "Authorization: your-private-token" -X GET "https://api.orats.io/backtest/input?backtestId=1DX2dr3m9yFeftF6ADYiyStjFHrPa2nv9q"
# JSON Response
{
"general": {
"exitAtSignal": null,
"returnType": {
"perTrade": "notional",
"daily": "average"
},
"commission": {
"option": 1,
"stock": 0.01
},
"backtestName": null,
"strategyName": null,
"startDate": "2007-01-03",
"endDate": "2018-10-05",
"expirationType": "all",
"stockPosition": {
"type": null,
"ratio": 0
},
"symbols": [
{
"weight": null,
"signals": null,
"symbol": "IBM"
}
],
"standardExpiration": null
},
"entry": {
"options": [
{
"ratio": 1,
"optionType": "call",
"leg": 1,
"opening": {
"dte": {
"target": 40,
"min": 30,
"max": 50
},
"strikeSelection": {
"type": "absDelta",
"value": {
"target": 0.35,
"min": 0.25,
"max": 0.45
}
}
},
"reEnter": null,
"iBidVol": {
"min": null,
"max": null
},
"iAskVol": {
"min": null,
"max": null
},
"optionBid": {
"min": null,
"max": null
},
"optionAsk": {
"min": null,
"max": null
},
"adjustment": null
}
],
"spread": {
"price": {
"target": null,
"min": null,
"max": null
},
"delta": {
"target": null,
"min": null,
"max": null
},
"yieldPct": {
"min": null,
"max": null
}
},
"entryDays": null,
"contractSize": 1,
"legRelation": {
"deltaTotal": {
"leg1Leg2": {
"min": null,
"max": null
},
"leg2Leg3": {
"min": null,
"max": null
},
"leg3Leg4": {
"min": null,
"max": null
}
},
"dteDiff": {
"leg1Leg2": {
"min": null,
"max": null
},
"leg2Leg3": {
"min": null,
"max": null
},
"leg3Leg4": {
"min": null,
"max": null
}
},
"strikeWidth": {
"leg1Leg2": {
"min": null,
"max": null
},
"leg2Leg3": {
"min": null,
"max": null
},
"leg3Leg4": {
"min": null,
"max": null
}
}
},
"mktWidthPct": {
"min": null,
"max": null
},
"absCpDiffStkPxRatioMax": null,
"stock": {
"iVRank": {
"min": null,
"max": null
},
"entryDaysToEarn": {
"min": null,
"max": null
}
}
},
"exit": {
"dteDays": "expire",
"holdDays": null,
"options": null,
"spread": {
"profitLossPct": {
"min": null,
"max": null
},
"strikeTrigger": {
"type": "absDelta",
"value": {
"min": null,
"max": null
}
},
"price": {
"min": null,
"max": null
},
"strikeDiffPctValue": {
"min": null,
"max": null
}
},
"bizDaysEarn": null
},
"hedge": {
"days": null,
"deltaTolerance": {
"min": null,
"max": null
}
}
}
# Setting a CallBack URL
A callback url is used so that you don't have to keep polling to get the status of the backtest using the status endpoint. The backtester will call a POST request to your callback url after the backtest has completed.
Example setting callback url:
{
"general": {
"startDate": "2007-01-03",
"endDate": "2019-04-15",
"symbols": [{
"symbol": "IBM",
"weight": null,
"signals": null
}],
"callBackUrl": "https://yourCallBackUrl.com"
},
"entry": {
"options": [{
"ratio": 1,
"optionType": "call",
"leg": 1,
"opening": {
"dte": {
"target": 40,
"min": 30,
"max": 50
},
"strikeSelection": {
"type": "absDelta",
"value": {
"target": 0.35,
"min": 0.25,
"max": 0.45
}
}
}
}]
}
}
After the backtester completes your test, it will attempt a post request to your callback url.
You should expect a JSON post payload in the format below:
{
"backtestId":"hxo70n0kz9v2p0sg",
"status":"completed",
"executionTime":1.49,
"totalWaitTime":9.92
}
# Backtest Status
Request status of a backtest.
GET | https://api.orats.io/backtest/status
# Get Status Example
curl -H "Authorization: your-private-token" -X GET "https://api.orats.io/backtest/status?backtestId=hxo70n0kz9v2p0sg"
Example Response
{
"backtestId":"hxo70n0kz9v2p0sg",
"status":"completed",
"executionTime":1.49,
"totalWaitTime":9.92
}
# Get multiple backtest status
POST | https://api.orats.io/backtest/status
# Get multiple status example
curl -H "Authorization: your-private-token" -X POST -d '["olhr49cdudx7m4w3","d9tcjv3l27kynvoo","k2wrar3fje52byvv"]' "https://api.orats.io/backtest/status"
Example Response
[{
"backtestId": "olhr49cdudx7m4w3",
"status": "completed",
"executionTime": 40.68,
"totalWaitTime": 46.74
}, {
"backtestId": "d9tcjv3l27kynvoo",
"status": "completed",
"executionTime": 80.67,
"totalWaitTime": 93.65
}, {
"backtestId": "k2wrar3fje52byvv",
"status": "completed",
"executionTime": 86.98,
"totalWaitTime": 97.73
}]
# Backtest Results
Request results of the backtest.
GET | https://api.orats.io/backtest/results
# Get Zip Formatted Results Example
curl -H "Authorization: your-private-token" -L "https://api.orats.io/backtest/results?backtestId=hxo70n0kz9v2p0sg" --output "LongCallBasicResults.zip"
In the zip file you will find a CSV version of the backtest results that includes
StrategyStats.csv, StrategyTrades.csv, StrategyReturns.csv, StrategySummary.csv, StockStats.csv, StockReturns.csv, and StockSummary.csv.
We will go over the details of the results in the Results Definitions section.
# Get JSON Formatted Results Example
curl -H "Authorization: your-private-token" -L "https://api.orats.io/backtest/results?backtestId=hxo70n0kz9v2p0sg&format=json"
Example Response
{
"strategy": {
"trades": [{
"date": "2007-01-09",
"ticker": "IBM",
"leg": 1,
"ratio": 1,
"optionType": "call",
"year": 2007,
"month": 2,
"strike": 105,
"dTE": 40,
"tradeOptPx": 0.938,
"delta": 0.25,
"entryStockPx": 100.07,
"ivr": "",
"exitDate": "2007-02-16",
"exitStockPx": 98.99,
"exitOptionPx": 0,
"expirDate": "2007-02-16",
"expirPx": 98.99,
"profit": -94.8,
"tradeType": "opening"
}, {
"date": "2007-02-16",
"ticker": "IBM",
"leg": 1,
"ratio": 1,
"optionType": "call",
"year": 2007,
"month": 3,
"strike": 100,
"dTE": 30,
"tradeOptPx": 1.188,
"delta": 0.44,
"entryStockPx": 98.99,
"ivr": "",
"exitDate": "2007-03-16",
"exitStockPx": 93.25,
"exitOptionPx": 0,
"expirDate": "2007-03-16",
"expirPx": 93.25,
"profit": -119.8,
"tradeType": "opening"
},
...
],
"returns": [{
"date": "2007-01-09",
"return": -9.9930048965724e-5,
"delta": 0.25,
"stockPx": 75.18776,
"totalOptionProfit": 0,
"totalTrades": 1
}, {
"date": "2007-01-10",
"return": -0.002748076346557409,
"delta": 0.202636,
"stockPx": 74.30116,
"totalOptionProfit": -27.499999999999993,
"totalTrades": 1
}, {
"date": "2007-01-11",
"return": -0.0013790346757269914,
"delta": 0.168502,
"stockPx": 74.12084,
"totalOptionProfit": -13.8,
"totalTrades": 1
},
...
],
"stats": {
"summary": {
"annReturn": -2.78,
"annSharpe": -0.67,
"maxDrawDownPct": 33.05,
"drawDownDays": 3795,
"pnlDollarPerTradeAvg": -39.72,
"pnlDollarPerDayAvg": -1.08,
"pnlPctPerTradeAvg": -0.19,
"pnlPctPerDayAvg": -0.52,
"strategyWinRate": 26.55,
"daysInTradeAvg": 37,
"totalTrades": 113,
"totalDollarProfits": -4488.5,
"totalPctProfits": -18.991305083670056,
"avgCreditReceived": 209.15,
"percentOfTimeInMarket": 96.93396226415094
},
"monthly": [{
"year": 2007,
"Jan": -0.92,
"Feb": -1.17,
"Mar": -0.09,
"Apr": -1.71,
"May": 1.15,
"Jun": -2.87,
"Jul": 4.15,
"Aug": -0.47,
"Sep": -0.62,
"Oct": -0.98,
"Nov": -3.11,
"Dec": -0.94,
"annReturn": -7.57,
"annSharpe": -1.31
}, {
"year": 2008,
"Jan": 0.36,
"Feb": 0.76,
"Mar": 1.37,
"Apr": 2.63,
"May": 2.47,
"Jun": -5.94,
"Jul": 3.18,
"Aug": -2.06,
"Sep": -1,
"Oct": -2.51,
"Nov": 0.45,
"Dec": -3,
"annReturn": -3.27,
"annSharpe": -0.53
},
...
]
}
},
"stock": {
"returns": [{
"date": "2007-01-03",
"return": 0,
"stockPx": 73.08397
}, {
"date": "2007-01-04",
"return": "0.0105551",
"stockPx": 73.86538
}, {
"date": "2007-01-05",
"return": "-0.0090530",
"stockPx": 73.19668
},
...
],
"stats": {
"summary": {
"annReturn": 7.23,
"annSharpe": 0.33,
"maxDrawDownPct": 40.64,
"drawDownDays": 119
},
"monthly": [{
"year": 2007,
"Jan": 2.03,
"Feb": -6.08,
"Mar": 1.49,
"Apr": 8.28,
"May": 4.7,
"Jun": -1.16,
"Jul": 5.23,
"Aug": 5.84,
"Sep": 1.01,
"Oct": -1.26,
"Nov": -8.96,
"Dec": 2.92,
"annReturn": 14.03,
"annSharpe": 0.76
}, {
"year": 2008,
"Jan": -0.37,
"Feb": 6.8,
"Mar": 1.26,
"Apr": 4.89,
"May": 7.53,
"Jun": -8.61,
"Jul": 7.89,
"Aug": -4.49,
"Sep": -3.39,
"Oct": -21.07,
"Nov": -11.17,
"Dec": 3.93,
"annReturn": -16.8,
"annSharpe": -0.71
},
...
]
}
}
}