Backtesting API Overview

Run a strategy template against historical market data and retrieve performance metrics. Backtests run as asynchronous jobs — submit a job, poll for completion, then download the result.

This module covers:

• Submitting and tracking backtest jobs.
• Reading the result format.
• The metrics PipAI computes (sharpe, max drawdown, win rate, etc.).

Job lifecycle

Every backtest job moves through a small state machine. Terminal states are done, failed, and cancelled.

            ┌──────────┐    slot free    ┌──────────┐
submit ───▶│  queued  │ ───────────────▶│ running  │
            └──────────┘                  └────┬─────┘
                  │                            │
                  │                            ├── success ──▶  done
              cancel                           │
                  │                            ├── error   ──▶  failed
                  ▼                            │
            cancelled                          └── cancel  ──▶  cancelled

Status	Description
queued	Job accepted, waiting for an execution slot.
running	Worker is replaying historical data. progress advances 0 → 1.
done	Job finished successfully. result is populated.
failed	Job aborted due to an error. error describes the cause.
cancelled	User cancelled the job before it finished.

Time handling

• All start and end timestamps are ISO 8601 strings in UTC (e.g. 2025-01-01T00:00:00Z).
• The interval is inclusive on both ends — bars at start and at end are part of the simulation.
• start must be strictly less than end.
• The maximum span is 5 years. Longer ranges are rejected with INVALID_PARAMETER.
• end may be in the past or up to "now"; future timestamps are rejected.

Fee model

PipAI applies trading fees during simulation according to the fee_model configured on the job.

Mode	Behavior
none	No fees applied. Useful for sanity checks; not realistic.
fixed_bps	Single basis-point rate applied to notional on every fill. Configure with fee_bps (default "5", i.e. 0.05%).
tiered_maker_taker	Uses the platform's default tiered maker/taker schedule based on simulated 30-day volume. Maker and taker rates differ.
match_exchange	Replays the actual fee schedule of the venue that listed the symbol at the simulated time, including historical changes. Most realistic, slowest to compute.

Funding rates for perpetual symbols are always applied regardless of fee_model.

Result retention

• Full results (equity curve and trades) are retained for 90 days after finished_at.
• After 90 days, the heavy payload is garbage-collected. Job summaries — config, status, timestamps, and metrics — remain accessible indefinitely so you can audit which backtests have been run.
• Export the result before the retention window expires if you need long-term storage.

Concurrency limits

• Each user may have at most 5 concurrent jobs in queued or running state.
• Submitting a 6th job returns 429 RATE_LIMITED.
• Queued jobs start automatically as slots free up. Order is FIFO per user.