接收抽卡事件流

提交已签名抽卡请求并流式接收结果

curl --request POST \
  --url https://api.renaiss.xyz/v2/gacha/pull/stream \
  --header 'Content-Type: application/json' \
  --header 'x-builder-api-key: <api-key>' \
  --data '
{
  "packId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "numOfTokens": 5,
  "amountPerToken": "<string>",
  "nonce": "<string>",
  "deadline": 123,
  "buyerWalletAddress": "<string>",
  "permitSignature": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {'x-builder-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    packId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    numOfTokens: 5,
    amountPerToken: '<string>',
    nonce: '<string>',
    deadline: 123,
    buyerWalletAddress: '<string>',
    permitSignature: '<string>'
  })
};

fetch('https://api.renaiss.xyz/v2/gacha/pull/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.renaiss.xyz/v2/gacha/pull/stream"

payload = {
    "packId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "numOfTokens": 5,
    "amountPerToken": "<string>",
    "nonce": "<string>",
    "deadline": 123,
    "buyerWalletAddress": "<string>",
    "permitSignature": "<string>"
}
headers = {
    "x-builder-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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"}]}]}

POST

gacha

pull

stream

提交已签名抽卡请求并流式接收结果

curl --request POST \
  --url https://api.renaiss.xyz/v2/gacha/pull/stream \
  --header 'Content-Type: application/json' \
  --header 'x-builder-api-key: <api-key>' \
  --data '
{
  "packId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "numOfTokens": 5,
  "amountPerToken": "<string>",
  "nonce": "<string>",
  "deadline": 123,
  "buyerWalletAddress": "<string>",
  "permitSignature": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {'x-builder-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    packId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    numOfTokens: 5,
    amountPerToken: '<string>',
    nonce: '<string>',
    deadline: 123,
    buyerWalletAddress: '<string>',
    permitSignature: '<string>'
  })
};

fetch('https://api.renaiss.xyz/v2/gacha/pull/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.renaiss.xyz/v2/gacha/pull/stream"

payload = {
    "packId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "numOfTokens": 5,
    "amountPerToken": "<string>",
    "nonce": "<string>",
    "deadline": 123,
    "buyerWalletAddress": "<string>",
    "permitSignature": "<string>"
}
headers = {
    "x-builder-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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"}]}]}

提交开发者密钥和买家对完整抽卡数据的 Permit2 签名。结果归属于该开发者和买家钱包。

请求

需要开发者密钥和钱包签名

响应

HTTP 200 事件流

收到的事件	处理方式
`pull_started`	保存 `data.requestId`。
`payment_queued` 或 `payment_submitting`	等待付款确认。
`payment_confirmed`	保存 `data.permitFundTxHash`，用于恢复查询。
`draws_resolved`	展示本次购买的全部卡牌。抽卡成功，事件流结束。
`pull_failed`	读取失败详情。事件流已结束。

事件与数据字段

每个 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）时，用它查询抽卡结果。
只有 pull_started 返回的 data.requestId 时，查询原请求状态。
两者都没有时，查询钱包抽卡记录。遇到未识别的错误码，也请先核对这笔抽卡。

如果 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 错误可能在事件流建立前返回。有关各接口通用的处理建议，请参阅错误码含义与处理方式。

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`

授权

x-builder-api-key

string

header

必填

已获准使用的开发者 API 密钥，仅在后端保存。抽卡和市场的写入操作还需钱包签名，实物兑换还需钱包签署登录消息后由 API 签发的 Bearer 令牌。

请求体

application/json

packId

string<uuid>

必填

numOfTokens

integer

必填

必填范围: 1 <= x <= 10

amountPerToken

string

必填

Pattern: ^\d+$

nonce

string

必填

Pattern: ^\d+$

deadline

integer

必填

buyerWalletAddress

string

必填

permitSignature

string

必填

对准备结果中结构化数据的签名，以最多 4,096 字节的十六进制表示。EOA 直接签署结构化数据；合约钱包提交其 isValidSignature 针对 EIP-712 摘要接受的数据，允许为空（0x）。调用方为 Permit2，签名在支付前及链上各验证一次。

响应

HTTP 200 表示事件流已建立。draws_resolved 表示抽卡成功，pull_failed 表示事件流以失败结束。以 : 开头的行用于保持连接。

The response is of type string.

入门

抽卡

交易市场

钱包收藏

实物兑换与配送

开发资源

合作伙伴接入

接收抽卡事件流

请求

响应

HTTP 200 事件流

事件流建立后的失败

错误码

授权

请求体

响应