Backtesting

Run a backtest

Run an options strategy over history and get back the equity curve, every trade, the positions they belong to and the performance statistics.

Describe the strategy in the request body: the legs and how their strikes and expiries are chosen, how positions are sized, when they are closed, and the cost model. See Strategy specification for every field.

Denomination is coin. Inverse options are quoted and settled in the base coin, so equity, premiums and P&L are in BTC (or ETH). equity_usd is a derived reading alongside.

Lookback. start must fall inside your backtest lookback: 1 year on the monthly add-on, 3 years on quarterly, full history (from September 2021) on annual. An earlier start returns 403. The Sandmark-Backtest-Window-Start response header gives your earliest allowed date.

Warnings are part of the result. Degraded fills, carried marks and bars the option chain could not serve are counted in warnings and diagnostics. Read them before trusting a number.

POST

backtest

Run a backtest

curl --request POST \
  --url https://api.sandmark.com/backtesting/v1/backtest \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "BTC 20-delta covered call",
  "asset": "DER.BTC_USD",
  "start": "2026-05-01",
  "end": "2026-10-31",
  "capital": {
    "initial_equity": 1,
    "sizing": {
      "mode": "contracts",
      "value": 1
    }
  },
  "structure": {
    "expiry": {
      "by": "monthly",
      "min_dte": 20
    },
    "legs": [
      {
        "id": "call",
        "type": "call",
        "direction": "short",
        "strike": {
          "by": "delta",
          "value": 0.2
        }
      }
    ]
  },
  "lifecycle": {
    "rules": [
      {
        "name": "take_profit_75",
        "when": {
          "predicate": {
            "subject": "structure",
            "metric": "premium",
            "op": "below",
            "value": -0.75,
            "unit": "percent",
            "reference": "entry"
          }
        },
        "do": {
          "action": "close_all"
        }
      },
      {
        "name": "delta_stop",
        "when": {
          "predicate": {
            "subject": "leg:call",
            "metric": "contract_delta",
            "op": "above",
            "value": 0.45
          }
        },
        "do": {
          "action": "close_all"
        }
      },
      {
        "name": "roll_before_expiry",
        "when": {
          "predicate": {
            "subject": "structure",
            "metric": "dte",
            "op": "below",
            "value": 2
          }
        },
        "do": {
          "action": "close_all"
        }
      }
    ]
  }
}
'

import requests

url = "https://api.sandmark.com/backtesting/v1/backtest"

payload = {
    "name": "BTC 20-delta covered call",
    "asset": "DER.BTC_USD",
    "start": "2026-05-01",
    "end": "2026-10-31",
    "capital": {
        "initial_equity": 1,
        "sizing": {
            "mode": "contracts",
            "value": 1
        }
    },
    "structure": {
        "expiry": {
            "by": "monthly",
            "min_dte": 20
        },
        "legs": [
            {
                "id": "call",
                "type": "call",
                "direction": "short",
                "strike": {
                    "by": "delta",
                    "value": 0.2
                }
            }
        ]
    },
    "lifecycle": { "rules": [
            {
                "name": "take_profit_75",
                "when": { "predicate": {
                        "subject": "structure",
                        "metric": "premium",
                        "op": "below",
                        "value": -0.75,
                        "unit": "percent",
                        "reference": "entry"
                    } },
                "do": { "action": "close_all" }
            },
            {
                "name": "delta_stop",
                "when": { "predicate": {
                        "subject": "leg:call",
                        "metric": "contract_delta",
                        "op": "above",
                        "value": 0.45
                    } },
                "do": { "action": "close_all" }
            },
            {
                "name": "roll_before_expiry",
                "when": { "predicate": {
                        "subject": "structure",
                        "metric": "dte",
                        "op": "below",
                        "value": 2
                    } },
                "do": { "action": "close_all" }
            }
        ] }
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'BTC 20-delta covered call',
    asset: 'DER.BTC_USD',
    start: '2026-05-01',
    end: '2026-10-31',
    capital: {initial_equity: 1, sizing: {mode: 'contracts', value: 1}},
    structure: {
      expiry: {by: 'monthly', min_dte: 20},
      legs: [
        {
          id: 'call',
          type: 'call',
          direction: 'short',
          strike: {by: 'delta', value: 0.2}
        }
      ]
    },
    lifecycle: {
      rules: [
        {
          name: 'take_profit_75',
          when: {
            predicate: {
              subject: 'structure',
              metric: 'premium',
              op: 'below',
              value: -0.75,
              unit: 'percent',
              reference: 'entry'
            }
          },
          do: {action: 'close_all'}
        },
        {
          name: 'delta_stop',
          when: {
            predicate: {subject: 'leg:call', metric: 'contract_delta', op: 'above', value: 0.45}
          },
          do: {action: 'close_all'}
        },
        {
          name: 'roll_before_expiry',
          when: {predicate: {subject: 'structure', metric: 'dte', op: 'below', value: 2}},
          do: {action: 'close_all'}
        }
      ]
    }
  })
};

