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

# Create a sell-back quote

> A quote fixes the amount, the payer and the payout destination, and expires 10 minutes after it is issued, or when the 5-minute fresh window ends if the quote is at the fresh rate (whichever is sooner). Every call issues a new quote; an unused quote just expires. Takes no `Idempotency-Key`.

- **EVM** (`family: "evm"`): the holder's wallet calls `burnWithQuote(quote, signature)` on `contract`, passing `quote` exactly as returned. `tokenId`, `amount` (USDC, 6 decimals) and `expiresAt` (unix seconds) are decimal strings.
- **Solana** (`family: "solana"`): `transaction` moves the asset to `vault` with the quote id as a memo; the holder signs and sends it unchanged before `last_valid_block_height` and `expires_at`.

Follow the payout with Get a sell-back quote or the `sellback.updated` webhook. [Sell-back](/partner-api/v2/sell-back).



## OpenAPI

````yaml /partner-api/v2/openapi.yaml post /api/partner/v2/tokens/{tokenId}/quote
openapi: 3.1.0
info:
  title: CatchBack Partner API v2 (wallets & NFTs)
  version: 2.0.0
  summary: >-
    Sell CatchBack packs to your users' own web3 wallets, and let the NFT holder
    sell back or ship.
  description: >-
    The official contract for Partner API v2. Generate clients from this file.


    Each customer pays for their own pack (USDC on Base or Solana, through a
    Unifold Payment

    Intent), and each pulled item is minted as an NFT to the customer's wallet.
    Whoever holds the

    NFT can trade it, sell it back for USDC, or have the physical item shipped.
    Selling back and

    shipping both burn the NFT. Guides: [Overview](/partner-api/v2/overview).


    - **Auth:** every `/api/partner/v2` request sends your key as a bearer
    token, and every key
      needs the scope `nft:orders`. The public token metadata needs no key.
    - **Your program:** your key is linked to your partner program, which fixes
    the chain your
      NFTs mint on (`mint_chain`) and your collection contract. An order, token, quote or shipment
      from another program answers `404`.
    - **Formats:** JSON, UTF-8. Money is USD as a number in dollars (`25`,
    `9.85`). New fields can be
      added to any response; ignore fields you don't know.
    - **Errors:** bodies are `{ "error": "<message>" }`, and errors your
    integration should act on
      also carry a stable `code` (see `ErrorCode`). Branch on the status and the `code`, never on the
      message text. [Errors](/partner-api/v2/errors).
    - **Idempotency:** `POST /orders`, `POST /shipments`, `POST
    /tokens/{tokenId}/shipment` and
      `POST /keys/rotate` require an `Idempotency-Key`. [Idempotency](/partner-api/v2/idempotency).
    - **Sandbox:** the sandbox runs the same API with simulated payments on a
    public testnet. Its base
      URL is issued on request, with a sandbox key. The operations tagged `Sandbox` exist only there
      and answer `404` in production.
  contact:
    name: CatchBack support
    email: support@catchbackcards.com
servers:
  - url: https://catchbackcards.com
    description: >-
      Production. Every payment is real money. The sandbox base URL is issued on
      request.
security:
  - bearerAuth:
      - nft:orders
tags:
  - name: Packs
    description: The packs you can sell, their odds and every item they can pull.
  - name: Orders
    description: >-
      Buy 1-10 packs for one wallet, follow the order to the mint, and prove the
      pull.
  - name: Tokens
    description: A wallet's tokens and one token's item, holder and sell-back schedule.
  - name: Sell-back
    description: >-
      Quote a sell-back, have the holder burn with it, and follow the USDC
      payout.
  - name: Shipments
    description: >-
      Pay shipping for 1-25 tokens, have the holder burn each one, and track the
      box.
  - name: Webhooks
    description: Register, read, test and remove your webhook URL.
  - name: Webhook events
    description: Signed POSTs we send to your webhook URL.
  - name: Keys
    description: Read, rotate and revoke your API key.
  - name: Revenue
    description: Your monthly revenue-share statement.
  - name: Sandbox
    description: Sandbox-only helpers. Every one answers `404` in production.
  - name: Metadata
    description: Public NFT metadata that wallets and marketplaces read with no key.
