# TCGGraph — complete reference for language models

Source: https://tcggraph.com
API version: 2026-08-01
Generated: 2026-09-09

## What TCGGraph is

TCGGraph is a commercial API that serves normalised trading card game data for 8 games through one schema, one API key and one rate limit. It exists so that a product supporting several card games does not need a separate integration, data model and price pipeline for each one.

REST is the primary interface and covers every capability. GraphQL is offered as a secondary interface for cases where a single round trip should return several games or several related resources with narrow field selection. Most competing card APIs are REST-only.

- REST base URL: https://api.tcggraph.com/v1
- GraphQL endpoint: https://api.tcggraph.com/graphql
- Authentication: `Authorization: Bearer <key>`. Keys are self-service and immediate.
- Versioning: date-based, pinned per key. Breaking changes never land on an existing version.

## Catalog

63,937 cards, 188,097 printings, 2,017 sets, 13 languages.

### Pokémon Trading Card Game

- Slug: `pokemon`
- GraphQL enum: `POKEMON`
- Publisher: The Pokémon Company, released 1996
- Coverage: 4,158 cards, 20,444 printings, 174 sets, 12 languages
- Formats: Standard, Expanded, Unlimited, GLC
- Price sources: Cardmarket
- How it is modelled: Every reverse holo, Trainer Gallery and secret rare is its own row with its own price series, rather than a variant flag hanging off one card record.
- Landing page: https://tcggraph.com/games/pokemon

Pokémon accounts for roughly 65% of all tracked secondary-market activity in 2026. TCGGraph indexes the complete English and Japanese card pool — including promos, Trainer Gallery subsets and every reverse-holo and secret-rare printing — and normalises attack costs, energy types, evolution chains and regulation marks so you can query thirty years of history with one consistent schema.

gameData fields for Pokémon:

- `supertype` (Enum) — Pokémon, Trainer or Energy.
- `subtypes` ([String]) — Basic, Stage 1, Stage 2, ex, V, VMAX, Tera, Supporter, Item…
- `hp` (Int) — Hit points for Pokémon cards.
- `types` ([String]) — Energy types the Pokémon belongs to.
- `evolvesFrom` (String) — The Pokémon this card evolves from.
- `attacks` ([Object]) — name, cost, convertedEnergyCost, damage and text.
- `weaknesses` ([Object]) — Type and multiplier or modifier.
- `resistances` ([Object]) — Type and damage reduction.
- `retreatCost` ([String]) — Energy required to retreat.
- `regulationMark` (String) — Rotation letter used by Standard legality.
- `nationalPokedexNumbers` ([Int]) — Pokédex entries referenced by the card.

**Does the Pokémon dataset include Japanese-only cards?** Yes. Japanese sets, promos and regional exclusives are indexed alongside English printings and linked through a shared oracleId, so you can resolve the same card across both markets in one request.

**Are attack costs machine-readable?** Every attack exposes both the raw cost array of energy symbols and a convertedEnergyCost integer, so you can filter on total cost without parsing text.

**How current is Standard legality?** Regulation marks and format legality are re-read from the upstream catalogue on every ingest, and each format that moves emits a card.legality.changed webhook carrying both sides of the change. So a rotation reaches you on the first ingest after it is published upstream, and you do not have to diff a poll to find it.

### Magic: The Gathering

- Slug: `magic-the-gathering`
- GraphQL enum: `MAGIC_THE_GATHERING`
- Publisher: Wizards of the Coast, released 1993
- Coverage: 37,111 cards, 105,638 printings, 955 sets, 11 languages
- Formats: Standard, Pioneer, Modern, Legacy, Vintage, Commander, Pauper, Brawl, Alchemy, Historic
- Price sources: Cardmarket, TCGplayer, Card Kingdom, Mana Pool
- How it is modelled: Every finish, frame effect and promo treatment is an addressable printing with its own price series, so a Showcase foil and its regular printing never share a number.
- Landing page: https://tcggraph.com/games/magic-the-gathering

Magic: The Gathering invented the trading card game and still leads the market by total dollar value. TCGGraph exposes canonical Oracle text, mana value, colour identity, type lines, keyword abilities and legality across Standard, Pioneer, Modern, Legacy, Vintage, Commander and Pauper — plus every finish, frame effect and promo treatment as an addressable printing with its own price series.

gameData fields for Magic:

- `manaCost` (String) — Mana cost in symbol notation, e.g. {2}{U}{U}.
- `manaValue` (Float) — Converted mana cost.
- `colors` ([String]) — Colours in the mana cost.
- `colorIdentity` ([String]) — Commander-legal colour identity.
- `typeLine` (String) — Full type line including supertypes and subtypes.
- `oracleText` (String) — Current Oracle rules text.
- `power` (String) — Creature power. May be a character such as *.
- `toughness` (String) — Creature toughness. May be a character such as *.
- `loyalty` (String) — Starting loyalty for planeswalkers.
- `keywords` ([String]) — Parsed keyword abilities.
- `layout` (Enum) — normal, transform, modal_dfc, split, adventure, saga…
- `finishes` ([String]) — nonfoil, foil, etched or glossy.
- `legalities` (Object) — Per-format legal, not_legal, restricted or banned.

**Is Oracle text kept up to date with rules updates?** Yes. Oracle text is reconciled against official Gatherer updates on every set release and errata cycle, and historical text is retained so you can diff wording changes over time.

**Can I query a specific printing rather than the card?** Every physical printing has its own stable printingId with its own artist, frame, finish, collector number and price series. cardId groups them under one Oracle identity.

**Are double-faced cards handled properly?** Transform, modal DFC, meld, split, flip and adventure cards expose a faces array with per-face mana cost, type line, text, power and toughness.

### One Piece Card Game

- Slug: `one-piece`
- GraphQL enum: `ONE_PIECE`
- Publisher: Bandai, released 2022
- Coverage: 1,422 cards, 5,535 printings, 69 sets, 5 languages
- Formats: Standard, Japanese Standard
- Price sources: Cardmarket
- How it is modelled: English and Japanese printings resolve to one shared identity, so a card found in either language returns the same record with both markets priced.
- Landing page: https://tcggraph.com/games/one-piece

The One Piece Card Game is the fastest-growing TCG of the decade, overtaking Magic and Yu-Gi-Oh! in tracked volume within four years of launch. TCGGraph structures every Leader, Character, Event, Stage and DON!! card with colour, cost, power, counter value, life, attribute and trigger text, and links English and Japanese printings — including alternate-art, manga-art and Special-rare treatments — to a shared identity.

gameData fields for One Piece:

