NeoSatoshi Card Recognition API

Card recognition API for Pokémon, One Piece, Disney Lorcana, Yu-Gi-Oh!, Magic: The Gathering, Star Wars: Unlimited, Digimon Card Game and football (soccer) cards: send a photo, get JSON with set, number, rarity, Cardmarket ID and daily prices (football: player, release and parallel).

This repository contains runnable examples (curl, Python, Node.js), an MCP server for AI assistants, a Postman collection and a copy of the OpenAPI spec. The API is run by NeoSatoshi (NeoGen Solutions GmbH, Bern, Switzerland).

• Endpoint: POST https://europe-west1-neosatoshi.cloudfunctions.net/detectApi

• Auth: Authorization: Bearer <API_KEY>

• Public demo key (no signup, 10 detections per day per network): nsk_live_9c253fbed995042a98280ad13e5c47d3c4a59c9b4f0f7274

• Docs: https://neosatoshi.com/developers/detection-api

• Card search and corrections: POST .../cardsApi/search, POST .../cardsApi/corrections, GET .../cardsApi/cards/{tcg}/{card_id} (see Card search and corrections)

• OpenAPI: openapi.json (also at https://neosatoshi.com/openapi.json)

Quickstart (30 seconds)

From a clone of this repository (or use any photo of a card). Works on macOS and Linux as is:

{ printf '{"tcg":"pokemon","image":"'; base64 < examples/images/example_api_single.jpg | tr -d '\n'; printf '"}'; } > body.json

curl -sS --max-time 120 -X POST https://europe-west1-neosatoshi.cloudfunctions.net/detectApi \
  -H "Authorization: Bearer nsk_live_9c253fbed995042a98280ad13e5c47d3c4a59c9b4f0f7274" \
  -H "Content-Type: application/json" \
  --data-binary @body.json

One card usually takes about 4 seconds, about 10 to 12 seconds on the first request after a quiet period; a binder page with 9 cards about 17 seconds. Keep the client timeout at 120 seconds or more.

Ready-made scripts that print a per-card summary:

./examples/curl/detect.sh examples/images/example_api_single.jpg
python3 examples/python/detect.py examples/images/example_api_lorcana_de.jpg lorcana
node examples/node/detect.mjs examples/images/example_api_multi.jpg pokemon --json

All scripts read NEOSATOSHI_API_KEY and fall back to the demo key.

Related MCP server: PokéWallet MCP

Streaming

Add "stream": true to get Server-Sent Events: each card as soon as it is recognised, then the same result as a normal call, at the same cost. On a Pokémon binder page with 9 cards the first card came after about 6 seconds and all nine after about 17. Football (one card per photo) gets progress events, not a faster result.

./examples/curl/stream.sh https://neosatoshi.com/static/images/example_api_multi.jpg
python3 examples/python/stream.py https://neosatoshi.com/static/images/example_api_multi.jpg
node examples/node/stream.mjs https://neosatoshi.com/static/images/example_api_lorcana.jpg lorcana

Events: accepted, progress, card (index, card), then exactly one of done (same body as the JSON response) or error (status, error, message). A : keep-alive comment comes every 15 seconds. Errors before the detection starts stay plain JSON with their status code. A stream cannot be resumed: a reconnect is a new, charged detection. Details: documentation.

Supported games and languages

Request

POST with a JSON body:

{ "image": "<base64 JPEG or PNG, max 12 MB>", "tcg": "pokemon" }

Response

Recorded response for examples/images/example_api_single.jpg (Pokémon, Cinderace ex, demo key, 2026-11-11):

{
  "request_id": "req_745cfd72-7f1c-4e4c-94d3-91e2485b8b2d",
  "count": 1,
  "cards": [
    {
      "name": "Cinderace ex",
      "name_ja": null,
      "name_ko": null,
      "name_zh": null,
      "language": "en",
      "card_id": "svp-163",
      "set": { "id": "svp", "ptcgo_code": "PR-SV", "name": "Scarlet & Violet Black Star Promos", "number": "163" },
      "rarity": "Promo",
      "cardmarket_id": 796939,
      "reverse_holo": false,
      "first_edition": false,
      "possible_variants": null,
      "special_variant": null,
      "price_basis": "normal",
      "prices": {
        "cardmarket": { "trend": 3.84, "low": 1, "avg7": 3.87, "avg30": 3.87, "currency": "EUR" },
        "cardmarket_normal": { "trend": 3.84, "low": 1, "avg7": 3.87, "avg30": 3.87, "currency": "EUR" },
        "cardmarket_reverse": { "trend": null, "low": null, "avg7": null, "avg30": null, "currency": "EUR" },
        "tcgplayer": { "market": 5.03, "currency": "USD" }
      },
      "images": {
        "small": "https://d1m1gwcombja0u.cloudfront.net/public_images/cards_en/svp/svp-163_small.webp",
        "large": "https://d1m1gwcombja0u.cloudfront.net/public_images/cards_en/svp/svp-163.png"
      },
      "confidence": 0.85,
      "image_quality": { "blurred": false, "unusual_dimensions": false },
      "alternatives": [
        { "name": "Cinderace ex", "set": "Stellar Crown", "number": "28", "score": 1, "possible_variants": null, "card_id": "sv7-28", "cardmarket_id": 785881 }
      ],
      "graded": null,
      "card_index": 0,
      "review": { "needed": false, "reasons": [], "search": null }
    }
  ],
  "demo": { "limit_per_day": 10, "remaining_today": 9 },
  "correction": {
    "request_id": "req_745cfd72-7f1c-4e4c-94d3-91e2485b8b2d",
    "until": "2026-11-12T17:52:33.487Z",
    "endpoint": "https://europe-west1-neosatoshi.cloudfunctions.net/cardsApi/corrections",
    "search_endpoint": "https://europe-west1-neosatoshi.cloudfunctions.net/cardsApi/search"
  }
}

The alternative Stellar Crown 28 has score 1 while the match has confidence 0.85. Score and confidence are different scales, so compare the set number printed on the card, not these two numbers. See Integration guide.

(Shortened; the full recording is in examples/responses/pokemon_single_cinderace.json.) For the 9 card binder page in example_api_multi.jpg the API returns every card in cards, one entry each.

More recordings:

• lorcana_en_genie.json: Disney Lorcana, English, photo example_api_lorcana.jpg

• lorcana_de_blume.json: Disney Lorcana, German (foil detected), photo example_api_lorcana_de.jpg

• football_beste_autograph.json: football, a numbered autograph (Gold Wave Refractor 37/50), shortened to two of its four alternatives

• catalog-shape/: One Piece, Lorcana, Yu-Gi-Oh! and Magic responses recorded from clean catalog images, included only to show the response shape per game (the catalog images themselves are not in this repo)

Fields shared by every game

A missing price is null, never 0.

Game-specific fields

Graded slabs: a photo of a PSA, BGS or CGC slab (football also SGC) fills graded with the grader, the grade and the cert number as read from the label; null for a raw card. The grade is never estimated.

The full field reference is in the documentation.

Errors

Errors return JSON with error (a code) and usually message.

Limits and pricing

• Images: JPEG or PNG, at most 12 MB (football 4 MB). All seven trading card games: several cards per photo (binder pages work; Pokémon best up to about 20), one game per photo. Football: one card per photo.

• One card usually takes about 4 seconds, about 10 to 12 seconds on the first request after a quiet period; a football card about 6 to 25 seconds. Use a client timeout of at least 120 seconds.

• Demo key: 10 detections per day per network, no signup. Good for trying the API, not for production.

• Own keys: create them in the dashboard at https://neosatoshi.com/dashboard/settings/settings#api-keys . Any paid plan works; the smallest, Start-Up, costs 19 per month and includes 1,000 card scans. One credit per detected card, also for a low-confidence best guess; card backs, images without a card and cards with a visual mismatch (review reason visual_mismatch) are not charged.

• The API identifies cards. It does not grade card condition.

Card search and corrections

Base URL: https://europe-west1-neosatoshi.cloudfunctions.net/cardsApi, same Bearer key. All seven trading card games and football.

• Correct a detection (free): every detected card has card_index and review, the response has correction with the request_id. Within 24 hours, POST /search with {"request_id": correction.request_id, ...card.review.search} (or your own q, or set + number) returns up to 5 full card objects; POST /corrections with request_id, card_index and the chosen card_id returns the corrected card. 5 searches and 3 corrections per detected card, 500 correction searches and 1000 corrections per account per day.

• Pokémon versions: add cardmarket_id to the correction (the card's own, its 1st Edition product or a possible_variants[].cardmarket_id of that card, else 400 unsupported_cardmarket_id) to pick a version, and reverse_holo (true or false) for a reverse holo copy. prices.cardmarket is then that version's price; price_basis says which. The lookup takes the same as ?cardmarket_id= and &reverse_holo=true. One Piece picks a parallel by cardmarket_id; Lorcana, Yu-Gi-Oh!, Magic, Star Wars: Unlimited and Digimon pick a printing by card_id or set + number and refuse a cardmarket_id that does not belong to the card (400 unsupported_cardmarket_id).

• Card search (paid): POST /search with tcg and q (or set + number), optional language and limit (up to 10). GET /cards/{tcg}/{card_id} returns one card, for example to refresh a price. 0.5 credits per call that returns a card, from the same balance as detection; no result is free. An Idempotency-Key header makes a repeat free. Daily limit per plan; the demo key allows 10 searches and 3 lookups per day per network.

curl -X POST https://europe-west1-neosatoshi.cloudfunctions.net/cardsApi/search \
  -H "Authorization: Bearer nsk_live_9c253fbed995042a98280ad13e5c47d3c4a59c9b4f0f7274" \
  -H "Content-Type: application/json" \
  -d '{"tcg": "pokemon", "q": "charizard 4/102", "limit": 3}'

Digimon: a card number alone is a query ({"tcg": "digimon", "q": "BT1-025"}, BT1-025_P1 for a printing), or set BT1 with number 025; language en or ja. GET /cards/digimon/dg-BT1-025_P1 returns a printing, dg-c-BT1-025 (or BT1-025) the card with its printings.

Football: {"tcg": "football", "q": "kane chrome 2023"}, text only (the player, optionally with set or season words), no language, no prices yet. Each result carries ref; GET /cards/football/{card_id}?ref=... (same key, within 24 hours) returns the card with all parallels of its subset and their print runs. Without a valid ref the lookup is 400 and free. Football detections cannot be corrected yet.

Details: https://neosatoshi.com/developers/detection-api#card-search

Integration guide for coding agents

The recommended bulk loop:

1. POST /detectApi with one photo. Keep request_id and correction.

2. For each card in cards: if review.needed is false, accept it.

3. Otherwise check it: read the set number on the photo, or show the card to a person.

4. If it is wrong, correct it: correction search (POST /cardsApi/search with {"request_id": correction.request_id, ...card.review.search, "number": "<read on the photo>"}), then POST /cardsApi/corrections with request_id, card_index and card_id. Both free.

5. Store card_id, cardmarket_id and price_basis with the card.

Confidence and score. confidence is a fixed step per match method, not a probability. Pokémon: 0.99 direct match, 0.95 number matched, 0.90 direct match (later step), 0.85 number matched (later step), 0.80 direct match (last step), 0.59 best guess. Japanese, Korean and Chinese cards have their own steps (0.99 down to 0.60). alternatives[].score is the similarity of a candidate inside this search, another scale. A German Gallopa 189 came back at 0.85 with the alternative Gallopa 30 at score 0.90, and 189 was right. Never pick an alternative by score alone; take one only when its set number matches the card.

Review reasons. low_confidence: check the set number. blurred, unusual_dimensions: check the card, a sharper photo helps. visual_mismatch, no_match: correct or drop (a visual mismatch is not charged). card_back: skip (not charged). variant_price_missing: the version has no own Cardmarket price, check the price. print_unconfirmed, rarity_unconfirmed, version_unconfirmed, number_unconfirmed, art_unconfirmed: a person picks the printing. graded_label_mismatch: show the slab to a person. Football not_sure, parallel_unconfirmed: a person confirms. Treat an unknown reason as needing review.

Special versions and reverse holo (Pokémon). prices.cardmarket is the price of the version the card is; price_basis says which (normal, reverse_holo, first_edition, special_variant). prices.cardmarket_normal is always the plain card, prices.cardmarket_reverse the reverse holo family. The photo does not tell which possible_variants entry a copy is: a person picks, and you send that entry's cardmarket_id with the same card_id in the correction. A reverse holo copy: "reverse_holo": true. first_edition comes from the detection and is kept; only Base Set has its own 1st Edition price.

Limits. 30 requests per minute per key for search, lookup and corrections (429 rate_limited, Retry-After 60). Correction window 24 hours. 5 correction searches and 3 corrections per card; 500 correction searches and 1000 corrections per account per day (429 daily_cap_reached, Retry-After until midnight UTC). A correction search returns at most 5 cards. Paid search and lookup: 0.5 credits each, only when a card is returned, with daily limits per plan. Exports: 200 per day, at most 20 request_ids.

Idempotency and retries. Send an Idempotency-Key header (8 to 100 characters of A-Z a-z 0-9 : _ -) on paid search and lookup: a repeat within 24 hours is answered from storage and not charged (Idempotent-Replayed: true); another body under the same key is 422 idempotency_key_reuse, a call still running 409 idempotency_in_progress. Retry 429 after Retry-After and 502, 503, 504 with backoff; never retry other 4xx. A retried detection is a new detection and is charged when it succeeds, so retry only after an error answer.

Errors of search, lookup and corrections. 400 invalid_json, invalid_card_index, invalid_card_id, invalid_query, unsupported_language, unsupported_tcg, unsupported_cardmarket_id, correction_not_available_for_tcg, query_too_broad, invalid_idempotency_key; 401 missing_api_key, invalid_api_key; 402 out_of_credits; 403 feature_not_enabled, request_not_yours, paid_search_not_enabled; 404 unknown_request_id, card_not_found; 409 idempotency_in_progress; 410 correction_window_closed; 422 idempotency_key_reuse; 429 rate_limited, daily_cap_reached, correction_budget_exhausted, correction_limit_reached; 502 lookup_failed, search_failed; 503 cards_api_disabled, limiter_unavailable, billing_unavailable.

Runnable: python3 examples/python/detect.py photo.jpg pokemon --review (standard library only) or node examples/node/detect.mjs photo.jpg pokemon --review asks for the set number of every card that needs review and corrects it.

Changelog

• 2026-11-11 (OpenAPI 1.15.0): Pokémon prices.cardmarket and cardmarket_id now describe the version the card is (picked version, detected special variant, 1st Edition, reverse holo, else the plain card; before: always the plain card). New price_basis, prices.cardmarket_normal, prices.cardmarket_reverse, prices.tcgplayer. possible_variants[].cardmarket_id is always an integer (before sometimes a digit string); possible_variants[].price has low and trend, lowPrice and trendPrice are deprecated. Corrections and the lookup take cardmarket_id (400 unsupported_cardmarket_id for an id of another card) and reverse_holo; exports use them. Corrected German, French, Spanish and Italian Pokémon cards keep their localized name. New review on every card and correction.search_endpoint. Docs: confidence steps vs score, billing of best guesses, 1000 corrections per day.

When to use this instead of a general vision LLM

A general vision model can often read a card name from a photo. Use this API when you need:

• Structured catalog IDs: set ID, set code and number in a fixed JSON shape, matched against a card database, plus alternatives when the print is ambiguous.

• Cardmarket product IDs and daily prices: cardmarket_id and Cardmarket trend, low, 7 day and 30 day averages (TCGplayer where available). General vision LLMs do not return these.

• Predictable per-card cost: one credit per detected card, nothing for images without a card.

If you only need a rough description of a photo, a general vision LLM may be enough.

MCP server (Claude, Cursor, Codex and other AI assistants)

mcp-server/ (npm: neosatoshi-card-mcp) is a stdio MCP server with eight tools: recognize_cards (local file, https URL or base64; cards reported one by one, catalog images on request), recognize_folder (a folder of photos to a CSV or JSON file), search_cards, correct_card, get_card, export_cards (the same file the NeoSatoshi website exports: custom CSV/JSON, TCGPowerTools CSV, Shopify product CSV or eBay Seller Hub CSV, free), list_export_presets and list_supported_games, for all seven trading card games and football. It is listed in the official MCP registry as io.github.Cookiebreed/card-recognition-mcp. Quick setup for Claude Code:

claude mcp add neosatoshi-cards -e NEOSATOSHI_API_KEY=your_key -- npx -y neosatoshi-card-mcp

Without NEOSATOSHI_API_KEY it uses the demo key. See mcp-server/README.md for Claude Desktop, Cursor and Codex, and for the file access restriction NEOSATOSHI_ALLOWED_DIRS.

Repository layout

FAQ

Is there a free API to identify Pokémon cards from a photo? Yes, for testing: the public demo key nsk_live_9c253fbed995042a98280ad13e5c47d3c4a59c9b4f0f7274 allows 10 detections per day per network without signup. For more, create your own key on any paid plan.

Can it recognise several cards in one photo? Yes, in all seven trading card games: binder pages work (Pokémon best up to about 20 cards per photo; an 8 card Lorcana page took about 8 seconds). One game per photo. Football cards: one card per photo.

Does it return prices? Yes. Each card comes with its Cardmarket product ID and daily Cardmarket prices in EUR (trend, low, 7 and 30 day average), plus TCGplayer prices in USD where available. A missing price is null. Football cards have no prices in the API yet.

Does it recognise Japanese, Korean or Chinese cards? Pokémon: Japanese, Korean and Simplified Chinese, besides English, German, French, Italian and Spanish. One Piece and Digimon Card Game: English and Japanese. See the table above for the other games.

Does it grade card condition? No. It identifies which card it is (set, number, rarity, language, variant fields). It does not judge condition.

Does it recognise football (soccer) cards? Yes, with "tcg": "football": Topps, Panini and other makers, one card front per photo (at most 4 MB). It returns the player, the release (set and number), season, subset, teams, rookie flag and the parallel (three candidates with print runs, a pick only when it is sure). No prices yet. search_cards and the card search find football cards by player name.

Does it recognise Digimon cards? Yes, the Digimon Card Game in English and Japanese, with "tcg": "digimon": recognised by card number and name, several cards per photo, graded slabs (PSA, BGS, CGC) with the grade read from the label. Alternative arts share the card number, so the printing comes from the picture or stays open with the printings as alternatives to pick. Cardmarket prices (EUR) for English and Japanese printings, TCGplayer (USD) for English only. Older Digimon products (the 1999 card game, the 2000 trading cards) are not recognised.

Does it support Yu-Gi-Oh! OCG (Asian) cards? No, only the TCG in English, German, French, Italian, Spanish and Portuguese.

How long does a request take? One card usually takes about 4 seconds, about 10 to 12 seconds on the first request after a quiet period, and a binder page with 9 cards about 17 seconds. Use a 120 second client timeout. 502 and 504 can be retried.

Can I get the cards one by one? Yes. With "stream": true each card arrives as a Server-Sent Event as soon as it is recognised. It helps with binder pages; see Streaming.

What does it cost? One credit per detected card, from the plan's monthly card scans, also for a low-confidence best guess. Card backs, images without a card and visual mismatches are not charged. The smallest paid plan, Start-Up, costs 19 per month and includes 1,000 card scans.

Can I send an image URL instead of base64? Yes, send "image_url": "https://..." instead of "image". The URL must be public https and point to a JPEG or PNG of at most 12 MB.

Can AI agents call it directly? Yes. Agents may call the endpoint with the demo key, use the OpenAPI spec, or use the MCP server.

Where do I get support? api@neosatoshi.com . Include the request_id from the response.

License and terms

The code in this repository is MIT licensed (see LICENSE). The API itself is a commercial service governed by https://neosatoshi.com/termsofuse . The example images in examples/images/ may only be used for testing the API.