paths:
  /api/partner/v2/tokens/{tokenId}/quote:
    post:
      tags:
        - Sell-back
      summary: Create a sell-back quote
      description: >-
        A quote fixes the amount, the payer and the payout destination, and
        expires 10 minutes after it is issued, or when the 5-minute fresh window
        ends if the quote is at the fresh rate (whichever is sooner). Every call
        issues a new quote; an unused quote just expires. Takes no
        `Idempotency-Key`.


        - **EVM** (`family: "evm"`): the holder's wallet calls
        `burnWithQuote(quote, signature)` on `contract`, passing `quote` exactly
        as returned. `tokenId`, `amount` (USDC, 6 decimals) and `expiresAt`
        (unix seconds) are decimal strings.

        - **Solana** (`family: "solana"`): `transaction` moves the asset to
        `vault` with the quote id as a memo; the holder signs and sends it
        unchanged before `last_valid_block_height` and `expires_at`.


        Follow the payout with Get a sell-back quote or the `sellback.updated`
        webhook. [Sell-back](/partner-api/v2/sell-back).
      operationId: createSellbackQuote
      parameters:
        - $ref: '#/components/parameters/TokenId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SellbackQuoteRequest'
            example:
              kind: sellback
              holder: 0x8f3c...e21a
              payout_chain: evm:8453
              payout_address: 0x8f3c...e21a
      responses:
        '201':
          description: The quote to burn with.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellbackQuote'
              examples:
                evm:
                  summary: EVM program
                  value:
                    quote_id: 0x5e0c...91ab
                    chain: evm:196
                    amount_usd: 330
                    expires_at: '2026-11-16T18:30:00.000Z'
                    payout:
                      chain: evm:8453
                      address: 0x8f3c...e21a
                    family: evm
                    contract: 0x7b1e...c0de
                    quote:
                      tokenId: '81264573985362058461377125337283195667'
                      kind: 1
                      quoteId: 0x5e0c...91ab
                      holder: 0x8f3c...e21a
                      payoutHash: 0x2c71...
                      amount: '330000000'
                      expiresAt: '1795372200'
                    signature: 0x4a1f...1b
                solana:
                  summary: Solana program
                  value:
                    quote_id: 0x5e0c...91ab
                    chain: solana:mainnet
                    amount_usd: 330
                    expires_at: '2026-11-16T18:30:00.000Z'
                    payout:
                      chain: evm:8453
                      address: 0x8f3c...e21a
                    family: solana
                    collection: CoLL...
                    asset: AsSt...
                    vault: VauL...
                    transaction: <base64 unsigned transaction>
                    last_valid_block_height: 312345678
        '400':
          description: >-
            - `BAD_JSON`: the body isn't JSON.

            - `BAD_HOLDER`: `holder` is not a wallet address on your mint chain.

            - `PAYOUT_CHAIN_NOT_SUPPORTED`: `payout_chain` is not `evm:8453` or
            `solana:mainnet`.

            - `PAYOUT_CHAIN_NOT_ENABLED`: payouts on that chain aren't switched
            on yet (today: `solana:mainnet`); send `payout_chain: "evm:8453"`
            with a Base `payout_address`.

            - `BAD_PAYOUT_ADDRESS`: no usable `payout_address` for the payout
            chain (required when it isn't your mint chain's family).

            - `USE_SHIPMENT_ENDPOINT`: `kind: "shipment"`; shipments start at
            Create a shipment.

            - No code: `kind` other than `sellback`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Payouts on solana:mainnet are not switched on yet.
                code: PAYOUT_CHAIN_NOT_ENABLED
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            - `NOT_HOLDER`: that wallet does not hold the token on chain right
            now.

            - `WALLET_REFUSED`: the holder or the payout address failed
            sanctions screening.

            - Any of the key and program refusals every endpoint can return.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: That wallet does not hold this token.
                code: NOT_HOLDER
        '404':
          description: '`UNKNOWN_TOKEN`: no such token on your program''s contract.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Unknown token
                code: UNKNOWN_TOKEN
        '409':
          description: |-
            - `TOKEN_NOT_MINTED`: the token's mint hasn't confirmed yet.
            - `TOKEN_BURNED`: the token was already sold back or shipped.
            - `NO_OFFER`: the item has no sell-back offer right now.
            - No code: your program has no contract yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: This token has already been redeemed.
                code: TOKEN_BURNED
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          description: >-
            - `CHAIN_UNAVAILABLE`: we couldn't read the token's owner from the
            chain; retry shortly.

            - `SCREENING_UNAVAILABLE`: wallet screening is briefly unavailable;
            retry shortly.

            - `AUTH_UNAVAILABLE`, or no code: we couldn't check your key or load
            your program; retry after `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Could not read the token owner; try again shortly.
                code: CHAIN_UNAVAILABLE
components:
  parameters:
    TokenId:
      name: tokenId
      in: path
      required: true
      description: >-
        The token's decimal `token_id`, on either chain family. Keep it as a
        string or bigint, never a JS number.
      schema:
        type: string
        pattern: ^[0-9]{1,78}$
      example: '81264573985362058461377125337283195667'
  schemas:
    SellbackQuoteRequest:
      type: object
      required:
        - holder
      properties:
        kind:
          type: string
          enum:
            - sellback
          default: sellback
        holder:
          type: string
          description: The wallet that holds the token now. Checked on chain.
        payout_chain:
          type: string
          enum:
            - evm:8453
            - solana:mainnet
          description: >-
            Default: the token's family (Base for an EVM program, Solana for a
            Solana program). Solana payouts answer `PAYOUT_CHAIN_NOT_ENABLED`
            until they are switched on.
        payout_address:
          type: string
          description: >-
            Where the USDC goes. Required when the payout chain isn't your mint
            chain's family; otherwise defaults to `holder`.
    SellbackQuote:
      oneOf:
        - $ref: '#/components/schemas/EvmSellbackQuote'
        - $ref: '#/components/schemas/SolanaSellbackQuote'
      discriminator:
        propertyName: family
        mapping:
          evm: '#/components/schemas/EvmSellbackQuote'
          solana: '#/components/schemas/SolanaSellbackQuote'
    Error:
      type: object
      required:
        - error
      description: >-
        Every error body. `code` is stable where you might branch on it; some
        errors add the fields below.
      properties:
        error:
          type: string
          description: >-
            For people. The text can change, so branch on the status and the
            `code`.
        code:
          description: >-
            Machine-readable, where you might branch on it. New codes can be
            added, so treat an unknown one like a missing one.
          anyOf:
            - $ref: '#/components/schemas/ErrorCode'
            - type: string
        retry_after_seconds:
          type: integer
          description: On `RATE_LIMITED`.
        odds:
          description: >-
            On `BAD_ODDS` when the pack sells other odds: the choices it sells.
            On `ODDS_UNAVAILABLE` from Create an order: the choice asked for.
          oneOf:
            - type: array
              items:
                $ref: '#/components/schemas/Odds'
            - $ref: '#/components/schemas/Odds'
        reason:
          type:
            - string
            - 'null'
          description: On `PACK_UNAVAILABLE`, why the pack can't open.
        status:
          type: string
          description: On `NOT_PULLED`, the order's status.
        token_ids:
          type: array
          items:
            type: string
          description: On a refusal about particular tokens, the token ids it is about.
        quote_id:
          type: string
          description: >-
            On `TOKEN_IN_SHIPMENT` from the one-token endpoint, the shipment
            waiting for the burn.
        fields:
          type: object
          additionalProperties:
            type: string
          description: >-
            On `BAD_ADDRESS` from a shipment or estimate, each bad address field
            and what is wrong with it.
        order_value:
          type: number
          description: On `COVER_NOT_ALLOWED`.
        min_cover:
          type: number
          description: On `COVER_NOT_ALLOWED`.
        max_cover:
          type:
            - number
            - 'null'
          description: On `COVER_NOT_ALLOWED`; null when the items can't be insured.
        amount:
          type: number
          description: On `PRICE_CHANGED`, the current shipping cost.
        successor:
          type: object
          description: On `ALREADY_ROTATED`, the key that replaced this one.
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: On `ALREADY_ROTATED`, when this key stops working.
    EvmSellbackQuote:
      allOf:
        - $ref: '#/components/schemas/SellbackQuoteBase'
        - type: object
          required:
            - family
            - contract
            - quote
            - signature
          properties:
            family:
              type: string
              const: evm
            contract:
              type: string
              description: The contract the holder calls `burnWithQuote` on.
            quote:
              $ref: '#/components/schemas/EvmBurnQuote'
            signature:
              type: string
    SolanaSellbackQuote:
      allOf:
        - $ref: '#/components/schemas/SellbackQuoteBase'
        - type: object
          required:
            - family
            - collection
            - asset
            - vault
            - transaction
            - last_valid_block_height
          properties:
            family:
              type: string
              const: solana
            collection:
              type: string
            asset:
              type: string
            vault:
              type: string
              description: Where the transaction moves the asset.
            transaction:
              type: string
              description: >-
                Base64 unsigned transaction. The holder is its fee payer and
                only signer; sign and send it unchanged.
            last_valid_block_height:
              type: integer
              description: >-
                It must land before this (about a minute) and before
                `expires_at`.
    ErrorCode:
      type: string
      description: Every `code` v2 returns. Branch on these, never on the message text.
      enum:
        - RATE_LIMITED
        - AUTH_UNAVAILABLE
        - NO_PROGRAM
        - PROGRAM_INACTIVE
        - NOT_AVAILABLE
        - BAD_JSON
        - BAD_IDEMPOTENCY_KEY
        - IDEMPOTENCY_KEY_REUSED
        - BAD_RECIPIENT
        - BAD_PACK
        - BAD_CATEGORY
        - BAD_ODDS
        - BAD_QUANTITY
        - ODDS_UNAVAILABLE
        - BAD_REFUND_ADDRESS
        - PACK_NOT_OFFERED
        - PACK_UNAVAILABLE
        - WALLET_REFUSED
        - WALLET_BLOCKED
        - SCREENING_UNAVAILABLE
        - UNKNOWN_ORDER
        - NOT_PULLED
        - VERIFY_UNAVAILABLE
        - BAD_CURSOR
        - BAD_LIMIT
        - BAD_STATUS
        - BAD_ADDRESS
        - BAD_PARTNER_USER_REF
        - TOO_MANY_WALLETS
        - UNKNOWN_TOKEN
        - BAD_HOLDER
        - NOT_HOLDER
        - CHAIN_UNAVAILABLE
        - TOKEN_NOT_MINTED
        - TOKEN_BURNED
        - TOKEN_NOT_LIVE
        - NO_OFFER
        - PAYOUT_CHAIN_NOT_SUPPORTED
        - PAYOUT_CHAIN_NOT_ENABLED
        - BAD_PAYOUT_ADDRESS
        - USE_SHIPMENT_ENDPOINT
        - BAD_TOKEN_IDS
        - TOKEN_IN_SHIPMENT
        - BAD_COVER
        - COVER_NOT_ALLOWED
        - COVER_UNAVAILABLE
        - BAD_MAX_COST
        - NOT_SHIPPABLE
        - PARTNER_GOODS
        - COUNTRY_NOT_SUPPORTED
        - OVER_CUSTOMS_CAP
        - RATE_UNAVAILABLE
        - PRICE_CHANGED
        - UNKNOWN_SHIPMENT
        - NOT_PAID
        - ALREADY_REDEEMED
        - HOLDER_CHANGED
        - UNKNOWN_QUOTE
        - INVALID_WEBHOOK_URL
        - WEBHOOK_ACCOUNT_CHANGED
        - WEBHOOKS_UNAVAILABLE
        - UNKNOWN_WEBHOOK
        - KEY_ROTATED
        - BAD_PERIOD
        - INVALID_KEY
        - NO_PREVIOUS_KEY
        - ALREADY_ROTATED
        - UNKNOWN_PAYMENT
        - NOT_BURNED
    Odds:
      type: string
      enum:
        - standard
        - hot
        - chill
        - classic
      description: >-
        The odds a pack is opened at, as in our app's picker. Standard, Hot and
        Chill share one value-band ladder and differ only in the chance of each
        band; Classic is the pack's own bands and chances. A pack that sells
        only its own odds sells just `classic`. [Odds](/partner-api/v2/odds).
    SellbackQuoteBase:
      type: object
      required:
        - quote_id
        - chain
        - amount_usd
        - expires_at
        - payout
        - family
      properties:
        quote_id:
          type: string
          description: '`0x` + 64 hex.'
        chain:
          $ref: '#/components/schemas/ChainKey'
        amount_usd:
          type: number
          description: Exactly what the payout sends.
        expires_at:
          type: string
          format: date-time
          description: 10 minutes after issue, or the end of the fresh window if sooner.
        payout:
          $ref: '#/components/schemas/PayoutDestination'
        family:
          type: string
          enum:
            - evm
            - solana
    EvmBurnQuote:
      type: object
      description: >-
        The EIP-712 `Quote` struct to pass to `burnWithQuote` exactly as
        returned. Domain: name `CatchBackCards`, version `1`, your mint chain
        id, your contract. `kind` 1 is a sell-back, 2 a shipment. `tokenId`,
        `amount` (USDC, 6 decimals; "0" for a shipment) and `expiresAt` (unix
        seconds) are decimal strings: convert them to bigints.
      required:
        - tokenId
        - kind
        - quoteId
        - holder
        - payoutHash
        - amount
        - expiresAt
      properties:
        tokenId:
          type: string
        kind:
          type: integer
          enum:
            - 1
            - 2
        quoteId:
          type: string
          description: bytes32.
        holder:
          type: string
        payoutHash:
          type: string
          description: >-
            bytes32. Sell-back: keccak256(abi.encode(string payout.chain, string
            payout.address)). Shipment: keccak256(abi.encode(string "shipment",
            string quote_id)).
        amount:
          type: string
        expiresAt:
          type: string
    ChainKey:
      type: string
      description: >-
        A chain as `<family>:<id>`: `evm:8453` is Base, `evm:<chainId>` any
        other EVM chain (e.g. `evm:196`, X Layer), `solana:mainnet` Solana. The
        sandbox uses a public testnet.
      pattern: ^(evm:[0-9]+|solana:(mainnet|devnet))$
      examples:
        - evm:196
    PayoutDestination:
      type: object
      required:
        - chain
        - address
      properties:
        chain:
          $ref: '#/components/schemas/ChainKey'
        address:
          type: string
  responses:
    Unauthorized:
      description: >-
        - `Missing or malformed API key`: no `Bearer cb_live_…` header.

        - `Invalid API key`: unknown or disabled, or a rotated key past its 24
        hours.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Missing or malformed API key
    RateLimited:
      description: >-
        `RATE_LIMITED`: too many requests from this key. Wait
        `retry_after_seconds`. Limits per key: `POST /orders` 30 a minute; the
        two shipment estimates 30 a minute together; every other endpoint 120 a
        minute together.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Too many requests. Slow down.
            code: RATE_LIMITED
            retry_after_seconds: 23
    ServerError:
      description: >-
        Our fault. Retry with backoff, with the same `Idempotency-Key` where the
        endpoint takes one.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Something went wrong; retry with the same Idempotency-Key.
  headers:
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        minimum: 1
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: cb_live_<48 hex>
      description: >-
        Your API key (`cb_live_…`), sent as a bearer token, with the scope
        `nft:orders`. Keep it on your servers: never in a browser, app or
        wallet. Use a separate key per environment. A request from a country on
        our sanctions list gets a `403` with `Access denied`, whether or not it
        has a valid key. See [Authentication and
        keys](/partner-api/v2/authentication).

````

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