@pokesats/api

Official TypeScript SDK for the PokéSats Data API — the Bitcoin-native REST API for Pokémon TCG market data.

Every price returned in sats alongside USD and CAD. Sealed expected-value math, 30-day sats-movers leaderboard, live PokéSats marketplace inventory, daily eBay price history for 2,773 cards.

Install

npm install @pokesats/api
# or
pnpm add @pokesats/api
# or
yarn add @pokesats/api

Requires Node.js 18 or newer (global fetch). Works in browsers, Bun, Deno, Cloudflare Workers, and any environment with fetch.

Quickstart

Get a free API key at pokesats.com/account/api-keys. Free tier: 1,000 credits/month at 10 requests/minute, no credit card.

import { PokeSatsClient } from "@pokesats/api";

const pokesats = new PokeSatsClient({
  apiKey: process.env.POKESATS_API_KEY!,
});

// Shadowless Charizard, current price
const charizard = await pokesats.cards.prices("base1-4");
console.log(charizard.prices.raw?.sats, "sats");

// Top 5 cards beating Bitcoin over 30 days
const movers = await pokesats.satsMovers({ cut: "gainers", limit: 5 });
movers.movers.forEach((m) =>
  console.log(m.name, m.sats_change_pct + "% in sats")
);

// Expected value of a Lost Origin booster box
const sealed = await pokesats.sealed.get("lost-origin-booster-box");
console.log(sealed.product.expected_box_value.sats, "sats EV");

All methods

await pokesats.btcPrice();                                      // current BTC/USD + BTC/CAD
await pokesats.cards.prices("base1-4");                         // single card
await pokesats.cards.priceHistory("swsh7-95", { days: 90 });    // daily snapshots
await pokesats.cards.population("swsh7-95");                    // PSA pop
await pokesats.cards.search({ name: "Charizard", page_size: 10 });
await pokesats.sets();                                          // every Pokémon set
await pokesats.inventory({ type: "slab", limit: 25 });          // PokéSats marketplace
await pokesats.satsMovers({ cut: "gainers" });                  // 30d sats leaderboard
await pokesats.sealed.list();                                   // all sealed EV models
await pokesats.sealed.get("lost-origin-booster-box");           // single sealed product

Every response includes a btc block with the BTC/USD and BTC/CAD rate used to compute the sats columns, plus an updated_at ISO timestamp. Responses are also tagged with X-PokeSats-BTC-USD and X-PokeSats-BTC-CAD headers.

Error handling

All client methods throw on non-2xx responses. The thrown error is a standard Error with extra fields:

import { PokeSatsClient, type ApiError } from "@pokesats/api";

try {
  const card = await pokesats.cards.prices("unknown-card-id");
} catch (e) {
  const err = e as ApiError;
  console.log(err.status);              // 404
  console.log(err.code);                // "not_found"
  console.log(err.message);             // human-readable
  console.log(err.retryAfterSeconds);   // null unless rate-limited
}

Error codes match the API:

• unauthorized (401) — missing or invalid API key
• forbidden (403) — endpoint not included in your tier
• not_found (404)
• rate_limited (429) — per-minute limit exceeded
• quota_exceeded (402) — monthly quota used up
• bad_request (400)
• internal_error (500/502)

Custom fetch / base URL

// Custom fetch (e.g. for proxy, instrumentation):
const pokesats = new PokeSatsClient({
  apiKey: "psk_live_...",
  fetch: customFetch,
});

// Custom base URL (e.g. local dev against a wrangler dev server):
const pokesats = new PokeSatsClient({
  apiKey: "psk_test_...",
  baseUrl: "http://localhost:8787/v1",
});

Bitcoin-native by default

Every endpoint returns a sats column computed against live Coinbase BTC FX (5-min edge cache). The sats value is always within five minutes of fresh, even on snapshot data captured days ago.

If you want to do your own conversion, every response also includes the BTC rate used:

const card = await pokesats.cards.prices("base1-4");
const myFavoriteFiat = card.prices.raw!.usd * customFxRate;
const mySats = Math.round((card.prices.raw!.usd / card.btc.usd) * 100_000_000);

Pricing

• Free: 1,000 credits / month, 10 req/min, no credit card
• Sats $9/mo: 50,000 credits, 60 req/min
• Stack $49/mo: 250,000 credits, 300 req/min + sats-movers + price history
• Vault: custom, contact [email protected]

Full pricing + tier comparison · Developer docs · OpenAPI 3.1 spec

License

MIT