> ## 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.

# Quickstart

> From a new API key to opening a pack and selling a pull back, end to end, with cURL.

This walk-through takes a new key from its first call to opening one pack and selling a card from it back to CatchBack. Every command runs as-is in bash or zsh; the last steps use [`jq`](https://jqlang.org) to read the purchase response.

> [!WARNING]
>
> Steps 5 and 6 spend and credit real CatchCoins: your key acts on its account's real balance. Use a cheap pack the first time. To try packs on a test balance first, see [Testing](https://catchbackcards.mintlify.site/partner-api/testing.md).

## Before you start

You need a CatchBack account with a funded CatchCoins balance and an API key linked to it, with at least the `read:catalog`, `read:account`, `rip:packs` and `sell:cards` [scopes](https://catchbackcards.mintlify.site/partner-api/authentication.md#scopes). We create the key and credit your balance when your wire lands. To get set up, or to talk funding, pricing or revenue share, [contact us](mailto:catchbackcards@gmail.com).

Keep the key in an environment variable, never in code:

```bash theme={null}
export CATCHBACK_KEY="cb_live_..."
export CB="https://catchbackcards.com/api/partner/v1"
```

**1. Check which account your key acts as**

[Who am I](https://catchbackcards.mintlify.site/partner-api/endpoints/get-me.md) works with any valid key.

```bash theme={null}
curl "$CB/me" -H "Authorization: Bearer $CATCHBACK_KEY"
```

You want `"linked": true` and the scopes above in `key.scopes`. Quote `account.id` whenever you contact us.

```json theme={null}
{
  "key": {
    "name": "acme",
    "scopes": ["read:catalog", "read:account", "rip:packs", "sell:cards"]
  },
  "linked": true,
  "account": {
    "id": "6f1c2a9e-3b4d-4c7a-9e21-5d8f0b7a1c34",
    "username": "acme-cards",
    "profile_url": "https://catchbackcards.com/user/acme-cards"
  }
}
```

**2. Check your balance and limits**

[Get account](https://catchbackcards.mintlify.site/partner-api/endpoints/get-account.md) shows your balance, how many packs you can still open today, and `next_purchase_at`, the earliest you can buy.

```bash theme={null}
curl "$CB/account" -H "Authorization: Bearer $CATCHBACK_KEY"
```

**3. Pick a pack**

[List packs](https://catchbackcards.mintlify.site/partner-api/endpoints/list-packs.md) returns exactly the packs you can buy, cheapest first, at the price you'll be charged.

```bash theme={null}
curl "$CB/catalog/packs?category=pokemon" \
  -H "Authorization: Bearer $CATCHBACK_KEY"
```

Note a `pack_type` with `"available": true`. This guide uses `bronze`.

**4. Look inside it (optional)**

[Get a pack's pool](https://catchbackcards.mintlify.site/partner-api/endpoints/get-pack-pool.md) shows the value bands, their odds at your risk level, and every card a pull can produce right now.

```bash theme={null}
curl "$CB/catalog/packs/pool?pack_type=bronze&category=pokemon&risk_level=standard" \
  -H "Authorization: Bearer $CATCHBACK_KEY"
```

**5. Open the pack**

[Buy packs](https://catchbackcards.mintlify.site/partner-api/endpoints/buy-packs.md) needs an `Idempotency-Key`: your own id for this order. Make one per order, and keep it until you have a response, because it's what makes a retry safe.

```bash theme={null}
ORDER_ID="order-$(uuidgen)"

curl -X POST "$CB/packs/purchase" \
  -H "Authorization: Bearer $CATCHBACK_KEY" \
  -H "Idempotency-Key: $ORDER_ID" \
  -H "Content-Type: application/json" \
  -d '{ "pack_type": "bronze", "category": "pokemon", "quantity": 1 }' \
  -o order.json

jq . order.json
```

The pack is charged at list price and every pull is already in your vault. Each entry in `pulls` has its `pull_id`, the card as `item`, its `value`, and its CatchBack offer: `catchback.amount` if you sell it back before `catchback.valid_until` (5 minutes after the pull), and `catchback.after` once that window closes. Its `proof` lets you check the draw: [Verify a pull](https://catchbackcards.mintlify.site/partner-api/verify-a-pull.md).

If the request times out or fails with a `5xx`, run the same `curl` again with the same `$ORDER_ID`. If the order went through you get it back; if it didn't, it runs again. Either way it's never charged twice. If you get a `409 IDEMPOTENCY_IN_PROGRESS`, or a `500` with `needs_review: true`, stop and follow the order with [Get an order](https://catchbackcards.mintlify.site/partner-api/endpoints/get-order.md). A `429 RATE_LIMITED` tells you how many seconds to wait. See [Idempotency](https://catchbackcards.mintlify.site/partner-api/idempotency.md) and [Rate limits](https://catchbackcards.mintlify.site/partner-api/rate-limits.md).

**6. Sell the pull back**

To take the fresh rate, sell within 5 minutes of the pull. [Sell back cards](https://catchbackcards.mintlify.site/partner-api/endpoints/sell-back.md) takes the card's id and its `pull_id`, both from the purchase response:

```bash theme={null}
ITEMS=$(jq -c '[.pulls[] | select(.kind == "card") | { card_id: .item.id, pull_id }][:1]' order.json)

curl -X POST "$CB/cards/sell-back" \
  -H "Authorization: Bearer $CATCHBACK_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"items\": $ITEMS }"
```

Each item comes back `sold`, with `payout_amount` and `payout_rate`, and `total_paid` is credited to your balance. Selling the same pull again returns `already_sold` with the earlier sale, so this call is safe to retry. If your pull was a sealed pack (`"kind": "sealed_pack"`), `ITEMS` is empty: sealed packs can't be sold back through the API.

```json theme={null}
{
  "total_paid": 16.2,
  "remaining_balance": 189937,
  "results": [
    {
      "card_id": "bee48cce-…",
      "pull_id": "873deb80-…",
      "status": "sold",
      "transaction_id": "93727497-…",
      "payout_amount": 16.2,
      "payout_rate": 0.9
    }
  ]
}
```

**7. See what you hold**

[Get vault](https://catchbackcards.mintlify.site/partner-api/endpoints/get-vault.md) lists the cards you still hold, each with its sell-back offer right now.

```bash theme={null}
curl "$CB/vault?category=pokemon" \
  -H "Authorization: Bearer $CATCHBACK_KEY"
```

## Next steps

> [card] [Buy a card](https://catchbackcards.mintlify.site/partner-api/endpoints/buy-card.md)
>
> Search the shop and user listings, then buy one card with a price guard.

> [card] [How it works](https://catchbackcards.mintlify.site/partner-api/how-it-works.md)
>
> The whole lifecycle, and what each sell-back pays.

> [card] [Errors](https://catchbackcards.mintlify.site/partner-api/errors-and-limits.md)
>
> Every status and error code, and what to do about it.

> [card] [Connect an AI agent](https://catchbackcards.mintlify.site/partner-api/mcp.md)
>
> The same flow as MCP tools, with the same key.

> [card] [Test accounts](https://catchbackcards.mintlify.site/partner-api/testing.md)
>
> Try packs on a test balance, and how to test everything else.

> [card] [Webhooks](https://catchbackcards.mintlify.site/partner-api/webhooks.md)
>
> Hear when an order finishes or a listing sells, instead of polling.


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