> ## 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. # Prepare a pull > Get the purchase details and Permit2 signing data for the buyer’s chosen pack and quantity. Compare the returned chain, wallet, pack, price and quantity with the purchase the buyer reviewed before asking them to sign. See [Gacha integration](https://docs.renaiss.xyz/gacha.md#pull-a-card). Before submitting, check the wallet’s allowance for `approval.spender` on `approval.token`. If it is below `approval.requiredAmount`, approve that amount and wait for confirmation. ## Request Builder key required ## 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` | `API_AUTH_INVALID_INPUT` | `error` | `Request body is too large` The request body exceeds 16 KiB. Send a smaller body. | | `400` | `CARD_PACK_NOT_ACTIVE` | `error` | `Card pack is not active` The pack is not on sale. Do not retry; show the pack as unavailable. | | `400` | `CONTRACT_WALLET_CANNOT_RECEIVE_NFT` | `error` | `The contract wallet does not accept ERC-721 transfers from the NFT contract` The wallet is a contract that cannot receive the collectible. Use a wallet that can receive collectibles. | | `400` | `WRONG_REQUEST_PARAMS` | `error` | `Delegated wallets are not supported by the v2 EOA contract` A field is missing or has the wrong form. Fix the request and send it again. It is also served as `{ error, code }` when the wallet is a delegated account, which this API does not support: use another wallet. | | `400` | `WRONG_REQUEST_PARAMS` | `message` | `Bad request - invalid parameters` | | `400` | No code | `text/plain` | `Malformed JSON in request body` | | `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. | | `401` | `API_AUTH_MISSING_CREDENTIAL` | `error` | `Required authentication credential is missing` No builder key was sent. Send your builder key in the `x-builder-api-key` header. | | `403` | `API_AUTH_CREDENTIAL_NOT_ALLOWED` | `error` | `Credential is not allowed by this policy` This route takes a builder key only. Remove the `Authorization` header and any other credential, then send the request again. | | `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` | `error` | `VRF card pack not found` The pack id is unknown or the pack is not public. Read the pack ids from `GET /v2/gacha/packs`. Do not retry with the same id. | | `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. | | `500` | `API_AUTH_ERROR` | `error` | `Internal server error` | | `500` | `FUNCTION_ERROR` | `error` | `Internal server error` | | `500` | `CARD_PACKS_QUERY_FAILED` `GACHA_V3_ON_CHAIN_PACK_ID_NOT_SET` `GACHA_V3_VENDING_MACHINE_ADDRESS_NOT_FOUND` `GACHA_V3_OPEN_PACK_CHECKOUT_BUDGET_ERROR` `GACHA_V3_SUB_PACK_LINEUP_LOAD_FAILED` | `error` | `Internal server error` If this persists, contact Renaiss with `x-request-id`. | | `500` | Other code | `error` | `Internal server error` | ## OpenAPI ````yaml api-reference/openapi.json POST /v2/gacha/pull/prepare 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/pull/prepare: post: tags: - Gacha v2 summary: Prepare a purchase and Permit2 typed data description: >- Get the purchase details and Permit2 signing data for the buyer’s chosen pack and quantity. requestBody: required: true content: application/json: schema: type: object properties: buyerWalletAddress: type: string packId: type: string format: uuid quantity: type: integer minimum: 1 maximum: 10 default: 1 required: - buyerWalletAddress - packId additionalProperties: false responses: '200': description: Success content: application/json: schema: allOf: - type: object properties: chainId: type: integer exclusiveMinimum: 0 buyerWalletAddress: type: string description: >- 20-byte, 0x-prefixed wallet or contract address. Use lowercase or a valid checksum. pack: type: object properties: id: type: string format: uuid onChainPackId: type: string description: >- 32 bytes encoded as 0x followed by 64 hexadecimal digits. priceInUsdt: type: string pattern: ^\d+$ vendingMachineAddress: type: string description: >- 20-byte, 0x-prefixed wallet or contract address. Use lowercase or a valid checksum. required: - id - onChainPackId - priceInUsdt - vendingMachineAddress permit2TypedData: type: object properties: domain: type: object properties: name: type: string enum: - Permit2 chainId: type: integer exclusiveMinimum: 0 verifyingContract: type: string description: >- 20-byte, 0x-prefixed wallet or contract address. Use lowercase or a valid checksum. required: - name - chainId - verifyingContract types: type: object additionalProperties: type: array items: type: object properties: name: type: string type: type: string required: - name - type primaryType: type: string enum: - PermitWitnessTransferFrom message: type: object properties: permitted: type: object properties: token: type: string description: >- 20-byte, 0x-prefixed wallet or contract address. Use lowercase or a valid checksum. amount: type: string pattern: ^\d+$ required: - token - amount spender: type: string description: >- 20-byte, 0x-prefixed wallet or contract address. Use lowercase or a valid checksum. nonce: type: string pattern: ^\d+$ deadline: type: string pattern: ^\d+$ witness: type: object properties: packId: type: string description: >- 32 bytes encoded as 0x followed by 64 hexadecimal digits. builder: type: string description: >- 32 bytes encoded as 0x followed by 64 hexadecimal digits. numOfTokens: type: string pattern: ^\d+$ required: - packId - builder - numOfTokens required: - permitted - spender - nonce - deadline - witness required: - domain - types - primaryType - message unsignedPullPayload: type: object properties: packId: type: string format: uuid builderCode: type: string description: >- 32 bytes encoded as 0x followed by 64 hexadecimal digits. numOfTokens: type: integer minimum: 1 maximum: 10 amountPerToken: type: string pattern: ^\d+$ nonce: type: string pattern: ^\d+$ deadline: type: integer exclusiveMinimum: 0 required: - packId - builderCode - numOfTokens - amountPerToken - nonce - deadline required: - chainId - buyerWalletAddress - pack - permit2TypedData - unsignedPullPayload - type: object properties: approval: type: object properties: token: type: string description: >- 20-byte, 0x-prefixed wallet or contract address. Use lowercase or a valid checksum. spender: type: string description: >- 20-byte, 0x-prefixed wallet or contract address. Use lowercase or a valid checksum. requiredAmount: type: string required: - token - spender - requiredAmount required: - approval '400': description: >- The request was refused before anything happened. See [error codes and recovery](/api-reference/gacha/prepare-pull#http-errors). content: text/plain: schema: type: string example: Malformed JSON in request body application/json: schema: anyOf: - type: object properties: error: type: string description: A short sentence about what went wrong. code: type: string enum: - WRONG_REQUEST_PARAMS - API_AUTH_INVALID_INPUT - CARD_PACK_NOT_ACTIVE - CONTRACT_WALLET_CANNOT_RECEIVE_NFT required: - error - code - type: object properties: code: type: string enum: - WRONG_REQUEST_PARAMS message: type: string description: A short sentence about what went wrong. required: - code - message example: code: WRONG_REQUEST_PARAMS message: Bad request - invalid parameters '401': description: >- The builder key is missing or not accepted. See [error codes and recovery](/api-reference/gacha/prepare-pull#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_MISSING_CREDENTIAL - API_AUTH_INVALID_CREDENTIAL required: - error - code example: error: Required authentication credential is missing code: API_AUTH_MISSING_CREDENTIAL '403': description: >- The builder key is not allowed to make this request. See [error codes and recovery](/api-reference/gacha/prepare-pull#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: >- The pack was not found. See [error codes and recovery](/api-reference/gacha/prepare-pull#http-errors). content: application/json: schema: type: object properties: error: type: string description: A short sentence about what went wrong. code: type: string enum: - CARD_PACK_NOT_FOUND required: - error - code example: error: VRF card pack not found code: CARD_PACK_NOT_FOUND '429': description: >- Too many requests with this builder key. See [error codes and recovery](/api-reference/gacha/prepare-pull#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_RATE_LIMITED required: - error - code example: error: Authentication rate limit exceeded code: API_AUTH_RATE_LIMITED '500': description: >- A failure on our side. Retry later. See [error codes and recovery](/api-reference/gacha/prepare-pull#http-errors). content: application/json: schema: type: object properties: error: type: string description: A short sentence about what went wrong. code: type: string required: - error - code example: error: Internal server error code: FUNCTION_ERROR security: - builderAuth: [] components: securitySchemes: builderAuth: type: apiKey in: header name: x-builder-api-key description: >- Your approved builder API key. Keep it on your backend. Gacha and marketplace writes also require wallet action signatures. Redeem also needs a wallet access token, a Bearer token the API issues after the wallet signs a sign-in message. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.