# TCG API — Universal Trading Card Game Pricing API

> Real-time prices for Pokemon, Magic: The Gathering, Yu-Gi-Oh!, and 85+ more trading card games. Cards and sealed products with per-printing (Normal/Foil) price tracking.

## API Base URL
https://api.tcgapi.dev/v1

## Authentication
Include your API key in the `X-API-Key` header:
```
X-API-Key: tcg_live_xxxxx
```

Get a free API key at https://tcgapi.dev/docs/quickstart

## Endpoints

### Public (no auth required)
- GET /v1/games — List all 85+ supported games
- GET /v1/games/{slug} — Get game details (e.g., /v1/games/pokemon)
- GET /v1/games/{slug}/sets — List sets for a game

### Free tier (100 req/day)
- GET /v1/sets?game={slug} — List sets, optional game filter
- GET /v1/sets/{id} — Get set details
- GET /v1/sets/{id}/cards?type=Cards — Cards in a set (filter: Cards or Sealed Products)
- GET /v1/cards/{id} — Card details with custom_attributes (attacks, HP, etc.)
- GET /v1/cards/{id}/prices?printing=Normal — Price data per printing (Normal/Foil)
- GET /v1/cards/tcgplayer/{tcgplayerId} — Lookup by TCGPlayer ID with all printing prices
- GET /v1/search?q={query}&game={slug}&type=Cards&printing=Foil — Search with filters
- GET /v1/prices/top-movers?game={slug}&printing=Normal&direction=up — Price movers

### Hobby tier ($9.99/mo, 1K req/day)
- GET /v1/cards/{id}/history?range=month&printing=Normal — 7-day price history

### Starter tier ($19.99/mo, 2.5K req/day)
- GET /v1/cards/{id}/history?range=month&printing=Normal — 30-day price history
- GET /v1/sets/{id}/prices — All prices in a set with printing breakdown
- POST /v1/bulk/resolve/tcgplayer — Batch resolve TCGPlayer IDs (up to 100, 1 credit each)
- POST /v1/bulk/resolve/name — Batch resolve card names with game/set hints (up to 100, 1 credit each)

### Pro tier ($49.99/mo, 10K req/day)
- GET /v1/cards/{id}/history?range=all — Full price history (all available data)
- GET /v1/cards/{id}/history/detailed — Full history with sales volume
- GET /v1/bulk/prices?ids=1,2,3 — Bulk prices with all printings (up to 500)
- GET /v1/bulk/cards?ids=1,2,3 — Bulk card data with prices array (up to 100)
- GET /v1/bulk/history?ids=1,2,3&printing=Normal — Bulk history per printing
- GET /v1/export/set/{id}?format=json — Set data export (CSV or JSON)
- POST /v1/bulk/resolve/tcgplayer — Batch resolve TCGPlayer IDs (up to 500, 0.5 credits each)
- POST /v1/bulk/resolve/name — Batch resolve card names (up to 500, 0.5 credits each)
- Commercial use license included

### Business tier ($99.99/mo, 50K req/day)
- All Pro features plus 50K daily requests
- POST /v1/bulk/resolve/tcgplayer — Batch resolve TCGPlayer IDs (up to 1000, 0.1 credits each)
- POST /v1/bulk/resolve/name — Batch resolve card names (up to 1000, 0.1 credits each)

## Bulk Resolve Endpoints (CSV Import)
POST body format for /v1/bulk/resolve/tcgplayer: { "ids": [12345, 67890] }
POST body format for /v1/bulk/resolve/name: { "items": [{ "name": "Charizard ex", "game": "pokemon", "set": "obsidian-flames" }] }
Response: { "data": { "resolved"/"results": [...], "not_found"/"unmatched": [...] }, "meta": { "credits_consumed": N } }
Name resolve returns confidence levels (exact/high/medium) and up to 3 alternatives per match.
Credits consumed = ceil(items * multiplier). Multiplier: Starter=1.0, Pro=0.5, Business=0.1.

## Data Model

### Games
Each game has: id, name, slug, tcgplayer_id, priority (3=daily, 2=every 3 days), set_count, card_count, image_url (TCGPlayer CDN image of the game's highest-value card, nullable), logo_url (self-hosted game logo, 400x200 transparent PNG, available for 21 major games, nullable), last_synced_at

### Sets
Each set has: id, name, slug, tcgplayer_id, abbreviation, release_date, card_count, image_url (TCGPlayer CDN image of the set's highest-value card, nullable), set_icon_url (TCGPlayer set icon/logo, nullable), game_name, game_slug

### Cards
Each card/sealed product has: id, name, number, rarity, image_url (TCGPlayer CDN image, computed from tcgplayer_id), tcgplayer_id, product_type (Cards/Sealed Products), foil_only, total_listings, shipping_category_id (1=card, 3=box, 4=case), product_status_id (1=active, 20=presale), custom_attributes (game-specific JSON: attacks, HP, energy type for Pokemon; color, mana cost for Magic; etc.)

### Prices (per printing)
Each card has 1-2 price rows (Normal and/or Foil): printing, market_price, low_price, median_price, lowest_with_shipping, buylist_price, price_change_24h/7d/30d, last_updated_at

### Price History
Daily snapshots per card per printing: date, printing, market_price, low_price, avg_sales_price, sales_volume

## Response Format
All responses use this envelope:
```json
{
  "data": { ... },
  "meta": { "total": 100, "page": 1, "per_page": 50, "has_more": true },
  "rate_limit": { "daily_limit": 100, "daily_remaining": 99, "daily_reset": "..." }
}
```

## Pagination
Use `page` and `per_page` query parameters. Max per_page is 100.

## Game Slugs (top games — daily updates)
- pokemon, magic, yugioh, lorcana-tcg, flesh-and-blood-tcg, one-piece-card-game
- riftbound-league-of-legends-trading-card-game
All other games (star-wars-unlimited, digimon-card-game, dragon-ball-super-ccg, etc.) update every 3 days.

## Documentation
- Full docs: https://tcgapi.dev/introduction
- API explorer: https://tcgapi.dev/api-explorer
- OpenAPI spec: https://tcgapi.dev/openapi.yaml

## Pricing
- Free: 100 req/day, $0 (testing/evaluating)
- Hobby: 1,000 req/day, $9.99/mo (personal projects)
- Starter: 2,500 req/day, $19.99/mo (small apps)
- Pro: 10,000 req/day, $49.99/mo (commercial use, bulk endpoints)
- Business: 50,000 req/day, $99.99/mo (high-volume commercial use)