---
title: "Run a Grid-Trading backtest (sync)"
method: POST
path: "/api/v1/backtests/grid"
tags: ["Backtests"]
---

# Run a Grid-Trading backtest (sync)

`POST /api/v1/backtests/grid`

## Request

- Base URL: `https://tradingstrategies.work`
- URL: `https://tradingstrategies.work/api/v1/backtests/grid`
- Auth: HTTP bearer

KuCoin-konformer Grid-Trading-Backtest (spot, 15-min candles). Eigenes Trade-Modell mit per-level coinSize-Allokation. Optional leverage 2/3/5 (grid_mode long only, API Pro): isolated-margin long grid — margin = total_investment, the grid trades margin × leverage, funding accrues daily on the open position, by default with an initial position at the start (start_rule), liquidation checked per candle at the low; result then carries liquidated / liquidation_time / liquidation_price / funding_cost_usd / funding_fell_back_to_conservative / max_notional_exposure and final_value is equity on the margin. Simulates, does not recommend. Free: BTCUSDT/ETHUSDT, 1x only. [Free / API Pro tier]

## Request body

- object
  - `pair` string, required
  - `start_date` string, date, required
  - `end_date` string, date, required
  - `total_investment` number, required: USDT; with leverage > 1 this is the margin.
  - `low_price` number, required
  - `high_price` number, required
  - `grid_count` integer, required
  - `grid_type` 'arithmetic' | 'geometric', required
  - `grid_mode` 'neutral' | 'long'
  - `fee_rate` number, required
  - `entry_price` number
  - `stop_loss_price` number
  - `take_profit_price` number
  - `stop_on_range_exit` boolean: Default false: the grid pauses outside the range and resumes when price returns. true: the first candle CLOSING outside low..high sells all coins at that close and ends the run (stop_reason range_exit_high/low).
  - `leverage` 1 | 2 | 3 | 5: Grid-Leverage v1: > 1 requires grid_mode long and API Pro.
  - `funding_mode` 'none' | 'conservative' | 'historical': Only with leverage > 1. historical = BTCUSDT from 2019-09-08, otherwise conservative fallback (flagged).
  - `start_rule` 'initial_position' | 'cash': Only with leverage > 1. initial_position = exchange rule of a futures long grid: one grid amount bought at the entry price for every level above the entry (position, funding and liquidation risk from the first candle). cash = start 100% in cash, buy only on dips.

## Response `200`

Grid backtest result with profit-per-grid statistics (leverage fields only when leverage > 1).

## Other responses

- `400`: Invalid input — fehlt Pflichtfeld oder Wert außerhalb des erlaubten Bereichs.
- `401`: Unauthenticated — kein gültiger Bearer-Token im Authorization-Header.
- `403`: Tier-Insufficient — Endpoint braucht höheren API-Tier. Response enthält upgrade_url.
- `404`: Not-Found — Resource existiert nicht oder gehört nicht dem aktuellen User.
- `429`: Rate-Limit überschritten — Tier-Quota (hourly/daily) oder Per-Endpoint-Quota erreicht. Retry-After-Header gesetzt.
- `500`: Internal Error.
- `503`: Upstream-Failure — Datenquelle nicht erreichbar (Binance, EODHD, etc.).

---

[API](https://skmtc.dev/tradingstrategies/apis/backtesting-arena-public-api.md) · [All operations](https://skmtc.dev/tradingstrategies/apis/backtesting-arena-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tradingstrategies/apis/backtesting-arena-public-api/revisions/f82e8d6eecd7?raw)