> ## Documentation Index
> Fetch the complete documentation index at: https://catchbackcards.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Partner API v2

CatchBack is a platform where collectors can create mystery packs of collectibles: graded Pokémon and sports cards, watches, jewelry and streetwear. Partner API v2 lets exchanges, prediction markets and wallet platforms distribute those packs to their own users, white-labeled.

## CatchBack in one minute

1. **A user buys a mystery pack** in your app. Each pack holds one real item, drawn with [provably fair](https://catchbackcards.mintlify.site/partner-api/v2/verify-a-pull.md) odds the user can see before buying.
2. **The user receives the item they pulled.** It arrives in their wallet as a digital representation (NFT) of the real item, which stays safe in our vault.
3. **The user keeps it, sells it back, or has it shipped.**
   * **Keep it**, or trade it with other collectors.
   * **Sell it back to us:** up to 100% of its value in the first 5 minutes, then a guaranteed 80% with no expiry.
   * **Have it shipped:** we mail the real item to their door.

## Why partners integrate

* **A new product with no inventory.** We source, store and ship every item, and back every digital representation with the real thing.
* **Revenue share on every pack.** The standard share is 3% of every pack opening. Premier partners earn more. See [your revenue statement](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/get-revenue.md).
* **No capital and no custody.** You don't prefund anything. Your users pay us directly, and digital representations and payouts go straight to their wallets, so you never hold their tokens or funds.
* **A safety net your users can see.** The guaranteed buyback means every item they pull keeps a cash value.

## New to crypto?

You don't need crypto expertise to integrate. The API is ordinary JSON over HTTPS, and we handle every on-chain step for you:

* **Payments:** we give you a hosted payment screen, or an address to pay to. You never build a checkout or hold user funds.
* **Minting and gas:** we create each digital representation and pay the network fee.
* **Payouts and refunds:** we send USDC straight to the user.
* **Shipping:** we pack and post the real item.

The one thing your users do need is **their own crypto wallet**, the kind where only they hold the keys. Their digital representations go there, and they sign a transaction from it for each item they sell back or ship. If your users already have wallets, as on an exchange or wallet app, there's nothing extra to set up.

We're also working with partners to give users automatically provisioned wallets, so they won't have to set one up themselves.

| Term | In plain terms |
| - | - |
| **Wallet** | The user's crypto account. It holds their digital representations and USDC. |
| **Digital representation (NFT)** | A digital certificate of ownership. Here, each one stands for one real item in our vault. |
| **USDC** | Cryptocurrency equivalent of \$1 US. |
| **Burn** | Permanently destroying a digital representation. A user burns one to sell it back or ship it, so the same item can never be claimed twice. |
| **Chain** | The network the digital representation lives on. Each partner program uses one, set when you join. |

## Who does what

Your platform is the storefront. CatchBack does everything behind it.

| Step | Your platform | CatchBack |
| - | - | - |
| **1. The user buys a pack** | Shows the packs and their odds, sends us the user's wallet address, and opens our payment screen | Supplies the packs, prices and odds, takes the payment, and refunds it if anything goes wrong |
| **2. The user receives their item** | Shows what they pulled | Opens the pack fairly and delivers the digital representation to their wallet, paying the network fee |
| **3. The user keeps it, sells it back, or ships it** | Shows those options, and collects the shipping address | Buys it back at the guaranteed price, or packs and ships the real item with tracking |

> [!NOTE]
>
> **v2 replaces v1.** The v1 Partner API is retired. v2 has no partner balance or prefunding: each customer pays for their own pack and gets each item as a digital representation in their wallet.

## How it works, technically

At purchase, each pack algorithmically selects one real item from our vault. The customer receives an NFT (a digital representation showing ownership) of that item in their wallet. They can then trade it, sell the hit back, or have the collectible shipped. Selling back and shipping burn the NFT.

```text theme={null}
 1. POST /orders  (quantity 1-10) ──▶ order awaiting_payment + payment details (one payment)
 2. customer pays (Base or Solana, through Unifold) ─▶ paid
 3. we open each pack ────────────────────────────────▶ rolled   (order.pull is set)
 4. we mint each NFT to the customer's wallet ────────▶ minted   (order.token is set)
    every step after 1 ─▶ webhook nft_order.updated, or GET /orders/{id}

 5. the customer holds it, or trades it on any marketplace (the token is a standard NFT)

 6a. SELL BACK                                  6b. SHIP (one token, or up to 25 in one box)
     POST /tokens/{id}/quote  (10-min quote)        POST /shipments/estimate
     holder burns with the quote                    POST /shipments  → pay shipping once
     we see the burn → USDC sent                    GET  /shipments/{id}  → a burn per token
     webhook sellback.updated, or                   holder burns each token → we ship the box
     GET /quotes/{quote_id} → payout.tx_hash        webhook nft_shipment.updated, or
                                                    GET  /shipments/{id}  → tracking
```

### Who delivers the digital representation?

We do, straight to the customer's wallet. Your platform passes us the wallet address and shows the result. It never holds the token, and it never touches the customer's money.

```text theme={null}
 your platform:  POST /orders  { "recipient": "0x8f3c…" }   ◀── you only pass the address
 CatchBack:      mints the digital representation ──────────▶ customer's wallet
```

#### Step by step

1. **Collect the customer's wallet address** on your program's chain (`mint_chain` in the [catalog](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/list-packs.md)). On EVM, one address is the same on every EVM chain, so a customer who pays from Base receives the token at that same address on your chain.
2. **Create the order** with that address as `recipient` ([Create an order](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/create-order.md)). The response includes the payment details. Hand them to the customer, who pays within 24 hours in USDC on Base or Solana ([Payments](https://catchbackcards.mintlify.site/partner-api/v2/payments.md)).
3. **We open the pack and mint the token.** Once the payment settles, the order moves `paid` → `rolled` (the item is chosen and `order.pull` is set) → `minted` (the token is confirmed on chain and `order.token` is set). We pay the minting fee. If a mint doesn't land, we retry it (`mint_failed`); the pack is never opened twice.
4. **Show the result.** Listen for the [`nft_order.updated`](https://catchbackcards.mintlify.site/partner-api/v2/webhooks) webhook, or poll `GET /orders/{id}`. At `minted`, show the customer the item from `order.pull`.

A multi-pack order (`quantity` 2-10) is paid once, then each pack opens and mints on its own, so each unit moves through these statuses separately. Every status is listed in [Orders](https://catchbackcards.mintlify.site/partner-api/v2/orders.md).

#### Where the money goes

Every payment and payout moves between the customer and CatchBack directly.

| Money | Goes to | Details |
| - | - | - |
| **The customer's payment** | CatchBack, through our payment provider Unifold | You never collect or forward it |
| **Sell-back payout** | USDC to the holder's wallet, or to the quote's `payout_address` | Paid on Base for EVM programs and on Solana for Solana programs. Solana payouts aren't on yet, so Solana programs send a Base `payout_address` for now. See [Sell-back](https://catchbackcards.mintlify.site/partner-api/v2/sell-back.md) |
| **Refund** | USDC on Base to the order's `refund_address` | Sent when the pack can't open after payment, the payment is more than 1% short, or it arrives after the 24-hour window. Defaults to `recipient` on EVM programs; required on Solana programs. See [Payments](https://catchbackcards.mintlify.site/partner-api/v2/payments.md) |
| **Your revenue share** | You | Reported month by month on your [revenue statement](https://catchbackcards.mintlify.site/partner-api/v2/endpoints/get-revenue.md) |

> [!WARNING]
>
> `recipient` must be a self-custody wallet the customer controls, **never an exchange deposit address**. A digital representation minted to a deposit address lands in the exchange's wallet, and the customer may never be able to reach it.

> [!NOTE]
>
> Want to become a partner? Email [support@catchbackcards.com](mailto:support@catchbackcards.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.