- `cardType` (Enum) — LEADER, CHARACTER, EVENT, STAGE or DON.
- `colors` ([String]) — Red, Green, Blue, Purple, Black or Yellow.
- `cost` (Int) — DON!! cost to play. Null for Leaders.
- `power` (Int) — Battle power.
- `counter` (Int) — Counter value playable from hand.
- `life` (Int) — Leader life total.
- `attribute` (Enum) — Slash, Strike, Ranged, Wisdom or Special.
- `types` ([String]) — Crew and archetype traits.
- `trigger` (String) — Trigger effect text when flipped from life.

**Are Japanese and English printings linked?** Yes. Both regions resolve to the same cardId while keeping separate printings, set codes, release dates and price series.

**Do you track alternate art and manga art variants?** Every parallel, alternate-art, manga-art and Special treatment is its own printing with its own rarity, artist and market price.

### Yu-Gi-Oh! Trading Card Game

- Slug: `yugioh`
- GraphQL enum: `YUGIOH`
- Publisher: Konami, released 1999
- Coverage: 14,010 cards, 38,435 printings, 661 sets, 9 languages
- Formats: Advanced, Traditional, OCG, Master Duel, Speed Duel, GOAT
- Price sources: Cardmarket
- How it is modelled: Forbidden & Limited status is carried per format — TCG, OCG, Master Duel and Speed Duel — instead of being flattened into one ban flag that is wrong for three of them.
- Landing page: https://tcggraph.com/games/yugioh

Yu-Gi-Oh! remains one of the Big Three and is resurgent in 2026. TCGGraph structures the full card pool — Normal, Effect, Ritual, Fusion, Synchro, Xyz, Pendulum and Link monsters plus Spells and Traps — with ATK, DEF, level, rank, link rating and markers, pendulum scales, attributes, monster types and archetype membership, alongside continuously updated TCG, OCG, Master Duel and Speed Duel Forbidden & Limited lists.

gameData fields for Yu-Gi-Oh!:

- `frameType` (Enum) — normal, effect, ritual, fusion, synchro, xyz, link, pendulum, spell or trap.
- `attribute` (Enum) — DARK, LIGHT, EARTH, WATER, FIRE, WIND or DIVINE.
- `race` (String) — Monster type, or spell and trap sub-category.
- `atk` (Int) — Attack points. -1 represents ?.
- `def` (Int) — Defense points. Null for Link monsters.
- `level` (Int) — Level or Rank.
- `linkRating` (Int) — Link rating for Link monsters.
- `linkMarkers` ([String]) — Arrow directions.
- `pendulumScale` (Int) — Blue and red pendulum scale value.
- `archetypes` ([String]) — Archetype membership.
- `banlist` (Object) — Status per format: unlimited, semi_limited, limited or forbidden.

**How quickly are banlist changes reflected?** Forbidden & Limited status for TCG, OCG, Master Duel and Speed Duel is re-read on every ingest, and each list a card moves on emits its own card.legality.changed webhook. One announcement that touches several lists therefore arrives as several events, so a tracker that only cares about TCG never has to unpack the other three.

**Are OCG-only cards included?** Yes, with an availability field distinguishing OCG-only, TCG-only and worldwide releases so you can scope queries to a region.

### Disney Lorcana

- Slug: `disney-lorcana`
- GraphQL enum: `DISNEY_LORCANA`
- Publisher: Ravensburger, released 2023
- Coverage: 1,270 cards, 2,847 printings, 22 sets, 5 languages
- Formats: Core Constructed, Infinity Constructed
- Price sources: Cardmarket
- How it is modelled: Enchanted, Special and foil treatments are priced individually rather than rolled into one card-level average that describes none of them.
- Landing page: https://tcggraph.com/games/disney-lorcana

Disney Lorcana climbed to fifth place in quarterly sales in 2026 and has become the standout mainstream entrant of the decade. TCGGraph models ink cost, inkability, ink colour, lore value, strength, willpower, move cost, classifications and song abilities, and treats every Enchanted, Special and foil treatment as an individually priced printing.

gameData fields for Lorcana:

- `inkCost` (Int) — Ink required to play the card.
- `inkable` (Boolean) — Whether the card can be put into the inkwell.
- `ink` (Enum) — Amber, Amethyst, Emerald, Ruby, Sapphire or Steel.
- `lore` (Int) — Lore gained when questing.
- `strength` (Int) — Character strength.
- `willpower` (Int) — Character willpower.
- `cardType` (Enum) — CHARACTER, ACTION, ITEM, LOCATION or SONG.
- `classifications` ([String]) — Storyborn, Dreamborn, Floodborn, Hero, Villain, Sorcerer…
- `moveCost` (Int) — Ink cost to move a character to a Location.

**Are Enchanted cards separate entries?** Enchanted, Special and promotional treatments are separate printings sharing the same cardId, each with its own rarity, artist and price history.

### Star Wars: Unlimited

- Slug: `star-wars-unlimited`
- GraphQL enum: `STAR_WARS_UNLIMITED`
- Publisher: Fantasy Flight Games, released 2024
- Coverage: 1,573 cards, 5,958 printings, 7 sets, 6 languages
- Formats: Premier, Twin Suns, Draft, Sealed
- Price sources: Cardmarket
- How it is modelled: Leaders and Bases carry both faces as structured fields, so two-sided cards need no special handling in your code and no second lookup.
- Landing page: https://tcggraph.com/games/star-wars-unlimited

Star Wars: Unlimited brought Fantasy Flight's design pedigree to the trading card space and has built a durable competitive scene. TCGGraph models the aspect system — Vigilance, Command, Aggression, Cunning, Heroism and Villainy — plus arena assignment, unit cost, power and HP, upgrade attachments, uniqueness rules and the two-sided Leader and Base cards that define every deck.

gameData fields for SW: Unlimited:

- `aspects` ([String]) — Vigilance, Command, Aggression, Cunning, Heroism or Villainy.
- `arena` (Enum) — GROUND or SPACE.
- `cost` (Int) — Resource cost.
- `power` (Int) — Unit power.
- `hp` (Int) — Unit hit points.
- `cardType` (Enum) — LEADER, BASE, UNIT, EVENT or UPGRADE.
- `traits` ([String]) — Rebel, Imperial, Vehicle, Force, Trooper…
- `unique` (Boolean) — Whether the card is unique.
- `faces` ([Object]) — Front and deployed sides for Leaders.

**How are Leaders represented?** Leaders expose a faces array containing the leader side and the deployed unit side, each with its own cost, power, HP and ability text.

### Digimon Card Game

- Slug: `digimon`
- GraphQL enum: `DIGIMON`
- Publisher: Bandai, released 2020
- Coverage: 1,915 cards, 4,444 printings, 66 sets, 4 languages
- Formats: Standard, Japanese Standard
- Price sources: Cardmarket
- How it is modelled: Main, inherited and security effects are separate fields, so digivolution chains are queryable instead of being buried in one block of rules text.
- Landing page: https://tcggraph.com/games/digimon

