Skip to content
TTCGAPIs

V2 developer documentation

Make the first request in minutes.

Follow the v2 catalog flow, authenticate with an x-api-key header, then add pricing, sales, listings, recognition or PSA data as your credits or plan allow.

Developer reference

API documentation

Start with v2, then drill into authentication, endpoints, errors, and access requirements.

Downloads a build-ready reference with API-key placeholders.

New accounts receive 100 free credits, no card needed, for all customer data API endpoints, including pricing, history, listings, PSA, board games and recognition. Credits pay for requests: 1 credit for a catalog lookup, 2 for a price or certificate lookup, 5 for live listings. After your free credits are used, buy a credit pack (from £10, no subscription) or choose a monthly plan. Each endpoint below shows its credit cost and how many calls it takes on each monthly plan; the full rules are under Credits and rate limits. Normal endpoint and pagination limits still apply.

V2 API Endpoints

The V2 API provides streamlined, high-performance endpoints with cleaner response formats. V2 endpoints return only the fields you need with consistent response structures.

V2 Base URL

https://api.tcgapis.com/api/v2

1. Get All Games

GET /api/v2/games

Public endpoint - no authentication required

Returns a paginated list of all supported trading card games with their category IDs.

Query Parameters (optional)

  • limit (integer): Number of results per page (default: 25, max: 100)
  • offset (integer): Number of results to skip (default: 0)

Example Request

curl -X GET "https://api.tcgapis.com/api/v2/games?limit=25&offset=0"

Example response (illustrative; arrays may be abbreviated)

// Public endpoint: inspect the returned page and its actual counts.
const response = await fetch('https://api.tcgapis.com/api/v2/games?limit=25&offset=0');
const body = await response.json();
if (!response.ok || !body.success) throw new Error(body.error || 'Request failed');
console.log(body.data); // Objects with categoryId, name, displayName and optional image
console.log(body.count, body.total, body.offset, body.limit);

2. Get Expansions by Category ID

GET /api/v2/expansions/{categoryId}

Credits (free or bought), 1 per request · monthly plans: 1 call

Returns paginated expansions for a specific game, sorted by release date (newest first).

Path Parameters

  • categoryId (integer): The category ID of the game

Query Parameters (optional)

  • limit (integer): Number of results per page (default: 25, max: 100)
  • offset (integer): Number of results to skip (default: 0)

Example Request

curl -X GET "https://api.tcgapis.com/api/v2/expansions/3?limit=25&offset=0" \
  -H "x-api-key: YOUR_API_KEY"

Example response (illustrative; arrays may be abbreviated)

{
  "success": true,
  "count": 25,
  "total": 150,
  "offset": 0,
  "limit": 25,
  "data": [
    {
      "groupId": 23551,
      "name": "Base Set",
      "abbreviation": "BS",
      "publishedOn": "1999-01-09T00:00:00.000Z"
    }
  ]
}

3. Get Cards by Group ID

GET /api/v2/cards/{groupId}

Credits (free or bought), 1 per request · monthly plans: 1 call

Returns paginated cards in an expansion, sorted alphabetically by name.

Path Parameters

  • groupId (integer): The group ID of the expansion

Query Parameters (optional)

  • limit (integer): Number of results per page (default: 25, max: 100)
  • offset (integer): Number of results to skip (default: 0)

Example Request

curl -X GET "https://api.tcgapis.com/api/v2/cards/23551" \
  -H "x-api-key: YOUR_API_KEY"

Example response (illustrative; arrays may be abbreviated)

{
  "success": true,
  "count": 25,
  "total": 102,
  "offset": 0,
  "limit": 25,
  "data": [
    {
      "productId": 87,
      "name": "Charizard",
      "image": "https://...",
      "rarity": "Rare Holo",
      "number": "4",
      "cleanName": "charizard"
    }
  ]
}

4. Get Prices by Product ID

GET /api/v2/prices/{productId}

Credits (free or bought), 2 per request · monthly plans: 1 call

Retrieve pricing information for a specific product.

Path Parameters

  • productId (integer): The product ID to get prices for

Example Request

curl -X GET "https://api.tcgapis.com/api/v2/prices/130289" \
  -H "x-api-key: YOUR_API_KEY"

Illustrative Response

Schema example only, not a current quote. Prices are grouped by printing; fields can be null or absent. TCGPlayer values are USD. The timestamp belongs to the record.

