> ## 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. # Settle a buyback > Settle a buyback using your builder key and the seller’s signed `BuybackUserAuthorization`. Review the selected settlement IDs and the total in USDT with the seller before signing. Submit settlement IDs from the same pack. An ID from another pack can return HTTP 404 with `EOA_PURCHASE_REJECTED` before the buyback is accepted. The wallet receives USDT. The seller can complete a buyback with zero USDT balance and zero Permit2 allowance. ## Request Builder key and wallet signature ## Response ## Error codes Braces in response text mark values supplied at runtime. 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` | `CONTRACT_REVERT` | `error` | `Smart contract execution reverted` `Contract error: {reason}` The buyback was rejected. Read `GET /v2/gacha/buyback/offers` to see which collectibles are still offered, then sign again. | | `400` | `EOA_PURCHASE_REJECTED` | `error` | `SAFE addresses are not supported by v2` The wallet cannot be used for this buyback. Use another wallet. | | `400` | `GACHA_V3_BUYBACK_EXPIRED` | `error` | `Buyback has expired for {buybackId}` No tier pays for a collectible now (window closed or a zero-percent hold). Read `GET /v2/gacha/buyback/offers` again and retry only the collectibles it returns. | | `400` | `GACHA_V3_BUYBACK_VERIFY_FAILED` | `error` | `Buyer does not own this card` The wallet does not own a collectible in the request. Read `GET /v2/gacha/buyback/offers` and sign only the collectibles it returns. | | `400` | `GACHA_V3_TOKEN_STATUS_INVALID` | `error` | `Card is already buyback or released` A collectible in the request was already sold back or sent to the wallet. Read `GET /v2/gacha/buyback/offers` and sign again for the collectibles that are still offered. | | `400` | `PERPETUAL_GACHA_PACK_VERIFY_BUYBACK_FAILED` | `error` | `Buyback token must be USDT` The signed token is not USDT. Prepare the buyback again from the offers list. | | `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` | Other code | `error` | Read the returned `error` string. | | `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 signed data, or the buyback window has closed. Read the offers again and sign the new data. For a contract wallet, its `isValidSignature` must return `0x1626ba7e` for the EIP-712 digest of the signed 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. | | `404` | `EOA_PURCHASE_REJECTED` | `error` | `One or more builder draws were not found` `Pack not found` One or more of the collectibles were not pulled by this wallet under your builder key, or the pack was not found. Check the pack id and the settlement ids from `GET /v2/gacha/buyback/offers`. | | `404` | `GACHA_V3_DRAW_RECORD_NOT_FOUND` | `error` | `Pack draw record not found for buybackId {buybackId}` A settlement ID could not be found for this pack. Refresh the offers and sign only the settlement IDs returned for that pack. | | `404` | `PERPETUAL_GACHA_PACK_NOT_FOUND` | `error` | `Perpetual VRF pack not found: {cardPackId}` The pack could not be found. Refresh the offers and check the pack ID. | | `404` | `PERPETUAL_GACHA_SUBPACK_RECORD_NOT_FOUND` | `error` | `Pack draw record not found for buybackId {buybackId}` `Perpetual set record not found` | | `404` | Other code | `error` | Read the returned `error` string. | | `409` | `GACHA_V3_BUYBACK_PRICE_CHANGED` | `error` | `amount {signedAmount} does not match expected total {expectedTotal}` The signed amount is not the price now: a buyback tier ended after you read the offers. Read `GET /v2/gacha/buyback/offers` again and sign the new amount. | | `409` | Other code | `error` | Read the returned `error` string. | | `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` The signature could not be checked because the chain could not be read. Retry the request. | | `500` | `FUNCTION_ERROR` | `error` | `Internal server error` | | `500` | `GACHA_V3_BUYBACK_SNAPSHOT_NOT_FOUND` `GACHA_V3_SETTLEMENT_ID_MISMATCH` `PERPETUAL_GACHA_BUYBACK_CONFIG_NOT_FOUND` `PERPETUAL_GACHA_VENDING_MACHINE_ADDRESS_NOT_FOUND` `GACHA_V3_BUYBACK_FAILED` `GACHA_V3_TIMESTAMP_MISSING` `CONTRACT_EXECUTION_ERROR` `OP_WALLET_NOT_AVAILABLE` `TRANSACTION_VERIFICATION_FAILED` `PERPETUAL_GACHA_BUYBACK_SYNC_FAILED` `INTERNAL_SERVER_ERROR` | `error` | `Internal server error` Check the wallet’s offers and activity before signing again. Provide `x-request-id` to Renaiss if the payout remains uncertain. | | `500` | Other code | `error` | `Internal server error` | | `503` | `OP_WALLET_BUSY` | `error` | `Payments are busy right now and nothing was charged. Please try again in a few seconds.` Every payment sender is busy. Retry the request. | | `503` | Other code | `error` | `Internal server error` | A `CONTRACT_REVERT` alone does not identify the cause of a transfer refusal. Check the wallet’s current offers before retrying. On HTTP 503 with `OP_WALLET_BUSY`, wait the number of seconds in `Retry-After` and resend the same signed buyback. A 404 with `PERPETUAL_GACHA_SUBPACK_RECORD_NOT_FOUND` can occur after the transaction confirms. Check the wallet’s activity and current offers before signing again. ## OpenAPI ````yaml api-reference/openapi.json POST /v2/gacha/buyback 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/buyback: post: tags: - Gacha v2 summary: Settle a wallet's draws for this builder using the wallet's signature description: >- Settle a buyback using your builder key and the seller’s signed `BuybackUserAuthorization`. requestBody: required: true content: application/json: schema: type: object properties: buyerWalletAddress: type: string cardPackId: type: string format: uuid buybackAuth: type: object properties: buybackIds: type: array items: type: string minItems: 1 maxItems: 10 token: type: string amount: type: string pattern: ^\d+$ required: - buybackIds - token - amount userSignature: type: string required: - buyerWalletAddress - cardPackId - buybackAuth - userSignature additionalProperties: false responses: '200': description: Success content: application/json: schema: type: object properties: txHash: type: string description: Hexadecimal string with a 0x prefix. totalAmountInUsdt: type: string pattern: ^[0-9]+$ itemCount: type: integer minimum: 1 required: - txHash - totalAmountInUsdt - itemCount '400': description: >- The request was refused before anything happened. - Other codes can appear when the chain rejects the buyback. Read `GET /v2/gacha/buyback/offers` before you send it again. See [error codes and recovery](/api-reference/gacha/settle-buyback#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 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/settle-buyback#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/settle-buyback#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: >- A collectible or the pack was not found. - Other codes can appear. Read `GET /v2/gacha/buyback/offers` before you send the request again. See [error codes and recovery](/api-reference/gacha/settle-buyback#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: One or more builder draws were not found code: EOA_PURCHASE_REJECTED '409': description: >- The buyback conflicts with an earlier one, or its price changed. - Other codes can appear. Read `GET /v2/gacha/buyback/offers` before you send the request again. See [error codes and recovery](/api-reference/gacha/settle-buyback#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: >- amount 1000000000000000000 does not match expected total 900000000000000000 code: GACHA_V3_BUYBACK_PRICE_CHANGED '429': description: >- Too many requests with this builder key. See [error codes and recovery](/api-reference/gacha/settle-buyback#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; before you send the request again, read `GET /v2/gacha/buyback/offers` to see whether it went through. See [error codes and recovery](/api-reference/gacha/settle-buyback#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 '503': description: >- A failure on our side. Every payment sender is busy: nothing was sent and nothing changed. Send the same signed buyback again after the `Retry-After` seconds. See [error codes and recovery](/api-reference/gacha/settle-buyback#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: type: object properties: error: type: string description: A short sentence about what went wrong. code: type: string required: - error - code example: code: OP_WALLET_BUSY error: >- Payments are busy right now and nothing was charged. Please try again in a few seconds. 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.