Batch lookup (auto-chunks at 20)

// Pass as many IDs as you want — the SDK transparently splits into 20-per-call
// requests and merges the results.
const portfolio = ["id-1", "id-2", /* … 50 ids … */];
const { data } = await tcg.cards.search({ ids: portfolio });
const total = data.reduce(
  (sum, c) => sum + (c.prices.raw.near_mint?.tcgplayer?.market ?? 0),
  0
);
console.log(`Portfolio value: $${total.toFixed(2)}`);

Price history (Trader plan and above)

import { PlanAccessError } from "@tcgpricelookup/sdk";

try {
  const history = await tcg.cards.history(card.id, { period: "30d" });
  for (const day of history.data) {
    const tcgRow = day.prices.find((p) => p.source === "tcgplayer" && p.condition === "near_mint");
    console.log(day.date, tcgRow?.price_market);
  }
} catch (err) {
  if (err instanceof PlanAccessError) {
    console.log("Upgrade to Trader to access price history");
  } else {
    throw err;
  }
}

List sets / games

const sets = await tcg.sets.list({ game: "pokemon", limit: 10 });
const games = await tcg.games.list();

Read rate-limit info

await tcg.cards.search({ q: "pikachu" });
console.log(tcg.rateLimit); // { limit: 100000, remaining: 99987 }

Retry on 429 / 5xx

Off by default — opt in explicitly:

const tcg = new TcgLookupClient({
  apiKey: process.env.TCG_API_KEY!,
  retry: { attempts: 3, baseDelayMs: 500 },
});

Error handling

Every non-2xx response is mapped to a typed error you can instanceof-check:

All of them extend TcgLookupError and expose .status, .url, .body, and .message.

import { TcgLookupClient, RateLimitError } from "@tcgpricelookup/sdk";

try {
  await tcg.cards.search({ q: "pikachu" });
} catch (err) {
  if (err instanceof RateLimitError) {
    console.log("Slow down. Backend says:", err.message);
  } else {
    throw err;
  }
}

Supported games

Plan tiers

The Free tier returns raw TCGPlayer prices only. The ebay price block, graded price block, and the cards.history() endpoint require the Trader plan or above. The SDK surfaces this as a PlanAccessError (HTTP 403) so you can branch in code.

See https://tcgpricelookup.com/pricing for current quotas.

API reference

The full HTTP API reference, parameters, and response shapes live at https://tcgpricelookup.com/docs/api-reference.

Sister SDKs

Same API, different language. Pick whichever fits your stack.

• tcglookup-py — Python (PyPI: tcglookup)
• tcglookup-go — Go (github.com/TCG-Price-Lookup/tcglookup-go)
• tcglookup-rs — Rust (crates.io: tcglookup)
• tcglookup-php — PHP (Packagist: tcgpricelookup/sdk)
• tcglookup CLI — Terminal client (npm: tcglookup)
• tcg-api-examples — Runnable code samples in 8 languages
• tcg-discord-bot — Self-hosted Discord bot built on this SDK

The full developer ecosystem index lives at awesome-tcg.

License

MIT © TCG Price Lookup