{
  "success": true,
  "data": {
    "productId": 130289,
    "prices": {
      "Normal": {
        "productId": 130289,
        "lowPrice": 1.25,
        "midPrice": 1.5,
        "highPrice": 4,
        "marketPrice": 1.4,
        "directLowPrice": null
      }
    },
    "last_updated": "2026-11-01T12:00:00Z"
  }
}

lowPrice, midPrice and highPrice describe for-sale listing references. marketPrice is a sales-derived reference, not an individual transaction. Use sales-history endpoints for completed-sale records.

5. Get Live Listings by Product ID

GET /api/v2/livelistings/{productId}

Credits (free or bought), 5 per request · monthly plans: 1 call on Unlimited, 5 on Hobby and Business

Retrieve the available listing snapshot for a product; caching and stored fallback can affect freshness.

Path Parameters

  • productId (integer): The product ID to get live listings for

Example Request

curl -X GET "https://api.tcgapis.com/api/v2/livelistings/3138" \
  -H "x-api-key: YOUR_API_KEY"

6. Get Sales History by Product ID

GET /api/v2/sales-history/{productId}

Credits (free or bought), 2 per request · monthly plans: 1 call

Retrieve recent completed source sales, which may be cached for up to four hours. Each returned price is the purchase price plus shipping, in USD; it is not a current asking price. Statistics are computed over the fetched source sample before pagination, not the complete market history. The statistics object contains last24Hours, priceAnalysis and byVariant. In this response, lastUpdated is response-preparation time, not an upstream freshness guarantee.

Path Parameters

  • productId (string): TCGPlayer product ID

Query Parameters (optional)

  • limit (integer): Number of sales per page (default: 25, max: 100)
  • offset (integer): Number of sales to skip (default: 0)

Example Request

curl -X GET "https://api.tcgapis.com/api/v2/sales-history/87" \
  -H "x-api-key: YOUR_API_KEY"

Inspect the actual response

// Run server-side with credits (2 per request) or a monthly plan (1 call), and a verified product ID.
const productId = process.env.TCGAPIS_PRODUCT_ID;
const response = await fetch('https://api.tcgapis.com/api/v2/sales-history/' + productId + '?limit=25&offset=0', {
  headers: { 'x-api-key': process.env.TCGAPIS_KEY }
});
const body = await response.json();
if (!response.ok || !body.success) throw new Error(body.error || 'Sales unavailable');
console.log(body.data.sales);
console.log(body.data.statistics); // last24Hours, priceAnalysis, byVariant
console.log(body.data.count, body.data.total, body.data.offset, body.data.limit);
// The upstream request is bounded; this is not the full market transaction history.

7. Get Full Sales History (filterable archive)

GET /api/v2/sales-history/{productId}/full

Credits (free or bought), 2 per request · monthly plans: 1 call

Reads available stored completed-sale archive rows in three-day buckets per condition, variant and language. The sold-price fields are lowSalePrice and highSalePrice; the corresponding WithShipping fields include shipping. marketPrice is a separate market estimate, not the price of every transaction. History depth and gaps depend on the product. Distinct from /sales-history/:productId, which returns recent source transactions cached for up to four hours. Use this when you need filtered historic series for charting, valuation models, or per-condition inventory pricing.

Path Parameters

  • productId (integer): TCGPlayer product ID

Query Parameters (all optional)

  • condition — comma-separated for OR (e.g. Near Mint,Lightly Played). Case-insensitive.
  • variant — comma-separated (e.g. Normal,Foil).
  • language — comma-separated (e.g. English,Japanese).
  • skuId — pin to a single SKU.
  • from / to — ISO dates YYYY-MM-DD; filter on bucketStartDate.
  • salesOnly — true to drop zero-volume buckets (price-only snapshots).
  • limit / offset — pagination over the flattened row set.

Example Requests

# All buckets, all SKUs
curl "https://api.tcgapis.com/api/v2/sales-history/660570/full" \
  -H "x-api-key: YOUR_API_KEY"

# Near Mint Normal English only, illustrative fixed date range
curl "https://api.tcgapis.com/api/v2/sales-history/660570/full?condition=Near%20Mint&variant=Normal&language=English&from=2026-04-06&to=2026-05-05" \
  -H "x-api-key: YOUR_API_KEY"

# Drop zero-volume buckets, get only days where sales actually happened
curl "https://api.tcgapis.com/api/v2/sales-history/660570/full?salesOnly=true" \
  -H "x-api-key: YOUR_API_KEY"

