Skip to main content
In about 15 minutes you’ll run the whole flow a customer goes through: buy a pack, receive the item, and sell it back. It all happens in the sandbox, a test copy of the API. Payments there are simulated, so no real money moves, but the digital representations are real tokens on a public test network.

Before you start

What we send you. Email support@catchbackcards.com and we’ll set you up with:
  • a sandbox base URL, where the test API lives;
  • a sandbox API key, which only works there;
  • your test chain and sandbox contract address.
What you need. A test wallet address on that chain, standing in for your customer. Any EVM wallet works (MetaMask, Rabby, or one your code creates). Selling back needs the wallet to sign one transaction, so give it a little testnet gas from a public faucet. Save the two values you’ll use in every call:

1. Check your key

You should see your key with "scopes": ["nft:orders"] and your program. A 401 means the key is wrong; a 403 means it’s missing the nft:orders scope, so contact us.

2. Pick a pack

List the packs you can sell:
Each pack has a pack_type (for example bronze), a price in dollars, and available. Pick one where available is true. To see its odds and every item it can pull, the same view you’d show a customer, call Get a pack’s odds and pool with that pack_type.

3. Create an order for your test wallet

  • recipient is the wallet the item is delivered to.
  • Idempotency-Key is your own id for the order. If a call fails or times out, send it again with the same key and you’ll get the same order back, never a second one. You’ll also use it to look the order up.
The response has the order, with "status": "awaiting_payment", and a payment. In production you’d hand payment to your customer to pay. Here, copy payment.intent_id: it starts with sbx_pi_.

4. Pay for it (simulated)

This marks the payment as settled, exactly as a real customer payment would.

5. Open the pack and receive the item

Our background work runs every two minutes. In the sandbox you can also run it straight away by calling tick, so you don’t have to wait:
Repeat both calls until order.status reaches minted. Along the way it moves: That’s the moment your app shows the customer what they pulled. Check your test wallet: the token is there.

6. Sell it back

Ask for a quote. It fixes the price for 10 minutes:
amount_usd is what the customer gets. To accept, the wallet holder signs one transaction that burns the token with the signed quote. The code for that is on the Sell-back page. Then tick and check the quote:
When quote.payout.status is sent, the sale is complete, and in the sandbox the payout lands instantly. That’s the whole flow. To try shipping instead, see Shipping: estimate, create and pay a shipment, burn, then mark it shipped with POST /sandbox/shipments/{id}.

How the sandbox differs from production

All three sandbox endpoints return 404 outside the sandbox.

A full run (TypeScript + viem)

The same flow our own certification suite runs against the sandbox. burnForQuote and CATCHBACK_CARDS_ABI are on the Sell-back page; alice, bob, their viem wallets and CONTRACT are yours.
Use a separate key per environment (sandbox, production).

Next steps

  • Webhooks: get each status change pushed to you instead of polling.
  • Orders: every status, including refunds and multi-pack orders.
  • Go-live checklist: what to confirm before switching to your production key.