traded.gg logotraded.gg
Skip to documentation content
On This Page

REST API

API Reference

Endpoints, parameters, and examples for Traded card and market data. New here? Start with the Quick Start.

Using the API

Base URL
https://api.traded.gg
Authentication
Authorization: Bearer $TRADED_API_KEY
Responses
Success includes ok, contract, and data. Errors include error.code. See Errors & Limits.
Defaults & Filters
Game
game=pokemon by default.
Quality
Prices default to quality=all; listings default to quality=verified.
Grade
Omitting grade returns raw:near_mint, except listings, which include all grades. Use the grade map and print data for grades and finishes, not free text.
Card & Set IDs
card_id for one card, card_ids for multiple cards, ids in batch bodies, and set_id for a set. Check each endpoint for its exact parameters.
Resolve IDs
Catalog and market IDs are not interchangeable. Use /v1/resolve to match them. A _ja suffix identifies the Japanese print.
Marketplace
Filter by venue with marketplace.
Dates & Windows
date_from and date_to use YYYY-MM-DD. Mover windows: 7d, 30d, 90d. History buckets: day, week, month.
Single, Batch & Market Requests
One Card
Use a card-scoped route, such as /v1/cards/{card_id}/prices.
Batch
Read up to 100 mixed IDs with POST /v1/cards:batch, POST /v1/prices/history:batch, or GET /v1/prices?ids=….
One Set
Use /v1/sets/{set_id}/market or /v1/sets/{set_id}/population for set-level data.
Market-Wide
Use /v1/market/deals, /v1/market/movers, /v1/sales, or /v1/listings.
Empty Results & Missing IDs
HTTP 200
Resolution and batch reads return a per-ID status or a not_found list, even when an ID is missing.
HTTP 404
Observation reads can return not_found when no rows match. This includes empty summary or history reads, unknown sets on the feed, and per-card deals with no matches.
Era Prints
Era print IDs return only their own cohort. A 1st-edition card ID never returns the plain print's price. A grade with no rows for that era cohort returns a miss, not a neighbouring print's value.

Search & Catalog

Search cards and browse catalog records, sets, and approved image redirects.

Search for cards

GET/v1/search
Required:q
Request · cURL
curl --get 'https://api.traded.gg/v1/search' \
  --data-urlencode 'q=charizard' \
  --data-urlencode 'limit=10' \
  --header "Authorization: Bearer $TRADED_API_KEY"

List catalog cards

GET/v1/catalog/cards
Request · cURL
curl --get 'https://api.traded.gg/v1/catalog/cards' \
  --data-urlencode 'q=charizard' \
  --data-urlencode 'limit=10' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Get a catalog card

GET/v1/catalog/cards/{card_id}
Required:card_id
Request · cURL
curl --request GET \
  'https://api.traded.gg/v1/catalog/cards/sv3pt5-199' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Get catalog cards in a batch

POST/v1/catalog/cards:batch
Request · cURL
curl --request POST \
  'https://api.traded.gg/v1/catalog/cards:batch' \
  --header "Authorization: Bearer $TRADED_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{"ids":["sv3pt5-199"],"game":"pokemon"}'

View a catalog card image

GET/v1/catalog/cards/{card_id}/image
Required:card_id
Request · cURL
curl --request GET \
  'https://api.traded.gg/v1/catalog/cards/sv3pt5-199/image'

List catalog sets

GET/v1/catalog/sets
Request · cURL
curl --get 'https://api.traded.gg/v1/catalog/sets' \
  --data-urlencode 'limit=10' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Get a catalog set

GET/v1/catalog/sets/{set_id}
Required:set_id
Request · cURL
curl --request GET \
  'https://api.traded.gg/v1/catalog/sets/sv3pt5' \
  --header "Authorization: Bearer $TRADED_API_KEY"

View catalog set artwork

