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

# Get a pack's pool

> What one pack can pull at one odds choice: the value bands with their chances, whether those odds are selling right now, and every item a pull can produce, highest value first. This is the same information as the odds panel in our app; show it to your customers before they buy.

A pack that sells only its own odds answers `odds: "classic"` with its own band shape (`ClassicPackPool`). Every other pack answers `ModePackPool`.



## OpenAPI

````yaml /partner-api/v2/openapi.yaml get /api/partner/v2/catalog/packs/pool
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/catalog/packs/pool:
    get:
      tags:
        - Packs
      summary: Get a pack's pool
      description: >-
        What one pack can pull at one odds choice: the value bands with their
        chances, whether those odds are selling right now, and every item a pull
        can produce, highest value first. This is the same information as the
        odds panel in our app; show it to your customers before they buy.


        A pack that sells only its own odds answers `odds: "classic"` with its
        own band shape (`ClassicPackPool`). Every other pack answers
        `ModePackPool`.
      operationId: getPackPool
      parameters:
        - name: pack_type
          in: query
          required: true
          description: A `pack_type` from List packs.
          schema:
            type: string
            minLength: 1
            maxLength: 100
          example: bronze
        - $ref: '#/components/parameters/PackCategory'
        - name: odds
          in: query
          description: One the pack sells. Default the pack's `default_odds`.
          schema:
            $ref: '#/components/schemas/Odds'
      responses:
        '200':
          description: The pool at those odds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackPool'
              example:
                pack_type: bronze
                name: Bronze Pack
                category: pokemon
                price: 25
                odds: hot
                label: Hot
                tagline: Fewer hits, bigger chase
                available: true
                fresh_buyback_rate: 1
                consolation_probability: null
                bands:
                  - band: 7.5-15
                    min_value: 7.5
                    max_value: 15
                    odds: 0.61
                    cards: 380
                  - band: 250-1000
                    min_value: 250
                    max_value: 1000
                    odds: 0.004
                    cards: 41
                odds_choices:
                  - odds: standard
                    label: Standard
                    available: true
                  - odds: hot
                    label: Hot
                    available: true
                  - odds: chill
                    label: Chill
                    available: true
                  - odds: classic
                    label: Classic
                    available: true
                total_cards: 1043
                cards:
                  - id: 0e94dc61-5a2f-4b1e-9c3d-7f8a1b2c3d4e
                    category: pokemon
                    name: Charizard ex
                    grading_company: PSA
                    grading_rank: 10
                    market_value: 410
                    render_image: https://...
                    band: 250-1000
        '400':
          description: >-
            - `BAD_PACK`: `pack_type` missing (or over 100 characters).

            - `BAD_CATEGORY`: unknown `category`.

            - `BAD_ODDS`: `odds` isn't `standard`, `hot`, `chill` or `classic`,
            or isn't one the pack sells; in the second case `odds` lists the
            choices it sells.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: bronze sells standard, hot, chill, classic
                code: BAD_ODDS
                odds:
                  - standard
                  - hot
                  - chill
                  - classic
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: '`PACK_NOT_OFFERED`: that pack isn''t sold through your program.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: >-
                  Unknown pack_type for pokemon. Use one from GET
                  /api/partner/v2/catalog/packs.
                code: PACK_NOT_OFFERED
        '409':
          description: >-
            `ODDS_UNAVAILABLE`: those odds aren't published for this pack right
            now; try another choice or later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: hot odds are not published for bronze
                code: ODDS_UNAVAILABLE
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          $ref: '#/components/responses/AuthUnavailable'
components:
  parameters:
    PackCategory:
      name: category
      in: query
      description: The catalog.
      schema:
        $ref: '#/components/schemas/PackCategory'
  schemas:
    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).
    PackPool:
      description: >-
        `ModePackPool` for a pack that sells the odds choice, `ClassicPackPool`
        (`odds: "classic"`, with `bucket_id` bands) for a pack that sells only
        its own odds.
      anyOf:
        - $ref: '#/components/schemas/ModePackPool'
        - $ref: '#/components/schemas/ClassicPackPool'
    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.
    PackCategory:
      type: string
      enum:
        - pokemon
        - onepiece
        - sports
        - riftbound
        - watches
        - goods
      default: pokemon
      description: >-
        `goods` packs hold streetwear and jewelry. Raw singles have no category
        of their own: they come out of other categories' packs.
    ModePackPool:
      type: object
      required:
        - pack_type
        - name
        - category
        - price
        - odds
        - label
        - tagline
        - available
        - fresh_buyback_rate
        - consolation_probability
        - bands
        - odds_choices
        - total_cards
        - cards
      properties:
        pack_type:
          type: string
        name:
          type: string
        category:
          $ref: '#/components/schemas/PackCategory'
        price:
          type: number
        odds:
          $ref: '#/components/schemas/Odds'
        label:
          type: string
        tagline:
          type: string
        available:
          type: boolean
          description: Whether these odds are selling right now.
        fresh_buyback_rate:
          type: number
          description: The sell-back rate in the fresh window, as a fraction (`1` = 100%).
        consolation_probability:
          type:
            - number
            - 'null'
          description: The chance of the pack's consolation prize, where it has one.
        bands:
          type: array
          items:
            $ref: '#/components/schemas/PoolBand'
        odds_choices:
          type: array
          items:
            $ref: '#/components/schemas/OddsChoice'
        total_cards:
          type: integer
        cards:
          type: array
          description: Every item a pull can produce at these odds, highest value first.
          items:
            allOf:
              - $ref: '#/components/schemas/Item'
              - type: object
                required:
                  - band
                properties:
                  band:
                    type: string
                    description: The `band` it sits in.
    ClassicPackPool:
      type: object
      required:
        - pack_type
        - name
        - category
        - price
        - odds
        - label
        - tagline
        - available
        - bands
        - chase
        - odds_choices
        - total_cards
        - cards
      properties:
        pack_type:
          type: string
        name:
          type: string
        category:
          $ref: '#/components/schemas/PackCategory'
        price:
          type: number
        odds:
          type: string
          const: classic
        label:
          type: string
          const: Classic
        tagline:
          type: string
        available:
          type: boolean
        reason:
          type: string
          description: Only on a pack that isn't on sale and has no pool right now.
        kind:
          type: string
          const: slab
        bands:
          type: array
          items:
            $ref: '#/components/schemas/ClassicPoolBand'
        chase:
          oneOf:
            - type: object
              required:
                - card
                - probability
                - odds_label
                - label
                - ends_at
              properties:
                card:
                  oneOf:
                    - $ref: '#/components/schemas/Item'
                    - type: 'null'
                probability:
                  type: number
                odds_label:
                  type:
                    - string
                    - 'null'
                label:
                  type:
                    - string
                    - 'null'
                ends_at:
                  type:
                    - string
                    - 'null'
                  format: date-time
            - type: 'null'
        odds_choices:
          type: array
          items:
            $ref: '#/components/schemas/OddsChoice'
        total_cards:
          type: integer
        cards:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/Item'
              - type: object
                required:
                  - bucket_id
                properties:
                  bucket_id:
                    type: string
    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
    PoolBand:
      type: object
      required:
        - band
        - min_value
        - max_value
        - odds
        - cards
      properties:
        band:
          type: string
          description: '`<min_value>-<max_value>`.'
        min_value:
          type: number
        max_value:
          type: number
        odds:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            The chance of a pull landing in this band at these odds. A band at 0
            can't pull.
        cards:
          type: integer
          description: How many items sit in it.
    OddsChoice:
      type: object
      required:
        - odds
        - label
        - available
      properties:
        odds:
          $ref: '#/components/schemas/Odds'
        label:
          type: string
        available:
          type: boolean
          description: Whether these odds are selling right now.
    Item:
      type: object
      description: >-
        An item's catalog fields. Which fields an item has depends on its
        category; every one can be absent or null.
      required:
        - id
        - category
      additionalProperties: true
      properties:
        id:
          type: string
        category:
          $ref: '#/components/schemas/PackCategory'
        name:
          type:
            - string
            - 'null'
        set:
          type:
            - string
            - 'null'
        year:
          type:
            - string
            - integer
            - 'null'
        number:
          type:
            - string
            - 'null'
        variant:
          type:
            - string
            - 'null'
        rarity:
          type:
            - string
            - 'null'
          description: Print rarity, e.g. "Rare Holo".
        card_type:
          type:
            - string
            - 'null'
        language:
          type:
            - string
            - 'null'
        slab_label:
          type:
            - string
            - 'null'
        grading_company:
          type:
            - string
            - 'null'
        grading_rank:
          type:
            - number
            - string
            - 'null'
        card_condition:
          type:
            - string
            - 'null'
        cert_number:
          type:
            - string
            - 'null'
        brand:
          type:
            - string
            - 'null'
        reference_number:
          type:
            - string
            - 'null'
        condition:
          type:
            - string
            - 'null'
        size:
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - 'null'
        video_url:
          type:
            - string
            - 'null'
        sport:
          type:
            - string
            - 'null'
        player_name:
          type:
            - string
            - 'null'
        team:
          type:
            - string
            - 'null'
        manufacturer:
          type:
            - string
            - 'null'
        parallel:
          type:
            - string
            - 'null'
        is_rookie:
          type:
            - boolean
            - 'null'
        is_autograph:
          type:
            - boolean
            - 'null'
        is_memorabilia:
          type:
            - boolean
            - 'null'
        serial_numbered:
          type:
            - string
            - integer
            - boolean
            - 'null'
        front_image:
          type:
            - string
            - 'null'
        back_image:
          type:
            - string
            - 'null'
        render_image:
          type:
            - string
            - 'null'
        image_url:
          type:
            - string
            - 'null'
        market_value:
          type:
            - number
            - 'null'
          description: The item's current market value in dollars.
    ClassicPoolBand:
      type: object
      required:
        - bucket_id
        - label
        - min_value
        - max_value
        - odds
        - is_consolation
        - hittable_cards
      properties:
        bucket_id:
          type: string
        label:
          type:
            - string
            - 'null'
        min_value:
          type: number
        max_value:
          type: number
        odds:
          type: number
          minimum: 0
          maximum: 1
        is_consolation:
          type: boolean
        hittable_cards:
          type: integer
  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
    Forbidden:
      description: >-
        - `API key lacks required scope: nft:orders`.

        - `NO_PROGRAM`: the key isn't linked to a partner program.

        - `PROGRAM_INACTIVE`: your program is not live.

        - `NOT_AVAILABLE`: wallet orders aren't switched on for your program
        yet.

        - `Access denied`: a request from a country on our sanctions list.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: This partner program is not live
            code: PROGRAM_INACTIVE
    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.
    AuthUnavailable:
      description: >-
        `AUTH_UNAVAILABLE`, or no code: we couldn't check your key or load your
        program right now. This never means the key is bad; retry after
        `Retry-After`.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Could not load the partner program; try again.
  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.