TypeScript npm Node 18+ / Browser / CF Workers / Bun / Deno

JavaScript & TypeScript SDK

Zero-dependency SDK with native fetch, ESM + CJS dual output, and full TypeScript types against production API shapes.

install npm

$ npm install @tcgpricelookup/sdk

Key Features

Zero Dependencies

Uses native fetch — no axios, no node-fetch, no bloat.

ESM + CJS

Dual package output. Works with any bundler or require().

Universal Runtime

Node 18+, browsers, Cloudflare Workers, Bun, and Deno.

Typed Errors

AuthenticationError, PlanAccessError, RateLimitError — handle with instanceof.

Auto-chunk Batches

Pass any number of IDs — SDK splits into ≤20-ID chunks automatically.

Retry with Backoff

Optional automatic retry on 429 and 5xx with exponential backoff.

Quickstart

quickstart.ts TypeScript

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

// Initialize the client
const tcg = new TcgLookupClient({ apiKey: process.env.TCG_API_KEY! });

// Search for cards
const res = await tcg.cards.search({ q: "charizard", game: "pokemon", limit: 20 });
console.log(res.data[0].name); // "Charizard ex"

// Get a specific card with full price data
const card = await tcg.cards.get("019535a1-d5d0-7c12-a3e8-b7f4c6d8e9a2");
console.log(card.prices.raw.near_mint?.tcgplayer?.market); // e.g. 4.25
console.log(card.prices.graded?.psa?.["10"]?.ebay?.avg_7d);  // Trader+

// Check rate limit state after any request
console.log(tcg.rateLimit); // { limit: 100000, remaining: 99987 }

API Surface

tcg.cards.search(params) Search & batch lookup

// Keyword search with filters
const res = await tcg.cards.search({ q: "charizard", game: "pokemon", set: "obsidian-flames", limit: 20 });

// Batch lookup by IDs — auto-chunks beyond 20
const portfolio = ["uuid1", "uuid2", /* ...100+ IDs */];
const { data } = await tcg.cards.search({ ids: portfolio });

tcg.cards.get(id) Single card with full price breakdown

const card = await tcg.cards.get("019535a1-d5d0-7c12-a3e8-b7f4c6d8e9a2");
console.log(card.name, card.set.name, card.game);
console.log(card.prices.raw.near_mint?.tcgplayer?.market);
console.log(card.prices.raw.near_mint?.ebay?.avg_7d);

tcg.cards.history(id, params) Trader+ required

const history = await tcg.cards.history(card.id, { period: "30d" });
// history.data: array of { date, near_mint: { tcgplayer: { market } } }

tcg.sets.list(params) Browse all sets

const sets = await tcg.sets.list({ game: "pokemon", limit: 10 });
// sets.data[0]: { id, name, series, released_at, card_count }

tcg.games.list() All 8 supported games

const games = await tcg.games.list();
// ['pokemon', 'mtg', 'yugioh', 'lorcana', 'onepiece', ...]

Error Handling

error-handling.ts TypeScript

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

try {
  const card = await tcg.cards.get("some-id");
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error("Invalid API key");
  } else if (err instanceof PlanAccessError) {
    console.error("Upgrade to Trader+ for price history");
  } else if (err instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${ err.retryAfter } seconds`);
  }
}

AuthenticationError

Invalid or missing API key (401)

PlanAccessError

Feature requires a higher plan (403)

RateLimitError

Too many requests. Has .retryAfter (429)

NotFoundError

Card or resource not found (404)

Rate Limit Headers

rate-limits.ts

// After any request the client caches the last rate-limit headers
await tcg.cards.search({ q: "pikachu" });
console.log(tcg.rateLimit);
// { limit: 100000, remaining: 99987, reset: 1712000000 }

Configuration

config.ts

const tcg = new TcgLookupClient({
  apiKey: process.env.TCG_API_KEY!,
  retry: { maxAttempts: 3, initialDelay: 500 },  // optional: retry 429/5xx
  baseUrl: "https://api.tcgpricelookup.com/v1",   // optional: override for testing
});

Links

Start building with JavaScript

Get your free API key and query card prices in minutes.

Get Free API Key Read the Docs