PokeTrace
←Back to Blog
Developer Resources/January 28, 2026/15 min read

PokeTrace API Developer Guide

The PokeTrace API provides real-time pricing data for over 60,000+ Pokemon cards. This guide covers everything you need to integrate the API into your application: authentication, endpoints, response formats, error handling, and production best practices.

Code editor showing PokeTrace API integration with JSON response data
Build Pokemon card applications with real pricing data from US and EU markets

Access PSA, BGS, and CGC graded prices alongside raw card values from TCGPlayer, eBay, and CardMarket.

01

Quick Start

Get up and running in three steps: (1) Create an account at poketrace.com/dashboard, (2) Generate an API key, (3) Add the X-API-Key header to your requests. That's it—you're ready to query card data.

The base URL for all API requests is https://api.poketrace.com/v1. All endpoints require authentication via the X-API-Key header. The API returns JSON responses with consistent structure across all endpoints.

Check API status at status.poketrace.com. For WebSocket real-time updates (Scale plan only), connect to wss://api.poketrace.com/ws with your API key.

02

Authentication

All API requests require an API key passed in the X-API-Key header. Keys are free to create and rate limits are enforced per account, not per key—create multiple keys for different projects without splitting your quota.

Steps

  1. 1.Sign up at poketrace.com/dashboard
  2. 2.Click 'Create' to generate a new API key
  3. 3.Copy your key (format: pc_xxxxxxxx)
  4. 4.Include X-API-Key: YOUR_KEY in request headers
cURL
curl -H "X-API-Key: pc_your_key" https://api.poketrace.com/v1/cards
JavaScript
fetch('https://api.poketrace.com/v1/cards', {
  headers: { 'X-API-Key': 'pc_your_key' }
})
Python
Never commit API keys to public repositories. Use environment variables: process.env.POKETRACE_API_KEY in Node.js or os.environ['POKETRACE_API_KEY'] in Python.
03
API Endpoints
The API provides four core endpoints. Cards are separated by market—US cards have TCGPlayer and eBay data, EU cards have CardMarket data.
GET /v1/cards
List cards with pagination and filters. Returns basic card info with nested prices by source and tier.
Params: limit (max 20), cursor, set, search, card_number, variant, market (US/EU), has_graded, tcgplayer_ids, cardmarket_ids
GET /v1/cards?market=US&set=base-set&limit=20
Response:
{
  "data": [{
    "id": "019bff77-befa-771d-bab0-f5909f0a78c9",
    "name": "Charizard",
    "cardNumber": "4/102",
    "set": { "slug": "base-set", "name": "Base Set" },
    "variant": "Holofoil",
    "rarity": "Rare Holo",
    "market": "US",
    "currency": "USD",
    "prices": {
      "ebay": {
        "NEAR_MINT": { "avg": 890, "low": 750, "high": 1050, "saleCount": 156 }
      },
      "tcgplayer": {
        "NEAR_MINT": { "avg": 420, "low": 380, "high": 480, "saleCount": 89 }
      }
    }
  }],
  "pagination": { "hasMore": true, "nextCursor": "YnNfNQ==", "count": 1 }
}
GET /v1/cards/:id
Get full card details with pricing by source and tier. US cards include ebay (all tiers) + tcgplayer (raw only). EU cards include cardmarket (Price Trend with historical averages) + cardmarket_unsold (active listings with tier/country breakdown).
GET /v1/cards/019bff77-befa-771d-bab0-f5909f0a78c9
Response:
// US Card
{
  "data": {
    "id": "019bff77-befa-771d-bab0-f5909f0a78c9",
    "name": "Charizard",
    "market": "US",
    "currency": "USD",
    "prices": {
      "ebay": {
        "PSA_10": { "avg": 5200, "low": 4800, "high": 5600, "saleCount": 47 },
        "NEAR_MINT": { "avg": 890, "low": 750, "high": 1050, "saleCount": 156 }
      },
      "tcgplayer": {
        "NEAR_MINT": { "avg": 420, "low": 380, "high": 480, "saleCount": 89 }
      }
    }
  }
}

