Frequently asked questions
Everything about TCG Price Lookup — the API, the SDKs, the data, and the plans. 40 questions across 7 categories. Can’t find an answer? Email us.
About TCG Price Lookup
What this service is, who it's for, and what data we provide.
TCG Price Lookup is a developer API and consumer price checker for trading card game prices. The API exposes live market data — TCGPlayer market prices, eBay sold-listing averages, and PSA / BGS / CGC graded slab values — across eight trading card games in a single normalized JSON response. The website at tcgpricelookup.com is the consumer-facing card price checker built on top of the same data.
Eight games are indexed deeply: Pokémon (English), Pokémon Japan, Magic: The Gathering, Yu-Gi-Oh!, One Piece Card Game, Disney Lorcana, Star Wars: Unlimited, and Flesh and Blood. The full slug list used in API queries is: pokemon, pokemon-jp, mtg, yugioh, onepiece, lorcana, swu, fab. Each game has its complete set catalog indexed with per-condition prices for raw cards and graded values for slabs.
Two primary sources. TCGPlayer provides marketplace listings — what sellers are currently asking — for raw cards in every condition (Near Mint to Damaged) with market, low, mid, and high values. eBay provides sold-listing data — what buyers actually paid — as rolling averages over 1-day, 7-day, and 30-day windows for both raw cards and graded slabs from PSA, BGS, CGC, SGC, ACE, and TAG. Both sources are normalized into a single JSON shape so you don't have to reconcile them yourself.
Marketplace prices and sold-listing averages refresh continuously throughout the day. TCGPlayer market data is typically updated every few hours; eBay rolling averages are recalculated as new sales are recorded. Card metadata and new set additions are pushed as soon as releases hit. The same data feeds tcgpricelookup.com's live consumer price checker, so the freshness bar is set by real consumer expectations — not by API tier marketing.
Indie developers building deck builders and portfolio trackers, marketplaces auto-pricing inventory, local card shops syncing prices across POS and online listings, investment analytics tools tracking grading premiums, Discord and Twitch bots answering 'what is this card worth' in chat, researchers studying secondary-market dynamics, and collectors who want their data at their fingertips. The common thread: needing fresh prices on demand, across multiple games, without building and maintaining the data pipeline themselves.
Using the API
Endpoints, authentication, parameters, and request shapes.
Sign up at tcgpricelookup.com/tcg-api with email or social login. The Free tier requires no credit card, takes about 10 seconds to set up, and gives you 200 requests per day. Your API key is shown once in the dashboard — copy it to a password manager or environment variable immediately.
Pass your API key in the X-API-Key header on every request. The format is: X-API-Key: YOUR_API_KEY. Example: curl 'https://api.tcgpricelookup.com/v1/cards/search?q=charizard' -H 'X-API-Key: tcg_xxx'. Never expose your key in client-side JavaScript — proxy requests through a backend you control. If you accidentally leak a key, rotate it immediately from the dashboard.
Five REST endpoints under /v1/. GET /v1/cards/search for full-text search, set filtering, game filtering, and batch lookup by IDs. GET /v1/cards/{id} for full details on one card including all conditions and graded values. GET /v1/cards/{id}/history for daily price history (Trader plan and above). GET /v1/sets for browsing sets across all games or filtering by game. GET /v1/games for the supported game list. Base URL: https://api.tcgpricelookup.com/v1.
TCGPlayer prices reflect what sellers are currently asking on the TCGPlayer marketplace — market, low, mid, and high values for each condition. eBay prices are aggregate averages (1-day, 7-day, 30-day) computed from actual completed sales — what buyers actually paid. Together they give you a complete picture: the retail listing price and the real-world transaction price. For graded cards we only return eBay sold-listing averages because graded slabs primarily trade on eBay, not TCGPlayer.
Yes. The search endpoint accepts a comma-separated list of card IDs via the ids parameter — for example, GET /v1/cards/search?ids=id1,id2,id3 returns all three cards in one response. The backend caps each request at 20 IDs; for larger portfolios the official @tcgpricelookup/sdk auto-chunks longer arrays into multiple requests transparently. Each batch request counts as one call against your daily quota regardless of how many cards you fetch.
Rate limits depend on your plan. Free: 200 requests per day with a burst limit of 1 request per 3 seconds. Trader: 10,000 requests per day with a burst limit of 1 request per second. Business: 100,000 requests per day with a burst limit of 3 requests per second. Daily counters reset at midnight UTC. Every response includes X-RateLimit-Limit and X-RateLimit-Remaining headers so you can back off proactively.
Pricing data details
Conditions, grades, currencies, and historical coverage.
For raw cards: six conditions — Mint, Near Mint, Lightly Played, Moderately Played, Heavily Played, and Damaged. Each condition includes TCGPlayer (market, low, mid, high) and eBay (1-day, 7-day, 30-day averages) where data is available. For graded cards: PSA grades 1-10, BGS grades 1-10 (including 9.5 half-grades), CGC grades 1-10, and we also surface SGC, ACE, and TAG values where the backend has data. Each grader-grade pair carries its own eBay sold-listing averages.
Yes. All prices are USD. Both TCGPlayer market data and eBay sold-listing averages are sourced from US-based marketplaces and reported in US dollars. There is no per-region price localization in the API today; if you need EUR/GBP/JPY equivalents, convert them yourself with a currency rate at request time.
Yes, on the Trader and Business plans. Card responses on paid plans include a `prices.graded` block with PSA, BGS, CGC, SGC, ACE, and TAG values across grades 1-10 where available, sourced from real eBay sold listings. The Free plan returns raw TCGPlayer prices only — eBay raw averages and graded data both require Trader or above. This is one of the main differentiators of TCG Price Lookup over scraping marketplaces yourself.
Yes, on the Trader and Business plans, via GET /v1/cards/{id}/history. Supported periods are 7d, 30d, 90d, and 1y. The response is an array of days, each containing all the price rows recorded for that card on that date — TCGPlayer market values per condition plus eBay rolling averages per condition and per grader-grade. Free-tier API keys receive a 403 with a clear error message when calling history.
Each variant is its own card record with its own UUID and its own price block. A 1st Edition Charizard, an Unlimited Charizard, and a Shadowless Charizard are three separate entries in the database — same name, same set, different IDs and different prices. The `variant` field on each card distinguishes them. Foil and reverse-holo printings are handled the same way: they're separate records, not modifiers on a single card.
SDKs, CLI & integrations
Official open-source tools and how to integrate them.
Yes — the official JavaScript / TypeScript SDK is published on npm as @tcgpricelookup/sdk. It exposes all five API endpoints with full TypeScript types, auto-chunked batch lookup beyond the 20-ID per-request cap, typed errors (AuthenticationError, PlanAccessError, NotFoundError, RateLimitError) you can instanceof-check, and an opt-in retry policy for 429 and 5xx responses. Zero runtime dependencies, native fetch, ESM and CJS bundles. Works in Node 18+, browsers, Cloudflare Workers, Bun, and Deno. MIT licensed, source code on GitHub.
Run: npm install @tcgpricelookup/sdk. Then import the client: import { TcgLookupClient } from '@tcgpricelookup/sdk'; create one with your API key: const tcg = new TcgLookupClient({ apiKey: process.env.TCG_API_KEY }); and call any endpoint, for example: const { data } = await tcg.cards.search({ q: 'charizard', game: 'pokemon' }); console.log(data[0].prices.raw.near_mint?.tcgplayer?.market). Full documentation lives in the GitHub README.
Yes — the official CLI is published on npm as `tcglookup`. Install globally with: npm install -g tcglookup. Authenticate once with: tcglookup auth login (paste your key when prompted; it's stored under XDG_CONFIG_HOME with file mode 600). Then run commands like: tcglookup search 'charizard' --game pokemon, tcglookup get <card-id>, tcglookup history <card-id> --period 30d, tcglookup sets pokemon, tcglookup games. Pretty colored tables by default; --json on every command for jq pipes.
Not yet. A Python SDK is on the roadmap and will be published to PyPI under the tcgpricelookup namespace when ready. In the meantime the API is plain JSON over HTTPS and works with any Python HTTP client — `requests`, `httpx`, `aiohttp`, or the standard library. The /docs/api-reference page includes copy-pasteable Python examples for every endpoint.
Both official packages are open source under MIT license, hosted at github.com/TCG-Price-Lookup. The repo `tcglookup-js` contains the JavaScript / TypeScript SDK source, tests, and CI config. The repo `tcglookup-cli` contains the command-line tool. Issues, pull requests, and feature requests are welcome on either repo. Releases are published to npm via GitHub Actions with verified provenance attestations.
Not yet. The API is REST-only today. The recommended real-time pattern is to poll /v1/cards/{id} every 15-30 seconds for active watchlists, or every 60-120 seconds for background pages. Webhooks and a streaming transport are on the roadmap. The /docs/websocket page documents the recommended polling strategy and explains how to keep your client transport-agnostic so you can upgrade to streams later without rewrites.
An OpenAPI 3 spec is on the roadmap. In the meantime, the live API reference at /docs/api-reference documents every endpoint, parameter, response shape, and HTTP status code with copy-pasteable examples in cURL, JavaScript, and Python. The official @tcgpricelookup/sdk's TypeScript types act as a de-facto schema that you can import and use for response validation in your own apps.
Plans & billing
Free vs paid tiers, what's included, and how billing works.
The Free plan gives you 200 requests per day at a burst limit of 1 request per 3 seconds, all 8 supported games, raw card prices from TCGPlayer (market, low, mid, high) for every condition, and full search / set browsing. It does NOT include eBay sold-listing data, graded card prices, or the price history endpoint. Free is for non-commercial use only — personal projects, learning, prototypes, and experimentation.
Upgrade to Trader ($14.99/month) when you need any of: more than 200 requests per day, eBay sold-listing data on raw cards, graded card prices (PSA / BGS / CGC / SGC / ACE / TAG), the historical price endpoint, or commercial usage rights. Upgrade to Business ($89.99/month) when you need more than 10,000 requests per day or higher burst limits for production traffic. Both paid plans are month-to-month, no long-term commitment, cancel anytime from the dashboard.
Commercial use is included on the Trader and Business plans. The Free tier is non-commercial only. Commercial usage covers things like resale apps, deck builders with monetization, marketplace integrations, graded-card analytics products, internal tooling at a card shop, and any product or service that bills its end users while consuming our data. If you have specific licensing questions for an unusual use case, contact us before launching.
No. The Free plan does not require any payment method. You can sign up, get an API key, and start making requests in under a minute. Credit card details are only requested when you choose to upgrade to Trader or Business.
Open the dashboard at tcgpricelookup.com/dashboard, click Billing, then Manage subscription. The link takes you to a Stripe-hosted billing portal where you can downgrade, cancel, update payment methods, view past invoices, and update your billing address. Cancellations take effect at the end of the current billing period — you keep paid features until then.
If something goes wrong on our end — extended downtime, data quality issues, or a bug that materially affected your usage — email [email protected] and we'll make it right, typically with a prorated refund or service credit. We don't offer no-fault refunds for unused time on paid plans, since the value of an API subscription is the access window itself, but month-to-month billing means you can cancel at any time and only pay for what you used.
Limits, errors & reliability
What to expect when things go wrong, and how to handle it.
200 for successful requests. 400 for malformed query parameters. 401 for missing or invalid API keys. 403 for plan-level access denials — for example, requesting graded data or history on the Free tier. 404 for cards, sets, or games that don't exist. 429 when you exceed your daily quota or burst rate limit. 5xx for upstream issues. Every error response includes a JSON `error` field with a human-readable message describing what went wrong.
On a 429, back off before retrying. For Free-tier traffic, wait at least a few seconds; for Trader and Business, a 1-2 second backoff is usually enough since the burst window resets every second. For 5xx responses, retry with exponential backoff starting at 1 second, capping at 30 seconds, with jitter to avoid thundering-herd retries. The official SDK has an opt-in retry policy that handles both — pass retry: { attempts: 3, baseDelayMs: 500 } to the client constructor.
Yes. Every response includes X-RateLimit-Limit (your tier's daily quota) and X-RateLimit-Remaining (calls left in the current window). Use these to back off proactively rather than waiting for a 429. The official SDK exposes these as client.rateLimit.{limit, remaining} after every request so you can log them, surface them in admin UIs, or pause work when you're approaching your daily cap.
Best-effort uptime targeting 99.9% across all paid tiers. We do not currently publish a contractual SLA on Free or Trader; the Business plan can be paired with a custom SLA agreement on request. Our infrastructure is monitored continuously with Sentry; incident reports and post-mortems are posted on the status page when material outages occur. For the most up-to-date health, hit GET https://api.tcgpricelookup.com/health from any client.
Yes, and you should. Marketplace prices don't change every second, so caching responses for 5 to 60 minutes is reasonable for most apps. Card metadata (name, set, image) is even more cache-friendly — it can be cached indefinitely and refreshed when a new set drops. Use the `updated_at` field on each card to know when the underlying data last changed. Caching reduces your daily quota usage and improves your app's perceived latency.
Open an issue on the relevant GitHub repo: github.com/TCG-Price-Lookup/tcglookup-js for the JavaScript SDK, github.com/TCG-Price-Lookup/tcglookup-cli for the CLI. For backend / API issues that aren't SDK-specific, email [email protected] with a clear repro and the request URL plus the response body. Feature requests are also welcome via GitHub issues — we read and prioritize all of them.
Account & support
Sign-in, key rotation, attribution, and getting help.
Open the dashboard at tcgpricelookup.com/dashboard, click API keys, click 'Create new key', copy the new key to your environment, deploy your app, then revoke the old key from the same page. The old key keeps working until you explicitly revoke it, so there's no downtime if you sequence the steps correctly. Rotate immediately if you suspect a leak.
Yes. The dashboard lets you create multiple named keys per account — one for production, one for staging, one for local development, one for that side project. Each key counts against the same daily quota, but per-key usage is logged so you can identify which environment is consuming the most. Revoke any individual key without affecting the others.
On the Free and Trader plans we ask for a small 'Powered by TCG Price Lookup' link somewhere visible in your app or website. On the Business plan and partnership arrangements this is optional. No attribution is required when the API is used purely server-side — for example, internal analytics, pricing automation, or ETL pipelines that never expose data to end users.
Yes. We do not store any personally identifying information about end users of your app — we only see your API key and the requests it makes. Account-level data (name, email, billing address) is processed under standard SaaS provider terms; see the Privacy Policy for full details. Analytics on tcgpricelookup.com itself are run through PostHog hosted in the EU region.
Email [email protected] with your question, your account email (if applicable), and any relevant request URLs or error messages. We typically respond within 24 hours. For urgent production issues on the Business plan, mention 'urgent' in the subject and we'll prioritize. For open-source SDK / CLI bugs, GitHub issues on the relevant repo are the fastest path to a fix.