GET/v1/catalog/sets/{set_id}/image
Required:set_id
Request · cURL
curl --request GET \
  'https://api.traded.gg/v1/catalog/sets/sv3pt5/image'

Cards

Read card lists, card details, and batch card records.

List cards

GET/v1/cards
Request · cURL
curl --get 'https://api.traded.gg/v1/cards' \
  --data-urlencode 'q=charizard' \
  --data-urlencode 'limit=10' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Get a card

GET/v1/cards/{card_id}
Required:card_id
Request · cURL
curl --request GET \
  'https://api.traded.gg/v1/cards/sv3pt5-199' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Get cards in a batch

POST/v1/cards:batch
Required:ids
Request · cURL
curl --request POST \
  'https://api.traded.gg/v1/cards:batch' \
  --header "Authorization: Bearer $TRADED_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{"ids":["sv3pt5-199"],"game":"pokemon"}'

Prices

Get current card prices, daily price history, and chart context.

Get prices for up to 100 cards

GET/v1/prices
Required:ids
Request · cURL
curl --get 'https://api.traded.gg/v1/prices' \
  --data-urlencode 'ids=sv3pt5-199' \
  --data-urlencode 'grade=raw:near_mint' \
  --data-urlencode 'method=median_3' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Get a card's prices

GET/v1/cards/{card_id}/prices
Required:card_id
Request · cURL
curl --get 'https://api.traded.gg/v1/cards/sv3pt5-199/prices' \
  --data-urlencode 'grades=raw:near_mint' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Get price history

GET/v1/cards/{card_id}/prices/history
Required:card_id
Request · cURL
curl --get 'https://api.traded.gg/v1/cards/sv3pt5-199/prices/history' \
  --data-urlencode 'grade=raw:near_mint' \
  --data-urlencode 'interval=day' \
  --data-urlencode 'limit=30' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Get price history in a batch

POST/v1/prices/history:batch
Required:ids
Request · cURL
curl --request POST \
  'https://api.traded.gg/v1/prices/history:batch' \
  --header "Authorization: Bearer $TRADED_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{"ids":["sv3pt5-199"],"grades":["raw:near_mint"],"game":"pokemon","interval":"day","date_from":"2026-01-01","date_to":"2026-01-31"}'

Get a card's insured value

GET/v1/cards/{card_id}/prices/insured-value
Required:card_id
Request · cURL
curl --request GET \
  'https://api.traded.gg/v1/cards/sv3pt5-199/prices/insured-value' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Get a card's chart series

GET/v1/cards/{card_id}/chart-series
Required:card_id
Request · cURL
curl --request GET \
  'https://api.traded.gg/v1/cards/sv3pt5-199/chart-series' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Sales

Read recent card sales and the market sales feed.

Get recent sales

GET/v1/sales
Request · cURL
curl --request GET \
  'https://api.traded.gg/v1/sales' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Get a card's sales

GET/v1/cards/{card_id}/sales
Required:card_id
Request · cURL
curl --request GET \
  'https://api.traded.gg/v1/cards/sv3pt5-199/sales' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Listings & Deals

Read live listings, listing details, and deal feeds.

Browse listings

GET/v1/listings
Request · cURL
curl --get 'https://api.traded.gg/v1/listings' \
  --data-urlencode 'limit=20' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Get listings for a card

GET/v1/cards/{card_id}/listings
Required:card_id
Request · cURL
curl --get 'https://api.traded.gg/v1/cards/sv3pt5-199/listings' \
  --data-urlencode 'limit=20' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Get listing details

GET/v1/listings/{listing_id}
Required:listing_id
Request · cURL
curl --request GET \
  'https://api.traded.gg/v1/listings/ebay_browse:357622163739' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Find market deals

GET/v1/market/deals
Request · cURL
curl --get 'https://api.traded.gg/v1/market/deals' \
  --data-urlencode 'limit=10' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Find deals for a card