// EU Card
{
  "data": {
    "id": "eu_273550",
    "name": "Charizard",
    "market": "EU",
    "currency": "EUR",
    "prices": {
      "cardmarket": { "avg": 385, "avg1d": 380, "avg7d": 375, "avg30d": 370 },
      "cardmarket_unsold": {
        "NEAR_MINT": { "avg": 420, "low": 350, "high": 890, "saleCount": 125, "country": { "DE": { "avg": 410 }, "FR": { "avg": 450 } } }
      }
    }
  }
}
GET /v1/sets
List all card sets with metadata. Use set slugs to filter cards.
Params: search, game (pokemon, pokemon-japanese), limit, cursor
GET /v1/sets?search=base&limit=5
Response:
{
  "data": [
    { "slug": "base-set", "name": "Base Set", "releaseDate": "1999-01-09", "cardCount": 102 },
    { "slug": "base-set-2", "name": "Base Set 2", "releaseDate": "2000-02-24", "cardCount": 130 }
  ],
  "pagination": { "hasMore": true, "nextCursor": "YmFzZS1zZXQtMg==", "count": 2 }
}
GET /v1/auth/info
Get your API key info and usage stats. Check remaining requests, reset time, and plan details.
GET /v1/auth/info
Response:
{
  "data": {
    "key": "pc_a1b2c3d4...",
    "name": "Production",
    "active": true,
    "createdAt": "2026-01-17T10:00:00Z",
    "lastUsedAt": "2026-01-17T12:30:00Z",
    "user": {
      "plan": "Free",
      "remaining": 208,
      "limit": 250,
      "resetsAt": "2026-01-18T00:00:00Z"
    }
  }
}
GET /v1/cards/:id/prices/:tier/history
Get historical price data for a specific tier. Useful for charts and trend analysis.
Params: period (7d, 30d, 90d, 1y, all), limit, cursor
GET /v1/cards/019bff77.../prices/PSA_10/history?period=30d
Response:
{
  "data": [
    { "date": "2026-01-27", "source": "ebay", "avg": 5200, "low": 4800, "high": 5600, "saleCount": 3 },
    { "date": "2026-01-26", "source": "ebay", "avg": 5150, "low": 4750, "high": 5500, "saleCount": 5 }
  ],
  "pagination": { "hasMore": true, "nextCursor": "MjAyNi0wMS0yNQ==", "count": 2 }
}
04
Rate Limits
Rate limits are enforced per account, not per key. Burst limits are per API key and plan-based: Free 1/2s, Pro 30/10s, Scale 60/10s. Daily limits reset at midnight UTC. Every response includes headers showing your current usage.
Free
250 / day
US only (eBay, TCGPlayer)
Raw conditions only
Pro
10,000 / day
US (eBay, TCGPlayer) + EU (Cardmarket)
Raw + Graded (PSA, BGS, CGC)
Scale
100,000 / day
US (eBay, TCGPlayer) + EU (Cardmarket)
Raw + Graded + WebSocket
Response Headers
  • X-RateLimit-Limit — Your plan's daily request limit
  • X-RateLimit-Remaining — Daily requests remaining
  • X-RateLimit-Reset — ISO8601 timestamp when daily limit resets
  • X-Plan — Your current plan (Free, Pro, Scale)
Cache responses aggressively. Prices update every few hours—caching for 15-60 minutes reduces API calls significantly.
05
Complete Code Examples
Copy-paste these examples to get started. Replace YOUR_KEY with your actual API key.
JavaScript / Node.js
const API_KEY = process.env.POKETRACE_API_KEY;
const BASE_URL = 'https://api.poketrace.com/v1';

async function getCard(cardId) {
  const response = await fetch(`${BASE_URL}/cards/${cardId}`, {
    headers: { 'X-API-Key': API_KEY }
  });
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }
  
  return response.json();
}

async function searchCards(query, market = 'US') {
  const params = new URLSearchParams({ search: query, market, limit: '20' });
  const response = await fetch(`${BASE_URL}/cards?${params}`, {
    headers: { 'X-API-Key': API_KEY }
  });
  return response.json();
}

// Usage
const card = await getCard('019bff77-befa-771d-bab0-f5909f0a78c9');
console.log(`${card.data.name}: $${card.data.prices.ebay.PSA_10.avg} (PSA 10)`);
Python
cURL
# Get a single card
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.poketrace.com/v1/cards/019bff77-befa-771d-bab0-f5909f0a78c9"

# Search for cards
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.poketrace.com/v1/cards?search=charizard&market=US&limit=10"

# List all sets
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.poketrace.com/v1/sets?limit=50"

# Check your usage
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.poketrace.com/v1/auth/info"

# Get price history
curl -H "X-API-Key: YOUR_KEY" \
  "https://api.poketrace.com/v1/cards/019bff77.../prices/PSA_10/history?period=30d"
06
Error Handling
The API uses standard HTTP status codes. All error responses include error and message fields.
400
Bad Request
Invalid parameters
{ "error": "Invalid limit parameter", "message": "Limit must be between 1 and 20" }
401
Unauthorized
Missing or invalid API key
{ "error": "API key required", "message": "Include your API key in the X-API-Key header" }
403
Forbidden
Plan upgrade required
{ "error": "Pro plan required", "message": "Graded card prices require a Pro plan.", "code": "UPGRADE_REQUIRED" }
404
Not Found
Resource doesn't exist
{ "error": "Card not found", "message": "No card exists with this ID" }
429
Rate Limited
Too many requests
{ "error": "Rate limit exceeded", "message": "Daily limit reached. Resets at 2026-01-18T00:00:00Z", "retryAfter": 3600 }
For 429 errors, use the retryAfter field (seconds) or X-RateLimit-Reset header. Implement exponential backoff: wait 1s, then 2s, then 4s between retries.
07
Frequently Asked Questions
What's the difference between US and EU cards?
Cards are market-specific. US cards have TCGPlayer and eBay pricing in USD. EU cards have CardMarket pricing in EUR with per-country breakdowns (DE, FR, IT, etc.). Each card belongs to one market only.
Which grading companies are supported?
We support 15 grading companies including PSA, BGS, CGC, ACE, TAG, and more. Graded prices are available on Pro and Scale plans. The gradedOptions field on each card shows available grades.
How do I get real-time price updates?
WebSocket connections are available on the Scale plan. Connect to wss://api.poketrace.com/ws with your API key. Subscribe to specific cards to receive instant price updates when new sales occur.
Can I use the API for commercial projects?
Yes. Free tier allows non-commercial use. Pro and Scale plans include commercial licenses. Check our terms of service for full details.
How accurate is the pricing data?
Prices are based on verified completed sales from TCGPlayer, eBay, and CardMarket. We update every few hours. Each price tier includes a confidence score (high, medium, low) and saleCount so you can assess reliability.
Start Building Today
Get your free API key and start building Pokemon card applications. 250 requests per day, no credit card required.
Get Free API Key→