# PokéQuant

PokéQuant is a professional market terminal for Pokémon cards: live prices,
price history charts, order-book depth, population (grading) data and
quantitative signals (fair value, liquidity, regime, recommendation) across
the covered card universe.

## Data caveats

- Every API payload carries `asOf` (an ISO 8601 timestamp: when the payload
  was computed) and `dataMode` (`DEMO` or `LIVE`).
- `DEMO` means deterministic fixture-derived data — realistic, but
  simulated, never a real market price. `LIVE` means the value came from a
  real provider.
- Money is always integer cents plus an ISO currency code (e.g. `1050`
  cents, `USD`) — never a floating-point dollar amount.
- A `null` value is a genuine coverage gap (unknown, insufficient data,
  illiquid), never an interpolated or fabricated placeholder. Never treat a
  `null` as zero.

## URL patterns

- `https://cardboardalpha.com/pokemon` — the market wall: every covered Pokémon
  card, filterable by set, era, product/card type, rarity and free-text
  search.
- `https://cardboardalpha.com/screener` — a cross-sectional screener across the
  covered card universe (undervalued / accumulation / tight-supply /
  high-liquidity presets).
- `https://cardboardalpha.com/pokemon/eras` — every Pokémon TCG era; `/pokemon/eras/
  {era}` for one era's sets (e.g. `/pokemon/eras/wotc`).
- `/pokemon/{set-slug}` — one set's full card list (e.g. `/pokemon/pitch-black`).
- `/pokemon/{set-slug}/{card-slug}` — per-card page, where `{card-slug}` is
  `{name}-{number}` (e.g. `/pokemon/pitch-black/mistys-vitality-111`).
- `/pokemon/{set-slug}/{card-slug}/{grade}` — per-grade instrument page (e.g.
  `.../psa-10`). Indexable, but intentionally not listed in the sitemap — a
  printing's representative (raw/base) instrument page is the canonical
  crawl target; every grade the printing has is one click away from it.
- `/pokemon/{set-slug}/{card-slug}.md` — a plain-Markdown twin of the card
  page: identity, current stats and provenance as text, no JavaScript
  rendering required. Linked from the HTML page and vice versa.
- `https://cardboardalpha.com/pokemon/sealed` — sealed product hub (booster boxes,
  elite trainer boxes, ...); `/pokemon/sealed/{product-slug}` for one product.
- `https://cardboardalpha.com/pokemon/indices` — the hosted POKE150 / POKE250
  indices; `/pokemon/indices/{poke150,poke250}` for one index.

## APIs

All endpoints below are read-only `GET` requests returning JSON (except
`/api/tape`, which is a Server-Sent Events stream). Full request/response
schemas: https://cardboardalpha.com/api/openapi.json (OpenAPI 3.1). Human-readable
reference: https://cardboardalpha.com/developers.

- `GET /api/wall` — the market wall grid. Query: `filter`, `era`, `set`,
  `ptype`, `ctype`, `rarity`, `q`, `limit`, `cursor`.
- `GET /api/terminal/{instrument}` — full card terminal snapshot (price
  series, indicators, depth, fair value, recommendation, population,
  provenance) for one instrument.
- `GET /api/screener` — cross-sectional screener rows. Query: `preset`
  (`UNDERVALUED` | `ACCUMULATION` | `TIGHT_SUPPLY` | `HIGH_LIQUIDITY`),
  `limit`.
- `GET /api/indices` — the hosted POKE150 / POKE250 index snapshots.
- `GET /api/quotes` — compact watchlist quote rows plus the hosted indices.
  Query: `instruments` (comma-separated instrument ids).
- `GET /api/search` — the omni-search palette's card/set/era matches. Query:
  `q`.

## Politeness

Please crawl at a modest rate (a handful of requests per second at most) and
identify your user agent. `/api/*` and the `.md` twins are backstopped by a
120-requests-per-minute-per-client limit; exceeding it gets a `429` with a
`Retry-After` header, not a ban. Questions or access requests:
ryan@rocketagents.com.