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 plan requires.

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.

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"

Response

{
  "success": true,
  "count": 25,
  "total": 42,
  "offset": 0,
  "limit": 25,
  "data": [
    {
      "categoryId": 1,
      "name": "Magic",
      "displayName": "Magic: The Gathering"
    }
  ]
}

2. Get Expansions by Category ID

GET /api/v2/expansions/{categoryId}

Requires Hobby plan or higher

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"

Response

{
  "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}

Requires Hobby plan or higher

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"

Response

{
  "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}

Requires Business or Unlimited plan

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"

5. Get Live Listings by Product ID

GET /api/v2/livelistings/{productId}

Requires Unlimited plan

Retrieve real-time marketplace listings for a specific product.

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}

Requires Business or Unlimited plan

Retrieve paginated historical sales data with statistics and price trend analysis. Statistics are computed over the full dataset regardless of pagination.

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"

Response

{
  "success": true,
  "data": {
    "sales": [
      {
        "date": "2026-01-25T17:53:29.187Z",
        "marketplace": "TCGPlayer",
        "condition": "Near Mint",
        "price": 49.99,
        "variant": "Normal"
      }
    ],
    "count": 25,
    "total": 145,
    "offset": 0,
    "limit": 25,
    "statistics": {
      "last24Hours": { "total": 5, "byVariant": { "Normal": 4, "Foil": 1 } },
      "priceAnalysis": { "trend": "increasing", "percentChange": 8.5 },
      "byVariant": {
        "Normal": {
          "count": 145,
          "averagePrice": 48.50,
          "medianPrice": 47.99,
          "priceTrend": "stable",
          "highestPrice": 65.00,
          "lowestPrice": 35.00
        }
      }
    },
    "lastUpdated": "2026-01-25T18:00:00.000Z"
  }
}

7. Get Full Sales History (filterable archive)

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

Requires Business or Unlimited plan

Reads from our stored sales archive — 90+ days of 3-day rolling buckets per (condition + variant + language) SKU. Distinct from /sales-history/:productId (which returns the live recent-transactions feed from TCGPlayer). 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, last 30 days
curl "https://api.tcgapis.com/api/v2/sales-history/660570/full?condition=Near%20Mint&variant=Normal&language=English&from=2026-04-06" \
  -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
      }
    ]
  }
}

7. Get Historic Prices by Product ID

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

Requires Business or Unlimited plan

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-variant entries (Normal, Foil) carrying lowPrice, midPrice, highPrice, marketPrice, and directLowPrice. Use this for charting trend lines or computing rolling averages.

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 sold price for the day
  • midPrice — median sold price for the day
  • highPrice — highest sold price for the day
  • marketPrice — TCGPlayer's computed market price for the day
  • directLowPrice — lowest TCGPlayer Direct price for the day (may be null if no Direct listings)

V2 Endpoint Tier Requirements

EndpointMinimum Plan
/api/v2/gamesPublic
/api/v2/expansions/:categoryIdHobby
/api/v2/cards/:groupIdHobby
/api/v2/prices/:productIdBusiness
/api/v2/livelistings/:productIdUnlimited
/api/v2/sales-history/:productIdBusiness
/api/v2/sales-history/:productId/fullBusiness
/api/v2/historic-prices/:productIdBusiness