查询抽卡状态

按 requestId 查询抽卡状态

curl --request GET \
  --url https://api.renaiss.xyz/v2/gacha/pull/status \
  --header 'x-builder-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-builder-api-key': '<api-key>'}};

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

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

GET

gacha

pull

status

按 requestId 查询抽卡状态

curl --request GET \
  --url https://api.renaiss.xyz/v2/gacha/pull/status \
  --header 'x-builder-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-builder-api-key': '<api-key>'}};

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

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

从提交抽卡的响应或事件流的 pull_started 事件中获取 requestId。
约每秒查询一次，直到状态为 RESOLVED 或 FAILED。付款确认后可能仍需等待分配卡牌，此后状态不会变为 FAILED。
如果付款结果尚未确认，或同一 nonce 或结账请求已用于之前的交易，状态会保持在 PENDING_PAYMENT。若该状态持续超过十分钟，请停止轮询，携原 ID 联系 Renaiss 后再决定是否重新签名。

FAILED 表示未扣款。再次提交同一份已签名的数据（包括仍在处理中的副本）可能使失败请求重新进入 PENDING_PAYMENT。请求至少可查询 30 天。

请求

需要开发者密钥

响应

提交后的失败

如果 HTTP 200 响应中的 status 为 FAILED，说明买家未被扣款。停止轮询，根据下表中的 error.code 决定下一步。多数错误的 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`	请更换可用的买家钱包，重新准备抽卡请求。

如果遇到表中未列出的错误码，请先核对该钱包的抽卡历史，再决定是否重新签名。主网的 USDT 转账因授权额度不足而失败时，也可能返回 INSUFFICIENT_USDT_AMOUNT。请同时检查钱包余额和授予 Permit2 的 USDT 额度。测试网上，余额充足但授权额度不足时会返回 INSUFFICIENT_ALLOWANCE。

错误码

在下表中查找接口返回的 HTTP 状态码和响应原文。有关各接口通用的处理建议，请参阅错误码含义与处理方式。

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`、`FUNCTION_ERROR` 或其他错误码	`error`	`Internal server error` 稍后使用原 `requestId` 重试查询。

授权

x-builder-api-key

string

header

必填

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

查询参数

requestId

string<uuid>

必填

响应

成功

requestId

string<uuid>

必填

status

enum<string>

必填

PENDING_PAYMENT — 抽卡请求已受理，付款正在处理中。
PENDING_RESOLUTION — 付款已确认，系统正在分配卡牌。此后状态不会变为 FAILED。
RESOLVED — 抽卡已完成。可在 result.draws 中查看抽到的卡牌。
FAILED — 买家未被扣款。可通过 error.code 查看原因。

可用选项:

PENDING_PAYMENT,

PENDING_RESOLUTION,

RESOLVED,

FAILED

buyerWalletAddress

string

必填

带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。

packId

string<uuid>

必填

nonce

string

必填

numOfTokens

integer

必填

permitFundTxHash

string | null

必填

付款交易哈希，确认前为 null。

error

object | null

必填

仅当 status 为 FAILED 时返回 code 和 message，其余状态均为 null。参见失败原因与处理方式。

Show child attributes

result

object · null · null

必填

与本次抽卡 GET /v2/gacha/draw-status 的响应体相同。仅 RESOLVED 时有值，否则为 null。

Show child attributes

入门

抽卡

交易市场

钱包收藏

实物兑换与配送

开发资源

合作伙伴接入

查询抽卡状态

请求

响应

提交后的失败

错误码

授权

查询参数

响应