Skip to main content

​
Backtest AI Agent BETA

Backtest AI Agent BETA turns a plain-English trading idea into a replay-ready strategy, then optionally runs it across historical resolved markets.
Backtest AI Agent BETA is available on Pro and Enterprise plans only. Pro includes the beta free with 5 strategy generations per month.

​
Authentication

Backtest AI Agent endpoints are authenticated dashboard endpoints. Use the same logged-in session or bearer token used by the PolyHistorical dashboard.
​
Authorization
string
Bearer token for a logged-in Pro or Enterprise customer.
​
Content-Type
string
required
Must be application/json for POST requests.

​
Endpoints

MethodEndpointDescriptionConsumes AI quota
POST/v1/backtest-ai/generateGenerate a replay-ready strategy from a promptYes
POST/v1/backtest-ai/strategyGenerate a strategy and backtest it across marketsYes
POST/v1/backtest-ai/runRun an already-generated strategy or strategy codeNo
GET/v1/backtest-ai/quotaGet monthly Backtest AI Agent quotaNo

​
Generate a strategy

POST /v1/backtest-ai/generate returns a normalized strategy object that can be inspected, copied, or sent to /v1/backtest-ai/run.

​
Body parameters

​
prompt
string
required
Natural-language strategy description.
​
preset
string
Optional preset identifier, such as mean_reversion, dip_buying, momentum_entry, or quick_scalp.
​
coin
string
Market coin. Allowed values include BTC, ETH, and SOL.
​
marketType
string
Market timeframe, such as 5m, 15m, 1h, 4h, or 24h.
​
marketCount
integer
Number of resolved markets to target when running the strategy. Must be between 1 and 100.
​
positionSize
number
Number of shares to simulate per trade. Must be between 1 and 10000.
​
maxLossPercent
number
Stop-loss percentage from 1 to 100.
​
orderType
string
Order type. Allowed values: MARKET, LIMIT.

​
Example

cURL
curl -X POST "https://api.polyhistorical.com/v1/backtest-ai/generate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Mean reversion: buy when UP price hits 80c, take profit at 10c profit, stop loss at 30c.",
    "preset": "mean_reversion",
    "coin": "BTC",
    "marketType": "5m",
    "marketCount": 25,
    "positionSize": 100,
    "maxLossPercent": 30,
    "orderType": "MARKET"
  }'

​
Response

{
  "success": true,
  "data": {
    "generated_strategy": {
      "name": "Mean reversion",
      "description": "Enter when the selected side is oversold and exit on reversion.",
      "rationale": "Generated from the user prompt and normalized to the replay DSL.",
      "side": "UP",
      "position_size": 100,
      "max_loss_percent": 30,
      "order_type": "MARKET",
      "entry_conditions": [
        { "field": "price_up", "operator": "<=", "value": 80 }
      ],
      "exit_conditions": [
        { "field": "price_up", "operator": ">=", "value": 90 },
        { "field": "price_up", "operator": "<=", "value": 30 }
      ]
    },
    "quota": {
      "used_this_month": 1,
      "monthly_limit": 5,
      "remaining_this_month": 4,
      "resets_at": "2026-07-01T00:00:00Z"
    }
  },
  "timestamp": "2026-06-13T08:30:00Z"
}

​
Generate and backtest

POST /v1/backtest-ai/strategy accepts the same body as /generate, then immediately runs the generated strategy across the requested resolved markets. The response includes:
  • generated_strategy — normalized replay-ready rules
  • aggregate — combined performance summary across tested markets
  • results — per-market replay results or errors
  • quota — updated monthly Backtest AI Agent quota

​
Run a generated strategy

POST /v1/backtest-ai/run runs an existing generated strategy without consuming another AI generation. You can send either:
  • generatedStrategy — the generated strategy object returned by /generate
  • strategy_code — copied strategy code generated by the dashboard

​
Example

cURL
curl -X POST "https://api.polyhistorical.com/v1/backtest-ai/run" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "coin": "BTC",
    "marketType": "5m",
    "marketCount": 25,
    "generatedStrategy": {
      "name": "Mean reversion",
      "description": "Enter when UP price is high and exit on a target or stop.",
      "rationale": "Replay-ready strategy generated from a prompt.",
      "side": "UP",
      "position_size": 100,
      "max_loss_percent": 30,
      "order_type": "MARKET",
      "entry_conditions": [
        { "field": "price_up", "operator": ">=", "value": 80 }
      ],
      "exit_conditions": [
        { "field": "price_up", "operator": ">=", "value": 90 },
        { "field": "price_up", "operator": "<=", "value": 30 }
      ]
    }
  }'

​
Get quota

GET /v1/backtest-ai/quota returns the current monthly Backtest AI Agent usage.
cURL
curl "https://api.polyhistorical.com/v1/backtest-ai/quota" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Errors

CodeHTTP StatusDescription
BACKTEST_AI_REQUIRED403Customer is not on Pro or Enterprise
BACKTEST_AI_QUOTA_EXCEEDED429Monthly Backtest AI Agent quota has been reached
AI_STRATEGY_GENERATION_FAILED502Strategy generation failed
NO_BACKTEST_MARKETS404No resolved markets matched the request