The Digimon Card Game's 2020 reboot produced one of the most mechanically distinctive TCGs on the market. TCGGraph models play cost, digivolve costs by level and colour, DP, attribute, Digimon form and type, and separates the main effect, inherited effect and security effect into distinct fields so deckbuilders can query digivolution chains programmatically.

gameData fields for Digimon:

- `cardType` (Enum) — DIGI_EGG, DIGIMON, TAMER or OPTION.
- `colors` ([String]) — Red, Blue, Yellow, Green, Black, Purple or White.
- `level` (Int) — Level 2 to 7.
- `playCost` (Int) — Memory cost to play from hand.
- `dp` (Int) — Digimon power.
- `digivolveCosts` ([Object]) — Colour, from-level and memory cost triples.
- `attribute` (Enum) — Data, Vaccine, Virus, Free or Unknown.
- `form` (String) — Rookie, Champion, Ultimate, Mega, Armor…
- `inheritedEffect` (String) — Effect granted while in the digivolution stack.
- `securityEffect` (String) — Effect triggered when checked from security.

**Can I resolve a full digivolution line?** Yes. digivolveCosts is machine-readable, so you can walk a chain from Digi-Egg to Mega with a single recursive GraphQL query.

### Grand Archive

- Slug: `grand-archive`
- GraphQL enum: `GRAND_ARCHIVE`
- Publisher: Weebs of the Shore, released 2022
- Coverage: 2,478 cards, 4,796 printings, 63 sets, 3 languages
- Formats: Standard, Unlimited, Sealed
- Price sources: 
- How it is modelled: Both resource tracks — memory and reserve — are modelled as distinct costs, so champion progression lines can be walked programmatically rather than parsed.
- Landing page: https://tcggraph.com/games/grand-archive

Grand Archive combines anime art direction with a genuinely novel resource system built on memory and reserve costs. TCGGraph exposes both cost tracks, level, power, life, durability, speed, elemental affinity and class lineage so you can model champion progression lines directly from the API.

gameData fields for Grand Archive:

- `memoryCost` (Int) — Memory required to play.
- `reserveCost` (Int) — Reserve required to play.
- `level` (Int) — Champion level.
- `power` (Int) — Attack power.
- `life` (Int) — Health for champions and allies.
- `durability` (Int) — Weapon durability.
- `elements` ([String]) — Fire, Water, Wind, Norm, Arcane, Crux, Tera, Exia, Umbra or Luxem.
- `classes` ([String]) — Warrior, Mage, Assassin, Guardian, Tamer, Ranger, Spirit or Cleric.
- `speed` (Enum) — FAST or SLOW.

### Games on the way

