Skip to main content
Changes to v1 are additive: a response can gain fields, an enum can gain values, and a new endpoint can appear, so build your parser to ignore what it doesn’t know. A breaking change would ship under a new version prefix. Dates are US Pacific time.
​
Withdrawal webhook
  • New webhook event: withdrawal.updated, sent when a USDC withdrawal changes status, with the object Get a withdrawal returns. Every webhook on the account whose key has withdraw:funds gets it.
​
Balance history
  • New: Balance history (GET /balance-history, scope read:account): every change to your balance in a window, newest first, in one list: orders, shipping charges, USDC withdrawals and money in (USDC deposits, wires we credited, card deposits). REST only.
​
Funding and withdrawals in USDC
  • New guide: Funding in USDC.
  • New: Get funding details (GET /funding, scope read:account): your permanent USDC deposit addresses. A deposit lands in your balance once it settles.
  • New: Withdraw (POST /withdrawals), List withdrawals (GET /withdrawals) and Get a withdrawal (GET /withdrawals/{id}), scope withdraw:funds, granted on request: send your balance as USDC on Base to the escrow address we set on your account, with no fee. REST only.
​
Sell-back quotes, min_payout, energy cards
  • New: Quote a sell-back (POST /cards/sell-back/quote, scope sell:cards, MCP tool quote_sell_back): what a sell-back pays for up to 100 cards, now and later, as a schedule of phases with the exact UTC time each starts and ends. It moves no money.
  • Sell back cards takes an optional min_payout per item. If the sell-back would pay less, nothing is sold and the item fails with PRICE_CHANGED and what it pays now.
  • Get vault and the quote take category=energy: the energy cards from base packs, which sell back at 100% of their value with no 5-minute window and no lock.
  • The vault’s catchback offer now includes insurance or a boost bought on the pull, as the sell-back pays it.
​
Buy packs refusals
  • Buy packs now refuses an order before it charges anything when the pack can’t be bought: a pack_type that List packs doesn’t offer your key is a 404, and a pack with available: false is a 409 PACK_UNAVAILABLE, with its reason. A risk_level outside the pack’s risk_levels, and the category goods, are a 400. A refused order charges nothing and frees its order id. A retry of a finished order is unaffected.
  • Card catalog export now lists only what Buy a card can sell, and category=goods is a 400.
​
Optional shipping insurance
  • Estimate a shipment and Create a shipment take an optional cover_amount, so you can insure a shipment from $100 up to the cards’ value, at most $10,000. You pay the rate plus the premium, and max_cost applies to the total. New codes: 400 COVER_NOT_ALLOWED and 409 COVER_UNAVAILABLE.
  • Every estimate now returns order_value and max_cover. A shipment, in responses and in shipment.updated, now has cover_amount and insurance_cost.
  • An estimate with cover_amount counts as two against the limit of 60 a minute.
​
Test accounts, public card metadata, shipments, webhooks, orders held for review
  • New: Create a test account (POST /test-accounts, MCP tool create_test_account) and List test accounts (GET /test-accounts, MCP tool list_test_accounts), scope create:test_accounts, granted on request: test logins with a $10,000 test balance. A test account is a login, not a key, and it can’t use the marketplace, gifts, drops, battles, shipping, chat, DMs or withdrawals. New guide: Testing.
  • New: Public card metadata (GET /api/public/v1/cards/{id}): a card’s metadata and image URLs with no key and no prices, cached for 5 minutes at the CDN.
  • New: Estimate a shipment (POST /shipments/estimate, MCP tool estimate_shipment), Create a shipment (POST /shipments, MCP tool create_shipment), List shipments (GET /shipments, MCP tool list_shipments) and Get a shipment (GET /shipments/{id}, MCP tool get_shipment), scope ship:cards, granted on request: ship cards you hold to your customers at the carrier’s full rate. New guide: Shipping cards.
  • New: Webhooks, which we set up for you: a signed POST with retries for order.completed, listing.sold and shipment.updated.
  • New: Where you can call from. A key doesn’t get around our sanctions list, and a valid key now gets past any other limit on where partner endpoints and the MCP server can be called from.
  • Rate limits now says that everything under /api/ has a shared limit of 300 requests a minute per IP address, on top of the per-key limits.
  • Buy packs and Buy a card: when we can’t confirm whether a purchase was charged, the answer is now 500 PAYMENT_OUTCOME_UNKNOWN with needs_review: true and the order’s checkout_id, not a 503. Nothing is delivered and the order is held for us to settle: stop retrying, never place it again under a new order id, and follow it with Get an order.
  • A resend with the same order id answers 409 IDEMPOTENCY_IN_PROGRESS with needs_review: true until we settle the order, and nothing is charged twice. Once we settle it, Get an order answers 404 and the id is free to send again. See Purchases that need review.
  • A 503 on a purchase means that attempt didn’t charge anything. An earlier attempt with the same order id may have gone through, so retry with the same order id, never a new one.
