API Reference

Backtest endpoint: https://api.orats.io/backtest

Examples shown use curl.

You can download the latest version of curl here and see instructions of how to use curl here.

Please use the latest version of curl 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
			},
			...
			]
		}
	}
}