# TCGGraph — complete reference for language models

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

## 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

76,500 cards, 215,200 printings, 1,698 sets, 13 languages.

### Pokémon Trading Card Game

- Slug: `pokemon`
- GraphQL enum: `POKEMON`
- Publisher: The Pokémon Company, released 1996
- Coverage: 19,840 cards, 41,200 printings, 168 sets, 12 languages
- Formats: Standard, Expanded, Unlimited, GLC
- Price sources: TCGplayer, Cardmarket, eBay sold
- Upstream data: Pokémon TCG API, publisher set lists and TCGplayer
- 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 refreshed within minutes of a rotation or ban announcement, and every change emits a card.legality.changed webhook.

### Magic: The Gathering

- Slug: `magic-the-gathering`
- GraphQL enum: `MAGIC_THE_GATHERING`
- Publisher: Wizards of the Coast, released 1993
- Coverage: 32,460 cards, 108,500 printings, 812 sets, 11 languages
- Formats: Standard, Pioneer, Modern, Legacy, Vintage, Commander, Pauper, Brawl, Alchemy, Historic
- Price sources: TCGplayer, Cardmarket, Card Kingdom, eBay sold
- Upstream data: Scryfall bulk data, Gatherer Oracle updates and TCGplayer
- 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: 3,180 cards, 9,640 printings, 46 sets, 5 languages
- Formats: Standard, Japanese Standard
- Price sources: TCGplayer, Cardmarket, Yahoo! Auctions JP
- Upstream data: Bandai official card list, OPTCG API and TCGplayer
- 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: 13,720 cards, 34,100 printings, 604 sets, 9 languages
- Formats: Advanced, Traditional, OCG, Master Duel, Speed Duel, GOAT
- Price sources: TCGplayer, Cardmarket, eBay sold
- Upstream data: YGOPRODeck, Konami card database and TCGplayer
- 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 list updates for TCG, OCG, Master Duel and Speed Duel are published within an hour of Konami's announcement and trigger a card.legality.changed webhook.

**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,720 cards, 5,480 printings, 12 sets, 5 languages
- Formats: Core Constructed, Infinity Constructed
- Price sources: TCGplayer, Cardmarket
- Upstream data: Lorcast, Ravensburger set lists and TCGplayer
- 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,460 cards, 4,920 printings, 9 sets, 6 languages
- Formats: Premier, Twin Suns, Draft, Sealed
- Price sources: TCGplayer, Cardmarket
- Upstream data: SWU-DB, Fantasy Flight card lists and TCGplayer
- 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: 2,940 cards, 8,120 printings, 38 sets, 4 languages
- Formats: Standard, Japanese Standard
- Price sources: TCGplayer, Cardmarket
- Upstream data: digimoncard.io, Bandai card lists and TCGplayer
- 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: 1,180 cards, 3,240 printings, 9 sets, 3 languages
- Formats: Standard, Unlimited, Sealed
- Price sources: TCGplayer, Cardmarket
- Upstream data: Grand Archive official API and TCGplayer
- 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 in ingest

- 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.
- `oracleId` (String) — Groups every printing and language of the same card.
- `game` (Enum) — Which game the card belongs to.
- `name` (String) — Card name in the requested language.
- `normalizedName` (String) — Accent-folded, lowercased name for fuzzy search.
- `set` (Object) — Set object: code, name, series, releasedAt, cardCount.
- `collectorNumber` (String) — Number printed on the card.
- `rarity` (String) — Publisher rarity, normalised per game.
- `rarityRank` (Int) — Cross-game 0–100 scarcity score for sorting.
- `artist` (String) — Illustrator credit.
- `flavorText` (String) — Non-rules flavour text.
- `text` (String) — Primary rules text, plain-text normalised.
- `language` (Enum) — BCP-47 language code of this printing.
- `finishes` ([String]) — Available finishes for this printing.
- `images` (Object) — small, normal, large, png and art-crop URLs on the TCGGraph CDN.
- `prices` ([Object]) — Per-source, per-condition, per-finish pricing with timestamps.
- `priceHistory` ([Object]) — Daily close prices, up to 5 years of history.
- `legalities` (Object) — Format legality map for the card's game.
- `externalIds` (Object) — tcgplayerId, cardmarketId, scryfallId, publisher SKUs and more.
- `gameData` (Object) — The game-specific payload. Typed per game in GraphQL.
- `updatedAt` (String) — ISO-8601 timestamp of the last change to this record.

