# Itô Markets - Public API

Base URL: `https://itomarkets.com/api/v1`. JSON over HTTPS, authenticated with an API key. Trading is not part of this API.

## Authentication
Send your key as `Authorization: Bearer` on every request. `401` means the request never authenticated; `403` means the key lacks the required scope. Generate an `ito_*` key from Settings in the dashboard - the full value is shown once.

Scopes:
- `baskets:read`: Basket catalog, pricing, history, chart, metrics, underlyers, overrides.
- `markets:read`: Market listing via GET /markets/search.
- `backtests:read`: Registries, validate, plan, run-status polling.
- `backtests:write`: Create custom strategies, dispatch runs.

## Rate limits
Per-key budgets: 120 requests / minute on GETs, 10 requests / minute on POSTs (the tier follows the method, not the scope). Responses carry `X-RateLimit-*` headers; a `429` adds `Retry-After`.

## Responses
Endpoints return the `{success, message, data}` envelope, except four basket reads (history, chart, metrics, underlyers) which return their payload natively.

## Python SDK
Install the official SDK (`httpx`-based, typed, auto-retries on 429/5xx):
```bash
pip install ito-markets
```

```python
from ito import ItoClient

client = ItoClient("ito_...")  # your API key

# List all baskets with current prices
baskets = client.baskets.list()
for b in baskets["data"]:
    print(f"{b['basket_id']}: ${b['stats']['current_price']:.2f}")

# Get a single market
market = client.markets.get("will-btc-reach-100k")
print(market["data"]["title"], market["data"]["last_price"])

# Historical L2 orderbook
book = client.data.orderbook(
    venue="polymarket",
    start="2026-06-01T00:00:00Z",
    end="2026-06-01T01:00:00Z",
    market_id="will-btc-reach-100k",
)

# Run a backtest (submit + poll to completion)
result = client.backtests.run(
    strategy_id="wsc_crypto_updown_delta_hedged_roll",
    dataset_id="clickhouse:ito_hot.platform_orderbook_l2",
    venues=["polymarket"],
    date_range={"start": "2026-05-01T00:00:00Z", "end": "2026-06-01T00:00:00Z"},
)
print(f"P&L: ${result['data']['metrics']['pnl_usd']:.2f}")
```

