<!-- stratex-marketing-and-planning/landing-stratex-trader-api-beta/api-reference.md — Stratex Trader API reference (July 2026 beta) -->

# Stratex Trader API Reference (Beta)

API base path: `/api/v1`.

**Scope:** This file documents the **July 2026 beta** for AI agents and integrators. It covers setups, markets discovery, backtesting, and usage.

**Coming soon:** live setup evaluation and alerts. Have your user register their email on the [landing page](./index.html) to be notified at launch. Do not call alert endpoints for beta integrations.

Also see: **[agent.md](./agent.md)** (product story) · **[quickstart.md](./quickstart.md)** (signup → first backtest).

---

## Authentication

Use an **API key** for authenticated endpoints.

| Header | Example |
|--------|--------|
| **Authorization** (preferred) | `Authorization: Bearer sk_live_xxxxxxxx...` |
| **X-Api-Key** | `X-Api-Key: sk_live_xxxxxxxx...` |

Create and manage keys in the **Account Dashboard** after signup (human session). For this beta, create a key with the **`backtest`** permission.

The raw key is shown only once at creation; store it securely.

---

## Endpoints

### Markets discovery

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/markets` | API key or session | Ready backtest markets: `market` key, human `label`, overall `earliest`/`latest`, and `timeframes[]` with per-TF ranges. Count = ingested catalog data. |

Use this response as the **source of truth** for `market` (and related labels/ranges) when estimating or running a backtest. Do not invent market identifiers.

`GET /api/v1/backtest/markets` returns the same ready-market list (UI helper; same capability).

---

### Setups

Requires capability `api.service_setups`.

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/api/v1/service/setups` | API key or session | Create setup (structured body). |
| GET | `/api/v1/service/setups` | API key or session | List your setups. |
| GET | `/api/v1/service/setups/:id` | API key or session | Get one setup. |
| DELETE | `/api/v1/service/setups/:id` | API key or session | Soft-delete a setup. |

**Create body (minimal):**

```json
{
  "name": "My US30 BUY setup",
  "symbol": "US30",
  "direction": "BUY",
  "timeframe": "5m"
}
```

Optional (when supported by validation): `entry` / `exit` (or `entryExpression` / `exitExpression`), `briefDescription`, `description`.

**Create response:** `setupId`, `description` (plain-English), and full setup object. On validation failure you receive a generic error (e.g. "Setup validation failed"); internal details are not exposed.

**Beta note:** New setups are backtestable immediately after create. To change core strategy fields after create, **create a new setup**. Live evaluation and alert delivery are **coming soon** — register on the [landing page](./index.html) for launch updates; do not rely on alert-related endpoints in this beta.

`PATCH /api/v1/service/setups/:id` is not part of the beta backtest workflow — omit it for now.

---

### Backtesting

Requires capability `api.backtest` (same capability as `GET /api/v1/markets`).

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/api/v1/backtest/run` | API key or session | Run a backtest. |
| GET | `/api/v1/backtest/estimate` | API key or session | Preview resolved range + bar cost before running. |
| GET | `/api/v1/backtest/markets` | API key or session | Same ready-market list as `GET /api/v1/markets`. |
| GET | `/api/v1/backtest/list` | API key or session | List your backtest runs. |
| GET | `/api/v1/backtest/:id` | API key or session | Get one run (full trades, summary). |
| GET | `/api/v1/backtest/:id/trades` | API key or session | Get trades for a run. |
| DELETE | `/api/v1/backtest/:id` | API key or session | Delete a run. |
| GET | `/api/v1/backtest/data-info` | API key or session | Backtest data info helper. |
| GET | `/api/v1/backtest/user-stats` | API key or session | User backtest stats helper. |
| GET | `/api/v1/backtest/:id/bars` | API key or session | Bars related to a run. |
| GET | `/api/v1/backtest/:id/progress` | API key or session | Progress for a run. |
| POST | `/api/v1/backtest/:id/cancel` | API key or session | Cancel a run. |

**Run body (required contract):**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| setupId | string | Yes | Setup ID from POST /api/v1/service/setups. |
| symbol | string | Yes | Setup market identity. Should match the setup. |
| timeframe | string | Yes | One of: 1m, 5m, 15m, 30m, 1h, 4h, D1, W1, MN1. Should match the setup. |
| market | string | Yes | Historic data key from **GET /api/v1/markets**. Used to load bars. |
| startDate or start | string (ISO) | Yes | Start of backtest range. |
| endDate or end | string (ISO) | Yes | End of backtest range (max span 2 years). |
| startingBalance | number | Yes | Simulated starting balance (must be &gt; 0). |
| positionSize | number | Yes | Position size in lots (must be &gt; 0). |
| includeChartImage | boolean | No | If true, response includes base64 summary chart. Default: false. |

Optional risk controls (same family as UI advanced/TP-SL fields): `stopLoss`, `takeProfit`, `slippagePips`, `commissionPerTrade`, `allowMultiplePositions`, `maxConcurrentPositions`, `useSetupExitExpression`, `maxBarsInTrade`, `name`.

`lookbackBars` is **not** accepted on `/run`. To preview bar cost, call `GET /api/v1/backtest/estimate`, then submit concrete `startDate` + `endDate` on `/run`.

A 403 is returned for true insufficient backtest balance (with `required`, `remaining`, `paygRequiredCents` when applicable). Missing/invalid required fields return 400 with a clear `message`.

**Run response:** `runId` (same as `id`), `setupId`, full list of executed trades, summary stats, agent-friendly summary fields when provided. If `includeChartImage: true`, `chartImageBase64` (PNG). Responses may include `X-Request-Id` for support.

**Estimate (`GET /api/v1/backtest/estimate`):** query params `market`, `timeframe`, and either `startDate` + `endDate` or (preview helper) `endDate` + `lookbackBars`. Returns bar-cost / range preview fields (e.g. `primaryBarCount`, `bars1mEquivalent`, `resolvedStartDate`, `resolvedEndDate`, `allowanceRemaining1m`, `wouldExceedAllowance`, `warnings[]`). Preview only — it never starts a run.

---

### Usage

Requires capability `api.usage`.

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/usage` | API key | Current billing period: bars processed (backtest), setup evaluations by timeframe (1m, 5m, 15m+). |

---

### API keys (session auth only — human dashboard)

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/api/v1/keys` | Session | Create key. Body: `{ "name": "...", "permissions": ["backtest"] }`. |
| GET | `/api/v1/keys` | Session | List keys (no secret). |
| DELETE | `/api/v1/keys/:id` | Session | Revoke key. |

For this beta, use **`backtest`** permission only.

---

## Error codes

| Code | Meaning |
|------|--------|
| 400 | Bad Request — invalid body or query. Body: `{ "error": "...", "message": "..." }`. |
| 401 | Unauthorized — missing or invalid API key / session. |
| 403 | Forbidden — authenticated but not allowed (e.g. over limit, missing capability). |
| 404 | Not Found — resource not found or not owned by you. |
| 409 | Conflict — resource state conflict. |
| 429 | Too Many Requests — rate limited. |
| 500 | Internal server error. |
| 503 | Service unavailable. |

**Setup creation:** On validation failure you receive a generic error; internal validation details are not exposed.

---

## Rate limits

Per API key: configurable (default 120 requests per minute). Exceeded requests return 429.

---

## CORS

Configured for allowed origins. Prefer server-to-server calls from your agent runtime.

---

## Links

- **[agent.md](./agent.md)** — Beta product story for AI agents.
- **[quickstart.md](./quickstart.md)** — Sign up → key → markets → setup → first backtest.