## 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.

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/search` for fuzzy or partial names. Use `/v1/cards` for
  structured filters. They are not interchangeable.
- Prices are per source, per condition, 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.
- Seed bulk data with `/v1/bulk/exports`, not by paginating `/v1/cards`.
- Sync incrementally on `updatedAt`. Upsert on `id`; group printings by `oracleId`.
- Card images come in small, normal, large, png and art-crop. Always set
  explicit dimensions — cards are 5:7.

## 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), `avg1`, `avg7` and `avg30` (rolling means), and `sellers` (how many live articles the quote is drawn from).

`?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.

## 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 crypto top-ups and the plan fee is drawn from it on each renewal date. Nothing is auto-charged; if the balance runs short the plan lapses and the API returns 402 until it is topped up. 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)
- Bulk export: 250 credits (Per game, per download)
- Image delivery: free (Never metered, on any plan)
- Cached response (304): free (Send If-None-Match and pay nothing)

### 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
- Cardmarket and TCGplayer prices
- Unmetered image CDN
- 2 years of daily price history
- 5 webhook endpoints
- 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
- Nightly bulk exports, all formats
- All five price sources
- Full price history, back to 2019
- Hourly intraday price snapshots
- Unlimited webhook endpoints
- 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
- Parquet exports to your own S3 bucket
- Priority request routing
- Dedicated regional cache
- Redistribution licence available
- SSO, SCIM and audit logs
- 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 five 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 if you cannot charge my card?** 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. Nobody can pull money from a wallet on a schedule, so nothing is ever charged automatically: money moves only when you send it. 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, no debt and no collections.

**How do I pay?** Cryptocurrency only. We accept USDC and USDT as ERC-20, plus Bitcoin, Ethereum, Solana and Tron — one network per asset, so there is no way to send on the wrong chain. Every top-up gets its own freshly derived address, so payments cannot be linked on-chain. Amounts are quoted in USD and converted at the rate when the transfer lands.

**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.

**Why do you not accept cards?** Card networks require handing a processor your name, billing address and a full transaction history, and that record outlives your subscription. We would rather not hold it, so we do not collect it. An account here is an email address and a payment. If you need a signed invoice with a company name and VAT number for your accountant, we will issue one on request — that is a document you ask for, not a profile we build.

**What if the price moves while I am paying?** The quoted rate is locked for 15 minutes from when the invoice is generated. If a payment arrives late or short we credit what landed at the new rate and show the shortfall on your billing page rather than failing the whole payment. Overpayments roll into the next period.

## 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 five marketplaces 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, the search syntax is unmatched and there is no commercial reason to pay us instead. We use Scryfall as an upstream source and think you should too. Come back when you add a second game.

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

pokemontcg.io is the community standard for Pokémon card data. TCGGraph offers the same Pokémon coverage plus seven more games, normalised prices from five marketplaces and a stricter uptime commitment.

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 five marketplaces 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. It is one of our upstream sources. 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 five marketplaces 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. It is one of our upstream sources. TCGGraph makes sense once you need a second game or want webhooks instead of polling.

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

The TCGplayer API is a marketplace API: excellent prices, but it requires partner approval and models products rather than cards. TCGGraph gives you game-native card data with prices from five marketplaces and a key you can 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 five marketplaces, 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, avg30 and seller depth.
- 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, sets and prices under game=grand-archive.
- added: gameData fields for memoryCost, reserveCost, level, durability, elements, classes and speed.
- added: GRAND_ARCHIVE added to the GraphQL Game enum.
- improved: Champion progression is linked across levels via lineageId.

### 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 configurable per key from the dashboard.
- 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 — Price history extended to five sources

Cardmarket, Card Kingdom, eBay sold listings and Yahoo! Auctions JP now sit alongside TCGplayer, each normalised by condition and finish.

- added: Per-source price series on the prices array.
- added: Blended market value that weights sources by liquidity.
- improved: Japanese card prices now resolve against Yahoo! Auctions JP.
- fixed: Foil and non-foil series no longer merge on Lorcana enchanted cards.

### 2026-06-25 — Webhooks are generally available

Signed, retried delivery for set releases, spoilers, errata and legality changes, so you can stop diffing a nightly poll.

- added: Six event types covering sets, cards, legality, prices and exports.
- added: HMAC-SHA256 signatures with replay protection.
- added: Per-endpoint event and game scoping.
- improved: Delivery attempts are visible in the dashboard for 30 days.

### 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