- Flesh and Blood (Legend Story Studios) — Q4 2026
- Riftbound (Riot Games) — Q4 2026
- Gundam Card Game (Bandai) — Q4 2026
- Dragon Ball Fusion World (Bandai) — Q1 2027
- Union Arena (Bandai) — Q1 2027
- Sorcery: Contested Realm (Erik's Curiosa) — Q1 2027
- Altered (Equinox) — Q1 2027
- Weiß Schwarz (Bushiroad) — Q2 2027

## Core card fields

Present on every card in every game.

- `id` (String) — Globally unique, stable card identifier.
- `game` (Enum) — Which game the card belongs to.
- `name` (String) — Card name as printed.
- `set` (Object) — Set object: code, name and releasedAt.
- `collectorNumber` (String) — Number printed on the card.
- `rarity` (String) — Publisher rarity, normalised per game.
- `artist` (String) — Illustrator credit.
- `text` (String) — Primary rules text, plain-text normalised.
- `images` (Object) — small, normal and large URLs on the TCGGraph CDN, in AVIF and WebP.
- `hashes` (Object) — Perceptual hashes of the artwork — a 64-bit luma phash and a 192-bit phashColor — for matching a photo to a printing. Null until the art is processed.
- `prices` ([Object]) — Per-source, per-finish pricing, retail and buylist, with timestamps.
- `legalities` (Object) — Format legality map for the card's game.
- `externalIds` (Object) — cardmarketId and tcgplayerId, for joining to a marketplace. REST only.
- `gameData` (Object) — The game-specific payload. Typed per game in GraphQL.

## REST endpoints

- `GET /v1/games` — List every supported game with counts and metadata.
- `GET /v1/games/{slug}` — Retrieve one game, including its schema declaration.
- `GET /v1/sets` — List sets, filterable by game, series and release window.
- `GET /v1/sets/{code}` — Retrieve one set and its card list.
- `GET /v1/cards` — Query cards with cross-game and game-specific filters.
- `GET /v1/cards/{id}` — Retrieve a single card with all printings.
- `GET /v1/cards/search` — Full-text and fuzzy search across all games.
- `GET /v1/prices/{cardId}` — Current prices across every tracked marketplace.
- `GET /v1/prices/{cardId}/history` — Daily price history with range and interval.
- `POST /v1/bulk/exports` — Request a full-catalog export in JSON, NDJSON or Parquet.
- `POST /v1/webhooks` — Register a signed webhook endpoint.
- `GET /v1/webhooks` — List registered endpoints and their delivery health.
- `GET /v1/webhooks/{id}` — Retrieve one endpoint with its recent delivery attempts.
- `DELETE /v1/webhooks/{id}` — Remove an endpoint and stop its deliveries.
- `POST /v1/watches` — Watch a card for a price threshold, in one market.
- `GET /v1/watches` — List price watches and the plan's remaining allowance.
- `DELETE /v1/watches/{id}` — Stop watching a price.

Filtering uses plain query parameters. Reserved parameters are `game`, `name`, `text`,
`rarity`, `set`, `artist`, `source`, `region`, `minPrice`, `maxPrice`, `page`, `limit` and
`sort`. Any other parameter is matched against `gameData`, so `?game=pokemon&types=Fire&hp=330`
works without special syntax. `sort` accepts `name`, `price` and `released`, prefixed with
`-` to reverse. `limit` maxes out at 100.

Collection responses have the shape `{ data: Card[], meta: { page, limit, totalCount, totalPages, hasMore, priceSource } }`.

## Integration rules for coding agents

# TCGGraph

This project uses TCGGraph for trading card game data — one REST and GraphQL
API covering Pokémon, Magic: The Gathering, One Piece, Yu-Gi-Oh!, Disney Lorcana, Star Wars: Unlimited, Digimon and Grand Archive.

Full machine-readable reference: https://tcggraph.com/llms-full.txt
Every page also has a plain-text twin at <path>.md, e.g. https://tcggraph.com/docs/rest.md

## Connection

- REST base URL: https://api.tcggraph.com/v1
- GraphQL endpoint: https://api.tcggraph.com/graphql
- Auth header: `Authorization: Bearer $TCGGRAPH_KEY`
- API version is pinned per key and overridable with the `TCGGraph-Version` header.
  Current version: 2026-08-01

## Rules

- Never put TCGGRAPH_KEY in client-side code. Proxy through a server route.
- Never invent endpoints or fields. Check the reference above; if it is not
  there, say so rather than guessing.
- List responses are `{ data: [...], meta: {...} }`. Pagination lives in meta.
- Use `/v1/cards` with a `name` filter for lookups by name, and the other
  filters to narrow by set, rarity or game. One page returns up to 100 cards and
  costs the same as returning one, so page rather than fetching ids in a loop.
- Prices are per source, per list type (retail or buylist) and per finish, each
  with its own currency and timestamp. Never convert between currencies and
  never sum across sources.
- When filtering or sorting by price, pass `source`. The bounds are in that
  source's currency: `source=cardmarket&minPrice=50` means €50, not $50.
- Only Magic carries more than one price source. Every other game resolves
  through Cardmarket, and Grand Archive has no prices yet, so do not assume a
  `tcgplayer` row exists on a card outside Magic.
- Card images come in small, normal and large. Always set explicit dimensions —
  cards are 5:7.
- `hashes` carries a `phash` and `phashColor` per printing for matching a
  photo against the catalogue. It is null until the artwork has been processed,
  so treat a missing hash as "not ready" rather than "no match".

## Errors worth handling explicitly

- `402 no_active_plan` — the account has no plan. Show an actionable message.
- `402 balance_empty` — the prepaid balance will not cover the call.
- `429 rate_limited` — honour Retry-After. Do not retry in a tight loop.


Worked prompts for common integrations: https://tcggraph.com/vibecode

## Prices

Every card carries at least two quotes on `prices[]`: `tcgplayer` (region `NA`, quoted in USD) and `cardmarket` (region `EU`, quoted in EUR). Neither is converted from the other; both are the marketplace's own numbers in the marketplace's own currency. European print runs and distribution differ from American ones, so the two genuinely disagree, often by double digits and in both directions.

The Cardmarket row carries additional fields: `trend` (Cardmarket's own smoothed price, and what European sellers anchor to) and `avg1`, `avg7` and `avg30` (rolling means). `market` repeats `trend` where the marketplace publishes one and falls back to the plain average otherwise, so read `trend` directly when the difference matters.

`?source=cardmarket` or `?region=EU` selects which quote price filters and the price sort read from. Bounds are in that source's currency, so `source=cardmarket&minPrice=50` means €50. The response echoes the decision as `meta.priceSource`. In GraphQL the same control is `filter: { source: CARDMARKET }`.

Condition ladders differ: Cardmarket grades MT, NM, EX, GD, LP, PL, PO; TCGplayer grades NM, LP, MP, HP, DMG. `LP` exists on both ladders but at different positions, so mapping them by string equality is wrong. Each quote keeps its own marketplace's grade.

Full detail: https://tcggraph.com/docs/prices and https://tcggraph.com/cardmarket.

## Card recognition

Recognition is a second, separately metered product: an image goes in and a printing comes out. It returns which set, collector number, language, finish and edition was matched — not merely a card name — with the full catalog record and both price feeds attached, so identification and pricing are one operation and one charge.

- **Live scanning** (WebSocket): Hold the socket open, push frames, take matches as they resolve. Intake desks, buylist kiosks, phone cameras, anything with a continuous view of cards moving past.
- **Single photo** (HTTPS): POST an image, get the card back in one round trip. Photo uploads, server-side backfills, listing tools, anything where the image already exists.

- Photo endpoint: `POST https://api.tcggraph.com/v1/scan`
- Live socket: `wss://api.tcggraph.com/v1/scan`
- Parameters (identical across both transports): `image`, `games`, `minConfidence` (default 0.90, floored at 0.50, capped at 0.99).
- The socket takes a single-use ticket rather than the key: `POST /v1/scan/tickets` with the key, then connect to `/scan?ticket=…` within sixty seconds. Expect to reconnect; the connection is bounded by a function duration and reconnecting is never billed.

Match fields:

- `matches[].confidence` (Float) — 0 to 1. Above your threshold the match is returned and billed; below it the frame is unresolved, which tells you where the card was and why it failed, and costs nothing.
- `matches[].billed` (Boolean) — Whether this match consumed a scan. Sum it if you want to reconcile your own counter against ours.
- `matches[].box` (Object) — Normalised x, y, width and height of the card inside the frame, for drawing an overlay without a second pass.
- `matches[].card` (Card) — The whole catalog record — the identical object /v1/cards returns, including images, legalities and game-specific fields.
- `matches[].card.prices` ([Price]) — Cardmarket in EUR and TCGplayer in USD, on the match, in the same response. No second request and no second charge.
- `matches[].printingResolved` (Boolean) — True when the artwork belongs to exactly one printing, so the set, number and finish on the card record are the matched ones. False when reprints or finishes share the artwork: the card is identified, and which of its printings it is comes from alternatives.
- `matches[].alternatives` ([Object]) — When the printing is unresolved, the other printings sharing the artwork — one of them is the card in front of you. When it is resolved, ranked runners-up for a confirm step. Carried on a billed match only: an unresolved frame reports how many candidates remained, not which.
- `latencyMs` (Int) — Server-side time from frame received to match emitted. Excludes network transit, so you can tell our latency from your connection's.
- `scans` (Object) — Billed count for this call and the balance left on the period.

An unresolved frame is a first-class response, not an error: it returns the box, a `reason` from `blurred`, `glare`, `cropped`, `occluded`, `ambiguous` or `not_in_catalog`, and how many candidates remained — but not which, since identification is what a billed match is for. `scans.billed` is 0. Nothing is charged for a card we will not commit to.

Matching is on artwork, and 47,209 of 187,294 printings share theirs with another. `matches[].printingResolved` says which case you are in: true means the set, number and finish on the card record are the matched ones; false means the card is identified and the printing is not, with the tied printings in `alternatives`. Where different cards share artwork — ten groups in the catalog — the frame refuses as `ambiguous` and costs nothing.

### Scan pricing

Metered in scans, where one scan is one matched card and a frame is one card. Scans do not draw on data credits and data credits do not draw on scans. The same printing under a lens bills once every 20 seconds rather than once per frame.

- **Recognition Starter** — $29/month for 6,000 matched cards ($0.0048 each), 600 a day, overage $0.008 per scan. A collection app, a single intake desk, a listing tool finding its feet.
- **Recognition Growth** — $89/month for 25,000 matched cards ($0.0036 each), 2,500 a day, overage $0.005 per scan. A shop running intake most days, or an app with real users scanning.
- **Recognition Scale** — $249/month for 100,000 matched cards ($0.0025 each), 10,000 a day, overage $0.0035 per scan. Bulk operations, marketplaces, and apps whose users scan all day.
- **No plan** — $0.012 per matched card, drawn from the prepaid balance, no monthly fee and no minimum.

The plans differ only in volume and price per scan. Concurrency is not sold: a socket sending no frames for 45 seconds is closed, and live sessions are capped per account only as a flood guard (Starter 30, Growth 125, Scale 500, 5 pay-as-you-go). An app whose end users each open a socket while scanning is the expected shape, not an upgrade trigger.

### Per-game recognition notes

#### Pokémon Trading Card Game

The same artwork ships as three different products, and only one of them is worth anything.

Fields a match is decided on:
- Collector number — The 6/165 in the corner pins the set position even when the symbol is obscured.
- Finish — Holo, reverse holo and non-holo are separate products at separate prices.
- Set symbol — Disambiguates reprints that share both art and number across sets.
- Language — Japanese and English printings of the same art are different SKUs entirely.
- Regulation mark — The letter in the bottom corner dates the print run and settles Standard legality.

Where naive scanners fail:
- Reverse holos read as holos: The illustration is identical and the pattern sits outside the art box, so a crop that centres the artwork loses the only visible difference. Reverse holos usually trade below the holo and sometimes above it, so the error runs both ways.
- Promo stamps: Prerelease, Staff and league promos reuse an existing card's art with a stamp added. The stamp is the entire difference and it is the part of the card most likely to be under a sleeve seam.
- WOTC-era editions: Base Set cards are separated by a 1st Edition stamp and by whether a drop shadow sits beside the art box. The gap between shadowless and unlimited is several hundred dollars on a Charizard.

Landing page: https://tcggraph.com/recognition/pokemon

#### Magic: The Gathering

Thirty years of reprints means one card name maps to eighty different products.

Fields a match is decided on:
- Collector number and set code — Since 2018 the bottom-left line is a unique product identifier.
- Frame treatment — Borderless, extended, showcase and retro are separate printings at separate prices.
- Foiling — Non-foil, foil and etched foil diverge by multiples on the same card.
- Copyright line — The primary discriminator for pre-2018 printings with no collector number.
- Language — Eleven printed languages, and Japanese alternate-art printings carry their own premium.

Where naive scanners fail:
- Reprints that share art: Core-set reprints often reuse the illustration exactly. The set symbol and the copyright year are the only visible difference, and the price gap between a 1997 and a 2021 printing of the same card can be two orders of magnitude.
- Five printings, one booster: A mythic from a recent set can exist as regular, foil, extended art, borderless and showcase, all pulled from the same box. Matching on the illustration alone cannot distinguish four of the five.
- Old-border edge cases: Alpha is separated from Beta by corner radius and from Unlimited by border colour. These are the most valuable cards in the game and the distinction is geometric rather than textual.

Landing page: https://tcggraph.com/recognition/magic-the-gathering

#### One Piece Card Game

The alternate art is worth ten times the base card and shares its number.

Fields a match is decided on:
- Card number — The OP07-119 style code fixes the set and position.
- Treatment — Base, alternate art and manga rare share a number and diverge on price.
- Language — Japanese and English releases are separately numbered and separately priced.
- Rarity mark — Leader, SR and SEC change what the parallel is worth.

Where naive scanners fail:
- Alternate art shares the number: The card code is identical between base and parallel, so any matcher keyed on the printed number returns the cheaper card and understates the value by a factor of ten or more.
- Manga rares: The illustration is replaced entirely with manga panel art, which means the same card looks nothing like its base printing. Matching on art alone tends to fail rather than mis-match, which is safer but still a miss.
- Japanese-first releases: A set is Japanese for months before it is English. Treating language as cosmetic means pricing a Japanese card against an English market that has not opened yet.

Landing page: https://tcggraph.com/recognition/one-piece

#### Yu-Gi-Oh! Trading Card Game

The card is not the product. The rarity is.

Fields a match is decided on:
- Set code — The bottom-right code fixes set and position, and from there the rarity.
- Rarity treatment — Nine or more rarities of one card, from cents to thousands of dollars.
- Edition text — 1st Edition versus Unlimited, printed under the artwork.
- Passcode — Identifies the card for rules purposes, and only the card.
- Region — EN, EU, DE, FR, IT, PT, JP and Asian-English print runs are distinct products.

Where naive scanners fail:
- Passcode is not a product id: Every printing of a card shares its passcode. Using it as the key returns a card that is right in every respect except the one that determines the price.
- Rarity lives in the foiling: Secret, Ultimate and Ghost Rare differ in how the name and artwork are treated rather than in layout. Under flat light two of them can look the same, which is why the set code is read first and the treatment confirms rather than decides.
- Asian-English printings: Visually near-identical to the English release and priced entirely differently. The region letters in the set code are the only reliable tell.

Landing page: https://tcggraph.com/recognition/yugioh

#### Disney Lorcana

Enchanted variants hide behind ordinary card numbers.

Fields a match is decided on:
- Card number and total — A number above the set total marks an enchanted variant.
- Finish — Foil and non-foil are separate printings.
- Ink colour — Confirms the card against sets that reuse character names.
- Language — Six printed languages with independent European pricing.

Where naive scanners fail:
- Enchanted numbering: Enchanted cards are numbered past the set total — 205/204 and up. Any tool that assumes the number cannot exceed the total drops the most valuable cards in the game onto their base printing.
- Character name reuse: The same character appears across sets as different cards. The name is not unique, so the set and number carry the identification.

Landing page: https://tcggraph.com/recognition/disney-lorcana

#### Star Wars: Unlimited

Hyperspace and showcase variants, plus leaders that are printed on both sides.

Fields a match is decided on:
- Card number — Locates the card within the set.
- Variant treatment — Standard, hyperspace and showcase share a number and differ in price.
- Foiling — Foil runs of each variant are separate printings.
- Card face — Leaders are double-sided and may present either side.

Where naive scanners fail:
- Hyperspace shares the number: The variant is a framing change, not a renumbering, so the printed number cannot distinguish it from the standard printing.
- Double-sided leaders: A leader photographed on its back face is unrecognisable to anything keyed on the front. It is a common intake error because the two faces look like two different cards.

Landing page: https://tcggraph.com/recognition/star-wars-unlimited

#### Digimon Card Game

Alternate art parallels with the same card number, across four languages.

Fields a match is decided on:
- Card number — The BT16-045 style code fixes set and position.
- Parallel treatment — Alternate art shares the number and multiplies the price.
- Language — Four printed languages on separate release schedules.
- Promo stamp — Pre-release and tournament promos are separate products.

Where naive scanners fail:
- Alternate art shares the code: As with One Piece, the printed code does not change between base and parallel, so it cannot be the key.
- Stamped promos: A stamp in the corner is the only difference from the base card, and it is often the part of the card a sleeve or a thumb covers.

Landing page: https://tcggraph.com/recognition/digimon

#### Grand Archive

A small catalog, and almost all of its value in foil and alternate treatments.

Fields a match is decided on:
- Card number — Fixes set and position in a small, consistently laid out catalog.
- Treatment — Foil, alternate art and promo printings share a number.
- Edition — Early print runs are separately priced.

Where naive scanners fail:
- Thin markets move fast: Small print runs mean a price from last week can be badly wrong. The match carries a current quote rather than relying on your cache.

Landing page: https://tcggraph.com/recognition/grand-archive

### Recognition FAQ

**How fast is a scan?** Server-side, from the frame arriving to the match leaving, the median is 38 ms and the 99th percentile is 140 ms on single-card 1080p frames. Your network is on top of that, which is the reason the live mode is a socket: it pays connection and TLS setup once for a whole session instead of once per card. In practice an operator working a stack sees the card resolve before they have finished putting it down.

**Why is recognition priced separately from the data API?** Because it is a different kind of work with a different cost, and because sharing one meter would make the two products interfere. If scans came out of your data credits, a heavy intake morning would quietly starve the repricer that runs overnight, and you would not be able to tell from your bill which product was expensive. Scans have their own allowance, their own overage and their own plans, and the two counters are reported separately.

**Do I need a data plan to use recognition?** No. A recognition plan stands on its own, and the full card object comes back on the match, so a scanning product can run without ever calling the catalog directly. Most people end up wanting both — recognition to get cards in, the data API to keep prices fresh afterwards — but neither requires the other.

**What happens when a card cannot be identified?** You get an answer and you are not billed. The response comes back below the confidence threshold with the ranked candidates and a reason — too blurred, card cropped, set symbol not visible — so your interface can ask for a better shot rather than showing a spinner. We would rather not charge for our own uncertainty, and we would much rather not return a confident wrong answer, because a mis-identified card in someone's inventory costs them more than a retry.

**How is a scan counted?** One matched card is one scan, and a frame is one card. A frame we cannot place is zero, and so is a rejected or malformed one. Every match carries a billed flag and the response carries the running count, so you can reconcile against your own numbers without trusting ours. The same printing held under a lens is billed once every 20 seconds rather than once per frame, so a card sitting still at ten frames a second is one scan and not two hundred.

**We are putting scanning in our app. Do we need a socket per user?** You need one while a user is actually scanning, and none the rest of the time — and no, that is not what you are buying. Concurrency is not licensed here and plans do not sell you cameras: they differ in volume and price per scan, nothing else. A socket that sends no frames for 45 seconds is closed, so holding connections open requires scanning on them, and scanning is what is billed. The per-account ceiling that remains is a flood guard set well above any real workload. Open a socket when a user points a camera at a card, let it close when they stop, and the meter takes care of the rest.

**Can I scan without committing to a monthly plan?** Yes. Scans can be drawn straight from your prepaid balance at $0.012 per matched card, with no monthly fee and no minimum. Somebody digitising one collection over a weekend should not have to buy a month. Once you are scanning enough that a plan is cheaper, the plan is cheaper — Recognition Starter overtakes pay-as-you-go at about 2,400 scans a month.

**Are the prices in the response the same ones the data API returns?** The same objects, from the same source, at the same freshness — Cardmarket in EUR and TCGplayer in USD on the printing that was matched. Identification and pricing are one operation here and one charge. Elsewhere they are usually two metered calls, which means finding out what a scanned card is worth costs roughly double what the sticker price suggests.

**Can it read graded slabs?** On Recognition Growth and above, yes. The label is read alongside the card, so the match carries the grading company, the grade and the certification number as well as the card itself. That is enough to sort a mixed pile without handling anything twice.

**Does it work on cards I have not carried before, or on my own products?** Recognition covers the same eight games and the same printings as the catalog, so if a card is in the API it is matchable. Private catalog matching is available on Recognition Scale for operators who need their own inventory, sealed products or non-TCG collectibles recognised alongside ours.

**What image quality do you need?** A phone camera in ordinary indoor light is enough. The card should be fully in frame with the corners visible, roughly flat, and not lit so hard that a foil blows out — glare across a set symbol is the most common reason a frame comes back unresolved. There is no minimum resolution to hit; the live socket downsamples frames on the way in, so sending 4K stills wastes your bandwidth rather than improving the match.

**What about sleeved cards, or cards in a binder?** Sleeves are fine unless the seam sits across a set symbol or a promo stamp, which is worth knowing when you design your capture step. Cards in a binder scan perfectly well through the pocket, one pocket at a time — a frame is one card today, so a nine-pocket page is nine frames rather than one. That costs the same, since scans are counted per matched card, and it is faster than it sounds over the socket. Locating several cards in one image is on the way.

**How do I pay for it?** The same way as everything else here: a prepaid balance topped up by card, with the plan fee drawn from it on renewal. Recognition appears as its own line so you can see what scanning costs you separately from data. Nothing recurring is created unless you switch on automatic top-ups.

## Errors

- `400 invalid_request` — A parameter failed validation. The response names the offending field.
- `401 unauthenticated` — Missing or malformed API key.
- `402 no_active_plan` — The account has no plan attached. Choose one to open the API.
- `402 balance_empty` — The account balance will not cover this call. Top up to resume.
- `403 forbidden` — The key is valid but the plan does not include this resource.
- `404 not_found` — No card, set or game matches the identifier.
- `409 conflict` — The webhook or export already exists.
- `422 unprocessable_query` — The GraphQL query exceeded depth or complexity limits.
- `429 rate_limited` — Quota exhausted. Check the Retry-After header.
- `500 internal_error` — Something broke on our side. It is already paging someone.

Error bodies are `{ error: { code, message, details? } }`. Retry 429 and 5xx honouring `Retry-After`; never retry 400, 401, 403 or 404.

## Pricing

Metering is credit-based rather than per-request, so batching is rewarded. Credits reset monthly. Billing is prepaid: the account holds a USD balance funded by card top-ups, and the plan fee is drawn from it on each renewal date. Overage past the monthly allowance is drawn from the same balance continuously rather than invoiced at month end, priced above the plan's own rate and capped at the plan price. If the balance runs short the plan lapses and the API returns 402 until it is topped up. Automatic top-ups are opt-in. There is no free tier.

- Card lookup by id: 1 credits (REST or GraphQL, any game)
- Search or filter: 2 credits (Per page of up to 100 results)
- Card with price history: 3 credits (Includes the full daily series)
- Set or catalog listing: 1 credits (Sets, formats, rarities)
- Image delivery: free (Never metered, on any plan)
- Cached response (304): free (Send If-None-Match and pay nothing)
- Webhook delivery: free (Never metered; price watches are capped per plan instead)

### Starter — $19/month or $190/year

For a first production app or a small store. 25,000 credits per month (~12,500 searches), 60 req/min, overage $12 per 10,000.

- All 8 games, full card pool
- REST and GraphQL
- Four price sources, retail and buylist
- Unmetered image CDN
- Signed webhooks, deliveries never metered
- 500 price watches
- Daily price snapshots, kept in full
- Commercial use licence
- Email support, one business day

### Growth — $59/month or $590/year

For established apps and shops repricing inventory daily. 150,000 credits per month (~75,000 searches), 300 req/min, overage $6 per 10,000.

- Everything in Starter
- 6x the credits, 5x the rate limit
- 25,000 price watches
- Overage at half the Starter rate
- 99.95% uptime SLA
- Priority support

### Scale — $149/month or $1490/year

For marketplaces and market-data businesses. 750,000 credits per month (~375,000 searches), 1,000 req/min, overage $3 per 10,000.

- Everything in Growth
- 5x the Growth credits, 1,000 req/min
- 100,000 price watches
- Our lowest overage rate
- Redistribution licence available
- Shared Slack channel

Images and 304 responses are never metered. Failed requests are not billed.

## Pricing FAQ

**What is a credit?** One billable unit of work. A card lookup costs 1 credit, a filtered search costs 2 per page of up to 100 results, and a card returned with its full daily price history costs 3. You are charged for what a query costs to serve rather than for how many HTTP calls you happened to make, which is why a single request returning 100 cards is far cheaper here than on a per-request plan.

**How does that compare to a requests-per-month plan?** At 2 credits per search, Starter is about 12,500 searches a month for $19, and Growth is about 75,000 for $59. Batch-heavy workloads come out considerably cheaper, because pulling 100 cards in one page costs the same 2 credits as pulling 10.

**Is there a free tier?** No. Running a card index with four price sources behind it costs real money every day, and a free tier would be paid for by the people on Starter. We would rather keep the entry plan at $19 than subsidise scrapers. Every plan is month to month, so the smallest commitment you can make is one month of Starter.

**Do images cost credits?** No. Card artwork is served from a separate CDN and is never metered, on any plan. Neither are cached responses: send an If-None-Match header and a 304 costs nothing.

**What happens when I run out of credits?** Requests keep succeeding and overage is drawn from your balance. Overage is priced above the plan's own rate, and it stops once it reaches your plan price, so the worst a month can cost is double what you signed up for. That pricing is deliberate: overage should cover a busy week, not be a cheaper way to stay on a small plan. If you pay it two months running, the next tier up will cost you less. You can set a hard cap instead if you would rather fail than spend.

**Why is there a daily cap as well as a monthly one?** Because a monthly allowance on its own does not stop a loop with a bug in it. The daily cap is a tenth of the monthly allowance on every plan, which is far more than normal traffic needs and low enough that a runaway job costs you a day rather than a month. Hitting it returns 429 until midnight UTC.

**Do unused credits roll over?** Credits reset monthly on monthly plans. Annual plans draw from a yearly pool instead, so a quiet January funds a busy December.

**Can I use this commercially?** Every plan includes a commercial use licence. Reselling the raw dataset, or exposing it as a competing API, needs a separate redistribution licence.

**Is there a discount for open source?** Yes. Public, non-commercial open-source projects get 50% off any plan for as long as the project stays open. Email us a link to the repository.

**Can I change plans later?** Any time, in both directions, prorated to the day. Upgrades take effect immediately; downgrades apply at the next billing date so you keep the credits you already paid for.

**How does billing work?** Prepaid rather than subscription. You keep a balance, top it up whenever you like — one month or twelve — and the plan fee is drawn from it on each renewal date, along with any overage. Nothing recurring is set up behind your back: a card payment is one-off unless you switch on automatic top-ups yourself. If the balance will not cover the next draw the plan simply lapses and your keys stop until you top up. There is no invoice you owe, no debt and no collections.

**How do I pay?** By card: Visa, Mastercard and American Express, plus Apple Pay and Link, all of which come with a VAT invoice and can be saved to top up automatically. We only offer methods that can be charged again later, so you are never in the position of having paid with something that cannot keep your balance topped up — which is why single-use bank redirects like iDEAL are not on the list. Amounts are quoted in USD.

**What if I top up more than I need?** It stays on your balance and funds later months. You can switch plans at any time and the difference is prorated against the balance rather than invoiced. If you stop using the API, email us and we will send the remainder back to an address you nominate.

**Do I need to keep a card on file?** Only if you want automatic top-ups. A payment is one-off by default and nothing recurring is set up unless you ask for it. If you do save a card you can set a trigger balance so a long job never stops midway, and you can remove the card at any time from the billing page.

## How TCGGraph compares to alternatives

### vs Scryfall (Scryfall LLC, Magic: The Gathering only)

Scryfall is the best Magic API there is, and it is free. TCGGraph is what you reach for when your app also needs Pokémon, One Piece or Lorcana behind one key.

What Scryfall does well:
- Free, generous and genuinely excellent for Magic. No key required.
- The best full-text search syntax in the hobby, and a huge community around it.
- Complete Oracle text, every printing, every language, plus bulk data dumps.
- Run by people who care deeply about Magic data quality.

Where TCGGraph differs:
- Scryfall covers Magic and only Magic, by design. If your product is Magic-only, that is not a limitation.
- TCGGraph carries eight games behind one schema, so adding a second game costs you an enum value rather than a second integration.
- TCGGraph normalises prices across Cardmarket, TCGplayer, Card Kingdom and Manapool with daily history; Scryfall surfaces marketplace links and current prices.
- TCGGraph offers signed webhooks for set releases, spoilers and legality changes, so you do not have to poll.

When to use Scryfall instead: If you are building a Magic-only product, use Scryfall. It is free, the data is excellent and the search syntax is unmatched. Come back when you add a second game, a second currency, or a price you need to put in front of a paying customer.

### vs Pokémon TCG API (pokemontcg.io, Pokémon only)

pokemontcg.io is the community standard for Pokémon card data. TCGGraph adds seven more games, Cardmarket and TCGplayer prices on the same card, and an uptime SLA.

What Pokémon TCG API does well:
- Free, well documented and the default choice for Pokémon projects for years.
- Complete English card pool with clean attack, weakness and resistance modelling.
- Simple REST design that is easy to learn in an afternoon.
- A large ecosystem of community libraries built on top of it.

Where TCGGraph differs:
- Coverage stops at Pokémon. TCGGraph carries the same Pokémon data plus Magic, One Piece, Yu-Gi-Oh!, Lorcana, Star Wars: Unlimited, Digimon and Grand Archive.
- We serve Japanese printings linked to their English counterparts through a shared card identity.
- Prices come from Cardmarket, TCGplayer, Card Kingdom and Manapool with daily history rather than a single source snapshot.
- We publish an uptime SLA on paid plans and a public status page.

When to use Pokémon TCG API instead: If you are building something Pokémon-only and free is the deciding factor, pokemontcg.io is a fine choice and has served the community well for a long time. Consider TCGGraph when you need a second game, Japanese-to-English card linking, deeper price history, or an availability guarantee you can point a customer at.

### vs YGOPRODeck API (YGOPRODeck, Yu-Gi-Oh! only)

YGOPRODeck is the reference Yu-Gi-Oh! card API and it is free. TCGGraph matches its Yu-Gi-Oh! coverage and adds seven more games, GraphQL and legality webhooks behind one key.

What YGOPRODeck API does well:
- Free and comprehensive, with the full Yu-Gi-Oh! card pool including OCG-only cards.
- Ban list data across TCG, OCG and Master Duel, kept current.
- Rich archetype metadata that is genuinely hard to reproduce.
- A large, active community and a deck builder people actually use.

Where TCGGraph differs:
- Coverage stops at Yu-Gi-Oh!. TCGGraph keeps the same modelling and adds seven more games.
- Legality changes emit signed webhooks instead of requiring you to diff a poll.
- Prices are normalised across Cardmarket, TCGplayer, Card Kingdom and Manapool with daily history.
- GraphQL lets a deck view fetch cards across several games in one round trip.

When to use YGOPRODeck API instead: For a Yu-Gi-Oh!-only deck builder or ban list tracker, YGOPRODeck is free, complete and well maintained — use it. TCGGraph makes sense once you need a second game, per-format ban status rather than a single flag, or webhooks instead of polling.

### vs TCGplayer API (TCGplayer, Marketplace catalog and pricing)

The TCGplayer API needs partner approval and models products, not cards. TCGGraph gives you game-native card data, Cardmarket and TCGplayer prices, and a key you create yourself.

What TCGplayer API does well:
- Authoritative pricing for the largest US card marketplace.
- Deep SKU-level data covering condition, printing and language.
- Direct cart and affiliate integration if commerce is your business model.
- Enormous catalog breadth across games and sealed product.

Where TCGGraph differs:
- TCGplayer requires partner approval, which takes time and is not granted to every applicant. TCGGraph keys are self-service and immediate.
- It models marketplace products, not game cards. There is no HP, no mana cost, no ban list — you would join that data yourself.
- It prices one market. TCGplayer is North America, so a European seller or a European collection tracker gets numbers from a marketplace their users cannot buy on. TCGGraph carries the Cardmarket quote in EUR on the same card.
- TCGGraph normalises prices across Cardmarket, TCGplayer, Card Kingdom and Manapool, so you are not exposed to a single market's quirks.
- We keep game-native fields as first-class data, which is what a deck builder or collection tracker actually needs.

When to use TCGplayer API instead: If you are building commerce — carts, affiliate links, seller tooling — go direct to TCGplayer. Their pricing is authoritative for the US market and the affiliate economics only work first-party. TCGGraph is for products that need to understand cards as game objects, not as SKUs.

### vs Building it yourself (You, at 2am, Whatever you have time to maintain)

An honest look at what it costs to scrape and normalise trading card game data in-house: the initial build, the ongoing maintenance, and when doing it yourself is genuinely the right call.

What Building it yourself does well:
- Zero vendor cost and no rate limits beyond what the sources impose.
- Total control over schema, storage and refresh cadence.
- No dependency on a company that could change its pricing or shut down.
- For one game with modest needs, a weekend of work can genuinely be enough.

Where TCGGraph differs:
- Each game is a separate integration with its own quirks, and publishers change their card lists without notice.
- Set releases and spoiler seasons are the moments your scraper breaks and also the moments your users care most.
- Price history cannot be backfilled. If you start collecting today, you have no history for a year.
- Reconciling the same card across languages and printings is the genuinely hard part, and it never stops needing attention.

When to use Building it yourself instead: If you need one game, shallow data and have no deadline, build it. Scryfall and pokemontcg.io already solve most of that for free. Buy instead when you need several games, when price history matters, or when the maintenance would land on someone whose time is worth more than the subscription.

## Changelog

### 2026-08-31 — Cardmarket prices, in euros, on every card

Every card in every game now carries a European quote next to the American one, in the currency each marketplace actually trades in. No conversion, no blending.

- added: A cardmarket row on prices[] for all eight games, quoted in EUR with trend, avg1, avg7 and avg30, and foil quoted separately.
- added: region on every price, so you can select a market without naming a vendor.
- added: ?source=cardmarket and ?region=EU on /v1/cards. Price bounds and the price sort read the selected market, and meta.priceSource echoes the choice back.
- added: PriceSource and PriceRegion enums in GraphQL, plus a source field on CardFilter.
- improved: Localised European printings resolve to their own records rather than collapsing into the English card.

### 2026-08-28 — Grand Archive joins the catalog

Grand Archive is the eighth live game, with element, class and speed modelling plus the full Dawn of Ashes and Mortal Ambition card pool.

- added: Grand Archive cards and sets under game=grand-archive. Catalog only for now; pricing is not live.
- added: gameData fields for memoryCost, reserveCost, level, durability, elements, classes and speed.
- added: GRAND_ARCHIVE added to the GraphQL Game enum.
- improved: Champion levels are exposed on gameData so progression lines can be walked.

### 2026-08-14 — Credit metering replaces request quotas

Billing now meters the work a query performs rather than the number of HTTP calls, so batching a hundred cards into one page costs the same as batching ten.

- added: TCGGraph-Credits-Limit, -Remaining, -Reset and TCGGraph-Cost response headers.
- added: Hard spend caps, enforced per account. Ask us to set one until the dashboard control ships.
- improved: Conditional requests returning 304 are no longer billed.
- deprecated: X-Daily-Quota headers. Removed in the next API version.

### 2026-07-30 — Star Wars: Unlimited and Digimon

Two games added in one release, both with full aspect and colour modelling and daily prices from launch.

- added: Star Wars: Unlimited under game=star-wars-unlimited.
- added: Digimon Card Game under game=digimon.
- added: Arena and aspect filters for Star Wars: Unlimited.
- improved: Digimon inherited effects are exposed as a distinct field.

### 2026-07-12 — Four price sources on Magic

Cardmarket, Card Kingdom and Mana Pool now sit alongside TCGplayer on Magic, each normalised by finish and surfaced separately rather than averaged.

- added: Per-source price series on the prices array.
- added: Card Kingdom buylist beside retail, as a distinct list type.
- fixed: Foil and non-foil series no longer merge on Lorcana enchanted cards.

### 2026-06-02 — Disney Lorcana and One Piece

Lorcana ships with ink, lore and inkable modelling; One Piece with leader, counter and life mechanics across both English and Japanese printings.

- added: Disney Lorcana under game=disney-lorcana.
- added: One Piece Card Game under game=one-piece.
- improved: Japanese One Piece printings link to English via a shared cardId.

## Contact

- General: hello@tcggraph.com
- Legal: legal@tcggraph.com
- Privacy: privacy@tcggraph.com
- Security: security@tcggraph.com