API docs

Get started

1. Sign in with your work email. Your organization is created on the first sign-in.
2. Create a key in API keys. It is shown once: store it in your secrets manager.
3. Call the API with the key in the Authorization header.

curl https://api.deckz.xyz/v1/variants/pkm:sv3-ja:134:charizard-ex:ja:holo:psa:10/price?regions=global,JP \
  -H "Authorization: Bearer dk_live_your_key"

{
  "variant_id": "pkm:sv3-ja:134:charizard-ex:ja:holo:psa:10",
  "card": { "name": "Charizard ex", "set": "sv3-ja", "number": "134", "language": "ja" },
  "printing": "holo",
  "type": "graded",
  "grading": { "company": "PSA", "grade": 10, "label": null, "qualifier": null, "canonical": "PSA 10" },
  "markets": [
    { "region": "global", "currency": "USD", "fmv": 41250, "low": 38900, "high": 44100, "confidence": 82, "n_comps": 14, "flags": [] },
    { "region": "JP", "currency": "JPY", "fmv": 59800, "low": 56000, "high": 64000, "confidence": 74, "n_comps": 9, "flags": [] }
  ],
  "sources": { "onchain": 6, "offchain": 8 },
  "stats": { "7d": { "change_pct": -2.4, "sales": 5 }, "30d": { "change_pct": 6.1, "sales": 14 } },
  "method_version": "fmv-1.1.0",
  "computed_at": "2026-10-02T13:05:00Z"
}

Authentication

Send Authorization: Bearer dk_live_… on every request, or a dk_test_ key for the sandbox. Each key has scopes (read:prices, read:comps, read:spreads, webhooks) and can be revoked at any time from the dashboard. Revocation takes effect immediately.

Amounts and markets

Every amount is an integer in the minor unit of its currency: cents for USD, yen for JPY. 41250 in USD is $412.50. The global market is in USD, converted at the daily rate. Regional markets (NA, JP) are priced from their own sales, in their own currency, never converted.

Each price comes with a range (low and high), a confidence score from 0 to 100 and the number of sales behind it. When a variant rarely sells, the price is an estimate from nearby grades of the same card, and the response says so. The confidence is measured on past sales: a price at 70 has about a 7 in 10 chance of landing within 15% of the next sale. Estimates and prices built only on onchain platforms stay below 40. The quality rank reads on the same scale: A when at least 85 in 100 sales land within 15%, B for 70, C for 50, D for estimates and less certain prices. English Pokémon and One Piece prices do not get an A yet, because that precision does not hold for them.

Flags tell you when to read a price with care. single_sale: it rests on one sale. unconfirmed_rise: the last sale is well above the ones before it and no sale has followed yet. grade_gap: the price is far from what the other grades of the card suggest. grade_inversion: this grade and a nearby grade from the same grader are priced in the wrong order, so one of the two prices is probably wrong; both carry the flag. platform_market: every sale behind the price comes from an onchain platform and no sale from the wider market confirms it, so its confidence is capped. trophy_outlier: the price rests on one sale far above every other grade of the card, such as a rare trophy copy; it stays in the price, but no other grade is estimated from it. A price with no flag has an empty list. Ignore any flag you do not know yet.

Limits

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Past the limit, the API answers 429 with Retry-After.

Errors

Errors share one shape. Keep the request_id when you contact us.

{ "error": { "code": "rate_limited", "message": "Too many requests", "request_id": "req_8k3m..." } }

Webhooks

Subscribe to fmv.changed, sale.created and pop.changed for the cards in your watchlists. Each delivery is signed with your endpoint secret (HMAC-SHA256) and retried with backoff for 24 hours.

An fmv.changed event says what triggered it: a threshold you set, a change of status, or a change of flags, with the flags from before in previous_flags.

signature = hex(hmac_sha256(secret, timestamp + "." + raw_body))
// Compare with the X-Signature header in constant time,
// and reject the event if X-Timestamp is more than 5 minutes old.

Endpoints

API reference