​
Pull proofs, one-step price changes, partner accounts
  • Buy packs: every pull carries a proof, its provably fair record, with a verify_path you can GET without a key to replay the draw. New guide: Verify a pull.
  • Change a listing’s price writes the new price in one step, so it lands whole or not at all. A buy or delist that lands first makes it a 409 LISTING_NOT_ACTIVE, another price change a 409 LISTING_CHANGED, and neither writes anything.
  • A partner account stays off CatchBack’s VIP and Top Gifters leaderboards and recent-pull feeds, its pulls aren’t posted as big-pull cards in chat, and it earns no CatchPoints or quest progress.
​
Card lookups, your listings, price changes, order history
  • New: Get a card (GET /cards/{id}, MCP tool get_card) and Find a card by cert (GET /cards?cert=, MCP tool find_card_by_cert), scope read:catalog: any card by its id or by the cert on its slab.
  • New: Price history (GET /cards/{id}/price-history, MCP tool get_price_history): a card’s CardLadder value readings, up to a year back.
  • New: Card activity (GET /cards/{id}/activity, MCP tool get_card_activity): a card’s recent sales and listings, with nobody named.
  • New: Your listings (GET /listings, scope read:account, MCP tool get_listings): your own active listings, with your payout on each.
  • New: Change a listing’s price (PATCH /listings/{listing_id}, scope write:listings, MCP tool update_listing_price): reprice a fixed-price listing in place, without delisting it.
  • New: List orders (GET /orders, MCP tool list_orders) and Get an order (GET /orders/{checkout_id}, MCP tool get_order), scope read:account: your order history, paged by cursor, and one order by its id, even while it is still running.
  • Search cards applies its filters to every listing it reads, up to 5,000 rows from each source, and gains truncated. has_more is false on the last page and on page 20.
  • Get vault: a listed card carries its listing_id and listing_price.
  • List a card runs the app’s seller checks, so the account needs a verified phone number.
​
Sealed pack pools
  • Get a pack’s pool covers sealed packs (the Starter and the sealed mystery packs). The response gains kind (slab or sealed); a sealed pack lists its products in products, with total_products, and one band per product.
  • A sold-out pack with no pool to show returns 200 with available: false and an empty pool, instead of an error.
  • The Starter pack opens at the standard risk level only, and List packs says so in its risk_levels.
​
Vault acquisitions
  • Get vault finds each card’s latest acquisition across every kind of pack pull and buy, so its pull_id or purchase_id always names the acquisition a sell-back pays on.
​
Who am I, card limits
  • New: Who am I (GET /me, MCP tool whoami) works with any valid key and shows which account it acts as.
  • Get account gains card_limits: your card and spend usage against the daily card caps.
​
Buying cards
  • New: Search cards (GET /marketplace/listings, MCP tool search_cards) finds every card you can buy, from the shop and fixed-price user listings.
  • New: Buy a card (POST /cards/purchase, scope buy:cards, MCP tool buy_card), with a max_price guard and daily card and spend caps.
  • Sell back cards takes a purchase_id for a card you bought, and Get vault returns purchase_id and purchased_at.
  • Card orders share your account’s order ids with pack orders, and an interrupted card order is closed the same way as a pack order.
​
Interrupted orders
  • A pack order cut off after it was charged is now closed from our records, usually within about 10 minutes. Resending its order id then returns a shorter body marked "reconciled": true. See Idempotency.
  • New error code: 409 IDEMPOTENCY_RETRY, when an earlier attempt with the same order id failed just as the retry arrived. Resend it.
​
Pack pools and the full card object
  • New: Get a pack’s pool (GET /catalog/packs/pool, MCP tool get_pack_pool): a pack’s value bands, their odds at a risk level, and every card a pull can produce.
  • Every endpoint that returns a card returns the same card object, with front, back and render images and the slab, set and value fields.
​
Buying packs and managing cards
​
Purchase report
  • New: Purchase report (GET /pulls, scope read:pulls, opt-in): completed pack purchases in a time window, for revenue-share reporting.
​
Partner API v1