Response Shape

{
  "success": true,
  "count": 25,
  "total": 1320,
  "offset": 0,
  "limit": 25,
  "data": {
    "productId": 660570,
    "name": "Badgermole Cub",
    "gameName": "Magic: The Gathering",
    "expansionName": "Avatar: The Last Airbender",
    "isSingle": true,
    "isSealed": false,
    "summary": {
      "avgMarketPrice": 36.66,
      "minMarketPrice": 0,
      "maxMarketPrice": 69.64,
      "totalSalesAllBuckets": 2110,
      "totalSalesLastBucket": 112,
      "lastBucketDate": "2026-05-02",
      "lastUpdated": "2026-05-05T12:16:35.318Z"
    },
    "available": {
      "skus": [
        { "skuId": "8977472", "condition": "Near Mint", "variant": "Normal", "language": "English" }
      ],
      "conditions": ["Damaged", "Heavily Played", "Lightly Played", "Moderately Played", "Near Mint"],
      "variants": ["Foil", "Normal"],
      "languages": ["English"]
    },
    "rows": [
      {
        "skuId": "8977472",
        "condition": "Near Mint",
        "variant": "Normal",
        "language": "English",
        "bucketStartDate": "2026-05-02",
        "marketPrice": 50.58,
        "quantitySold": 82,
        "transactionCount": 64,
        "lowSalePrice": 44.10,
        "lowSalePriceWithShipping": 45.98,
        "highSalePrice": 64.41,
        "highSalePriceWithShipping": 64.41
      }
    ]
  }
}

8. Get Historic Prices by Product ID

GET /api/v2/historic-prices/{productId}

Credits (free or bought), 2 per request · monthly plans: 1 call

Returns long-term daily price snapshots for a TCGPlayer product. The response contains a prices map keyed by date (YYYY-MM-DD); each date has per-printing entries (for example Normal, Foil or Reverse Holofoil; available keys vary by product) carrying lowPrice, midPrice, highPrice, marketPrice, and directLowPrice. Use this for charting trend lines or computing rolling averages. These are snapshots of price-guide metrics, not completed-sale records. Use the sales-history endpoints for sold prices.

Path Parameters

  • productId (integer): TCGPlayer product ID

Example Request

curl -X GET "https://api.tcgapis.com/api/v2/historic-prices/130289" \
  -H "x-api-key: YOUR_API_KEY"

Response Shape

{
  "success": true,
  "data": {
    "productId": 130289,
    "createdAt": "2026-01-30T23:46:34.092Z",
    "prices": {
      "2024-02-19": {
        "Foil":   { "directLowPrice": 0.04, "highPrice": 5.99, "lowPrice": 0.04, "marketPrice": 0.05, "midPrice": 0.28 },
        "Normal": { "directLowPrice": 0.01, "highPrice": 8.00, "lowPrice": 0.01, "marketPrice": 0.02, "midPrice": 0.15 }
      },
      "2024-02-20": { ... },
      ...
    }
  }
}

Per-Variant Price Fields

  • lowPrice — lowest for-sale listing price in that day's snapshot
  • midPrice — median for-sale listing price in that day's snapshot
  • highPrice — highest for-sale listing price in that day's snapshot; asking-price outliers are possible
  • marketPrice — TCGPlayer's sales-derived market-price estimate recorded in that day's snapshot; not an individual sale or the daily closing transaction
  • directLowPrice — lowest TCGPlayer Direct for-sale listing price in the snapshot (may be null)

See TCGPlayer's price-point definitions for the distinction between sales-derived market prices and listed asking prices.

V2 endpoints: credit cost and monthly plan

Every protected endpoint works with credits (free or bought) and on every monthly plan. On a monthly plan a request takes 1 call, except live listings, which take 5 calls on Hobby and Business and 1 on Unlimited.

EndpointCredits per requestCalls per request on a monthly plan
/api/v2/games0Public
/api/v2/expansions/:categoryId11 on every plan
/api/v2/cards/:groupId11 on every plan
/api/v2/prices/:productId21 on every plan
/api/v2/livelistings/:productId5Hobby 5 · Business 5 · Unlimited 1
/api/v2/sales-history/:productId21 on every plan
/api/v2/sales-history/:productId/full21 on every plan
/api/v2/historic-prices/:productId21 on every plan