> ## Documentation Index > Fetch the complete documentation index at: https://docs.renaiss.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Get a pack > Look up a pack by `slug` to see its price, tier odds and buyback terms. The response includes catalog value ranges and the advertised buyback percentage. Use these fields when explaining the odds and value to a buyer. | Value | What it describes | | - | - | | Tier percentages | Rounded odds across the whole set. | | `expectedValueInUsd` | The expected value stored with the pack. | | `activeSetExpectedValueInUsd` | The average value across the entire active set used by the v3 machine. The remaining undrawn cards can have a different average. | USD amounts use cents. USDT amounts use 18 decimal places. Both are encoded as integer strings. See [pack catalog access](https://docs.renaiss.xyz/gacha.md#browse-packs) for builder-only packs. ## Request Optional builder key ## Response ## Error codes Match the HTTP status and response text to a row below. For guidance on codes shared across endpoints, see [Error meanings and recovery](https://docs.renaiss.xyz/api-reference/errors.md). | HTTP | Error code | Text field | Response text and recovery | | :- | :- | :- | :- | | `400` | `INVALID_SCHEMA` | `message` | `Unable to load pack details` | | `400` | `WRONG_REQUEST_PARAMS` | `message` | `Bad request - invalid parameters` | | `401` | `API_AUTH_INVALID_CREDENTIAL` | `error` | `Invalid authentication credential` The builder key is malformed, unknown, expired or revoked. Check the key. Do not retry with the same key. | | `403` | `API_AUTH_CREDENTIAL_NOT_ALLOWED` | `error` | `Credential is not allowed by this policy` Omit credentials, or send only an optional builder key in `x-builder-api-key`. | | `403` | `GACHA_V3_BUILDER_NOT_ACCEPTED_ON_PUBLIC_API` | `error` | `This builder checks out on its own surface, not on the public API` This builder key cannot be used on this API. Do not retry; contact Renaiss. | | `404` | `CARD_PACK_NOT_FOUND` | `message` | `Pack not found` | | `408` | `SUBGRAPH_ABORTED` | `message` | `Unable to load pack details` Mainnet can return this for a timed-out pack read. Testnet returns HTTP `502` with `SUBGRAPH_NETWORK_ERROR` for that timeout. | | `429` | `API_AUTH_RATE_LIMITED` | `error` | `Authentication rate limit exceeded` The builder key hit its rate limit. Wait a little, then retry at a lower rate. | | `429` | `SUBGRAPH_RATE_LIMITED` | `message` | `Unable to load pack details` | | `500` | `API_AUTH_ERROR` | `error` | `Internal server error` | | `500` | `FUNCTION_ERROR` | `error` | `Internal server error` | | `500` | `FUNCTION_ERROR` | `message` | `Unable to load pack details` | | `500` | `CARD_PACKS_QUERY_FAILED` `SUBGRAPH_QUERY_FAILED` | `message` | `Unable to load pack details` Read again after a short wait. | | `500` | Other code | `message` | `Unable to load pack details` | | `502` | `SUBGRAPH_NETWORK_ERROR` `SUBGRAPH_REQUEST_FAILED` `SUBGRAPH_QUERY_ERROR` | `message` | `Unable to load pack details` Read again after a short wait. | | `502` | Other code | `message` | `Unable to load pack details` | ## OpenAPI ````yaml api-reference/openapi.json GET /v2/gacha/packs/{slug} openapi: 3.1.1 info: version: 1.0.0 title: Renaiss Builder API v2 description: >- Builder API v2 for gacha, marketplace and redemption with external wallets on BNB Smart Chain (chain 56). Any active, approved builder key can prepare purchases. A collectible is an item a wallet can pull, trade, sell back or redeem, such as a card. This API calls every such item a collectible (e.g. cards), in paths, fields and descriptions. Browse publicly, then prepare and sign actions with the buyer wallet. Gacha history and buyback offers require your builder key; purchases and buybacks also require a wallet action signature. Private shipping data and redemption require a wallet access token, which the API issues from a registered partner origin after the wallet signs a sign-in message. Gacha and marketplace never use a wallet access token. Keep the builder key on your backend. The acting wallet is an EOA or a deployed ERC-1271 contract account. EIP-7702 delegated accounts, ERC-6492 and ERC-8010 wrapped signatures and Renaiss-managed Safes are refused (a Safe only after its signature verified). A pull to a contract account that cannot receive ERC-721 tokens returns `CONTRACT_WALLET_CANNOT_RECEIVE_NFT`. A failed chain read returns `API_AUTH_ERROR` (500). Wallet access tokens and redemption are EOA only. servers: - url: https://api.renaiss.xyz description: BNB Smart Chain - url: https://dev-api.renaiss.xyz description: BNB testnet security: [] tags: - name: Gacha v2 description: >- Direct-EOA pack browsing, purchases, collectible (e.g. card) reveals, purchase history and buybacks. Start here; no wallet access token is needed. - name: Marketplace description: >- Public collectible (e.g. card) browsing and external-wallet asks, bids, purchases and cancellations. Trading requires builder authorization and wallet action signatures. - name: Users description: >- What one wallet address has and did: its collectibles (e.g. cards), their total market value and its activities. The whole wallet, whichever builder it used. Requires your builder key only. - name: Redemption description: >- Shipping eligibility, quotes, redemption preparation, submission and tracking. Requires your builder key and a wallet access token for the same wallet. - name: Wallet access tokens description: >- Get, refresh and revoke the wallet access tokens that Redeem needs. The wallet signs a sign-in message (valid 5 minutes, one use); the API returns a wallet access token (15 minutes) and a refresh token (7 days, single use). Register exact partner frontend origins with Renaiss before use. Gacha and marketplace never use a wallet access token. paths: /v2/gacha/packs/{slug}: get: tags: - Gacha v2 summary: Get VRF gacha pack by slug description: Look up a pack by `slug` to see its price, tier odds and buyback terms. parameters: - schema: type: string minLength: 1 required: true name: slug in: path - $ref: '#/components/parameters/OptionalPackBuilderKey' responses: '200': description: Success content: application/json: schema: type: object properties: cardPack: type: object properties: id: type: string format: uuid slug: type: string name: type: string packType: type: string enum: - limited - perpetual - v3 - v3-limited stage: type: string enum: - countdown - active - soldout-or-restocking - archived description: type: string description: >- Pack description as authored: inline-only markdown (**bold**, *italic*, __underline__) priceInUsdt: type: string pattern: ^[0-9]+$ description: >- Pack purchase price in 18-decimal USDT units, serialized as a decimal string. expectedValueInUsd: type: - string - 'null' pattern: ^[0-9]+$ description: >- Stored pack EV metadata in USD cents, serialized as a decimal string; null when unset. For v3 machine display use `activeSetExpectedValueInUsd` from `GET /v2/gacha/packs/{slug}`. This field is not recomputed from active or remaining collectibles. packBannerVideoUrl: type: - string - 'null' gachaMachineVideoUrl: type: - string - 'null' gachaRippingPackAnimationVideoUrl: type: - string - 'null' onChainPackId: type: string description: >- 32 bytes encoded as 0x followed by 64 hexadecimal digits. vendingMachineAddress: type: string description: >- 20-byte, 0x-prefixed wallet or contract address. Use lowercase or a valid checksum. tiers: type: array items: type: object properties: tier: type: integer name: anyOf: - type: string enum: - TOP - S - A - B - C - D - type: string enum: - epic - rare - uncommon - common - legendary - thorn - bloom - crown chance: anyOf: - type: number - type: string enum: - UNDER-1-PERCENT description: >- Whole-set tier percentage, rounded to the nearest integer; a positive percentage below 1 is `UNDER-1-PERCENT`. Rounded tiers need not sum to 100. This is not the probability among remaining undrawn collectibles. priceRangeInUsd: type: object properties: min: type: string pattern: ^[0-9]+$ max: type: string pattern: ^[0-9]+$ required: - min - max description: >- Storefront catalog display range in USD cents, serialized as decimal strings. Min is the configured tier floor; max is the next higher tier's floor, or the public catalog maximum for the highest tier. Not active-set or remaining-collectible values; not a guaranteed prize range. required: - tier - name - chance - priceRangeInUsd activeSetExpectedValueInUsd: type: string pattern: ^[0-9]+$ description: >- Mean base collectible value across every slot in the selected active set, including collectibles already drawn, in USD cents, rounded half-up to the nearest cent; 0 for an empty set. This is the EV displayed by the renaiss.xyz v3 machine, before buyback percentage, not the EV of remaining collectibles or a guaranteed return. buybackConfig: type: array items: type: object properties: buybackPercentage: type: number description: >- Share of the collectible's base value the buyback pays, e.g. 85 means 85%. buybackExpiredInSeconds: type: integer minimum: 0 description: >- How long after the draw this tier lasts, in seconds. required: - buybackPercentage - buybackExpiredInSeconds description: >- The pack's buyback tiers, soonest end first. A draw resolved now gets these tiers and keeps them: a later change to the pack reaches new draws only. A buyback pays the percent of the first tier whose `buybackExpiredInSeconds` has not passed since the draw resolved; a tier still applies at that second. The largest `buybackExpiredInSeconds` is the longest window: a collectible is released only after it, and a pull appears in `GET /v2/gacha/packs/{slug}/pull-history` after it or after 24 hours, whichever is shorter. Empty when the pack has no tiers. Read `GET /v2/gacha/buyback/offers` for the actual amount and expiry. required: - id - slug - name - packType - stage - description - priceInUsdt - expectedValueInUsd - packBannerVideoUrl - gachaMachineVideoUrl - gachaRippingPackAnimationVideoUrl - onChainPackId - vendingMachineAddress - tiers - activeSetExpectedValueInUsd - buybackConfig required: - cardPack '400': description: >- Bad request - invalid parameters See [error codes and recovery](/api-reference/gacha/get-pack#http-errors). content: application/json: schema: type: object properties: code: type: string enum: - WRONG_REQUEST_PARAMS - INVALID_SCHEMA description: |- Possible codes: - `WRONG_REQUEST_PARAMS`: The request payload is invalid - `INVALID_SCHEMA`: Invalid schema message: type: string required: - code - message '401': description: >- The supplied builder key is not accepted. See [error codes and recovery](/api-reference/gacha/get-pack#http-errors). content: application/json: schema: type: object properties: error: type: string description: A short sentence about what went wrong. code: type: string enum: - API_AUTH_INVALID_CREDENTIAL required: - error - code example: error: Invalid authentication credential code: API_AUTH_INVALID_CREDENTIAL '403': description: >- The supplied credential is not allowed on this public read. See [error codes and recovery](/api-reference/gacha/get-pack#http-errors). content: application/json: schema: type: object properties: error: type: string description: A short sentence about what went wrong. code: type: string enum: - API_AUTH_CREDENTIAL_NOT_ALLOWED - GACHA_V3_BUILDER_NOT_ACCEPTED_ON_PUBLIC_API required: - error - code example: error: Credential is not allowed by this policy code: API_AUTH_CREDENTIAL_NOT_ALLOWED '404': description: >- Pack not found See [error codes and recovery](/api-reference/gacha/get-pack#http-errors). content: application/json: schema: type: object properties: code: type: string enum: - CARD_PACK_NOT_FOUND description: |- Possible codes: - `CARD_PACK_NOT_FOUND`: Card pack not found message: type: string required: - code - message '408': description: Mainnet pack-read timeout. Testnet reports this condition as 502. content: application/json: schema: type: object properties: code: type: string enum: - SUBGRAPH_ABORTED message: type: string required: - code - message example: code: SUBGRAPH_ABORTED message: Unable to load pack details '429': description: >- Too many requests - `SUBGRAPH_RATE_LIMITED` carries a `Retry-After` header: wait that many whole seconds, then retry. Too many requests with this builder key. See [error codes and recovery](/api-reference/gacha/get-pack#http-errors). headers: Retry-After: description: Seconds to wait before retrying when this header is present. schema: type: integer minimum: 0 content: application/json: schema: anyOf: - type: object properties: code: type: string enum: - SUBGRAPH_RATE_LIMITED description: >- Possible codes: - `SUBGRAPH_RATE_LIMITED`: Too many requests right now. Retry after a short wait. message: type: string required: - code - message - type: object properties: error: type: string description: A short sentence about what went wrong. code: type: string enum: - API_AUTH_RATE_LIMITED required: - error - code '500': description: >- A failure on our side. Retry later. See [error codes and recovery](/api-reference/gacha/get-pack#http-errors). content: application/json: schema: anyOf: - type: object properties: code: type: string message: type: string required: - code - message - type: object properties: error: type: string description: A short sentence about what went wrong. code: type: string required: - error - code example: code: FUNCTION_ERROR message: Unable to load pack details '502': description: >- A failure on our side. Retry later. See [error codes and recovery](/api-reference/gacha/get-pack#http-errors). content: application/json: schema: type: object properties: code: type: string examples: - SUBGRAPH_NETWORK_ERROR - SUBGRAPH_REQUEST_FAILED - SUBGRAPH_QUERY_ERROR message: type: string required: - code - message example: message: Unable to load pack details code: SUBGRAPH_NETWORK_ERROR security: [] components: parameters: OptionalPackBuilderKey: name: x-builder-api-key in: header required: false description: >- Leave blank to browse public packs. Supply your builder key to include packs available to your builder. schema: type: string ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.