GET/v1/cards/{card_id}/deals
Required:card_id
Request · cURL
curl --get 'https://api.traded.gg/v1/cards/miscp-1/deals' \
  --data-urlencode 'limit=10' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Population

Read card population history and set grading population. grade_key takes the canonical grade-key form (e.g. PSA:10, raw:near_mint).

Get a card's population history

GET/v1/cards/{card_id}/population/history
Required:card_id
Request · cURL
curl --get 'https://api.traded.gg/v1/cards/sv3pt5-199/population/history' \
  --data-urlencode 'grade_key=PSA:10' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Get a set's graded population

GET/v1/sets/{set_id}/population
Required:set_id
Request · cURL
curl --get 'https://api.traded.gg/v1/sets/sv3pt5/population' \
  --data-urlencode 'top_n=10' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Sets

Browse sets and read details about each set.

List sets

GET/v1/sets
Request · cURL
curl --get 'https://api.traded.gg/v1/sets' \
  --data-urlencode 'limit=10' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Get a set

GET/v1/sets/{set_id}
Required:set_id
Request · cURL
curl --request GET \
  'https://api.traded.gg/v1/sets/sv3pt5' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Market

Read card, set, and market-wide movement analytics.

Find market movers

GET/v1/market/movers
Request · cURL
curl --request GET \
  'https://api.traded.gg/v1/market/movers' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Get market data for a card

GET/v1/cards/{card_id}/market
Required:card_id
Request · cURL
curl --request GET \
  'https://api.traded.gg/v1/cards/sv3pt5-199/market' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Get market data for a set

GET/v1/sets/{set_id}/market
Required:set_id
Request · cURL
curl --request GET \
  'https://api.traded.gg/v1/sets/sv3pt5/market' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Metrics

Browse the metric catalog and read uniform metric values across cards and windows. New metrics arrive as data: re-read the catalog instead of refreshing your client.

Median Price

median_price

The median of clean sales in the last 7, 30, or 90 days for the same card and cohort.

Price Change

price_change

Compares that median with the previous period of the same length. Market movers use a separate ranking series.

Reading Metric Values
Discover
Read GET /v1/metric-catalog for supported metrics, windows, subject types, cohort axes, grain, source, availability rules, and methodology versions. Check catalog_version for updates.
Query
POST /v1/metric-values:query returns one row per subject, cohort, metric, and window.
Row Identity
subject_type, subject_id, metric, window, and cohort (including game and grade_key).
Value & Evidence
value, unit, sample size n, as_of, quality, availability, reason, and methodology_version.
Missing Data
value: null with an availability status and reason. Missing data is never reported as zero.
Small Samples
Values are still returned with quality: thin. Check n before relying on them.
Validation
Unsupported metrics, windows, subject types, or cohort axes return 422 with valid values or a narrowing hint. Unsupported finishes are rejected, not blended.
Other Analyses
Use Market to rank movers. Named indexes and ad-hoc research are available through the MCP tools, not this REST reference.
Metric Query Limits
Subject Type
card is supported. set and index currently return 422.
Per Request
Up to 100 subject_ids, 16 metrics, and 5,000 requested cells.
Per Page
Up to 2,000 rows with limit.

Browse the metric catalog

GET/v1/metric-catalog
Request · cURL
curl --get 'https://api.traded.gg/v1/metric-catalog' \
  --data-urlencode 'subject_type=card' \
  --data-urlencode 'limit=2' \
  --header "Authorization: Bearer $TRADED_API_KEY"

Read metric values

POST/v1/metric-values:query
Required:metricssubject_idswindows
Request · cURL
curl --request POST \
  'https://api.traded.gg/v1/metric-values:query' \
  --header "Authorization: Bearer $TRADED_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{"metrics":["price_change"],"windows":["30d"],"subject_type":"card","subject_ids":["sv3pt5-199"],"grades":["raw:near_mint"]}'

Coming Soon

Watchlists and portfolios are planned. They are not available through the API yet.