提交抽卡请求

提交已签名抽卡请求并按请求 ID 轮询

curl --request POST \
  --url https://api.renaiss.xyz/v2/gacha/pull/request \
  --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/request', 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/request"

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)

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

POST

gacha

pull

request

提交已签名抽卡请求并按请求 ID 轮询

curl --request POST \
  --url https://api.renaiss.xyz/v2/gacha/pull/request \
  --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/request', 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/request"

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)

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

提交并跟踪抽卡

签署购买请求。 让买家签署准备抽卡返回的完整 Permit2 数据，再用开发者密钥提交。流式接口使用相同的请求体和签名校验规则。
保存请求 ID。 接口立即返回 HTTP 202、requestId 和当前状态。此次购买归属于当前开发者和买家钱包。
查询结果。 使用该 ID 约每秒查询一次抽卡状态，直到返回 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`	请更换可用的买家钱包，重新准备抽卡请求。

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

错误码

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

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` 请从卡包列表中选择可用的卡包 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 无法读取链上数据时，签名验证可能失败。请稍后重发同一份已签名的数据，找回原请求。

授权

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，签名在支付前及链上各验证一次。

响应

已接受抽卡请求，响应体为请求状态。

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

入门

抽卡

交易市场

钱包收藏

实物兑换与配送

开发资源

合作伙伴接入

提交抽卡请求

提交并跟踪抽卡

请求

响应

提交后的失败

错误码

授权

请求体

响应