使用钱包签名结算回购
curl --request POST \
--url https://api.renaiss.xyz/v2/gacha/buyback \
--header 'Content-Type: application/json' \
--header 'x-builder-api-key: <api-key>' \
--data '
{
"buyerWalletAddress": "<string>",
"cardPackId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"buybackAuth": {
"buybackIds": [
"<string>"
],
"token": "<string>",
"amount": "<string>"
},
"userSignature": "<string>"
}
'const options = {
method: 'POST',
headers: {'x-builder-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
buyerWalletAddress: '<string>',
cardPackId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
buybackAuth: {buybackIds: ['<string>'], token: '<string>', amount: '<string>'},
userSignature: '<string>'
})
};
fetch('https://api.renaiss.xyz/v2/gacha/buyback', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.renaiss.xyz/v2/gacha/buyback"
payload = {
"buyerWalletAddress": "<string>",
"cardPackId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"buybackAuth": {
"buybackIds": ["<string>"],
"token": "<string>",
"amount": "<string>"
},
"userSignature": "<string>"
}
headers = {
"x-builder-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"txHash": "<string>",
"totalAmountInUsdt": "<string>",
"itemCount": 2
}Malformed JSON in request body{
"error": "Required authentication credential is missing",
"code": "API_AUTH_MISSING_CREDENTIAL"
}{
"error": "Invalid wallet action proof",
"code": "API_AUTH_INVALID_ACTION"
}{
"error": "One or more builder draws were not found",
"code": "EOA_PURCHASE_REJECTED"
}{
"error": "amount 1000000000000000000 does not match expected total 900000000000000000",
"code": "GACHA_V3_BUYBACK_PRICE_CHANGED"
}{
"error": "Authentication rate limit exceeded",
"code": "API_AUTH_RATE_LIMITED"
}{
"error": "Internal server error",
"code": "FUNCTION_ERROR"
}{
"code": "OP_WALLET_BUSY",
"error": "Payments are busy right now and nothing was charged. Please try again in a few seconds."
}抽卡与回购
结算回购
使用开发者密钥和卖家签署的 BuybackUserAuthorization 结算回购。
POST
/
v2
/
gacha
/
buyback
使用钱包签名结算回购
curl --request POST \
--url https://api.renaiss.xyz/v2/gacha/buyback \
--header 'Content-Type: application/json' \
--header 'x-builder-api-key: <api-key>' \
--data '
{
"buyerWalletAddress": "<string>",
"cardPackId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"buybackAuth": {
"buybackIds": [
"<string>"
],
"token": "<string>",
"amount": "<string>"
},
"userSignature": "<string>"
}
'const options = {
method: 'POST',
headers: {'x-builder-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
buyerWalletAddress: '<string>',
cardPackId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
buybackAuth: {buybackIds: ['<string>'], token: '<string>', amount: '<string>'},
userSignature: '<string>'
})
};
fetch('https://api.renaiss.xyz/v2/gacha/buyback', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.renaiss.xyz/v2/gacha/buyback"
payload = {
"buyerWalletAddress": "<string>",
"cardPackId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"buybackAuth": {
"buybackIds": ["<string>"],
"token": "<string>",
"amount": "<string>"
},
"userSignature": "<string>"
}
headers = {
"x-builder-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"txHash": "<string>",
"totalAmountInUsdt": "<string>",
"itemCount": 2
}Malformed JSON in request body{
"error": "Required authentication credential is missing",
"code": "API_AUTH_MISSING_CREDENTIAL"
}{
"error": "Invalid wallet action proof",
"code": "API_AUTH_INVALID_ACTION"
}{
"error": "One or more builder draws were not found",
"code": "EOA_PURCHASE_REJECTED"
}{
"error": "amount 1000000000000000000 does not match expected total 900000000000000000",
"code": "GACHA_V3_BUYBACK_PRICE_CHANGED"
}{
"error": "Authentication rate limit exceeded",
"code": "API_AUTH_RATE_LIMITED"
}{
"error": "Internal server error",
"code": "FUNCTION_ERROR"
}{
"code": "OP_WALLET_BUSY",
"error": "Payments are busy right now and nothing was charged. Please try again in a few seconds."
}EOA_PURCHASE_REJECTED。回购款以 USDT 支付给钱包。即使卖家的 USDT 余额和 Permit2 授权额度都为零,也可以完成回购。请求
需要开发者密钥和钱包签名
响应
错误码
响应原文中花括号内的内容会替换为实际值。有关各接口通用的处理建议,请参阅错误码含义与处理方式。
| HTTP | 错误码 | 文本字段 | 响应文本与处理方式 |
|---|---|---|---|
400 | API_AUTH_INVALID_INPUT | error | Request body is too large请求体超过 16 KiB。请缩小请求体。 |
400 | CONTRACT_REVERT | error | Smart contract execution revertedContract error: {reason}链上拒绝回购。查询 GET /v2/gacha/buyback/offers,确认哪些藏品仍有报价后再签名。 |
400 | EOA_PURCHASE_REJECTED | error | SAFE addresses are not supported by v2该钱包无法用于本次回购。请换用其他钱包。 |
400 | GACHA_V3_BUYBACK_EXPIRED | error | Buyback has expired for {buybackId}目前没有可付款档位,可能是窗口已关闭或当前为零比例档。重新获取 GET /v2/gacha/buyback/offers,按结果重试。 |
400 | GACHA_V3_BUYBACK_VERIFY_FAILED | error | Buyer does not own this card钱包不持有其中一件藏品。请查询 GET /v2/gacha/buyback/offers,仅为返回的藏品签名。 |
400 | GACHA_V3_TOKEN_STATUS_INVALID | error | Card is already buyback or released藏品已回售或已交付钱包。重新读取 GET /v2/gacha/buyback/offers,仅为仍有报价的藏品签名。 |
400 | PERPETUAL_GACHA_PACK_VERIFY_BUYBACK_FAILED | error | Buyback token must be USDT签署的代币不是 USDT。请从报价列表重新准备回购。 |
400 | WRONG_REQUEST_PARAMS | message | Bad request - invalid parameters字段缺失或格式错误。修正后重新发送, |
400 | 其他错误码 | error | 读取响应中 error 的字符串值。 |
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 | One or more builder draws were not foundPack not found部分藏品并非该钱包在当前开发者处抽取,或卡包不存在。请核对卡包 ID 和 GET /v2/gacha/buyback/offers 返回的结算 ID。 |
404 | GACHA_V3_DRAW_RECORD_NOT_FOUND | error | Pack draw record not found for buybackId {buybackId}该卡包中没有对应的结算 ID。刷新报价,并只为该卡包实际返回的结算 ID 签名。 |
404 | PERPETUAL_GACHA_PACK_NOT_FOUND | error | Perpetual VRF pack not found: {cardPackId}未找到卡包。请刷新报价并核对卡包 ID。 |
404 | PERPETUAL_GACHA_SUBPACK_RECORD_NOT_FOUND | error | Pack draw record not found for buybackId {buybackId}Perpetual set record not found |
404 | 其他错误码 | error | 读取响应中 error 的字符串值。 |
409 | GACHA_V3_BUYBACK_PRICE_CHANGED | error | amount {signedAmount} does not match expected total {expectedTotal}读取报价后档位已截止,签名金额与当前价格不符。重新查询 GET /v2/gacha/buyback/offers 并签署新金额。 |
409 | 其他错误码 | error | 读取响应中 error 的字符串值。 |
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 | GACHA_V3_BUYBACK_SNAPSHOT_NOT_FOUNDGACHA_V3_SETTLEMENT_ID_MISMATCHPERPETUAL_GACHA_BUYBACK_CONFIG_NOT_FOUNDPERPETUAL_GACHA_VENDING_MACHINE_ADDRESS_NOT_FOUNDGACHA_V3_BUYBACK_FAILEDGACHA_V3_TIMESTAMP_MISSINGCONTRACT_EXECUTION_ERROROP_WALLET_NOT_AVAILABLETRANSACTION_VERIFICATION_FAILEDPERPETUAL_GACHA_BUYBACK_SYNC_FAILEDINTERNAL_SERVER_ERROR | error | Internal server error重新签名前,请核对钱包的回购报价和活动。若仍不能确认收款结果,请将 x-request-id 提供给 Renaiss。 |
500 | 其他错误码 | error | Internal server error |
503 | OP_WALLET_BUSY | error | Payments are busy right now and nothing was charged. Please try again in a few seconds.付款发送方均忙,请稍后重试。 |
503 | 其他错误码 | error | Internal server error |
CONTRACT_REVERT 无法判断转账失败的具体原因。重试前请核对钱包当前的回购报价。若 HTTP 503 返回 OP_WALLET_BUSY,请按 Retry-After 指定的秒数等待,再重发原签名。交易确认后仍可能返回 HTTP 404 和 PERPETUAL_GACHA_SUBPACK_RECORD_NOT_FOUND。再次签名前请先核对钱包活动和当前报价。授权
请求体
application/json