Source: [ito-python on GitHub](https://github.com/Ito-Markets/ito-python) · [ito-markets on PyPI](https://pypi.org/project/ito-markets/)

## Endpoints

### Baskets
Basket catalog, live pricing, history, and analytics.
- `GET /baskets` - [List baskets](https://app.itomarkets.com/docs/md/public-api/get-baskets): All system baskets with current price and 24h change.
- `GET /baskets/{basket_id}` - [Get basket](https://app.itomarkets.com/docs/md/public-api/get-baskets-basket-id): Details and composition stats for one basket.
- `GET /baskets/{basket_id}/price` - [Get basket price](https://app.itomarkets.com/docs/md/public-api/get-baskets-basket-id-price): Current price plus the latest per-underlyer snapshot.
- `GET /baskets/{basket_id}/history` - [Price history](https://app.itomarkets.com/docs/md/public-api/get-baskets-basket-id-history): Time-ordered price series for charting.
- `GET /baskets/{basket_id}/chart` - [Chart series](https://app.itomarkets.com/docs/md/public-api/get-baskets-basket-id-chart): Aggregated OHLC-style chart data for a period.
- `GET /baskets/{basket_id}/metrics` - [Basket metrics](https://app.itomarkets.com/docs/md/public-api/get-baskets-basket-id-metrics): Period returns, intraday change, and 30d volatility.
- `GET /baskets/{basket_id}/underlyers` - [Underlyers](https://app.itomarkets.com/docs/md/public-api/get-baskets-basket-id-underlyers): Component market prices, weights, and stats.
- `GET /baskets/overrides` - [List basket overrides](https://app.itomarkets.com/docs/md/public-api/get-baskets-overrides): Manual price/composition overrides currently applied to baskets.
- `GET /baskets/volume/daily` - [Daily traded volume](https://app.itomarkets.com/docs/md/public-api/get-baskets-volume-daily): Total traded volume aggregated by UTC day from the platform trade ledger.

### Markets
Search, discover, and analyze individual prediction markets across Polymarket and Kalshi.
- `GET /markets/search` - [List markets](https://app.itomarkets.com/docs/md/public-api/get-markets-search): Filtered listing of open Polymarket and Kalshi markets, sorted by volume.
- `GET /markets/{market_id}` - [Get market](https://app.itomarkets.com/docs/md/public-api/get-markets-market-id): Full metadata for a single market including categorization, basket assignment, and trading data.
- `GET /markets/{market_id}/history` - [Market price history](https://app.itomarkets.com/docs/md/public-api/get-markets-market-id-history): Daily close price time series for a single market.

### Research Data
Raw data access for researchers: historical L2 orderbook snapshots and bulk price series. Designed for quantitative analysis, backtesting pipelines, and academic research.
- `GET /data/orderbook` - [Historical orderbook](https://app.itomarkets.com/docs/md/public-api/get-data-orderbook): L2 orderbook snapshots from ClickHouse hot storage. Maximum 168-hour (7-day) query window per request.
- `GET /data/prices` - [Bulk price history](https://app.itomarkets.com/docs/md/public-api/get-data-prices): Daily close prices for up to 50 markets in a single request.
- `GET /data/spot/klines` - [Spot klines](https://app.itomarkets.com/docs/md/public-api/get-data-spot-klines): Historical spot OHLCV candles for major cryptoassets (BTC, ETH, SOL). Sourced from ClickHouse hot storage.

### Backtesting
Run ATOP strategy backtests on hosted replay datasets — discover registries, validate a spec, submit, then poll for results.
- `GET /backtests/atop/strategies` - [List strategies](https://app.itomarkets.com/docs/md/public-api/get-backtests-atop-strategies): Dispatchable strategy templates with parameter schemas.
- `POST /backtests/atop/strategies` - [Create custom strategy](https://app.itomarkets.com/docs/md/public-api/post-backtests-atop-strategies): Create a dispatchable custom strategy from an approved template. Returns 201.
- `GET /backtests/atop/custom-strategies` - [List custom strategies](https://app.itomarkets.com/docs/md/public-api/get-backtests-atop-custom-strategies): Custom strategies created through the API.
- `GET /backtests/atop/datasets` - [List datasets](https://app.itomarkets.com/docs/md/public-api/get-backtests-atop-datasets): Registered ClickHouse replay datasets available as backtest inputs.
- `GET /backtests/atop/execution-models` - [List execution models](https://app.itomarkets.com/docs/md/public-api/get-backtests-atop-execution-models): Fill/execution models for replay runs.
- `GET /backtests/atop/orderbook` - [Read ATOP orderbook](https://app.itomarkets.com/docs/md/public-api/get-backtests-atop-orderbook): Pull a bounded sample from registered historical L2 datasets for inspection before replay.
- `POST /backtests/atop/dataset` - [Assemble backtest dataset](https://app.itomarkets.com/docs/md/public-api/post-backtests-atop-dataset): Bundle L2 orderbook windows + spot klines for a symbol and period into a single response ready for backtest replay.
- `POST /backtests/atop/validate` - [Validate run spec](https://app.itomarkets.com/docs/md/public-api/post-backtests-atop-validate): Validate a run spec without dispatching execution.
- `POST /backtests/atop/plan` - [Plan experiment](https://app.itomarkets.com/docs/md/public-api/post-backtests-atop-plan): Validate a multi-window experiment plan without dispatching jobs. The body wraps a shared base_spec with named windows; each window is validated as its own run spec.
- `POST /backtests/atop` - [Submit backtest](https://app.itomarkets.com/docs/md/public-api/post-backtests-atop): Submit a validated run spec for execution. Returns 202 with data.run_id to poll.
- `GET /backtests/atop/{run_id}` - [Get run result](https://app.itomarkets.com/docs/md/public-api/get-backtests-atop-run-id): Run status, or the durable result artifact once complete. Returns 202 while running.

---

# List baskets

`GET /baskets`

All system baskets with current price and 24h change.

Rate limit: 120 requests / minute per key (read tier). Returns the {success, message, data} + meta envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `baskets:read` scope.

## Query parameters
- `page` (int, optional): Page number (default 1)
- `per_page` (int, optional): Items per page (default 20, max 100)

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/baskets" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

baskets = client.baskets.list()
for b in baskets["data"]:
    print(f"{b['basket_id']}: ${b['stats']['current_price']:.2f}")
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": [
    {
      "basket_id": "ai-frontier",
      "name": "AI Frontier",
      "stats": {
        "current_price": 42.5,
        "change_1d": 1.8,
        "underlyers_count": 12
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 38,
    "pages": 2
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-baskets

---

# Get basket

`GET /baskets/{basket_id}`

Details and composition stats for one basket.

Rate limit: 120 requests / minute per key (read tier). Returns the {success, message, data} envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `baskets:read` scope.

## Path parameters
- `basket_id` (string, required): Basket identifier, e.g. ai-frontier

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/baskets/ai-frontier" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

basket = client.baskets.get("ai-frontier")
print(basket["data"]["name"], basket["data"]["stats"])
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "basket_id": "ai-frontier",
    "name": "AI Frontier",
    "stats": {
      "current_price": 42.5,
      "underlyers_count": 12
    }
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-baskets-basket-id

---

# Get basket price

`GET /baskets/{basket_id}/price`

Current price plus the latest per-underlyer snapshot.

Rate limit: 120 requests / minute per key (read tier). Returns the {success, message, data} envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `baskets:read` scope.

## Path parameters
- `basket_id` (string, required): Basket identifier

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/baskets/ai-frontier/price" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

price = client.baskets.price("ai-frontier")
print(f"${price['data']['current_price']:.2f}")
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "basket_id": "ai-frontier",
    "current_price": 42.5,
    "last_updated": "2026-06-09T14:02:11+00:00",
    "underlyer_prices": {
      "will-x-happen": 0.61
    }
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-baskets-basket-id-price

---

# Price history

`GET /baskets/{basket_id}/history`

Time-ordered price series for charting.

Rate limit: 120 requests / minute per key (read tier). Returns its payload natively - no envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `baskets:read` scope.

## Path parameters
- `basket_id` (string, required): Basket identifier

## Query parameters
- `hours` (int, optional): Lookback window in hours (default 24)

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/baskets/ai-frontier/history" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

history = client.baskets.history("ai-frontier", hours=24)
for ts, px in zip(history["timestamps"], history["basket_prices"]):
    print(ts, px)
```

## Response
```json
{
  "timestamps": [
    "2026-06-09T13:00:00+00:00",
    "2026-06-09T13:01:00+00:00"
  ],
  "basket_prices": [
    42.1,
    42.3
  ],
  "underlyer_series": {},
  "basket_id": "ai-frontier",
  "basket_name": "AI Frontier"
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-baskets-basket-id-history

---

# Chart series

`GET /baskets/{basket_id}/chart`

Aggregated OHLC-style chart data for a period.

Rate limit: 120 requests / minute per key (read tier). Returns its payload natively - no envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `baskets:read` scope.

## Path parameters
- `basket_id` (string, required): Basket identifier

## Query parameters
- `period` (string, optional): 1d, 1w, 5d, 1m, 3m, 6m, ytd, 1y, all (default 1d)

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/baskets/ai-frontier/chart" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

chart = client.baskets.chart("ai-frontier", period="1w")
for point in chart["data"]:
    print(point["timestamp"], point["price"])
```

## Response
```json
{
  "basket_id": "ai-frontier",
  "period": "1d",
  "data": [
    {
      "timestamp": "2026-06-09T13:00:00+00:00",
      "price": 42.1
    }
  ]
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-baskets-basket-id-chart

---

# Basket metrics

`GET /baskets/{basket_id}/metrics`

Period returns, intraday change, and 30d volatility.

Rate limit: 120 requests / minute per key (read tier). Returns its payload natively - no envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `baskets:read` scope.

## Path parameters
- `basket_id` (string, required): Basket identifier

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/baskets/ai-frontier/metrics" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

metrics = client.baskets.metrics("ai-frontier")
print(f"1d: {metrics['change_1d']}%  vol: {metrics['volatility']}%")
```

## Response
```json
{
  "basket_id": "ai-frontier",
  "basket_name": "AI Frontier",
  "current_price": 42.5,
  "change_1d": 1.8,
  "change_1w": 3.2,
  "change_1m": 5.6,
  "volatility": 11.4
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-baskets-basket-id-metrics

---

# Underlyers

`GET /baskets/{basket_id}/underlyers`

Component market prices, weights, and stats.

Rate limit: 120 requests / minute per key (read tier). Returns its payload natively - no envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `baskets:read` scope.

## Path parameters
- `basket_id` (string, required): Basket identifier

## Query parameters
- `as_of` (string, optional): Historical composition date (YYYY-MM-DD)
- `fast` (int, optional): Set to 1 to serve cached prices without refreshing

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/baskets/ai-frontier/underlyers" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

data = client.baskets.underlyers("ai-frontier")
for u in data["underlyers"]:
    print(f"{u['market_name']}: {u['weight']*100:.1f}%")
```

## Response
```json
{
  "basket_id": "ai-frontier",
  "underlyers": [
    {
      "identifier": "will-x-happen",
      "platform": "polymarket",
      "market_name": "Will X happen?",
      "weight": 0.08,
      "side": "yes",
      "current_price": 0.61,
      "change_1d": 1.2
    }
  ],
  "fast_mode": false
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-baskets-basket-id-underlyers

---

# List basket overrides

`GET /baskets/overrides`

Manual price/composition overrides currently applied to baskets.

Rate limit: 120 requests / minute per key (read tier). Returns the {success, message, data} + meta envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `baskets:read` scope.

## Query parameters
- `basket_name` (string, optional): Filter by basket name
- `platform` (string, optional): Filter by platform
- `page` (int, optional): Page number (default 1)
- `per_page` (int, optional): Items per page (default 20, max 100)

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/baskets/overrides" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

overrides = client.baskets.overrides()
print(overrides["data"])
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": [
    {
      "id": 12,
      "market_id": "will-x-happen",
      "platform": "polymarket",
      "override_basket_name": "ai-frontier",
      "override_direction": null,
      "reason": "Manual reclassification",
      "updated_at": "2026-06-09T14:02:11+00:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "pages": 1
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-baskets-overrides

---

# Daily traded volume

`GET /baskets/volume/daily`

Total traded volume aggregated by UTC day from the platform trade ledger.

Rate limit: 120 requests / minute per key (read tier). Returns the {success, message, data} envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `baskets:read` scope.

## Query parameters
- `days` (int, optional): Lookback window in calendar days (default 30, max 365)
- `basketId` (string, optional): Filter to a single basket

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/baskets/volume/daily" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

vol = client.baskets.volume_daily(days=30)
for day in vol["data"]["days"]:
    print(day["date"], day["totalVolumeUsd"])
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "days": [
      {
        "date": "2026-06-17",
        "totalVolumeUsd": "350.00",
        "tradeCount": 3,
        "buyVolumeUsd": "300.00",
        "sellVolumeUsd": "50.00"
      }
    ],
    "summary": {
      "totalVolumeUsd": "350.00",
      "totalTradeCount": 3,
      "daysWithActivity": 1
    }
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-baskets-volume-daily

---

# List markets

`GET /markets/search`

Filtered listing of open Polymarket and Kalshi markets, sorted by volume.

Rate limit: 120 requests / minute per key (read tier). Returns the {success, message, data} + meta envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `markets:read` scope.

## Query parameters
- `platform` (string, optional): all, polymarket, or kalshi (default all)
- `category` (string, optional): Filter by category
- `expiration` (string, optional): Filter by expiration (YYYY-MM or YYYY)
- `limit` (int, optional): Max results per platform (default 100, max 500)

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/markets/search" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

markets = client.markets.search(category="crypto", limit=10)
for m in markets["data"]:
    print(f"{m['title']}: {m['last_price']}")
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": [
    {
      "market_id": "will-x-happen",
      "platform": "polymarket",
      "title": "Will X happen?",
      "last_price": 0.61,
      "volume": 120000.0,
      "expiration": "2026-12-31",
      "category": "crypto"
    }
  ],
  "meta": {
    "total": 1,
    "platform": "all",
    "category": null,
    "expiration": null
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-markets-search

---

# Get market

`GET /markets/{market_id}`

Full metadata for a single market including categorization, basket assignment, and trading data.

Rate limit: 120 requests / minute per key (read tier). Returns the {success, message, data} envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `markets:read` scope.

## Path parameters
- `market_id` (string, required): Market identifier (ticker for Kalshi, token_id for Polymarket)

## Query parameters
- `platform` (string, optional): Disambiguate if market_id exists on multiple platforms (polymarket or kalshi)

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/markets/will-x-happen" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

market = client.markets.get("will-x-happen")
print(market["data"]["title"], market["data"]["last_price"])
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "market_id": "will-x-happen",
    "platform": "polymarket",
    "ticker": "will-x-happen",
    "title": "Will X happen?",
    "status": "open",
    "volume": 120000.0,
    "last_price": 0.61,
    "market_type": "binary",
    "main_category": "politics",
    "basket_name": "middle-east-conflict",
    "tags": [
      "conflict",
      "geopolitics"
    ]
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-markets-market-id

---

# Market price history

`GET /markets/{market_id}/history`

Daily close price time series for a single market.

Rate limit: 120 requests / minute per key (read tier). Returns the {success, message, data} + meta envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `markets:read` scope.

## Path parameters
- `market_id` (string, required): Market identifier

## Query parameters
- `days` (int, optional): Lookback window in days (default 90, max 365)
- `platform` (string, optional): Optional platform filter

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/markets/will-x-happen/history" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

history = client.markets.history("will-x-happen", days=90)
for point in history["data"]["series"]:
    print(point["date"], point["close_price"])
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "market_id": "will-x-happen",
    "platform": "polymarket",
    "title": "Will X happen?",
    "days": 90,
    "series": [
      {
        "date": "2026-03-24",
        "close_price": 0.55,
        "volume": 8400.0
      }
    ]
  },
  "meta": {
    "points": 1,
    "start_date": "2026-03-24"
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-markets-market-id-history

---

# Historical orderbook

`GET /data/orderbook`

L2 orderbook snapshots from ClickHouse hot storage. Maximum 168-hour (7-day) query window per request.

Rate limit: 120 requests / minute per key (read tier). Returns the {success, message, data} + meta envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `markets:read` scope.

## Query parameters
- `venue` (string, required): One of: polymarket, kalshi, hyperliquid
- `market_id` (string, optional): Filter by market identifier (condition_id, ticker, etc.)
- `start` (string, required): ISO 8601 start timestamp
- `end` (string, required): ISO 8601 end timestamp
- `limit` (int, optional): Max rows to return (default 5000, max 50000)
- `offset` (int, optional): Pagination offset (default 0)

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/data/orderbook?venue=VALUE&start=VALUE&end=VALUE" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

book = client.data.orderbook(
    venue="polymarket",
    start="2026-06-09T13:00:00Z",
    end="2026-06-09T14:00:00Z",
    market_id="will-x-happen",
    limit=5000,
)
for snap in book["data"]["snapshots"]:
    print(snap["snapshot_ts"], snap["best_yes_bid"], snap["best_yes_ask"])
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "venue": "polymarket",
    "snapshots": [
      {
        "snapshot_ts": "2026-06-09T14:00:01",
        "best_yes_bid": 0.6,
        "best_yes_ask": 0.62,
        "spread_bps": 33,
        "venue": "polymarket"
      }
    ]
  },
  "meta": {
    "rows": 1,
    "limit": 5000,
    "offset": 0,
    "start": "2026-06-09T13:00:00+00:00",
    "end": "2026-06-09T14:00:00+00:00"
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-data-orderbook

---

# Bulk price history

`GET /data/prices`

Daily close prices for up to 50 markets in a single request.

Rate limit: 120 requests / minute per key (read tier). Returns the {success, message, data} + meta envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `markets:read` scope.

## Query parameters
- `market_ids` (string, required): Comma-separated market identifiers (max 50)
- `days` (int, optional): Lookback window in days (default 30, max 365)

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/data/prices?market_ids=VALUE" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

prices = client.data.prices(["will-x-happen"], days=30)
for date_row in prices["data"]["will-x-happen"]:
    print(date_row["date"], date_row["close_price"])
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "will-x-happen": [
      {
        "date": "2026-05-23",
        "close_price": 0.55,
        "volume": 8400.0
      }
    ]
  },
  "meta": {
    "market_count": 1,
    "days": 30,
    "start_date": "2026-05-23"
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-data-prices

---

# Spot klines

`GET /data/spot/klines`

Historical spot OHLCV candles for major cryptoassets (BTC, ETH, SOL). Sourced from ClickHouse hot storage.

Rate limit: 120 requests / minute per key (read tier). Returns the {success, message, data} + meta envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `markets:read` scope.

## Query parameters
- `symbol` (string, required): Asset symbol: BTC, ETH, or SOL
- `interval` (int, optional): Candle interval in seconds, 60–86400 (default 300 = 5m)
- `start` (string, required): ISO 8601 start time
- `end` (string, required): ISO 8601 end time
- `limit` (int, optional): Max rows (default 5000, max 50000)

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/data/spot/klines?symbol=VALUE&start=VALUE&end=VALUE" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

klines = client.data.spot_klines(
    symbol="BTC",
    interval=300,
    start="2026-06-09T13:00:00Z",
    end="2026-06-09T14:00:00Z",
)
for k in klines["data"]["klines"]:
    print(k["ts"], k["close"])
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "symbol": "BTC",
    "interval": 300,
    "klines": [
      {
        "ts": "2026-06-09T14:00:00Z",
        "open": 97245.3,
        "high": 97301.1,
        "low": 97198.7,
        "close": 97267.4
      }
    ]
  },
  "meta": {
    "rows": 1,
    "interval": 300
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-data-spot-klines

---

# List strategies

`GET /backtests/atop/strategies`

Dispatchable strategy templates with parameter schemas.

Rate limit: 120 requests / minute per key (read tier). Returns the {success, message, data} envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `backtests:read` scope.

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/backtests/atop/strategies" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

strategies = client.backtests.strategies()
for s in strategies["data"]["strategies"]:
    print(s["strategy_id"])
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "registry_version": "atop-strategy-registry-v1",
    "hot_path_runtime": "rust",
    "strategies": [
      {
        "strategy_id": "wsc_crypto_updown_delta_hedged_roll"
      }
    ]
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-backtests-atop-strategies

---

# Create custom strategy

`POST /backtests/atop/strategies`

Create a dispatchable custom strategy from an approved template. Returns 201.

Rate limit: 10 requests / minute per key (write tier). Returns the {success, message, data} envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `backtests:write` scope.

## Body
- `strategy_id`: "my_liquidity_roll"
- `name`: "My Liquidity Roll"
- `template_strategy_id`: "wsc_crypto_updown_delta_hedged_roll"
- `venues`: ["polymarket"]
- `default_params`: {"roll_trigger":"liquidity_spread_score","size_mode":"liquidity_weighted","liquidity_size_fraction":0.1}

## Request - cURL
```bash
curl -X POST "https://itomarkets.com/api/v1/backtests/atop/strategies" \
  -H "Authorization: Bearer $ITO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
  {
    "strategy_id": "my_liquidity_roll",
    "name": "My Liquidity Roll",
    "template_strategy_id": "wsc_crypto_updown_delta_hedged_roll",
    "venues": [
      "polymarket"
    ],
    "default_params": {
      "roll_trigger": "liquidity_spread_score",
      "size_mode": "liquidity_weighted",
      "liquidity_size_fraction": 0.1
    }
  }
  '
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

result = client.backtests.create_strategy(
    strategy_id="my_liquidity_roll",
    name="My Liquidity Roll",
    template_strategy_id="wsc_crypto_updown_delta_hedged_roll",
    venues=["polymarket"],
    default_params={"roll_trigger": "liquidity_spread_score"},
)
print(result["data"]["strategy_id"])
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "strategy_id": "my_liquidity_roll",
    "template_strategy_id": "wsc_crypto_updown_delta_hedged_roll",
    "runtime": "custom_template"
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/post-backtests-atop-strategies

---

# List custom strategies

`GET /backtests/atop/custom-strategies`

Custom strategies created through the API.

Rate limit: 120 requests / minute per key (read tier). Returns the {success, message, data} envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `backtests:read` scope.

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/backtests/atop/custom-strategies" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

custom = client.backtests.custom_strategies()
for s in custom["data"]["strategies"]:
    print(s["strategy_id"])
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "registry_version": "atop-custom-strategy-registry-v1",
    "template_strategy_ids": [
      "wsc_crypto_updown_delta_hedged_roll"
    ],
    "strategies": [
      {
        "strategy_id": "my_liquidity_roll"
      }
    ]
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-backtests-atop-custom-strategies

---

# List datasets

`GET /backtests/atop/datasets`

Registered ClickHouse replay datasets available as backtest inputs.

Rate limit: 120 requests / minute per key (read tier). Returns the {success, message, data} envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `backtests:read` scope.

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/backtests/atop/datasets" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

datasets = client.backtests.datasets()
for d in datasets["data"]["datasets"]:
    print(d["dataset_id"])
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "registry_version": "atop-dataset-registry-v1",
    "datasets": [
      {
        "dataset_id": "clickhouse:ito_hot.platform_orderbook_l2"
      }
    ]
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-backtests-atop-datasets

---

# List execution models

`GET /backtests/atop/execution-models`

Fill/execution models for replay runs.

Rate limit: 120 requests / minute per key (read tier). Returns the {success, message, data} envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `backtests:read` scope.

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/backtests/atop/execution-models" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

models = client.backtests.execution_models()
for m in models["data"]["models"]:
    print(m["fill_model"])
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "registry_version": "atop-execution-registry-v1",
    "models": [
      {
        "fill_model": "l2_vwap"
      }
    ]
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-backtests-atop-execution-models

---

# Read ATOP orderbook

`GET /backtests/atop/orderbook`

Pull a bounded sample from registered historical L2 datasets for inspection before replay.

Rate limit: 120 requests / minute per key (read tier). Returns the {success, message, data} + meta envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `backtests:read` scope.

## Query parameters
- `source` (string, optional): Dataset alias: platform_l2, kalshi_pmxt (default platform_l2)
- `venue` (string, optional): Filter by venue name
- `start` (string, required): ISO 8601 start timestamp
- `end` (string, required): ISO 8601 end timestamp
- `limit` (int, optional): Max rows (default 5000, max 50000)
- `offset` (int, optional): Pagination offset (default 0)

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/backtests/atop/orderbook?start=VALUE&end=VALUE" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

book = client.backtests.orderbook(
    source="platform_l2",
    venue="polymarket",
    start="2026-06-09T13:00:00Z",
    end="2026-06-09T14:00:00Z",
    limit=5000,
)
for row in book["data"]["rows"]:
    print(row["epoch"], row["best_bid"], row["best_ask"])
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "rows": [
      {
        "epoch": 1718010000,
        "venue": "polymarket",
        "best_bid": 0.6,
        "best_ask": 0.62,
        "spread_bps": 33
      }
    ],
    "total": 1
  },
  "meta": {
    "source": "platform_l2",
    "limit": 5000,
    "offset": 0
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-backtests-atop-orderbook

---

# Assemble backtest dataset

`POST /backtests/atop/dataset`

Bundle L2 orderbook windows + spot klines for a symbol and period into a single response ready for backtest replay.

Rate limit: 10 requests / minute per key (write tier). Returns the {success, message, data} envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `backtests:read` scope.

## Body
- `symbol`: "BTC"
- `interval`: 300
- `start`: "2026-02-01T00:00:00Z"
- `end`: "2026-02-08T00:00:00Z"
- `include_l2`: false

## Request - cURL
```bash
curl -X POST "https://itomarkets.com/api/v1/backtests/atop/dataset" \
  -H "Authorization: Bearer $ITO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
  {
    "symbol": "BTC",
    "interval": 300,
    "start": "2026-02-01T00:00:00Z",
    "end": "2026-02-08T00:00:00Z",
    "include_l2": false
  }
  '
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

dataset = client.backtests.dataset(
    symbol="BTC",
    interval=300,
    start="2026-02-01T00:00:00Z",
    end="2026-02-08T00:00:00Z",
    include_l2=True,
)
print(len(dataset["data"]["windows"]), "windows")
print(len(dataset["data"]["spot_klines"]), "klines")
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "symbol": "BTC",
    "interval": 300,
    "period": {
      "start": "2026-02-01T00:00:00+00:00",
      "end": "2026-02-08T00:00:00+00:00"
    },
    "windows": [
      {
        "ts": "2026-02-01T00:05:00Z",
        "mid": 0.52,
        "spread": 0.04
      }
    ],
    "spot_klines": [
      {
        "ts": "2026-02-01T00:05:00Z",
        "open": 97200,
        "high": 97350,
        "low": 97100,
        "close": 97280
      }
    ],
    "metadata": {
      "source": "ito-cloud-runtime/api/v1/backtests/atop",
      "clickhouse_table": "platform_orderbook_l2",
      "data_quality": "production_hot_storage"
    }
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/post-backtests-atop-dataset

---

# Validate run spec

`POST /backtests/atop/validate`

Validate a run spec without dispatching execution.

Rate limit: 10 requests / minute per key (write tier). Returns the {success, message, data} envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `backtests:read` scope.

## Body
- `strategy_id`: "wsc_crypto_updown_delta_hedged_roll"
- `dataset_id`: "clickhouse:ito_hot.platform_orderbook_l2"
- `venues`: ["polymarket"]
- `date_range`: {"start":"2026-05-14T14:45:00Z","end":"2026-05-14T14:46:00Z"}
- `params`: {"roll_trigger":"liquidity_spread_score","size_mode":"liquidity_weighted","liquidity_size_fraction":0.1}
- `execution`: {"fill_model":"l2_vwap","latency_ms":50,"max_book_age_ms":1000,"partial_fills":true,"fee_bps":0}
- `budgets`: {"max_wall_clock_seconds":1800,"max_rows":10000000000,"max_cost_usd":25}

## Request - cURL
```bash
curl -X POST "https://itomarkets.com/api/v1/backtests/atop/validate" \
  -H "Authorization: Bearer $ITO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
  {
    "strategy_id": "wsc_crypto_updown_delta_hedged_roll",
    "dataset_id": "clickhouse:ito_hot.platform_orderbook_l2",
    "venues": [
      "polymarket"
    ],
    "date_range": {
      "start": "2026-05-14T14:45:00Z",
      "end": "2026-05-14T14:46:00Z"
    },
    "params": {
      "roll_trigger": "liquidity_spread_score",
      "size_mode": "liquidity_weighted",
      "liquidity_size_fraction": 0.1
    },
    "execution": {
      "fill_model": "l2_vwap",
      "latency_ms": 50,
      "max_book_age_ms": 1000,
      "partial_fills": true,
      "fee_bps": 0
    },
    "budgets": {
      "max_wall_clock_seconds": 1800,
      "max_rows": 10000000000,
      "max_cost_usd": 25
    }
  }
  '
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

result = client.backtests.validate(
    strategy_id="wsc_crypto_updown_delta_hedged_roll",
    dataset_id="clickhouse:ito_hot.platform_orderbook_l2",
    venues=["polymarket"],
    date_range={"start": "2026-05-14T14:45:00Z", "end": "2026-05-14T14:46:00Z"},
)
print(result["data"]["status"])  # "validated"
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "run_id": "dry_run",
    "status": "validated",
    "spec": {
      "strategy_id": "wsc_crypto_updown_delta_hedged_roll",
      "spec_hash": "6a91f0c4e2d85b37a1c9f4e0d2b6873c5e1a0f9d4c8b2e6a7d3f5c1b8e4a0d92",
      "budgets": {
        "max_wall_clock_seconds": 1800,
        "max_rows": 10000000000,
        "max_cost_usd": 25
      }
    },
    "metrics": {}
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/post-backtests-atop-validate

---

# Plan experiment

`POST /backtests/atop/plan`

Validate a multi-window experiment plan without dispatching jobs. The body wraps a shared base_spec with named windows; each window is validated as its own run spec.

Rate limit: 10 requests / minute per key (write tier). Returns the {success, message, data} envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `backtests:read` scope.

## Body
- `name`: "rolling_eval"
- `base_spec`: {"strategy_id":"wsc_crypto_updown_delta_hedged_roll","dataset_id":"clickhouse:ito_hot.platform_orderbook_l2","venues":["polymarket"],"date_range":{"start":"2026-05-14T14:45:00Z","end":"2026-05-14T14:46:00Z"},"params":{"roll_trigger":"liquidity_spread_score","size_mode":"liquidity_weighted","liquidity_size_fraction":0.1},"execution":{"fill_model":"l2_vwap","latency_ms":50,"max_book_age_ms":1000,"partial_fills":true,"fee_bps":0},"budgets":{"max_wall_clock_seconds":1800,"max_rows":10000000000,"max_cost_usd":25}}
- `windows`: [{"name":"may_w1","role":"train","date_range":{"start":"2026-05-14T14:45:00Z","end":"2026-05-14T14:46:00Z"}},{"name":"may_w2","role":"test","date_range":{"start":"2026-05-14T14:46:00Z","end":"2026-05-14T14:47:00Z"}}]

## Request - cURL
```bash
curl -X POST "https://itomarkets.com/api/v1/backtests/atop/plan" \
  -H "Authorization: Bearer $ITO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
  {
    "name": "rolling_eval",
    "base_spec": {
      "strategy_id": "wsc_crypto_updown_delta_hedged_roll",
      "dataset_id": "clickhouse:ito_hot.platform_orderbook_l2",
      "venues": [
        "polymarket"
      ],
      "date_range": {
        "start": "2026-05-14T14:45:00Z",
        "end": "2026-05-14T14:46:00Z"
      },
      "params": {
        "roll_trigger": "liquidity_spread_score",
        "size_mode": "liquidity_weighted",
        "liquidity_size_fraction": 0.1
      },
      "execution": {
        "fill_model": "l2_vwap",
        "latency_ms": 50,
        "max_book_age_ms": 1000,
        "partial_fills": true,
        "fee_bps": 0
      },
      "budgets": {
        "max_wall_clock_seconds": 1800,
        "max_rows": 10000000000,
        "max_cost_usd": 25
      }
    },
    "windows": [
      {
        "name": "may_w1",
        "role": "train",
        "date_range": {
          "start": "2026-05-14T14:45:00Z",
          "end": "2026-05-14T14:46:00Z"
        }
      },
      {
        "name": "may_w2",
        "role": "test",
        "date_range": {
          "start": "2026-05-14T14:46:00Z",
          "end": "2026-05-14T14:47:00Z"
        }
      }
    ]
  }
  '
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

plan = client.backtests.plan(
    name="rolling_eval",
    base_spec={
        "strategy_id": "wsc_crypto_updown_delta_hedged_roll",
        "dataset_id": "clickhouse:ito_hot.platform_orderbook_l2",
        "venues": ["polymarket"],
    },
    windows=[
        {"name": "may_w1", "role": "train",
         "date_range": {"start": "2026-05-14T14:45:00Z", "end": "2026-05-14T14:46:00Z"}},
    ],
)
print(plan["data"]["plan_id"])
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "plan_version": "atop-experiment-plan-v1",
    "name": "rolling_eval",
    "plan_id": "3d7e5a1f9c2b8e4d6a0c5f3b7e9d1a8c2f4b6d0e8a3c5e7f9b1d4a6c8e0f2b53",
    "created_at": "2026-05-14T14:50:00+00:00",
    "runs": [
      {
        "name": "may_w1",
        "role": "train",
        "status": "validated"
      },
      {
        "name": "may_w2",
        "role": "test",
        "status": "validated"
      }
    ]
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/post-backtests-atop-plan

---

# Submit backtest

`POST /backtests/atop`

Submit a validated run spec for execution. Returns 202 with data.run_id to poll.

Rate limit: 10 requests / minute per key (write tier). Returns the {success, message, data} envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `backtests:write` scope.

## Body
- `strategy_id`: "wsc_crypto_updown_delta_hedged_roll"
- `dataset_id`: "clickhouse:ito_hot.platform_orderbook_l2"
- `venues`: ["polymarket"]
- `date_range`: {"start":"2026-05-14T14:45:00Z","end":"2026-05-14T14:46:00Z"}
- `params`: {"roll_trigger":"liquidity_spread_score","size_mode":"liquidity_weighted","liquidity_size_fraction":0.1}
- `execution`: {"fill_model":"l2_vwap","latency_ms":50,"max_book_age_ms":1000,"partial_fills":true,"fee_bps":0}
- `budgets`: {"max_wall_clock_seconds":1800,"max_rows":10000000000,"max_cost_usd":25}

## Request - cURL
```bash
curl -X POST "https://itomarkets.com/api/v1/backtests/atop" \
  -H "Authorization: Bearer $ITO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
  {
    "strategy_id": "wsc_crypto_updown_delta_hedged_roll",
    "dataset_id": "clickhouse:ito_hot.platform_orderbook_l2",
    "venues": [
      "polymarket"
    ],
    "date_range": {
      "start": "2026-05-14T14:45:00Z",
      "end": "2026-05-14T14:46:00Z"
    },
    "params": {
      "roll_trigger": "liquidity_spread_score",
      "size_mode": "liquidity_weighted",
      "liquidity_size_fraction": 0.1
    },
    "execution": {
      "fill_model": "l2_vwap",
      "latency_ms": 50,
      "max_book_age_ms": 1000,
      "partial_fills": true,
      "fee_bps": 0
    },
    "budgets": {
      "max_wall_clock_seconds": 1800,
      "max_rows": 10000000000,
      "max_cost_usd": 25
    }
  }
  '
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

# Submit and poll until completion
result = client.backtests.run(
    strategy_id="wsc_crypto_updown_delta_hedged_roll",
    dataset_id="clickhouse:ito_hot.platform_orderbook_l2",
    venues=["polymarket"],
    date_range={"start": "2026-05-14T14:45:00Z", "end": "2026-05-14T14:46:00Z"},
    params={"roll_trigger": "liquidity_spread_score"},
)
print(f"P&L: ${result['data']['metrics']['pnl_usd']:.2f}")
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "run_id": "atop_20260514T144500Z_8f3a2c1b9d",
    "status": "accepted"
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/post-backtests-atop

---

# Get run result

`GET /backtests/atop/{run_id}`

Run status, or the durable result artifact once complete. Returns 202 while running.

Rate limit: 120 requests / minute per key (read tier). Returns the {success, message, data} envelope.

## Authorization
- `Authorization: Bearer` - an `ito_*` key (from Settings) holding the `backtests:read` scope.

## Path parameters
- `run_id` (string, required): Run id returned by submit

## Request - cURL
```bash
curl "https://itomarkets.com/api/v1/backtests/atop/atop_run_8f3a2c" \
  -H "Authorization: Bearer $ITO_API_KEY"
```

## Request - Python
```python
from ito import ItoClient

client = ItoClient("ito_...")

result = client.backtests.get_result("atop_20260514T144500Z_8f3a2c1b9d")
print(result["data"]["status"], result["data"]["metrics"])
```

## Response
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "run_id": "atop_20260514T144500Z_8f3a2c1b9d",
    "status": "succeeded",
    "metrics": {
      "pnl_usd": 412.7,
      "fills": 96
    },
    "summary": {
      "rows_replayed": 182304,
      "total_rolls": 17
    },
    "artifacts": {
      "gcs_prefix": "gs://.../runs",
      "gcs_result_uri": "gs://.../runs/atop_20260514T144500Z_8f3a2c1b9d/result.json",
      "gcs_summary_uri": "gs://.../runs/atop_20260514T144500Z_8f3a2c1b9d/summary.json"
    }
  }
}
```

---
Source: https://app.itomarkets.com/docs/public-api/get-backtests-atop-run-id

---

# Itô Markets - Dashboard HTTP API

Read the dashboard snapshot, basket state/summary/exposures, live streams, and submit paper basket tickets. Use `authorization: Bearer $DASHBOARD_API_KEY` for scripts; browser pages use the session cookie. Live reads return `cache-control: no-store`.

## Endpoints
- `GET /api/snapshot` - Dashboard account, positions, histories, thematic baskets, strategy previews, and custom basket metadata.
- `GET /api/baskets/btc-eth-short-term/state` - Full hedge-board state: summary, constituents, exposures, events, hedge hint, deployment state, and raw strategy snapshot.
- `GET /api/baskets/btc-eth-short-term/summary` - Fast header: NAV, cash reserve, total P&L, BTC/ETH deltas, last roll, next expected roll, update time.
- `GET /api/baskets/btc-eth-short-term/constituents` - Raw BTC/ETH prediction-market positions with mark, notional, weight, and indicative MTM.
- `GET /api/baskets/btc-eth-short-term/exposures` - Hedge-relevant BTC/ETH delta, tenor breakdowns, top contributors, and delta change since last roll.
- `GET /api/baskets/btc-eth-short-term/events` - Chronological roll, rebalance, mark-change, and exposure-change events.
- `GET /api/baskets/btc-eth-short-term/hedge_hint` - Read-only Hyperliquid offset hint. It never places orders.
- `GET /api/baskets/btc-eth-short-term/stream` - Server-sent events for basket state, summary, delta, and tick channels.
- `GET /api/backtests/atop/nowcast/wsc_crypto_updown_delta_hedged_roll` - Current ATOP nowcast source-of-truth with full L2 legs and executable VWAP scenarios.
- `GET /api/backtests/atop/nowcast/wsc_crypto_updown_delta_hedged_roll/stream` - Narrowest realtime stream: crypto basket price, legs, paper lots, roll count, executable orderbook.
- `POST /api/baskets/btc-eth-short-term/trade` - Deploy paper capital into the BTC/ETH hedge basket (capital_usd, optional hedge_hyperliquid).
- `POST /api/cli/basket-trade` - Paper basket ticket. Body: basket, size, optional side, max_legs.
- `GET / POST /api/custom-baskets` - List or create account-local custom paper baskets (max 20 legs; never broadcasts venue orders).

## Code samples

### Read full dashboard snapshot - cURL
```bash
curl "https://app.itomarkets.com/api/snapshot" \
  -H "authorization: Bearer $DASHBOARD_API_KEY"
```

### Read full dashboard snapshot - Python
```python
import os
import requests

base_url = os.environ.get("INSTITUTIONAL_API_BASE_URL", "https://app.itomarkets.com")
api_key = os.environ["INSTITUTIONAL_API_KEY"]
headers = {"authorization": f"Bearer {api_key}"}

response = requests.get(f"{base_url}/api/snapshot", headers=headers, timeout=30)
response.raise_for_status()
snapshot = response.json()

print(snapshot.keys())
print("positions", len(snapshot.get("positions", [])))
print("custom baskets", len(snapshot.get("custom_baskets", [])))
```

### Read full basket state - cURL
```bash
curl "https://app.itomarkets.com/api/baskets/btc-eth-short-term/state" \
  -H "authorization: Bearer $DASHBOARD_API_KEY"
```

### Read full basket state - Python
```python
import os
import requests

base_url = os.environ.get("INSTITUTIONAL_API_BASE_URL", "https://app.itomarkets.com")
api_key = os.environ["INSTITUTIONAL_API_KEY"]
headers = {"authorization": f"Bearer {api_key}"}

state = requests.get(
    f"{base_url}/api/baskets/btc-eth-short-term/state",
    headers=headers,
    timeout=30,
).json()

summary = state["summary"]
print("basket", state["basket_id"])
print("price/nav", summary.get("nav"), "pnl", summary.get("total_pnl"))
print("constituents", len(state["constituents"]))
print("net deltas", state["exposures"]["net_btc_delta"], state["exposures"]["net_eth_delta"])

# The raw source-of-truth strategy snapshot used by the strategy page is embedded here.
strategy_snapshot = state["snapshot"]
print(strategy_snapshot["basket"]["price"], strategy_snapshot["orderbook"]["spreadBps"])
```

### Deploy paper capital - cURL
```bash
curl -X POST "https://app.itomarkets.com/api/baskets/btc-eth-short-term/trade" \
  -H "authorization: Bearer $DASHBOARD_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "capital_usd": 10, "hedge_hyperliquid": true }'
```

### Submit paper trade - cURL
```bash
curl -X POST "https://app.itomarkets.com/api/cli/basket-trade" \
  -H "authorization: Bearer $DASHBOARD_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "basket": "ITO-P3",
    "size": 10,
    "max_legs": 12
  }'
```

---
Source: https://app.itomarkets.com/docs/api