---
title: Markets
description: Market discovery for supported venues.
---

### GET /context/markets

Search or list instruments on supported venues. Hyperliquid is supported now; Lighter and Polymarket are live for Nautilus backtesting, while Binance is coming soon.

**Query parameters**

| Param | Type | Notes |
|---|---|---|
| `query` | string | Optional free-text search across venue, symbol, name, and Polymarket question text |
| `limit` | integer | 1–200 results; default 100 |

**Response — `200`** (Hyperliquid example)

```json
{
  "markets": [
    {
      "venue": "hyperliquid",
      "symbol": "BTC",
      "kind": "perp",
      "status": "live",
      "backtest_ready": true,
      "framework_symbols": {
        "freqtrade": "BTC/USDC:USDC",
        "nautilus": "BTC-PERP.HYPERLIQUID"
      },
      "tick_size": 0.1,
      "min_order_usd": 10,
      "max_leverage": 40
    }
  ],
  "next_cursor": null
}
```

For Nautilus backtesting, search for the native instrument, for example [`GET /context/markets?query=SOL-PERP.LIGHTER&limit=20`](/context/markets) or [`GET /context/markets?query=512329.POLYMARKET&limit=20`](/context/markets). For Polymarket, search establishes that the outcome token is live; use the exact dataset lookup below to verify backtest readiness.

## Polymarket source split

Polymarket live discovery is Gamma-backed. Superior applies the complete lifecycle predicate before returning a Gamma market: `active` must be `true`, `closed` must be `false`, `archived` must not be `true`, `acceptingOrders` must be `true`, `endDate` must be valid, and `endDate` must be strictly later than server time. Missing, malformed, inactive, closed, archived, non-orderable, and expired markets are omitted.

Backtest coverage comes from a separate Superior-owned GCS readiness object for each Gamma slug. These per-slug markers point to validated immutable releases. With the rollout enabled, Markets, Datasets, and the exact latest-backtest-dataset lookup do not read the legacy global Polymarket catalog.

The canonical public search accepts only `query` and `limit`. A non-empty Polymarket search runs in live mode: live and all search modes intentionally perform zero readiness reads, so `backtest_ready: false` means unverified, not unavailable. In short, false means unverified for these searches. The internal `backtest_ready` filtering mode reads the exact marker for each surviving Gamma slug and returns only identity-matching, supported, unexpired tokens; it does not scan ahead to fill a short page.

Without search text, Polymarket contributes one bounded readiness page only, for every accepted internal status. It does not enumerate every Gamma market. The compatibility cursor is opaque and non-snapshot: Gamma or GCS drift can invalidate it, so restart the query after an invalid-cursor response.

## `backtest_ready`

`true` means the market has a valid per-slug readiness marker for a published [dataset release](/context/datasets). A market can be live but not yet ready, and a live search deliberately does not check readiness. Before [`POST /runtime/backtests`](/runtime/backtests), call `GET /runtime/backtests/dataset?venue=polymarket&market={symbol}`. Exact resolution is token → Gamma slug → readiness marker; clients must not guess a slug.

An unfiltered `GET /context/datasets?venue=polymarket` returns one bounded page and has no cursor, so it is not an exhaustive historical universe. Readiness does not carry a row count: `tables.trades.rows=0` means the count is unknown, not that the dataset is empty.

## Errors and rollout

- Production enables `FEATURE_POLYMARKET_GAMMA_SLUG_READINESS` after per-slug readiness objects have been published/backfilled and their production-bucket immutable references verified. Job readiness publication remains enabled so new validated releases maintain those markers.
- Gamma transport/payload failure returns `502 context_upstream_unavailable`. A single market with malformed lifecycle fields is omitted by the fail-closed lifecycle predicate. Invalid or cross-environment readiness markers are isolated to their market: readiness-filtered search and listing omit that market, and exact dataset resolution returns not-ready.
- A missing readiness marker is a normal not-ready result. An actual GCS permission, network, or availability failure returns `503 context_store_unavailable`; the old oversized catalog is not read and cannot cause this error on the enabled path.
- Production uses the existing secret-backed `TRADE_HTTP_PROXY`; credentials are never part of public configuration or errors.
- Roll back discovery by setting `FEATURE_POLYMARKET_GAMMA_SLUG_READINESS=false`. This restores the legacy implementation without changing immutable datasets.

## Identifier conventions

`symbol` is the canonical **venue-native** market id across Context endpoints (`/context/markets`, `/context/candles`, `/context/funding`, datasets). Use it when reading market data or addressing a market through the API.

Context and dataset routes use the top-level `symbol`. A runtime backtest `symbols` list and framework-native strategy config use the alias under `framework_symbols.<framework>`: Freqtrade uses `framework_symbols.freqtrade` for both runtime `symbols` and `config.exchange.pair_whitelist`; Nautilus uses `framework_symbols.nautilus` for both runtime `symbols` and `config.instrument_ids`. Where an alias equals the canonical form, the map still lists it — agents never have to guess.

| Venue | Canonical `symbol` | `framework_symbols.freqtrade` | `framework_symbols.nautilus` |
|---|---|---|---|
| Hyperliquid | `BTC/USDC:USDC` | `BTC/USDC:USDC` | `BTC-PERP.HYPERLIQUID` |
| Binance | `ETH/USDT` | `ETH/USDT` | — |
| Lighter | `SOL-PERP.LIGHTER` | — | `SOL-PERP.LIGHTER` |
| Polymarket | `512329.POLYMARKET` | — | `512329.POLYMARKET` |

Binance remains a planned venue; Lighter and Polymarket identifiers are live for Nautilus backtesting.

When a symbol goes in a URL path (e.g. [`GET /context/setup/:pair`](/context/intelligence)), URL-encode the canonical `symbol`. The API never guesses between venue-native ids and framework aliases; sending a framework alias where a Context endpoint expects `symbol` returns `400 symbol_not_canonical` with the canonical candidate when one can be found.