fetch('https://api.sandmark.com/backtesting/v1/backtest', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "name": "BTC 20-delta covered call",
  "asset": "DER.BTC_USD",
  "bars": 183,
  "runtime_seconds": 0.149,
  "strategy": {
    "headline": "Short call",
    "legs": [
      {
        "id": "call",
        "direction": "Short",
        "kind": "call",
        "strike": "20 delta",
        "expiry": "front monthly (last Friday) at least 20 days out",
        "ratio": 1,
        "sentence": "Short 20 delta call, front monthly (last Friday) at least 20 days out"
      }
    ],
    "lifecycle": [
      "enter whenever flat",
      "close the position when the structure's premium falls -75% below entry",
      "close the position when the call leg's delta rises above 0.45",
      "close the position when days to expiry falls below 2"
    ],
    "sizing": "1 contracts, fixed",
    "hedge": null,
    "costs": "filled at mark, 0.03% taker fee, capped at 12.5% of premium"
  },
  "stats": {
    "start": "2026-05-01T08:00:00+00:00",
    "end": "2026-10-30T08:00:00+00:00",
    "duration_days": 182,
    "initial_equity": 0.9997,
    "final_equity": 0.998437,
    "total_return": -0.001263,
    "cagr": -0.002531,
    "volatility": 0.09877,
    "sharpe": 0.024579,
    "sortino": 0.026966,
    "calmar": -0.028629,
    "drawdown": {
      "max_drawdown": -0.088411,
      "avg_drawdown": -0.038878,
      "longest_underwater_days": 75,
      "max_drawdown_start": "2026-08-16T08:00:00+00:00",
      "max_drawdown_trough": "2026-09-23T08:00:00+00:00"
    },
    "trades": {
      "count": 14,
      "winners": 11,
      "losers": 3,
      "win_rate": 0.785714,
      "avg_pnl": -0.000112,
      "avg_win": 0.009131,
      "avg_loss": -0.034,
      "best": 0.01155,
      "worst": -0.0764,
      "profit_factor": 0.984681,
      "avg_holding_days": 13,
      "total_fees": 0.008063
    },
    "structures": {
      "count": 14,
      "win_rate": 0.785714,
      "avg_pnl": -0.000112,
      "best": 0.01155,
      "worst": -0.0764,
      "profit_factor": 0.984681,
      "avg_legs": 1,
      "avg_holding_days": 13
    },
    "yearly_returns": {
      "2026": -0.001263
    }
  },
  "equity": [
    {
      "timestamp": "2026-05-01T08:00:00+00:00",
      "equity": 0.9997,
      "equity_usd": 77088.725817,
      "cash": 1.0111,
      "positions_value": -0.0114,
      "spot": 77111.859375,
      "open_positions": 1
    },
    {
      "timestamp": "2026-05-02T08:00:00+00:00",
      "equity": 0.9974,
      "equity_usd": 78011.633222,
      "cash": 1.0111,
      "positions_value": -0.0137,
      "spot": 78214.992188,
      "open_positions": 1
    }
  ],
  "positions": [
    {
      "position": "BTC 20-delta covered call-00001",
      "entry_time": "2026-05-01T08:00:00",
      "exit_time": "2026-05-18T08:00:00",
      "legs": 1,
      "expiry": "2026-05-29T08:00:00",
      "net_premium": 0.0114,
      "fees": 0.000588,
      "pnl": 0.008513,
      "reason": "take_profit_75"
    }
  ],
  "trades": [
    {
      "instrument": "BTC-29MAY26-84000-C",
      "type": "C",
      "strike": 84000,
      "expiry": "2026-05-29T08:00:00",
      "entry_time": "2026-05-01T08:00:00",
      "exit_time": "2026-05-18T08:00:00",
      "quantity": -1,
      "entry_price": 0.0114,
      "exit_price": 0.0023,
      "fees": 0.000588,
      "pnl": 0.008513,
      "entry_dte": 28,
      "exit_dte": 11,
      "holding_days": 17,
      "reason": "take_profit_75",
      "position": "BTC 20-delta covered call-00001",
      "tags": [
        "call"
      ],
      "entry_delta": 0.21217,
      "exit_delta": 0.08431,
      "entry_iv": 0.3584,
      "exit_iv": 0.3539
    }
  ],
  "warnings": [
    "only 14 positions: ratio estimates are dominated by noise below ~30"
  ],
  "diagnostics": {
    "fills_total": 28,
    "fills_degraded": 0,
    "fills_degraded_pct": 0
  }
}

