# Official-API connectors

Sources with a public, documented API (engine priority `api`, optional `feed` fallback). They provide
the **catalog backbone** (canonical printings with deterministic identifiers) plus **price-guide
observations** — never transactions.

| id | source | catalog | prices | full run | notes |
|---|---|---|---|---|---|
| `scryfall` | Scryfall bulk `default_cards` (JSONL gz, daily) | ~110k printings × finishes | USD/EUR market (TCGplayer/Cardmarket aggregates), dated with the bulk `updated_at` | 1 listing call + 1 streamed 78 MB download | cursor `{updatedAt}` skips unchanged bulks; `lookup()` for scryfall.com card URLs |
| `pokemontcg` | api.pokemontcg.io v2 | ~19k cards / 174 sets (× TCGplayer variants) | TCGplayer USD low/mid/high/market per variant + Cardmarket EUR aggregates, each with its own `updatedAt` | 1 sets call + ~190 card pages at ≤28 req/min ≈ 8 min | API is intermittently 5xx → 5 retries w/ backoff, then GitHub mirror (catalog only) |
| `ygoprodeck` | db.ygoprodeck.com v7 `cardinfo.php?misc=yes` | ~14.5k cards / ~44k printings | per-printing `set_price` (USD, `guide_value`) + card-level tcgplayer/cardmarket/ebay/amazon/coolstuffinc | ONE ~21 MB request | no price timestamp → dated at fetch, confidence 0.7 |

## Identifiers for entity resolution

- Scryfall: `scryfall_id` (printing, unique) · `oracle_id` (card concept) · `tcgplayer_id` · `cardmarket_id` · `mtgo_id` · `multiverse_id` · `finish` (nonfoil/foil/etched). Canonical printing key ≈ `magic_the_gathering|<setCode>|<number>|<lang>|<variant>`.
- Pokémon: `pokemontcg_id` (e.g. `base1-4`) · `pokemontcg_set_id` · `tcgplayer_url`. Variants: null / Holo / Reverse Holo / 1st Edition / 1st Edition Holo (from TCGplayer price keys). Canonical key ≈ `pokemon|<setCode>|<number>|<variant>`.
- Yu-Gi-Oh!: `ygo_id` (passcode) · `konami_id` · `set_code` (e.g. `LOB-EN001`; same code may exist in several rarities → distinct printings). Canonical key ≈ `yugioh|<set_code>|<rarity>`.

## Tooling

- `pnpm tsx connectors/api/_lib/capture.ts` — refresh fixtures from live responses (small, trimmed).
- `pnpm tsx connectors/api/_lib/smoke.ts [id…]` — live probe crawl (limit 5) through the real router/context.
- Tests: `pnpm --filter @rareindex/source-connectors run test` (fixture suite + targeted assertions).