tcglookup-py

The official Python SDK for the TCG Price Lookup API — live trading card prices across Pokemon, Magic: The Gathering, Yu-Gi-Oh!, Disney Lorcana, One Piece TCG, Star Wars: Unlimited, and Flesh and Blood.

One API for every major trading card game. TCGPlayer market prices, eBay sold averages, and PSA / BGS / CGC graded comps — all in one place.

Install

pip install tcglookup

Quickstart

from tcglookup import TcgLookupClient

client = TcgLookupClient(api_key="tlk_live_...")

# Search for cards
results = client.cards.search(q="charizard", game="pokemon", limit=5)
for card in results["data"]:
    print(card["name"], card["prices"]["raw"])

# Get a single card by ID
card = client.cards.get("a3f8c1e2-...")
print(card["name"], card["prices"])

# Daily price history (Trader plan and above)
history = client.cards.history("a3f8c1e2-...", period="30d")
for day in history["data"]:
    print(day["date"], day["prices"])

# List all supported games
for game in client.games.list()["data"]:
    print(game["slug"], game["name"], game["count"], "cards")

Get an API key

Sign up at tcgpricelookup.com/tcg-api. Free tier includes 10,000 requests per month with TCGPlayer market prices. Trader plan unlocks eBay sold averages, PSA / BGS / CGC graded prices, and full price history.

API surface

Cards

client.cards.search(
    q="blue-eyes white dragon",
    game="yugioh",       # pokemon | mtg | yugioh | onepiece | lorcana | swu | fab
    set="lob",           # set slug
    limit=20,
    offset=0,
)

client.cards.get("<card-uuid>")

client.cards.history("<card-uuid>", period="30d")  # 7d | 30d | 90d | 1y

Sets

client.sets.list(game="mtg", limit=50)

Games

client.games.list()

Batch lookups

Pass an iterable of IDs and the SDK auto-chunks into 20-ID batches:

results = client.cards.search(ids=["uuid1", "uuid2", ..., "uuid100"])

Error handling

from tcglookup import (
    TcgLookupClient,
    AuthenticationError,
    PlanAccessError,
    NotFoundError,
    RateLimitError,
)

client = TcgLookupClient(api_key="tlk_live_...")

try:
    history = client.cards.history("<uuid>", period="1y")
except AuthenticationError:
    print("Bad API key")
except PlanAccessError:
    print("History requires Trader plan — upgrade at tcgpricelookup.com/tcg-api")
except NotFoundError:
    print("That card doesn't exist")
except RateLimitError:
    print(f"Rate limited. Quota: {client.rate_limit.remaining}/{client.rate_limit.limit}")

Rate limits

After every successful request, the most recent rate-limit headers are available on the client:

client.cards.search(q="pikachu")
print(client.rate_limit.remaining, "/", client.rate_limit.limit)

Use as a context manager

with TcgLookupClient(api_key="tlk_live_...") as client:
    cards = client.cards.search(q="black lotus", game="mtg")
# HTTP connection pool is closed automatically

Sister SDKs

• tcglookup-js — JavaScript / TypeScript
• tcglookup-go — Go
• tcglookup-rs — Rust
• tcglookup-php — PHP
• tcglookup CLI — terminal client
• tcg-api-examples — runnable code samples in 8 languages
• tcg-discord-bot — self-hosted Discord bot with slash commands

The full developer ecosystem index lives at awesome-tcg.

License

MIT — see LICENSE.

Built by TCG Price Lookup. Get a free API key at tcgpricelookup.com/tcg-api.