API credits

Usage is metered in credits. Every catalog request costs a flat 1 credit — per request, not per object, so a search returning 100 cards costs the same as fetching one. Every account includes 500 free credits a month, and you buy more pay-as-you-go with USDC. There is no surprise overage billing: when the balance hits zero, requests return 402 until you top up.

What a call costs

Credits	Call	Detail
1	All catalog reads	Card, expansion and sealed-product search / get / current prices — flat, regardless of page size
1	`include=prices`	No surcharge — embedded pricing is part of the request
5	Price history (coming soon)	Daily time series for a card — premium rate when it ships
5	Vision (coming soon)	Identify a card from an image — premium rate when it ships

Costs are per call, not per result: a page of 100 cards costs the same one credit as a page of one, and cached responses are normal served requests (they cost the same and return faster).

Cost by endpoint

Every metered endpoint and what one call costs. This table is generated from the same manifest that prints the cost on each reference page, so the two can never disagree.

Credits	Endpoint	What it does
1	/api/v1/{game}/cards	Search cards
1	/api/v1/{game}/cards/{id}	Get a card
1	/api/v1/{game}/cards/{id}/prices	Get card pricing
1	/api/v1/{game}/cards/{id}/printings	List a card’s printings
1	/api/v1/{game}/expansions	Search expansions
1	/api/v1/{game}/expansions/{id}	Get an expansion
1	/api/v1/{game}/expansions/{id}/cards	List cards in an expansion
1	/api/v1/{game}/sealed	Search sealed products
1	/api/v1/{game}/sealed/{id}	Get a sealed product
1	/api/v1/{game}/sealed/{id}/prices	Get sealed pricing
1	/api/v1/grading/certs/{provider}/{certNumber}	Look up a graded certificate

Endpoints marked not live yet are documented ahead of the build: calling one today returns 404 and costs nothing. Everything else in the table is live and metered.

The Gacha, Instant Pack and Vaulting APIs don't spend credits at all. They are commerce rather than data, and bill on transaction volume — see pricing. Card Data calls your gacha integration happens to make are metered normally.

Tracking your balance

Every metered response carries real-time accounting in its headers — no delayed dashboard, the numbers are current as of that request:

X-Credits-Cost: 1
X-Credits-Remaining: 47913

Header	Meaning
X-Credits-Cost	What this specific call cost
X-Credits-Remaining	Your balance after this call
X-Credits-Metering	Present on unmetered legacy keys (unmetered) — absent on normal metered responses

For a full account view — balance, plan and month-to-date usage — call GET /api/v1/account/usage with your key, or open your dashboard.

Buying credits (x402)

Top-ups are pay-as-you-go USDC payments over the x402 protocol: 500 credits per $1, from $5 to $1,000 per payment. The transfer is a gasless signed authorization — your wallet needs USDC on Base and no ETH — and credits land the moment the payment settles on-chain, typically under two seconds. Purchased credits never expire.

# 1. Ask for a top-up — the response is an x402 payment challenge
POST /api/v1/credits/topup?usd=25
X-API-Key: rip_v1_...

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64 payment requirements: $25.00 USDC on Base>

# 2. Your x402 client signs a gasless USDC transfer and retries.
#    On settle (~2s) the same call returns:
{ "success": true,
  "data": { "credits_granted": 12500, "balance_credits": 12503,
            "usd": 25, "tx_hash": "0x…" } }

Any x402 client completes this in one call (for TypeScript, @x402/fetch wraps fetch and handles the challenge automatically). Payments are idempotent on the transaction hash — a retried or replayed payment can never be credited twice.

Allowances

Plan	Included / month	Rate limit	Status
Pay as you go	500	300 req/min	Available now
Starter	7,500	300 req/min	Coming soon
Growth	60,000	300 req/min	Coming soon
Professional	300,000	300 req/min	Coming soon

Free monthly credits reset at the start of each month (they top the balance back up to 500; they don't stack). Purchased credits sit in the same balance and never expire. The pricing page has an estimator for your volume.

Spending fewer credits

• Page wide, not deep. page_size goes to 100 and costs the same as 1, so a 100-card page is a hundred times cheaper per card than fetching them one at a time.
• include=prices is free. Embedding current prices in a catalog read costs nothing extra — prefer it over a separate prices call when you need both.
• Cache what doesn't move. Card, expansion and sealed-product metadata change only when a set is released or corrected. Prices update on a schedule (see Pricing data) — there is nothing to gain from polling faster than market_updated_at changes. Cache for your own app freely; redistribution isn't allowed.