A card scanner does three things: it reads the card, works out exactly which card it is, and shows what it's worth. The first part is your app's job. The other two take a single request to the match endpoint, which takes what your app read off the card and sends back the best matching cards with their current prices.
This guide uses Pokémon as the example. The same steps work for Magic: The Gathering, One Piece and every other game we cover.
How a scan works
- The camera takes a picture. Crop it to the card.
- Your app reads the card. A text recognition model or a vision model reads the card's name and its collector number, such as "Charizard" and "4/102". On phones, the built-in text recognition (Apple's Vision framework or Google's ML Kit) does this well and works offline. A vision model works too.
- One request finds the card and its prices. Send the name and number to
POST /v1/cards/match. - The user confirms. Show the best match with its picture, and let them tap a different one if needed.
The match request
POST /v1/cards/match
{"name": "Charizard", "number": "4/102", "game": "Pokemon", "condition": "Near Mint"}
Only name is required. Everything else helps:
| Field | Why send it |
|---|---|
number |
The collector number as printed. 4/102, 004/102 and 4 all work. It's what tells reprints apart. |
game |
Limits the search to one game. Use Pokemon Japan for Japanese cards. |
set |
If your model can read the set name or symbol, cards from that set are ranked first. |
condition, printing, language |
Only return those prices, such as Near Mint. |
limit |
How many candidates to return. 5 is the default. |
The answer lists the best matches first:
{
"candidates": [
{
"match": "exact",
"card": {
"card_id": "card_...",
"name": "Charizard",
"set": "Base Set",
"number": "4/102",
"image_url": "https://...",
"skus": [
{"printing": "Holofoil", "condition": "Near Mint", "language": "English",
"market_price": ..., "listing_price_low": ..., "listing_price_low_shipping": ..., ...}
]
}
}
]
}
Run the request to see the real prices. Each card has the same fields as GET /v1/cards/{card_id}.
match tells you how sure the result is:
exact: same name and same number. Show it straight away.number: same number, and the name you sent is part of a longer name, such as "Charizard" for "Charizard ex". Usually right, but worth a confirm.name: the name matches but the number doesn't, or you didn't send one. Show the candidates and let the user pick.
Use image_url on the confirm screen. Seeing the card's picture next to the photo is the quickest way for a user to spot a wrong match.
Keep your API key on your server
Never put the API key inside the app itself. Anyone can pull a key out of an app download and use up your plan. Send scans to a small backend of your own, and let the backend call the API with the key. The backend is also the right place for a cache.
# A tiny backend with FastAPI: the app sends what it read, the server adds the key.
import os
import requests
from fastapi import FastAPI
app = FastAPI()
API = "https://tcgpriceapi.com"
HEADERS = {"X-API-Key": os.environ["TCGPRICEAPI_KEY"]}
@app.post("/scan")
def scan(name: str, number: str | None = None, game: str = "Pokemon"):
body = {"name": name, "game": game, "limit": 5}
if number:
body["number"] = number
answer = requests.post(f"{API}/v1/cards/match", headers=HEADERS, json=body, timeout=30)
answer.raise_for_status()
return answer.json()
Add a price chart
Once the user has confirmed a card, show how its price has moved:
GET /v1/cards/{card_id}/history?timeframe=30d&condition=Near Mint
Free includes 7 days of history, Starter 30 days, and Pro and up a full year. A 7 or 30 day chart counts as one request. Charts of 3 months or more count one request per card, so load them when the user opens the card, not for every scan.
Let users save what they scan
Most scanner apps grow a collection screen. Save the card_id of each confirmed scan, and the sku_id of the printing and condition the user picks. Both IDs never change. The collection tracker guide shows how to keep a whole collection's value current in a few bulk requests.
How many requests a scanner uses
Each scan is one request and counts as one card. A price chart is one more.
| Plan | Requests a day | Requests a month | Good for |
|---|---|---|---|
| Free | 100 | 1,500 | Building and testing. Personal projects only. |
| Starter | 1,000 | 12,000 | A first release, up to 1,000 cards a day |
| Pro | 6,000 | 60,000 | A growing app, with a full year of history for charts |
| Business | 25,000 | 250,000 | Thousands of scans a day |
| Enterprise | 100,000 | 1,000,000 | Large apps |
Every paid plan allows commercial use, so you can put a scanner in a paid app from Starter up. A cache in your backend stretches any plan further: two users scanning the same card within an hour can share one answer, since market prices only refresh every 6 hours.
Scanning with an AI agent
If you're building with an AI agent rather than a phone app, the MCP server has an identify_card tool that does the same match. The agent reads the card from a photo, calls the tool, and gets the card with its prices.
Checklist
- Read the name and the collector number. The number matters more than the name for telling printings apart.
- Send
game, andPokemon Japanfor Japanese cards. - Show the picture and ask the user to confirm anything that isn't an
exactmatch. - Keep the key on your server, and cache answers for an hour or two.
- Store
card_idandsku_idfor everything a user saves.