> ## 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. # Submit a pull > Submit a signed pack purchase and get a `requestId` immediately. The draw continues after you close the connection. ## Submit and track a pull 1. **Sign the purchase.** Have the buyer sign the full Permit2 payload from [Prepare a pull](https://docs.renaiss.xyz/api-reference/gacha/prepare-pull.md). Send it with your builder key. The streaming endpoint accepts the same body and checks the same signature. 2. **Save the request ID.** The API returns HTTP `202` with `requestId` and the current status. The purchase belongs to this builder and buyer wallet. 3. **Check the result.** Use the ID to [get pull status](https://docs.renaiss.xyz/api-reference/gacha/get-pull-status.md) about once per second. Stop at `RESOLVED` or `FAILED`. If you lose the response, resend the **same signed payload** to recover the same `requestId`. A failed request can restart. The same signature can charge the buyer only once. If the pull stays in `PENDING_PAYMENT` for more than 10 minutes, stop polling and contact Renaiss with the original `requestId` before signing again. ## Request Builder key and wallet signature ## Response ### Failures after submission A new submission returns HTTP `202` with `PENDING_PAYMENT`. Resubmitting the same signed pull can restart a failed attempt. To check an existing request without restarting it, poll its `requestId`. A recorded `FAILED` means nothing was charged. Most codes return `Unable to fund the pull.` in `error.message`. The table quotes the other messages where they apply. | Code | `error.message` and recovery | | - | - | | `FUNCTION_ERROR` `GACHA_V3_ON_CHAIN_PACK_ID_NOT_SET` `GACHA_V3_SUB_PACK_LINEUP_LOAD_FAILED` `GACHA_V3_OPEN_PACK_CHECKOUT_BUDGET_ERROR` `GACHA_V3_MERKLE_ROOT_CHECK_FAILED` | `Unable to fund the pull.` If this persists, contact Renaiss with `x-request-id`. | | `CARD_PACK_NOT_ACTIVE` | Show the pack as unavailable. | | `CARD_PACK_NOT_FOUND` | The pack does not exist. Stop retrying this pack ID. | | `CONTRACT_REVERT` | A `FAILED` status confirms this pull was unpaid. Check the wallet balance and allowance before another attempt. | | `CONTRACT_WALLET_CANNOT_RECEIVE_NFT` | Use a wallet that can receive the collectible. | | `EOA_PURCHASE_REJECTED` | `Permit deadline must be within the next five minutes` Prepare a new pull with a valid deadline. | | `GACHA_V3_NOT_ENOUGH_CARDS_IN_SET` | Request fewer collectibles or wait. | | `GACHA_V3_NO_SELLABLE_LINEUP` | Try again when the pack is available. | | `GACHA_V3_PRICE_MISMATCH` | Read the new price, then prepare and sign again. | | `INSUFFICIENT_ALLOWANCE` | Approve at least `approval.requiredAmount` of USDT for `approval.spender` from the prepare response. Resend the signed pull before it expires. | | `INSUFFICIENT_USDT_AMOUNT` | Top up the wallet’s USDT balance. Resend the same signed pull before it expires, or prepare a new one. | | `OP_WALLET_BUSY` | `Payments are busy right now and nothing was charged. Please try again in a few seconds.` If the signature is still valid, resend the same signed request. Otherwise, prepare a new one. | | `PERMIT_DEADLINE_TOO_FAR` | Prepare again and use the new deadline. | | `PERMIT_EXPIRED` | Prepare and sign a fresh permit after checking payment status. | | `PULL_NOT_STARTED` | `The connection closed before the pull started. Nothing was charged. Send the same signed pull again.` | | `WRONG_REQUEST_PARAMS` | Use an eligible buyer wallet and prepare the pull again. | For an unrecognized code, check the [wallet’s pull history](https://docs.renaiss.xyz/api-reference/gacha/list-wallet-pulls.md) before signing again. On mainnet, a refused USDT transfer can still return `INSUFFICIENT_USDT_AMOUNT` when the allowance is short. Check both the balance and the USDT allowance for Permit2. On testnet, `INSUFFICIENT_ALLOWANCE` identifies a short approval when the balance covers the price. ## Error codes For HTTP `4xx` or `5xx`, match the status and response text 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` `404` | `EOA_PURCHASE_REJECTED` | `error` | **400** · `SAFE addresses are not supported by v2` Use a different buyer wallet. **404** · `Pack not found` Choose an available pack ID from [List packs](https://docs.renaiss.xyz/api-reference/gacha/list-packs.md). | | `400` | `WRONG_REQUEST_PARAMS` | `message` | `Bad request - invalid parameters` A field is missing or has the wrong form. Fix the request and send it again. | | `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` | `API_AUTH_INVALID_ACTION` | `error` | `Invalid wallet action proof` The signature was not accepted for the wallet and the prepared data, or the deadline has passed. Prepare again and sign the new data. For a contract wallet, its `isValidSignature` must return `0x1626ba7e` for the EIP-712 digest of the prepared data. | | `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. | | `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`, `FUNCTION_ERROR`, or another code | `error` | `Internal server error` Signature verification can fail if the API cannot read the chain. Retry later with the **same signed payload** to recover the original request. | | `500` | `CARD_PACKS_QUERY_FAILED` | `error` | `Internal server error` Read again after a short wait. | ## OpenAPI ````yaml api-reference/openapi.json POST /v2/gacha/pull/request 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/request: post: tags: - Gacha v2 summary: Submit a signed pull and poll its requestId description: >- Submit a signed pack purchase and get a `requestId` immediately. The draw continues after you close the connection. requestBody: required: true content: application/json: schema: type: object properties: packId: type: string format: uuid numOfTokens: type: integer minimum: 1 maximum: 10 amountPerToken: type: string pattern: ^\d+$ nonce: type: string pattern: ^\d+$ deadline: type: integer exclusiveMinimum: 0 buyerWalletAddress: type: string permitSignature: type: string description: >- Signature over the typed data that prepare returned, as hex of at most 4,096 bytes. An EOA signs the typed data. A contract wallet submits what its `isValidSignature` accepts for that data's EIP-712 digest, which can be empty (`0x`); Permit2 is the caller. The signature is checked before payment and again on chain. required: - packId - numOfTokens - amountPerToken - nonce - deadline - buyerWalletAddress - permitSignature additionalProperties: false responses: '202': description: The pull was accepted. The body is the pull status. content: application/json: schema: type: object properties: requestId: type: string format: uuid status: type: string enum: - PENDING_PAYMENT - PENDING_RESOLUTION - RESOLVED - FAILED description: >- - `PENDING_PAYMENT` — The API accepted the pull and is processing the payment. - `PENDING_RESOLUTION` — Payment is confirmed and the API is assigning cards. The status can no longer change to `FAILED`. - `RESOLVED` — The pull is complete. Read `result.draws` for the cards. - `FAILED` — The buyer was never charged. Read `error.code` for the reason. buyerWalletAddress: type: string description: >- 20-byte, 0x-prefixed wallet or contract address. Use lowercase or a valid checksum. packId: type: string format: uuid nonce: type: string numOfTokens: type: integer exclusiveMinimum: 0 permitFundTxHash: type: - string - 'null' description: >- The funding transaction hash. Null until payment is confirmed. error: type: - object - 'null' properties: code: type: string description: Why the request failed. message: type: string description: A short sentence about what went wrong. required: - code - message description: >- Contains `code` and `message` when `status` is `FAILED`. Null for all other statuses. See [pull failures and recovery](/api-reference/gacha/submit-pull#pull-failures). result: anyOf: - $ref: '#/components/schemas/GachaV2DrawStatus' - type: 'null' - type: 'null' description: >- The same body as `GET /v2/gacha/draw-status` for this pull. Null unless the status is `RESOLVED`. required: - requestId - status - buyerWalletAddress - packId - nonce - numOfTokens - permitFundTxHash - error - result examples: PENDING_PAYMENT: summary: The payment is in progress. value: requestId: 6f1c2a9e-4b7d-4e3a-9c15-8a2d0f7b3e64 buyerWalletAddress: '0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2' packId: 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13 nonce: '48210937465120938475' numOfTokens: 1 status: PENDING_PAYMENT permitFundTxHash: null error: null result: null PENDING_RESOLUTION: summary: The payment is confirmed. value: requestId: 6f1c2a9e-4b7d-4e3a-9c15-8a2d0f7b3e64 buyerWalletAddress: '0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2' packId: 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13 nonce: '48210937465120938475' numOfTokens: 1 status: PENDING_RESOLUTION permitFundTxHash: >- 0x9999999999999999999999999999999999999999999999999999999999999999 error: null result: null RESOLVED: summary: The collectibles are assigned. value: requestId: 6f1c2a9e-4b7d-4e3a-9c15-8a2d0f7b3e64 buyerWalletAddress: '0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2' packId: 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13 nonce: '48210937465120938475' numOfTokens: 1 status: RESOLVED permitFundTxHash: >- 0x9999999999999999999999999999999999999999999999999999999999999999 error: null result: permitFundTxHash: >- 0x9999999999999999999999999999999999999999999999999999999999999999 buyerWalletAddress: '0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2' packId: 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13 packName: Example Pack status: RESOLVED numOfTokens: 1 pulledAt: '2026-10-28T08:00:03.000Z' draws: - settlementId: >- 0x2222222222222222222222222222222222222222222222222222222222222222 tokenId: '1234567' releaseTxHash: null buybackTxHash: null buybackTiers: - buybackPercentage: 90 amountInUsdt: '40500000000000000000' expiresAt: '2026-10-28T09:00:04.000Z' tier: rare buybackBaseValueInUSD: '4500' buybackBonus: null type: POKEMON name: >- PSA 10 Gem Mint 2025 Example Set #001 Example Collectible frontImageUrl: https://example.com/collectibles/example-front.png attributes: - key: Grader value: PSA - key: Grade value: 10 Gem Mint FAILED: summary: The pull failed and nothing was charged. value: requestId: 6f1c2a9e-4b7d-4e3a-9c15-8a2d0f7b3e64 buyerWalletAddress: '0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2' packId: 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13 nonce: '48210937465120938475' numOfTokens: 1 status: FAILED permitFundTxHash: null error: code: INSUFFICIENT_USDT_AMOUNT message: Unable to fund the pull. result: null '400': description: >- The request was refused before anything happened. See [error codes and recovery](/api-reference/gacha/submit-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: - API_AUTH_INVALID_INPUT - EOA_PURCHASE_REJECTED 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/submit-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 request is refused. See [error codes and recovery](/api-reference/gacha/submit-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_INVALID_ACTION - API_AUTH_CREDENTIAL_NOT_ALLOWED - GACHA_V3_BUILDER_NOT_ACCEPTED_ON_PUBLIC_API required: - error - code example: error: Invalid wallet action proof code: API_AUTH_INVALID_ACTION '404': description: >- The pack was not found. See [error codes and recovery](/api-reference/gacha/submit-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: - EOA_PURCHASE_REJECTED required: - error - code example: error: Pack not found code: EOA_PURCHASE_REJECTED '429': description: >- Too many requests with this builder key. See [error codes and recovery](/api-reference/gacha/submit-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. Send the same signed pull again later: it returns the same `requestId` and is never charged twice. If you sent this signed pull before, it may already be paid; do not sign a new pull for it. See [error codes and recovery](/api-reference/gacha/submit-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: schemas: GachaV2DrawStatus: type: object properties: permitFundTxHash: type: string description: 32 bytes encoded as 0x followed by 64 hexadecimal digits. buyerWalletAddress: type: string description: >- 20-byte, 0x-prefixed wallet or contract address. Use lowercase or a valid checksum. packId: type: string format: uuid packName: type: string status: type: string enum: - PENDING_RESOLUTION - RESOLVED numOfTokens: type: integer exclusiveMinimum: 0 pulledAt: type: - string - 'null' format: date-time draws: type: array items: type: object properties: settlementId: type: string description: 32 bytes encoded as 0x followed by 64 hexadecimal digits. tokenId: type: string releaseTxHash: type: - string - 'null' description: 32 bytes encoded as 0x followed by 64 hexadecimal digits. buybackTxHash: type: - string - 'null' description: 32 bytes encoded as 0x followed by 64 hexadecimal digits. buybackTiers: type: array items: type: object properties: buybackPercentage: type: number description: Percent of the card's base value, e.g. 90 means 90%. amountInUsdt: type: string description: Price in USDT with 18 decimals in this tier. expiresAt: type: string description: >- When this tier ends. The tier still applies at that moment. required: - buybackPercentage - amountInUsdt - expiresAt description: >- Every buyback tier of this draw, past ones too, soonest end first, with the same prices as `GET /v2/gacha/buyback/offers`. The price at a moment is the `amountInUsdt` of the first tier whose `expiresAt` has not passed; a tier still applies at its `expiresAt`. Use it to display the offer. Before the user confirms a buyback, read `GET /v2/gacha/buyback/offers` and sign the amount it returns. The list stays the same after the collectible is sold back or delivered: read `buybackTxHash` and `releaseTxHash` for that. Empty when the draw has no buyback. tier: anyOf: - type: string enum: - TOP - S - A - B - C - D - type: string enum: - epic - rare - uncommon - common - legendary - thorn - bloom - crown - type: 'null' description: >- The collectible's tier for this draw. Null when the collectible details could not be loaded. buybackBaseValueInUSD: type: - string - 'null' description: >- The collectible's base buyback value in USD cents, bonus included. Null when the collectible details could not be loaded. buybackBonus: type: - object - 'null' properties: originalBuybackBaseValueInUSD: type: string description: >- The base buyback value before the bonus, in USD cents. Frozen when the set formed. bonusBps: type: integer description: 'The bonus in basis points: 2000 means +20%.' required: - originalBuybackBaseValueInUSD - bonusBps description: >- The buyback bonus of this collectible. The base buyback value field next to it and the `buybackTiers` amounts already include the bonus: do not apply it again. Null when the collectible has no bonus. Null when the collectible details could not be loaded. type: type: string enum: - POKEMON - ONE_PIECE - SPORTS description: The collectible's category. name: type: string description: Grade, year, set, number and title. frontImageUrl: type: string format: uri description: The graded slab in its Renaiss frame, on a dark background. attributes: type: array items: type: object properties: key: type: string value: type: string required: - key - value description: >- The collectible's details as key and value pairs. For a card, the keys in this order: Grader, Grade, Cert Number, Year, Set, Card Number, Character, Language. A key without a value is left out. Every value is a string. required: - settlementId - tokenId - releaseTxHash - buybackTxHash - buybackTiers - tier - buybackBaseValueInUSD - buybackBonus required: - permitFundTxHash - buyerWalletAddress - packId - packName - status - numOfTokens - pulledAt - draws 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.