{
  "statusCode": 400,
  "message": "start must be a date such as 2025-11-01"
}

{
  "statusCode": 401,
  "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
}

{
  "statusCode": 403,
  "message": "start is before your backtest lookback, which begins 2025-11-07"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "statusCode": 429,
  "message": "Rate limit is exceeded. Try again in 31 seconds."
}

Start from a recipe rather than a blank spec, and see Strategy specification for what every field does.

Authorizations

X-API-Key

string

header

required

Your Sandmark Backtesting API key.

Query Parameters

format

enum<string>

default:json

json for the full result, html for a self-contained report, csv for a zip of trades, positions and equity, xlsx for an Excel workbook.

Available options:

json,

html,

csv,

xlsx

theme

enum<string>

default:light

Colour theme of the html report. Ignored for other formats.

Available options:

light,

dark

Body

application/json

start

string<date>

required

First day of the backtest, YYYY-MM-DD. Must fall inside your backtest lookback; data begins 2021-09-01.

end

string<date>

required

Last day of the backtest, YYYY-MM-DD, inclusive.

structure

StructureSpecModel · object

required

The legs to trade, how their expiry is chosen, and an optional hedge.

Show child attributes

schema_version

integer

Defaults to 1.

Required range: 1 <= x <= 1

name

string

default:backtest

Required string length: 1 - 120

asset

enum<string>

default:DER.BTC_USD

Underlying to trade. Inverse BTC and ETH carry history from September 2021.

Available options:

DER.BTC_USD,

DER.ETH_USD,

DER.SOL_USDC,

DER.XRP_USDC

clock

ClockSpec · object

When the strategy looks at the market.

Show child attributes

capital

CapitalSpec · object

Starting equity, in coin, and how each new position is sized.

Show child attributes

lifecycle

LifecycleSpec · object

When positions are opened and closed. With no rules, positions are held to expiry.

Show child attributes

costs

CostsSpec · object

Fill model and fees.

Show child attributes

Response

The backtest result, in the requested format.

name

string

required

asset

string

required

bars

integer

required

runtime_seconds

number

required

stats

StatsModel · object

required

Show child attributes

equity

EquityPointModel · object[]

required

Show child attributes

positions

PositionModel · object[]

required

Show child attributes

trades

TradeModel · object[]

required

Show child attributes

strategy

StrategyDescriptionModel · object | null

What the strategy does, derived from its configuration rather than its name, so it cannot describe something other than what ran.

Show child attributes

warnings

string[]

Not decoration. Silent data holes are the main way an options backtest lies, so degraded fills, carried marks and bars the chain could not serve are counted here.

diagnostics

Diagnostics · object

Show child attributes

Run a backtest

