@poketrace/sdk

The official TypeScript SDK for PokeTrace — real-time Pokemon card prices from TCGPlayer and eBay, PSA / BGS / CGC graded values, daily price history, and market movers.

Every Pokemon card ever printed. English + Japanese. Raw + graded. Updated daily.

Install

npm install @poketrace/sdk
# or
pnpm add @poketrace/sdk
# or
yarn add @poketrace/sdk

Quick Start

import { PokeTrace } from "@poketrace/sdk";

const client = new PokeTrace({ apiKey: "pc_your_api_key" });

// Search for cards
const cards = await client.cards.list({
  search: "Charizard",
  market: "US",
  has_graded: true,
});

// Get detailed pricing
const card = await client.cards.get(cards.data[0].id);
console.log(card.data.prices.ebay.PSA_10.avg);

API Surface

Cards

// Search / filter cards
const cards = await client.cards.list({
  search: "Pikachu",
  set: "base-set",
  variant: "Holofoil",
  market: "EU",
  tcgplayer_ids: ["123", "456"],
  has_graded: true,
});

for (const card of cards.data) {
  console.log(card.name, card.market, card.currency);
  console.log(card.prices);
}

// Get one card by UUID
const card = await client.cards.get("card-uuid");
console.log(card.data.name);
console.log(card.data.refs.tcgplayerId);
console.log(card.data.gradedOptions);
console.log(card.data.prices.ebay.NEAR_MINT.avg);

// Daily price history
const history = await client.cards.history("card-uuid", "PSA_10", {
  period: "90d",
  limit: 50,
});
for (const point of history.data) {
  console.log(point.date, point.source, point.avg, point.saleCount);
}

// Top gainers / losers
const movers = await client.cards.movers({
  market: "US",
  direction: "gainers",
  min_price: 20,
});
for (const item of movers.data) {
  console.log(item.name, item.tier, item.changePct);
}

// eBay sold listings for a card
const listings = await client.cards.listings("card-uuid", {
  grader: "PSA",
  grade: "10",
  sort: "sold_at_desc",
});
for (const listing of listings.data) {
  console.log(listing.title, listing.price, listing.soldAt);
}

Sets

const sets = await client.sets.list({
  search: "Base",
  game: "pokemon",
});

const set = await client.sets.get("base-set");
console.log(set.data.externalIds.tcgplayer);

Auth

const info = await client.auth.info();
console.log(info.data.user.plan);            // 'Free' | 'Pro' | 'Scale'
console.log(info.data.user.daily.remaining); // requests left today
console.log(info.data.user.daily.resetsAt);  // next reset time

Error Handling

import {
  PokeTrace,
  PokeTraceError,
  AuthenticationError,
  ForbiddenError,
  NotFoundError,
  RateLimitError,
} from "@poketrace/sdk";

const client = new PokeTrace({ apiKey: "pc_your_key" });

try {
  await client.cards.get("missing-id");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log("Card not found");
  } else if (error instanceof AuthenticationError) {
    console.log("Invalid API key");
  } else if (error instanceof ForbiddenError) {
    console.log("Plan upgrade required — visit poketrace.com");
  } else if (error instanceof RateLimitError) {
    console.log("Rate limited, retry after:", error.retryAfter);
  } else if (error instanceof PokeTraceError) {
    console.log(error.status, error.message);
  }
}

What data is available?

Data	Description	Plan
TCGPlayer market prices	Market / low / mid / high for every condition	Free
eBay sold averages	1-day, 7-day, 30-day rolling averages of actual completed sales	Free
Graded prices	PSA, BGS, CGC, SGC, ACE, TAG — every grade from 1 to 10	Free
Price history	Daily price snapshots for up to 1 year	Pro
Market movers	Top gainers and losers by percentage change	Pro
Sold listings	Individual eBay completed sale records	Pro

License

MIT