> ## 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. # 接收抽卡事件流 > 实时跟踪已签名的开包请求。事件流会更新付款进度，并在返回抽到的卡牌或失败事件后结束。 提交开发者密钥和买家对完整抽卡数据的 Permit2 签名。结果归属于该开发者和买家钱包。 ## 请求 需要开发者密钥和钱包签名 ## 响应 ### HTTP 200 事件流 | 收到的事件 | 处理方式 | | - | - | | `pull_started` | 保存 `data.requestId`。 | | `payment_queued` 或 `payment_submitting` | 等待付款确认。 | | `payment_confirmed` | 保存 `data.permitFundTxHash`，用于恢复查询。 | | `draws_resolved` | 展示本次购买的全部卡牌。抽卡成功，事件流结束。 | | `pull_failed` | 读取失败详情。事件流已结束。 | > [accordion] 事件与数据字段 > > 每个 `data` 都是 JSON 对象。所有事件均按下表顺序包含这些字段，对应 `GachaV2PullStreamProgressData`。 > > | 字段 | 类型 | 含义 | > | - | - | - | > | `buyerWalletAddress` | address | 签署抽卡的钱包。 | > | `packId` | uuid | 本次抽取的卡包。 | > | `nonce` | string | 签名请求的 nonce。 | > | `numOfTokens` | integer | 购买的藏品数量，1 至 10。 | > | `message` | string | 用于显示的简短消息。 | > > `pull_started` 的附加字段见 `GachaV2PullStreamStartedData`。 > > | 字段 | 类型 | 含义 | > | - | - | - | > | `requestId` | uuid | 本次抽卡的 ID。断线后用它查询 `GET /v2/gacha/pull/status?requestId=`。 | > > `payment_confirmed` 的附加字段见 `GachaV2PullStreamPaymentConfirmedData`。 > > | 字段 | 类型 | 含义 | > | - | - | - | > | `permitFundTxHash` | hash | 付款交易哈希，用于恢复本次抽卡。 | > > `draws_resolved` 在通用字段之后返回以下字段，见 `GachaV2PullStreamDrawsResolvedData`。 > > | 字段 | 类型 | 含义 | > | - | - | - | > | `permitFundTxHash` | hash | 付款交易哈希。 | > | `packName` | string | 卡包名称。 | > | `pulledAt` | date-time or `null` | 付款交易被打包的时间。 | > | `draws` | array | 按顺序列出本次获得的藏品，每件一项。 | > | `draws[].settlementId` | hash | 回购时用于标识藏品的结算 ID。 | > | `draws[].tokenId` | string | 藏品的代币 ID。 | > | `draws[].releaseTxHash` | hash or `null` | 藏品转入钱包后填入。 | > | `draws[].buybackTxHash` | hash or `null` | 藏品回售后填入。 | > | `draws[].tier` | string | 藏品在本次抽卡中的档位。 | > | `draws[].buybackBaseValueInUSD` | string | 本次抽卡已锁定的基础价值，以美分计，含加成。 | > | `draws[].buybackBonus` | object or `null` | 回购加成包括 `originalBuybackBaseValueInUSD`（加成前价值，美分）及 `bonusBps`（2000 表示 +20%）。基础价值及 `buybackTiers` 已计入加成，无加成时为 `null`。 | > | `draws[].type` | string | 藏品类别，可为 `POKEMON`、`ONE_PIECE` 或 `SPORTS`。 | > | `draws[].name` | string | 评级、年份、系列、编号和名称。 | > | `draws[].frontImageUrl` | url | 深色背景下带 Renaiss 边框的评级卡盒照片。 | > | `draws[].attributes` | array | `{ key, value }` 属性，依次为 Grader、Grade、Cert Number、Year、Set、Card Number、Character、Language。空属性会省略。 | > > `pull_failed` 的附加字段见 `GachaV2PullStreamFailedData`。 > > | 字段 | 类型 | 含义 | > | - | - | - | > | `code` | string | 失败原因，参见失败事件表。 | > | `error` | string | 与 `message` 相同的消息。 | > | `permitFundTxHash` | hash or `null` | 付款交易哈希；没有已确认交易时为 `null`。 | > | `fundingConfirmed` | boolean | 若失败前付款已确认，则为 true。 | ### 事件流建立后的失败 收到 `pull_failed` 时，根据 `data.code` 处理失败，并用 `data.message` 展示原因。`data.error` 返回相同文本。 若事件流失败或连接中断，先核对原请求，再决定是否签名。付款可能已经确认。 * 有 `data.permitFundTxHash`（来自 `payment_confirmed` 或 `pull_failed`）时，用它[查询抽卡结果](https://docs.renaiss.xyz/cn/api-reference/gacha/get-draw.md)。 * 只有 `pull_started` 返回的 `data.requestId` 时，[查询原请求状态](https://docs.renaiss.xyz/cn/api-reference/gacha/get-pull-status.md)。 * 两者都没有时，[查询钱包抽卡记录](https://docs.renaiss.xyz/cn/api-reference/gacha/list-wallet-pulls.md)。遇到未识别的错误码，也请先核对这笔抽卡。 如果 `data.message` 是 `Unable to fund the pull.`，请按 `data.code` 查下表。其他响应文本列在对应错误码旁。 | 错误码 | 响应文本与处理方式 | | - | - | | `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` `GACHA_V3_CHECKOUT_STATUS_UNAVAILABLE` `OPEN_PACK_VRF_FAILED` | `Unable to fund the pull.` 再次付款前，请查询原请求状态。 | | `GACHA_V3_RESOLVE_DRAWS_NOT_CANONICAL` `GACHA_V3_RESOLVE_DRAWS_NOT_FINALIZED` `GACHA_V3_RESOLVE_DRAWS_PARTIAL_BATCH` `GACHA_V3_RESOLVE_DRAWS_SUBGRAPH_BEHIND` `GACHA_V3_UPDATE_FAILED` `GACHA_V3_PULL_NOT_YET_RESOLVED` `INTERNAL_SERVER_ERROR` | `Payment confirmed, but draw resolution could not finish. Recover using the funding hash.` | | `CARD_PACK_NOT_ACTIVE` | 卡包未在售，标记为不可购买，无需重试。 | | `CARD_PACK_NOT_FOUND` | 若 `fundingConfirmed` 为 true，请使用 `permitFundTxHash` 找回抽卡结果。若付款失败，请在重试前核对卡包 ID。 | | `CONTRACT_REVERT` | 再次付款前，请查询原 `requestId`。结果尚未确定的请求可能仍处于 `PENDING_PAYMENT`。 | | `CONTRACT_WALLET_CANNOT_RECEIVE_NFT` | 使用支持接收该藏品的钱包。 | | `EOA_PURCHASE_REJECTED` | `Permit deadline must be within the next five minutes` `Unable to finish the pull. Reconcile its outcome before retrying.` 核对签名截止时间。若事件流意外结束，先查询该笔抽取。 | | `GACHA_V3_CHECKOUT_ALREADY_PROCESSED` | 本次开包已处理，不要重复购买。 | | `GACHA_V3_CHECKOUT_REQUEST_MISMATCH` | 相同钱包和 nonce 之前签署的抽卡请求与本次请求不同。再次签名前先查原请求状态或钱包抽卡记录。 | | `GACHA_V3_DRAW_REVEAL_FAILED` | `Payment confirmed, but collectible details could not be loaded. Recover using the funding hash.` | | `GACHA_V3_DRAW_UPDATES_UNAVAILABLE` | `Payment confirmed, but live draw updates are unavailable. Recover using the funding hash.` | | `GACHA_V3_NOT_ENOUGH_CARDS_IN_SET` | 减少抽取数量或稍后再试。 | | `GACHA_V3_NO_SELLABLE_LINEUP` | 卡包恢复可售后重试。 | | `GACHA_V3_PRICE_MISMATCH` | 读取新价格，重新准备并签名。 | | `GACHA_V3_RESOLVE_DRAWS_FAILED` | `Payment confirmed, but draw resolution could not finish. Recover using the funding hash.` | | `GACHA_V3_STREAM_TIMEOUT` | `The stream timed out. Check existing funding and draw history before retrying.` 流等待 90 秒仍未获得结果，付款可能仍在进行。 | | `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.` 付款发送方均忙，尚未扣款。几秒后在到期前重发同一签名请求，或重新准备。 | | `PERMIT2_NONCE_ALREADY_USED` | 已使用该签名请求，不要重复签署。 | | `PERMIT_DEADLINE_TOO_FAR` | 重新准备请求并使用新的截止时间。 | | `PERMIT_EXPIRED` | 已签名的请求在发送前过期，未付款。可以重新准备并签名。 | | `WRONG_REQUEST_PARAMS` | 此钱包无法用于本次开包。更换钱包后重新准备请求。 | 主网的 USDT 转账因授权额度不足而失败时，也可能返回 `INSUFFICIENT_USDT_AMOUNT`。请同时检查钱包余额和授予 Permit2 的 USDT 额度。测试网上，余额充足但授权额度不足时会返回 `INSUFFICIENT_ALLOWANCE`。 ## 错误码 以下 HTTP 错误可能在事件流建立前返回。有关各接口通用的处理建议，请参阅[错误码含义与处理方式](https://docs.renaiss.xyz/cn/api-reference/errors.md)。 | HTTP | 错误码 | 文本字段 | 响应文本与处理方式 | | :- | :- | :- | :- | | `400` | `API_AUTH_INVALID_INPUT` | `error` | `Request body is too large` 请求体超过 16 KiB。请缩小请求体。 | | `400` | `EOA_PURCHASE_REJECTED` | `error` | `SAFE addresses are not supported by v2` 该钱包无法用于此次抽卡。请更换钱包， | | `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，无需重试。 | | `404` | `EOA_PURCHASE_REJECTED` | `error` | `Pack not found` 卡包 ID 未知或未公开。请从 `GET /v2/gacha/packs` 获取有效 ID，不要以相同 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` | `CARD_PACKS_QUERY_FAILED` | `error` | `Internal server error` 请稍后重新查询。 | | `500` | 其他错误码 | `error` | `Internal server error` | ## OpenAPI ````yaml cn/api-reference/openapi.json POST /v2/gacha/pull/stream 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/stream: post: tags: - Gacha v2 summary: 提交已签名抽卡请求并流式接收结果 description: 实时跟踪已签名的开包请求。事件流会更新付款进度，并在返回抽到的卡牌或失败事件后结束。 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: '200': description: >- HTTP `200` 表示事件流已建立。`draws_resolved` 表示抽卡成功，[`pull_failed`](#事件流建立后的失败) 表示事件流以失败结束。以 `:` 开头的行用于保持连接。 content: text/event-stream: schema: type: string examples: success: summary: 抽卡成功 value: >+ event: pull_started data: {"buyerWalletAddress":"0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2","packId":"3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13","nonce":"48210937465120938475","numOfTokens":1,"requestId":"6f1c2a9e-4b7d-4e3a-9c15-8a2d0f7b3e64","message":"Your signed pull has been accepted for processing."} event: payment_queued data: {"buyerWalletAddress":"0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2","packId":"3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13","nonce":"48210937465120938475","numOfTokens":1,"message":"Your payment is queued for processing."} event: payment_submitting data: {"buyerWalletAddress":"0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2","packId":"3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13","nonce":"48210937465120938475","numOfTokens":1,"message":"Your payment transaction is being submitted."} event: payment_confirmed data: {"buyerWalletAddress":"0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2","packId":"3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13","nonce":"48210937465120938475","numOfTokens":1,"message":"Payment confirmed. Resolving your collectibles.","permitFundTxHash":"0x9c1d0e4a7b2f6385a1c9d4e7f20b3a6c5d8e1f4a7b0c3d6e9f2a5b8c1d4e7f0a"} event: draws_resolved data: {"buyerWalletAddress":"0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2","packId":"3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13","nonce":"48210937465120938475","numOfTokens":1,"message":"Your collectibles are ready.","permitFundTxHash":"0x9c1d0e4a7b2f6385a1c9d4e7f20b3a6c5d8e1f4a7b0c3d6e9f2a5b8c1d4e7f0a","packName":"Example Pack","pulledAt":"2026-01-15T10:30:00.000Z","draws":[{"settlementId":"0x2b7e4c9a1d5f8036e2a4c7b9d1f3058a6c8e0b2d4f6a8c0e1b3d5f7a9c2e4b60","tokenId":"1234567","releaseTxHash":null,"buybackTxHash":null,"buybackTiers":[{"buybackPercentage":90,"amountInUsdt":"40500000000000000000","expiresAt":"2026-01-15T11:30:04.000Z"},{"buybackPercentage":85,"amountInUsdt":"38250000000000000000","expiresAt":"2026-01-16T10:30:04.000Z"},{"buybackPercentage":80,"amountInUsdt":"36000000000000000000","expiresAt":"2026-01-18T10:30:04.000Z"}],"tier":"rare","buybackBaseValueInUSD":"4500","buybackBonus":{"originalBuybackBaseValueInUSD":"3750","bonusBps":2000},"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"},{"key":"Cert Number","value":"PSA00000001"},{"key":"Year","value":"2025"},{"key":"Set","value":"Example Set"},{"key":"Card Number","value":"001"},{"key":"Character","value":"Example Collectible"},{"key":"Language","value":"English"}]}]} failure: summary: 抽卡失败 value: >+ event: pull_failed data: {"buyerWalletAddress":"0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2","packId":"3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13","nonce":"48210937465120938475","numOfTokens":1,"message":"The stream timed out. Check existing funding and draw history before retrying.","code":"GACHA_V3_STREAM_TIMEOUT","error":"The stream timed out. Check existing funding and draw history before retrying.","permitFundTxHash":"0x9c1d0e4a7b2f6385a1c9d4e7f20b3a6c5d8e1f4a7b0c3d6e9f2a5b8c1d4e7f0a","fundingConfirmed":true} '400': description: |- 请求在执行前被拒绝。 见[错误码与处理方式](/cn/api-reference/gacha/stream-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/stream-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/stream-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/stream-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/stream-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: |- 服务端在流启动前失败，没有扣款，请稍后重试。 见[错误码与处理方式](/cn/api-reference/gacha/stream-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: 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.