curl --request POST \
  --url https://api.sandmark.com/backtesting/v1/backtest \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "BTC 20-delta covered call",
  "asset": "DER.BTC_USD",
  "start": "2026-05-01",
  "end": "2026-10-31",
  "capital": {
    "initial_equity": 1,
    "sizing": {
      "mode": "contracts",
      "value": 1
    }
  },
  "structure": {
    "expiry": {
      "by": "monthly",
      "min_dte": 20
    },
    "legs": [
      {
        "id": "call",
        "type": "call",
        "direction": "short",
        "strike": {
          "by": "delta",
          "value": 0.2
        }
      }
    ]
  },
  "lifecycle": {
    "rules": [
      {
        "name": "take_profit_75",
        "when": {
          "predicate": {
            "subject": "structure",
            "metric": "premium",
            "op": "below",
            "value": -0.75,
            "unit": "percent",
            "reference": "entry"
          }
        },
        "do": {
          "action": "close_all"
        }
      },
      {
        "name": "delta_stop",
        "when": {
          "predicate": {
            "subject": "leg:call",
            "metric": "contract_delta",
            "op": "above",
            "value": 0.45
          }
        },
        "do": {
          "action": "close_all"
        }
      },
      {
        "name": "roll_before_expiry",
        "when": {
          "predicate": {
            "subject": "structure",
            "metric": "dte",
            "op": "below",
            "value": 2
          }
        },
        "do": {
          "action": "close_all"
        }
      }
    ]
  }
}
'

import requests

url = "https://api.sandmark.com/backtesting/v1/backtest"

payload = {
    "name": "BTC 20-delta covered call",
    "asset": "DER.BTC_USD",
    "start": "2026-05-01",
    "end": "2026-10-31",
    "capital": {
        "initial_equity": 1,
        "sizing": {
            "mode": "contracts",
            "value": 1
        }
    },
    "structure": {
        "expiry": {
            "by": "monthly",
            "min_dte": 20
        },
        "legs": [
            {
                "id": "call",
                "type": "call",
                "direction": "short",
                "strike": {
                    "by": "delta",
                    "value": 0.2
                }
            }
        ]
    },
    "lifecycle": { "rules": [
            {
                "name": "take_profit_75",
                "when": { "predicate": {
                        "subject": "structure",
                        "metric": "premium",
                        "op": "below",
                        "value": -0.75,
                        "unit": "percent",
                        "reference": "entry"
                    } },
                "do": { "action": "close_all" }
            },
            {
                "name": "delta_stop",
                "when": { "predicate": {
                        "subject": "leg:call",
                        "metric": "contract_delta",
                        "op": "above",
                        "value": 0.45
                    } },
                "do": { "action": "close_all" }
            },
            {
                "name": "roll_before_expiry",
                "when": { "predicate": {
                        "subject": "structure",
                        "metric": "dte",
                        "op": "below",
                        "value": 2
                    } },
                "do": { "action": "close_all" }
            }
        ] }
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'BTC 20-delta covered call',
    asset: 'DER.BTC_USD',
    start: '2026-05-01',
    end: '2026-10-31',
    capital: {initial_equity: 1, sizing: {mode: 'contracts', value: 1}},
    structure: {
      expiry: {by: 'monthly', min_dte: 20},
      legs: [
        {
          id: 'call',
          type: 'call',
          direction: 'short',
          strike: {by: 'delta', value: 0.2}
        }
      ]
    },
    lifecycle: {
      rules: [
        {
          name: 'take_profit_75',
          when: {
            predicate: {
              subject: 'structure',
              metric: 'premium',
              op: 'below',
              value: -0.75,
              unit: 'percent',
              reference: 'entry'
            }
          },
          do: {action: 'close_all'}
        },
        {
          name: 'delta_stop',
          when: {
            predicate: {subject: 'leg:call', metric: 'contract_delta', op: 'above', value: 0.45}
          },
          do: {action: 'close_all'}
        },
        {
          name: 'roll_before_expiry',
          when: {predicate: {subject: 'structure', metric: 'dte', op: 'below', value: 2}},
          do: {action: 'close_all'}
        }
      ]
    }
  })
};

