> ## 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`。断开连接后，抽卡仍会继续。 ## 提交并跟踪抽卡 1. **签署购买请求。** 让买家签署[准备抽卡](https://docs.renaiss.xyz/cn/api-reference/gacha/prepare-pull.md)返回的完整 Permit2 数据，再用开发者密钥提交。流式接口使用相同的请求体和签名校验规则。 2. **保存请求 ID。** 接口立即返回 HTTP `202`、`requestId` 和当前状态。此次购买归属于当前开发者和买家钱包。 3. **查询结果。** 使用该 ID 约每秒[查询一次抽卡状态](https://docs.renaiss.xyz/cn/api-reference/gacha/get-pull-status.md)，直到返回 `RESOLVED` 或 `FAILED`。 如果没有收到响应，重新发送**同一份已签名的数据**即可找回原 `requestId`。失败的请求可以重新启动，同一签名最多扣款一次。 如果 `PENDING_PAYMENT` 持续超过 10 分钟，请停止轮询，并在再次签名前携原 `requestId` 联系 Renaiss。 ## 请求 需要开发者密钥和钱包签名 ## 响应 ### 提交后的失败 首次提交返回 HTTP `202` 和 `PENDING_PAYMENT`。重发同一签名可能会重新开始失败的请求。如只需查询，请使用原 `requestId` 轮询。状态为 `FAILED` 表示未扣款。 多数错误的 `error.message` 都是 `Unable to fund the pull.`。如果接口返回其他消息，表中会列出原文。 | 错误码 | `error.message` 和处理方式 | | - | - | | `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.` 若问题持续出现，请将 `x-request-id` 提供给 Renaiss。 | | `CARD_PACK_NOT_ACTIVE` | 该卡包当前不可购买。 | | `CARD_PACK_NOT_FOUND` | 卡包不存在。请停止使用该 ID 重试。 | | `CONTRACT_REVERT` | `FAILED` 表示本次抽卡未扣款。请在重试前检查钱包余额和授权额度。 | | `CONTRACT_WALLET_CANNOT_RECEIVE_NFT` | 使用支持接收该藏品的钱包。 | | `EOA_PURCHASE_REJECTED` | `Permit deadline must be within the next five minutes` 重新准备抽卡请求，并使用有效的截止时间。 | | `GACHA_V3_NOT_ENOUGH_CARDS_IN_SET` | 减少抽取数量或稍后再试。 | | `GACHA_V3_NO_SELLABLE_LINEUP` | 卡包恢复可售后重试。 | | `GACHA_V3_PRICE_MISMATCH` | 读取新价格，重新准备并签名。 | | `INSUFFICIENT_ALLOWANCE` | 按准备接口返回的 `approval.spender` 授权至少 `approval.requiredAmount` 的 USDT，在签名过期前重发原请求。 | | `INSUFFICIENT_USDT_AMOUNT` | 补足钱包内的 USDT 余额，在签名过期前重发原请求。若签名已过期，请重新准备。 | | `OP_WALLET_BUSY` | `Payments are busy right now and nothing was charged. Please try again in a few seconds.` 稍等几秒，在签名过期前重发原请求。若签名已过期，请重新准备。 | | `PERMIT_DEADLINE_TOO_FAR` | 重新准备请求并使用新的截止时间。 | | `PERMIT_EXPIRED` | 签名已过期。请重新准备并签名。 | | `PULL_NOT_STARTED` | `The connection closed before the pull started. Nothing was charged. Send the same signed pull again.` 重发同一份已签抽取请求。 | | `WRONG_REQUEST_PARAMS` | 请更换可用的买家钱包，重新准备抽卡请求。 | 如果遇到表中未列出的错误码，请先核对[该钱包的抽卡历史](https://docs.renaiss.xyz/cn/api-reference/gacha/list-wallet-pulls.md)，再决定是否重新签名。 主网的 USDT 转账因授权额度不足而失败时，也可能返回 `INSUFFICIENT_USDT_AMOUNT`。请同时检查钱包余额和授予 Permit2 的 USDT 额度。测试网上，余额充足但授权额度不足时会返回 `INSUFFICIENT_ALLOWANCE`。 ## 错误码 如果接口返回 HTTP `4xx` 或 `5xx`，可按下表中的状态码和响应原文查找处理方式。有关各接口通用的处理建议，请参阅[错误码含义与处理方式](https://docs.renaiss.xyz/cn/api-reference/errors.md)。 | HTTP | 错误码 | 文本字段 | 响应文本与处理方式 | | :- | :- | :- | :- | | `400` | `API_AUTH_INVALID_INPUT` | `error` | `Request body is too large` 请求体超过 16 KiB。请缩小请求体。 | | `400` `404` | `EOA_PURCHASE_REJECTED` | `error` | **400** · `SAFE addresses are not supported by v2` 请更换买家钱包。 **404** · `Pack not found` 请从[卡包列表](https://docs.renaiss.xyz/cn/api-reference/gacha/list-packs.md)中选择可用的卡包 ID。 | | `400` | `WRONG_REQUEST_PARAMS` | `message` | `Bad request - invalid parameters` 字段缺失或格式错误。修正后重新发送。 | | `400` | 无错误码 | `text/plain` | `Malformed JSON in request body` | | `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` | `API_AUTH_INVALID_ACTION` | `error` | `Invalid wallet action proof` 钱包签名与准备数据不符或已过期。请重新准备和签名。合约钱包的 `isValidSignature` 对准备数据的 EIP-712 摘要必须返回 0x1626ba7e。 | | `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，无需重试。 | | `429` | `API_AUTH_RATE_LIMITED` | `error` | `Authentication rate limit exceeded` 已达到密钥的请求频率上限。稍候再以较低频率重试。 | | `500` | `CARD_PACKS_QUERY_FAILED` | `error` | `Internal server error` 请稍后重新查询。 | | `500` | `API_AUTH_ERROR`、`FUNCTION_ERROR` 或其他错误码 | `error` | `Internal server error` API 无法读取链上数据时，签名验证可能失败。请稍后重发**同一份已签名的数据**，找回原请求。 | ## OpenAPI ````yaml cn/api-reference/openapi.json POST /v2/gacha/pull/request 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/pull/request: post: tags: - Gacha v2 summary: 提交已签名抽卡请求并按请求 ID 轮询 description: 提交已签名的开包请求，立即获取 `requestId`。断开连接后，抽卡仍会继续。 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: >- 对准备结果中结构化数据的签名，以最多 4,096 字节的十六进制表示。EOA 直接签署结构化数据；合约钱包提交其 `isValidSignature` 针对 EIP-712 摘要接受的数据，允许为空（0x）。调用方为 Permit2，签名在支付前及链上各验证一次。 required: - packId - numOfTokens - amountPerToken - nonce - deadline - buyerWalletAddress - permitSignature additionalProperties: false responses: '202': description: 已接受抽卡请求，响应体为请求状态。 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` — 抽卡请求已受理，付款正在处理中。 - `PENDING_RESOLUTION` — 付款已确认，系统正在分配卡牌。此后状态不会变为 `FAILED`。 - `RESOLVED` — 抽卡已完成。可在 `result.draws` 中查看抽到的卡牌。 - `FAILED` — 买家未被扣款。可通过 `error.code` 查看原因。 buyerWalletAddress: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 packId: type: string format: uuid nonce: type: string numOfTokens: type: integer exclusiveMinimum: 0 permitFundTxHash: type: - string - 'null' description: 付款交易哈希，确认前为 `null`。 error: type: - object - 'null' properties: code: type: string description: 请求失败的原因。 message: type: string description: 简短的错误说明。 required: - code - message description: >- 仅当 `status` 为 `FAILED` 时返回 `code` 和 `message`，其余状态均为 `null`。 参见[失败原因与处理方式](/cn/api-reference/gacha/submit-pull#pull-failures)。 result: anyOf: - $ref: '#/components/schemas/GachaV2DrawStatus' - type: 'null' - type: 'null' description: >- 与本次抽卡 `GET /v2/gacha/draw-status` 的响应体相同。仅 `RESOLVED` 时有值，否则为 `null`。 required: - requestId - status - buyerWalletAddress - packId - nonce - numOfTokens - permitFundTxHash - error - result examples: PENDING_PAYMENT: summary: 付款处理中。 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: 付款已确认。 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: 藏品已分配。 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: 抽卡失败，未扣款。 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: |- 请求在执行前被拒绝。 见[错误码与处理方式](/cn/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: 简短的错误说明。 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: 简短的错误说明。 required: - code - message example: code: WRONG_REQUEST_PARAMS message: Bad request - invalid parameters '401': description: |- 缺少开发者密钥或密钥未通过验证。 见[错误码与处理方式](/cn/api-reference/gacha/submit-pull#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/submit-pull#http-errors)。 content: application/json: schema: type: object properties: error: type: string description: 简短的错误说明。 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: |- 未找到该卡包。 见[错误码与处理方式](/cn/api-reference/gacha/submit-pull#http-errors)。 content: application/json: schema: type: object properties: error: type: string description: 简短的错误说明。 code: type: string enum: - EOA_PURCHASE_REJECTED required: - error - code example: error: Pack not found code: EOA_PURCHASE_REJECTED '429': description: |- 该开发者密钥的请求过于频繁。 见[错误码与处理方式](/cn/api-reference/gacha/submit-pull#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: |- 服务端出错。稍后可以重发同一份签名请求，返回的 `requestId` 不变且不会重复扣款。原请求可能已付款，不要重新签名。 见[错误码与处理方式](/cn/api-reference/gacha/submit-pull#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: schemas: GachaV2DrawStatus: type: object properties: permitFundTxHash: type: string description: 32 字节，以 0x 开头，后接 64 个十六进制数字。 buyerWalletAddress: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 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 字节，以 0x 开头，后接 64 个十六进制数字。 tokenId: type: string releaseTxHash: type: - string - 'null' description: 32 字节，以 0x 开头，后接 64 个十六进制数字。 buybackTxHash: type: - string - 'null' description: 32 字节，以 0x 开头，后接 64 个十六进制数字。 buybackTiers: type: array items: type: object properties: buybackPercentage: type: number description: 相对于卡牌基础价值的百分比，例如 90 表示 90%。 amountInUsdt: type: string description: 本档回购价格，以精度为 18 位的 USDT 最小单位表示。 expiresAt: type: string description: 本档截止时间。在此时刻该档仍有效。 required: - buybackPercentage - amountInUsdt - expiresAt description: >- 本次抽卡的全部回购档位（包含已过期档位），按截止时间排序。价格与 `GET /v2/gacha/buyback/offers` 一致。展示第一个尚未超过 `expiresAt` 的档位的 `amountInUsdt`，在截止时刻该档仍有效。确认回购前再次查询报价，并签署该接口返回的金额。回售或交付后档位仍会保留，通过 `buybackTxHash` 和 `releaseTxHash` 判断实际结果。无回购时返回空列表。 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: 藏品在本次抽卡中的档位。无法加载藏品详情时为 `null`。 buybackBaseValueInUSD: type: - string - 'null' description: 藏品的回购基础价值，以美分计，已含加成。无法加载藏品详情时为 `null`。 buybackBonus: type: - object - 'null' properties: originalBuybackBaseValueInUSD: type: string description: 加成前的回购基础价值，以美分计，在该组卡牌形成时确定。 bonusBps: type: integer description: 加成基点数，例如 2000 表示增加 20%。 required: - originalBuybackBaseValueInUSD - bonusBps description: 藏品的回购加成。回购基础价值及 `buybackTiers` 已包含该加成。没有加成或无法加载详情时为 `null`。 type: type: string enum: - POKEMON - ONE_PIECE - SPORTS description: 藏品类别。 name: type: string description: 评级、年份、系列、编号和名称。 frontImageUrl: type: string format: uri description: 深色背景下带 Renaiss 边框的评级卡盒照片。 attributes: type: array items: type: object properties: key: type: string value: type: string required: - key - value description: >- 藏品属性以键值对返回。卡牌依次使用 Grader、Grade、Cert Number、Year、Set、Card Number、Character、Language。没有值的属性会省略，所有值均为字符串。 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: >- 已获准使用的开发者 API 密钥，仅在后端保存。抽卡和市场的写入操作还需钱包签名，实物兑换还需钱包签署登录消息后由 API 签发的 Bearer 令牌。 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.