查询回购状态

按 requestId 查询回购状态

curl --request GET \
  --url https://api.renaiss.xyz/v2/gacha/buyback/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/buyback/status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "requestId": "b81d0f7e-2c4a-4d6b-8e13-5a9c7d1f3b20",
  "buyerWalletAddress": "0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2",
  "cardPackId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13",
  "settlementIds": [
    "0x2222222222222222222222222222222222222222222222222222222222222222"
  ],
  "status": "PENDING",
  "txHash": null,
  "totalAmountInUsdt": null,
  "itemCount": null,
  "error": null
}

GET

gacha

buyback

status

按 requestId 查询回购状态

curl --request GET \
  --url https://api.renaiss.xyz/v2/gacha/buyback/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/buyback/status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "requestId": "b81d0f7e-2c4a-4d6b-8e13-5a9c7d1f3b20",
  "buyerWalletAddress": "0x4f2a9c1e7b3d58a60c9e1f2b3d4a5c6e7f8091a2",
  "cardPackId": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6c4f13",
  "settlementIds": [
    "0x2222222222222222222222222222222222222222222222222222222222222222"
  ],
  "status": "PENDING",
  "txHash": null,
  "totalAmountInUsdt": null,
  "itemCount": null,
  "error": null
}

约每秒查询一次，直到状态为 COMPLETED 或 FAILED。请求至少可查询 30 天。若 PENDING 持续超过十分钟，请停止轮询，携原 requestId 联系 Renaiss。先确认原请求的结果，再为同一批卡牌签署其他回购请求。

请求

需要开发者密钥

响应

提交后的失败

若 HTTP 200 响应体中的 status 为 FAILED，请读取 error.code 和 error.message。FAILED 表示未回购任何藏品。重新签名前请刷新钱包的回购报价。若 PENDING 持续超过 10 分钟，请停止轮询并提供原 requestId 联系 Renaiss。下表花括号内的内容会替换为实际值。

错误码	`error.message`
`GACHA_V3_BUYBACK_SNAPSHOT_NOT_FOUND` `GACHA_V3_SETTLEMENT_ID_MISMATCH` `PERPETUAL_GACHA_BUYBACK_CONFIG_NOT_FOUND` `PERPETUAL_GACHA_VENDING_MACHINE_ADDRESS_NOT_FOUND`	`Internal server error` 请将原 `requestId` 提供给 Renaiss。
`CONTRACT_REVERT`	`Smart contract execution reverted` `Contract error: {reason}`
`GACHA_V3_BUYBACK_EXPIRED`	`Buyback has expired for {buybackId}`
`GACHA_V3_BUYBACK_PRICE_CHANGED`	`amount {signedAmount} does not match expected total {expectedTotal}`
`GACHA_V3_BUYBACK_VERIFY_FAILED`	`Buyer does not own this card`
`GACHA_V3_DRAW_RECORD_NOT_FOUND`	`Pack draw record not found for buybackId {buybackId}`
`GACHA_V3_TOKEN_STATUS_INVALID`	`Card is already buyback or released`
`OP_WALLET_BUSY`	`Payments are busy right now and nothing was charged. Please try again in a few seconds.` 请等待几秒，然后重发原签名回购请求。
`PERPETUAL_GACHA_PACK_NOT_FOUND`	`Perpetual VRF pack not found: {cardPackId}`
`PERPETUAL_GACHA_PACK_VERIFY_BUYBACK_FAILED`	`Buyback token must be USDT`

错误码

在下表中查找接口返回的 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`	`error`	`Internal server error`
`500`	`FUNCTION_ERROR`	`error`	`Internal server error`
`500`	其他错误码	`error`	`Internal server error`

授权

x-builder-api-key

string

header

必填

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

查询参数

requestId

string<uuid>

必填

响应

成功

requestId

string<uuid>

必填

status

enum<string>

必填

PENDING 表示处理中；COMPLETED 表示已在链上结算；FAILED 表示未回购任何藏品。

可用选项:

PENDING,

COMPLETED,

FAILED

buyerWalletAddress

string

必填

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

cardPackId

string<uuid>

必填

settlementIds

string[]

必填

32 字节，以 0x 开头，后接 64 个十六进制数字。

txHash

string | null

必填

回购交易哈希，仅 COMPLETED 时有值，其余为 null。

totalAmountInUsdt

string | null

必填

已支付的 USDT 金额，精度为 18 位，仅 COMPLETED 时有值。

Pattern: ^\d+$

itemCount

integer | null

必填

已回购藏品数量，仅 COMPLETED 时有值，其余为 null。

error

object | null

必填

失败原因，格式为 { code, message }。仅 FAILED 时有值，其余为 null。失败时未回购任何藏品。错误码和文字与 POST /v2/gacha/buyback 相同，code 是可扩展的字符串。

PERPETUAL_GACHA_PACK_VERIFY_BUYBACK_FAILED：签署的代币不是 USDT。请从报价列表重新准备回购。
GACHA_V3_TOKEN_STATUS_INVALID：藏品已回售或已交付钱包。重新读取 GET /v2/gacha/buyback/offers，仅为仍有报价的藏品签名。
GACHA_V3_BUYBACK_VERIFY_FAILED：钱包不持有其中一件藏品。请查询 GET /v2/gacha/buyback/offers，仅为返回的藏品签名。
GACHA_V3_BUYBACK_EXPIRED：目前没有可付款档位，可能是窗口已关闭或当前为零比例档。重新获取 GET /v2/gacha/buyback/offers，按结果重试。
CONTRACT_REVERT：链上拒绝回购。查询 GET /v2/gacha/buyback/offers，确认哪些藏品仍有报价后再签名。
PERPETUAL_GACHA_PACK_NOT_FOUND：未找到卡包。请刷新报价并核对卡包 ID。
GACHA_V3_DRAW_RECORD_NOT_FOUND：该卡包中没有对应的结算 ID。刷新报价，并只为该卡包实际返回的结算 ID 签名。
GACHA_V3_BUYBACK_PRICE_CHANGED：读取报价后档位已截止，签名金额与当前价格不符。重新查询 GET /v2/gacha/buyback/offers 并签署新金额。
OP_WALLET_BUSY：付款发送方均忙。等待几秒后重发同一回购签名。
其他错误码：再次发送前先读取 GET /v2/gacha/buyback/offers。如果交易可能已经发送（例如确认超时或发送时被拒），将保持 PENDING 直到核对完毕，不会标记为 FAILED。

Show child attributes

入门

抽卡

交易市场

钱包收藏

实物兑换与配送

开发资源

合作伙伴接入

查询回购状态

请求

响应

提交后的失败

错误码

授权

查询参数

响应