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/v21. Get All Games
GET /api/v2/gamesPublic 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}/fullCredits (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 datesYYYY-MM-DD; filter onbucketStartDate.salesOnly—trueto 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 snapshotmidPrice— median for-sale listing price in that day's snapshothighPrice— highest for-sale listing price in that day's snapshot; asking-price outliers are possiblemarketPrice— TCGPlayer's sales-derived market-price estimate recorded in that day's snapshot; not an individual sale or the daily closing transactiondirectLowPrice— 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.
| Endpoint | Credits per request | Calls per request on a monthly plan |
|---|---|---|
| /api/v2/games | 0 | Public |
| /api/v2/expansions/:categoryId | 1 | 1 on every plan |
| /api/v2/cards/:groupId | 1 | 1 on every plan |
| /api/v2/prices/:productId | 2 | 1 on every plan |
| /api/v2/livelistings/:productId | 5 | Hobby 5 · Business 5 · Unlimited 1 |
| /api/v2/sales-history/:productId | 2 | 1 on every plan |
| /api/v2/sales-history/:productId/full | 2 | 1 on every plan |
| /api/v2/historic-prices/:productId | 2 | 1 on every plan |