> ## 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. # 查询回购状态 > 使用回购的 `requestId` 和提交时的开发者密钥查询回售结果。 约每秒查询一次，直到状态为 `COMPLETED` 或 `FAILED`。请求至少可查询 30 天。 若 `PENDING` 持续超过十分钟，请停止轮询，携原 `requestId` 联系 Renaiss。先确认原请求的结果，再为同一批卡牌签署其他回购请求。 ## 请求 需要开发者密钥 ## 响应 ### 提交后的失败 若 HTTP 200 响应体中的 `status` 为 `FAILED`，请读取 `error.code` 和 `error.message`。`FAILED` 表示未回购任何藏品。重新签名前请刷新钱包的回购报价。若 `PENDING` 持续超过 10 分钟，请停止轮询并提供原 `requestId` 联系 Renaiss。下表花括号内的内容会替换为实际值。 | 错误码 | `error.message` | | - | - | | `GACHA_V3_BUYBACK_SNAPSHOT_NOT_FOUND` `GACHA_V3_SETTLEMENT_ID_MISMATCH` `PERPETUAL_GACHA_BUYBACK_CONFIG_NOT_FOUND` `PERPETUAL_GACHA_VENDING_MACHINE_ADDRESS_NOT_FOUND` | `Internal server error` 请将原 `requestId` 提供给 Renaiss。 | | `CONTRACT_REVERT` | `Smart contract execution reverted` `Contract error: {reason}` | | `GACHA_V3_BUYBACK_EXPIRED` | `Buyback has expired for {buybackId}` | | `GACHA_V3_BUYBACK_PRICE_CHANGED` | `amount {signedAmount} does not match expected total {expectedTotal}` | | `GACHA_V3_BUYBACK_VERIFY_FAILED` | `Buyer does not own this card` | | `GACHA_V3_DRAW_RECORD_NOT_FOUND` | `Pack draw record not found for buybackId {buybackId}` | | `GACHA_V3_TOKEN_STATUS_INVALID` | `Card is already buyback or released` | | `OP_WALLET_BUSY` | `Payments are busy right now and nothing was charged. Please try again in a few seconds.` 请等待几秒，然后重发原签名回购请求。 | | `PERPETUAL_GACHA_PACK_NOT_FOUND` | `Perpetual VRF pack not found: {cardPackId}` | | `PERPETUAL_GACHA_PACK_VERIFY_BUYBACK_FAILED` | `Buyback token must be USDT` | ## 错误码 在下表中查找接口返回的 HTTP 状态码和响应原文。有关各接口通用的处理建议，请参阅[错误码含义与处理方式](https://docs.renaiss.xyz/cn/api-reference/errors.md)。 | HTTP | 错误码 | 文本字段 | 响应文本与处理方式 | | :- | :- | :- | :- | | `400` | `WRONG_REQUEST_PARAMS` | `message` | `Bad request - invalid parameters` 字段缺失或格式错误。修正后重新发送， | | `401` | `API_AUTH_INVALID_CREDENTIAL` | `error` | `Invalid authentication credential` 开发者密钥格式错误、未知、已过期或已撤销。请核对并更换密钥。 | | `401` | `API_AUTH_MISSING_CREDENTIAL` | `error` | `Required authentication credential is missing` 请在 `x-builder-api-key` 请求头中提供开发者密钥。 | | `403` | `API_AUTH_CREDENTIAL_NOT_ALLOWED` | `error` | `Credential is not allowed by this policy` 此路由只接受开发者密钥。移除 `Authorization` 请求头及其他凭据，再重新发送。 | | `403` | `GACHA_V3_BUILDER_NOT_ACCEPTED_ON_PUBLIC_API` | `error` | `This builder checks out on its own surface, not on the public API` 此密钥无法用于当前 API。请联系 Renaiss，无需重试。 | | `404` | `REQUEST_NOT_FOUND` | `error` | `Request not found` 请求 ID 未知、属于其他开发者或其他请求类型。请核对创建请求的 POST 接口返回的 ID。 | | `429` | `API_AUTH_RATE_LIMITED` | `error` | `Authentication rate limit exceeded` 已达到密钥的请求频率上限。稍候再以较低频率重试。 | | `500` | `API_AUTH_ERROR` | `error` | `Internal server error` | | `500` | `FUNCTION_ERROR` | `error` | `Internal server error` | | `500` | 其他错误码 | `error` | `Internal server error` | ## OpenAPI ````yaml cn/api-reference/openapi.json GET /v2/gacha/buyback/status openapi: 3.1.1 info: version: 1.0.0 title: Renaiss 开发者 API v2 description: >- 在 BNB 智能链（链 ID 56）上使用外部钱包接入抽卡、交易市场和实物兑换。所有已批准且有效的开发者密钥均可准备购买。 藏品包括钱包可抽取、交易、回售或兑换的物品，例如卡牌。接口路径、字段和描述统一使用 collectible 表示藏品。 可以匿名浏览目录。准备购买后，请由买家钱包签名。抽卡记录和回购报价需要开发者密钥，购买和回购还需操作签名。私有配送信息及兑换需要钱包访问令牌，由钱包在已注册的合作方来源签署登录消息后签发。抽卡和市场不使用钱包访问令牌。请在后端保管开发者密钥。 操作钱包可以是 EOA 或已部署的 ERC-1271 合约账户。不支持 EIP-7702 委托账户、ERC-6492 或 ERC-8010 封装签名及 Renaiss 托管的 Safe（签名验证后才会识别并拒绝该类 Safe）。无法接收 ERC-721 的合约钱包抽卡会返回 `CONTRACT_WALLET_CANNOT_RECEIVE_NFT`。链上读取失败返回 `API_AUTH_ERROR`（500）。钱包访问令牌及实物兑换仅支持 EOA。 servers: - url: https://api.renaiss.xyz description: BNB 智能链主网 - url: https://dev-api.renaiss.xyz description: BNB 测试网 security: [] tags: - name: Gacha v2 description: 使用 EOA 浏览和购买卡包、揭晓藏品、读取购买记录及回购。无需钱包访问令牌。 - name: Marketplace description: 公开浏览藏品，通过外部钱包挂牌、出价、购买或撤单。交易需要开发者授权及钱包操作签名。 - name: Users description: 查询特定钱包的藏品、市场总估值和链上活动。仅需开发者密钥，各接口按相应的可见范围返回记录。 - name: Redemption description: 查询兑换资格、运费报价，准备并提交兑换及跟踪物流。需要开发者密钥及同一钱包的访问令牌。 - name: Wallet access tokens description: >- 获取、刷新或撤销实物兑换使用的钱包访问令牌。钱包签署一次性登录消息（5 分钟有效）后，API 返回访问令牌（15 分钟）和一次性刷新令牌（7 天）。先注册精确的合作方前端来源。抽卡和市场无需钱包访问令牌。 paths: /v2/gacha/buyback/status: get: tags: - Gacha v2 summary: 按 requestId 查询回购状态 description: 使用回购的 `requestId` 和提交时的开发者密钥查询回售结果。 parameters: - schema: type: string format: uuid required: true name: requestId in: query responses: '200': description: 成功 content: application/json: schema: type: object properties: requestId: type: string format: uuid status: type: string enum: - PENDING - COMPLETED - FAILED description: '`PENDING` 表示处理中；`COMPLETED` 表示已在链上结算；`FAILED` 表示未回购任何藏品。' buyerWalletAddress: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 cardPackId: type: string format: uuid settlementIds: type: array items: type: string description: 32 字节，以 0x 开头，后接 64 个十六进制数字。 txHash: type: - string - 'null' description: 回购交易哈希，仅 `COMPLETED` 时有值，其余为 `null`。 totalAmountInUsdt: type: - string - 'null' pattern: ^\d+$ description: 已支付的 USDT 金额，精度为 18 位，仅 `COMPLETED` 时有值。 itemCount: type: - integer - 'null' exclusiveMinimum: 0 description: 已回购藏品数量，仅 `COMPLETED` 时有值，其余为 `null`。 error: type: - object - 'null' properties: code: type: string description: 请求失败的原因。 examples: - PERPETUAL_GACHA_PACK_VERIFY_BUYBACK_FAILED - GACHA_V3_TOKEN_STATUS_INVALID - GACHA_V3_BUYBACK_VERIFY_FAILED - GACHA_V3_BUYBACK_EXPIRED - CONTRACT_REVERT - PERPETUAL_GACHA_PACK_NOT_FOUND - GACHA_V3_DRAW_RECORD_NOT_FOUND - GACHA_V3_BUYBACK_PRICE_CHANGED - OP_WALLET_BUSY message: type: string description: 简短的错误说明。 required: - code - message description: >- 失败原因，格式为 `{ code, message }`。仅 `FAILED` 时有值，其余为 `null`。失败时未回购任何藏品。错误码和文字与 `POST /v2/gacha/buyback` 相同，code 是可扩展的字符串。 - `PERPETUAL_GACHA_PACK_VERIFY_BUYBACK_FAILED`：签署的代币不是 USDT。请从报价列表重新准备回购。 - `GACHA_V3_TOKEN_STATUS_INVALID`：藏品已回售或已交付钱包。重新读取 `GET /v2/gacha/buyback/offers`，仅为仍有报价的藏品签名。 - `GACHA_V3_BUYBACK_VERIFY_FAILED`：钱包不持有其中一件藏品。请查询 `GET /v2/gacha/buyback/offers`，仅为返回的藏品签名。 - `GACHA_V3_BUYBACK_EXPIRED`：目前没有可付款档位，可能是窗口已关闭或当前为零比例档。重新获取 `GET /v2/gacha/buyback/offers`，按结果重试。 - `CONTRACT_REVERT`：链上拒绝回购。查询 `GET /v2/gacha/buyback/offers`，确认哪些藏品仍有报价后再签名。 - `PERPETUAL_GACHA_PACK_NOT_FOUND`：未找到卡包。请刷新报价并核对卡包 ID。 - `GACHA_V3_DRAW_RECORD_NOT_FOUND`：该卡包中没有对应的结算 ID。刷新报价，并只为该卡包实际返回的结算 ID 签名。 - `GACHA_V3_BUYBACK_PRICE_CHANGED`：读取报价后档位已截止，签名金额与当前价格不符。重新查询 `GET /v2/gacha/buyback/offers` 并签署新金额。 - `OP_WALLET_BUSY`：付款发送方均忙。等待几秒后重发同一回购签名。 - 其他错误码：再次发送前先读取 `GET /v2/gacha/buyback/offers`。 如果交易可能已经发送（例如确认超时或发送时被拒），将保持 `PENDING` 直到核对完毕，不会标记为 `FAILED`。 required: - requestId - status - buyerWalletAddress - cardPackId - settlementIds - txHash - totalAmountInUsdt - itemCount - error examples: PENDING: summary: 回购处理中。 value: requestId: b81d0f7e-2c4a-4d6b-8e13-5a9c7d1f3b20 buyerWalletAddress: '0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2' cardPackId: 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13 settlementIds: - >- 0x2222222222222222222222222222222222222222222222222222222222222222 status: PENDING txHash: null totalAmountInUsdt: null itemCount: null error: null COMPLETED: summary: 回购已结算。 value: requestId: b81d0f7e-2c4a-4d6b-8e13-5a9c7d1f3b20 buyerWalletAddress: '0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2' cardPackId: 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13 settlementIds: - >- 0x2222222222222222222222222222222222222222222222222222222222222222 status: COMPLETED txHash: >- 0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc totalAmountInUsdt: '39141000000000000000' itemCount: 1 error: null FAILED: summary: 回购失败，未回购任何藏品。 value: requestId: b81d0f7e-2c4a-4d6b-8e13-5a9c7d1f3b20 buyerWalletAddress: '0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2' cardPackId: 3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13 settlementIds: - >- 0x2222222222222222222222222222222222222222222222222222222222222222 status: FAILED txHash: null totalAmountInUsdt: null itemCount: null error: code: GACHA_V3_TOKEN_STATUS_INVALID message: Card is already buyback or released '400': description: |- 请求在执行前被拒绝。 见[错误码与处理方式](/cn/api-reference/gacha/get-buyback-status#http-errors)。 content: application/json: schema: type: object properties: code: type: string enum: - WRONG_REQUEST_PARAMS message: type: string description: 简短的错误说明。 required: - code - message example: code: WRONG_REQUEST_PARAMS message: Bad request - invalid parameters '401': description: |- 缺少开发者密钥或密钥未通过验证。 见[错误码与处理方式](/cn/api-reference/gacha/get-buyback-status#http-errors)。 content: application/json: schema: type: object properties: error: type: string description: 简短的错误说明。 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: |- 当前凭据无权执行此请求。 见[错误码与处理方式](/cn/api-reference/gacha/get-buyback-status#http-errors)。 content: application/json: schema: type: object properties: error: type: string description: 简短的错误说明。 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: |- 找不到该请求。 见[错误码与处理方式](/cn/api-reference/gacha/get-buyback-status#http-errors)。 content: application/json: schema: type: object properties: error: type: string description: 简短的错误说明。 code: type: string enum: - REQUEST_NOT_FOUND required: - error - code example: error: Request not found code: REQUEST_NOT_FOUND '429': description: |- 该开发者密钥的请求过于频繁。 见[错误码与处理方式](/cn/api-reference/gacha/get-buyback-status#http-errors)。 content: application/json: schema: type: object properties: error: type: string description: 简短的错误说明。 code: type: string enum: - API_AUTH_RATE_LIMITED required: - error - code example: error: Authentication rate limit exceeded code: API_AUTH_RATE_LIMITED '500': description: |- 服务端暂时失败，请稍后重试。 见[错误码与处理方式](/cn/api-reference/gacha/get-buyback-status#http-errors)。 content: application/json: schema: type: object properties: error: type: string description: 简短的错误说明。 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: >- 已获准使用的开发者 API 密钥，仅在后端保存。抽卡和市场的写入操作还需钱包签名，实物兑换还需钱包签署登录消息后由 API 签发的 Bearer 令牌。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.