Conventions

Game

Every card and set response includes game, a stable slug (pokemon or one-piece today), and game_name, a display string (Pokemon TCG, One Piece). cards_search, sets_list, and market_movers accept an optional ?game= filter using the same slug, to restrict results to one game.

Identifiers

Treat every id (card or set) as an opaque string; do not parse meaning from it. A slug works everywhere an id does, for both cards and sets. Upstream provider names and ids are never exposed; if your workflow needs to match against a provider catalog, match on card name, set, and number instead.

Money

Prices are an integer market_price_cents plus an explicit currency, always "USD" today. For example, 1299 cents is $12.99. Use integer arithmetic; format dollars only for display. market_price_cents: null means BinderDex has no current price for that variant or condition, which is different from a price of zero.

Time

Timestamps are ISO 8601 UTC with a Z suffix, for example 2026-09-18T04:00:00Z. price_updated_at on every price tells you how fresh it is; BinderDex's newest sets refresh within 6 hours, older sets on a daily backstop.

Missing values

A nullable field is always present, explicitly null, never omitted. Ignore response fields you do not recognize; new fields may be added without a version bump. Unknown query parameters are ignored, not rejected.

Pagination

List operations (cards_search, sets_list) use an opaque cursor, not an offset. Pass next_cursor back as ?cursor= to get the next page; next_cursor: null means you are on the last page. A cursor expires 15 minutes after it is issued and is tied to the same filters and sort you started with.

Variants and conditions

A card can have multiple variant values (for example Normal, Holofoil, Reverse Holofoil, Unlimited, Shadowless). condition is a single tracked value today, Near Mint; the field and filter exist so a future schema that adds graded or played conditions does not need a new query param. cards_get and cards_price_history return every variant and condition BinderDex tracks; the top-level price on a search result is BinderDex's single display price for that card, the same one shown on binderdex.com. cards_search also accepts ?condition= and ?variant= to restrict results to cards with a tracked price for that exact value; an unrecognized value is rejected with 400 invalid_request, the same as any other malformed parameter.

See the full reference for exact per-operation schemas, and the API Terms for the rights and caching rules that apply to everything above.