fetch('https://api.sandmark.com/backtesting/v1/backtest', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "name": "BTC 20-delta covered call",
  "asset": "DER.BTC_USD",
  "bars": 183,
  "runtime_seconds": 0.149,
  "strategy": {
    "headline": "Short call",
    "legs": [
      {
        "id": "call",
        "direction": "Short",
        "kind": "call",
        "strike": "20 delta",
        "expiry": "front monthly (last Friday) at least 20 days out",
        "ratio": 1,
        "sentence": "Short 20 delta call, front monthly (last Friday) at least 20 days out"
      }
    ],
    "lifecycle": [
      "enter whenever flat",
      "close the position when the structure's premium falls -75% below entry",
      "close the position when the call leg's delta rises above 0.45",
      "close the position when days to expiry falls below 2"
    ],
    "sizing": "1 contracts, fixed",
    "hedge": null,
    "costs": "filled at mark, 0.03% taker fee, capped at 12.5% of premium"
  },
  "stats": {
    "start": "2026-05-01T08:00:00+00:00",
    "end": "2026-10-30T08:00:00+00:00",
    "duration_days": 182,
    "initial_equity": 0.9997,
    "final_equity": 0.998437,
    "total_return": -0.001263,
    "cagr": -0.002531,
    "volatility": 0.09877,
    "sharpe": 0.024579,
    "sortino": 0.026966,
    "calmar": -0.028629,
    "drawdown": {
      "max_drawdown": -0.088411,
      "avg_drawdown": -0.038878,
      "longest_underwater_days": 75,
      "max_drawdown_start": "2026-08-16T08:00:00+00:00",
      "max_drawdown_trough": "2026-09-23T08:00:00+00:00"
    },
    "trades": {
      "count": 14,
      "winners": 11,
      "losers": 3,
      "win_rate": 0.785714,
      "avg_pnl": -0.000112,
      "avg_win": 0.009131,
      "avg_loss": -0.034,
      "best": 0.01155,
      "worst": -0.0764,
      "profit_factor": 0.984681,
      "avg_holding_days": 13,
      "total_fees": 0.008063
    },
    "structures": {
      "count": 14,
      "win_rate": 0.785714,
      "avg_pnl": -0.000112,
      "best": 0.01155,
      "worst": -0.0764,
      "profit_factor": 0.984681,
      "avg_legs": 1,
      "avg_holding_days": 13
    },
    "yearly_returns": {
      "2026": -0.001263
    }
  },
  "equity": [
    {
      "timestamp": "2026-05-01T08:00:00+00:00",
      "equity": 0.9997,
      "equity_usd": 77088.725817,
      "cash": 1.0111,
      "positions_value": -0.0114,
      "spot": 77111.859375,
      "open_positions": 1
    },
    {
      "timestamp": "2026-05-02T08:00:00+00:00",
      "equity": 0.9974,
      "equity_usd": 78011.633222,
      "cash": 1.0111,
      "positions_value": -0.0137,
      "spot": 78214.992188,
      "open_positions": 1
    }
  ],
  "positions": [
    {
      "position": "BTC 20-delta covered call-00001",
      "entry_time": "2026-05-01T08:00:00",
      "exit_time": "2026-05-18T08:00:00",
      "legs": 1,
      "expiry": "2026-05-29T08:00:00",
      "net_premium": 0.0114,
      "fees": 0.000588,
      "pnl": 0.008513,
      "reason": "take_profit_75"
    }
  ],
  "trades": [
    {
      "instrument": "BTC-29MAY26-84000-C",
      "type": "C",
      "strike": 84000,
      "expiry": "2026-05-29T08:00:00",
      "entry_time": "2026-05-01T08:00:00",
      "exit_time": "2026-05-18T08:00:00",
      "quantity": -1,
      "entry_price": 0.0114,
      "exit_price": 0.0023,
      "fees": 0.000588,
      "pnl": 0.008513,
      "entry_dte": 28,
      "exit_dte": 11,
      "holding_days": 17,
      "reason": "take_profit_75",
      "position": "BTC 20-delta covered call-00001",
      "tags": [
        "call"
      ],
      "entry_delta": 0.21217,
      "exit_delta": 0.08431,
      "entry_iv": 0.3584,
      "exit_iv": 0.3539
    }
  ],
  "warnings": [
    "only 14 positions: ratio estimates are dominated by noise below ~30"
  ],
  "diagnostics": {
    "fills_total": 28,
    "fills_degraded": 0,
    "fills_degraded_pct": 0
  }
}

{
  "statusCode": 400,
  "message": "start must be a date such as 2025-11-01"
}

{
  "statusCode": 401,
  "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
}

{
  "statusCode": 403,
  "message": "start is before your backtest lookback, which begins 2025-11-07"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "statusCode": 429,
  "message": "Rate limit is exceeded. Try again in 31 seconds."
}

Reference data

Timeseries

Backtesting

Run a backtest

Authorizations

Query Parameters

Body

Response