购买卡牌

提交已签名的购买请求

curl --request POST \
  --url https://dev-api.renaiss.xyz/v2/marketplace/buy \
  --header 'Content-Type: application/json' \
  --header 'x-builder-api-key: <api-key>' \
  --data '
{
  "tokenId": "9007199254740993",
  "bidData": {
    "bidder": "<string>",
    "feeBps": "<string>",
    "tokenId": "9007199254740993",
    "amount": "<string>",
    "nonce": "<string>",
    "deadline": "<string>"
  },
  "bidSignature": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {'x-builder-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tokenId: '9007199254740993',
    bidData: {
      bidder: '<string>',
      feeBps: '<string>',
      tokenId: '9007199254740993',
      amount: '<string>',
      nonce: '<string>',
      deadline: '<string>'
    },
    bidSignature: '<string>'
  })
};

fetch('https://dev-api.renaiss.xyz/v2/marketplace/buy', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://dev-api.renaiss.xyz/v2/marketplace/buy"

payload = {
    "tokenId": "9007199254740993",
    "bidData": {
        "bidder": "<string>",
        "feeBps": "<string>",
        "tokenId": "9007199254740993",
        "amount": "<string>",
        "nonce": "<string>",
        "deadline": "<string>"
    },
    "bidSignature": "<string>"
}
headers = {
    "x-builder-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "operation": "ask",
  "orderId": "<string>",
  "status": "ACTIVE",
  "executed": true,
  "executionTxHash": "<string>",
  "matchedOrderId": "<string>"
}

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": "Collectible not found",
  "code": "COLLECTIBLE_NOT_FOUND"
}

Payload Too Large

{
  "error": "Authentication rate limit exceeded",
  "code": "API_AUTH_RATE_LIMITED"
}

Internal Server Error

POST

marketplace

buy

提交已签名的购买请求

curl --request POST \
  --url https://dev-api.renaiss.xyz/v2/marketplace/buy \
  --header 'Content-Type: application/json' \
  --header 'x-builder-api-key: <api-key>' \
  --data '
{
  "tokenId": "9007199254740993",
  "bidData": {
    "bidder": "<string>",
    "feeBps": "<string>",
    "tokenId": "9007199254740993",
    "amount": "<string>",
    "nonce": "<string>",
    "deadline": "<string>"
  },
  "bidSignature": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {'x-builder-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tokenId: '9007199254740993',
    bidData: {
      bidder: '<string>',
      feeBps: '<string>',
      tokenId: '9007199254740993',
      amount: '<string>',
      nonce: '<string>',
      deadline: '<string>'
    },
    bidSignature: '<string>'
  })
};

fetch('https://dev-api.renaiss.xyz/v2/marketplace/buy', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://dev-api.renaiss.xyz/v2/marketplace/buy"

payload = {
    "tokenId": "9007199254740993",
    "bidData": {
        "bidder": "<string>",
        "feeBps": "<string>",
        "tokenId": "9007199254740993",
        "amount": "<string>",
        "nonce": "<string>",
        "deadline": "<string>"
    },
    "bidSignature": "<string>"
}
headers = {
    "x-builder-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "operation": "ask",
  "orderId": "<string>",
  "status": "ACTIVE",
  "executed": true,
  "executionTxHash": "<string>",
  "matchedOrderId": "<string>"
}

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": "Collectible not found",
  "code": "COLLECTIBLE_NOT_FOUND"
}

Payload Too Large

{
  "error": "Authentication rate limit exceeded",
  "code": "API_AUTH_RATE_LIMITED"
}

Internal Server Error

从准备购买的响应中取出顶层 tokenId 和 payload.bidData。分别填入 tokenId 和 bidData，再附上买家的 bidSignature。在测试网上，请提交此处所示的顶层 tokenId。主网更新前，请将准备响应的 payload.collectibleId 作为主网请求的顶层 collectibleId。签名订单数据应与准备响应保持一致。

请求

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

响应

错误码

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

HTTP	错误码	文本字段	响应文本与处理方式
`400`	`ASK_HAS_ALREADY_EXPIRED`	`error`	`Ask has already expired` 挂牌已过期。请刷新挂牌列表，不要重发原请求。
`400`	`BID_HAS_ALREADY_EXPIRED`	`error`	`Bid has already expired` 购买授权在处理期间过期。请延长有效期并重新准备、签名。
`400`	`BID_LOWER_THAN_ASK`	`error`	`Bid amount is lower than current ask price` 签名的出价低于挂牌价。请重新准备并签名。
`400`	`BID_TOKEN_ID_MISMATCH`	`error`	`Signed order token ID differs from the submitted token ID` `Bid token ID does not match the collectible` 核对 `tokenId` 与 `bidData.tokenId` 是否指向同一张卡牌。两个字段都应取自同一次准备响应。
`400`	`INSUFFICIENT_ALLOWANCE`	`error`	`Insufficient token allowance for Permit2` 当前 USDT 授权额度不足。授权所需金额后再提交购买。
`400`	`INVALID_ASK_SIGNATURE`	`error`	`Ask signature is invalid` 该挂牌已无法购买。请刷新挂牌列表，不要重发原请求。
`400`	`INVALID_BID_FEE_BPS`	`error`	`Invalid bid fee BPS` 购买签名中的费率无效。请重新准备并签名。
`400`	`INVALID_BID_SIGNATURE`	`error`	`Bid signature is invalid` 购买签名无效。请重新准备并让钱包签署新数据。
`400`	`MATCHING_ASK_NOT_FOUND`	`error`	`Listing is no longer available` 藏品没有有效挂牌。请刷新挂牌列表，不要重复发送原请求。
`400`	`MATCHING_ASK_PERMIT_NOT_FOUND`	`error`	`Stored ask payload is invalid` 该挂牌无法购买。请刷新挂牌列表，不要重复发送原请求。
`400`	`WRONG_REQUEST_PARAMS`	`error`	`Invalid marketplace request: tokenId: Required` `Invalid marketplace request: Expected object, received array` 请用 JSON 对象传入必填字段。复制准备响应顶层的 `tokenId`，并省略 `collectibleId`。
`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`	`COLLECTIBLE_NOT_FOUND`	`error`	`Collectible not found` 代币 ID 未知或藏品在该 API 中不可用。请核对 ID，不要用同一 ID 重试。
`413`	无错误码	`text/plain`	`Payload Too Large`
`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`	无错误码	`text/plain`	`Internal Server Error`
`500`	`COLLECTIBLE_GET_FAILED` `BID_ORDER_INSERT_FAILED` `MATCHING_ASK_PERMIT_NOT_FOUND` `BUY_NOW_FAILED` `MATCHING_ASK_SHOULD_BE_ONLY_ONE` `EXECUTE_TRADE_INTERNAL_FAILED` `OP_WALLET_NOT_AVAILABLE` `TRANSACTION_VERIFICATION_FAILED` `RPC_BLOCK_NUMBER_NOT_UPDATED` `ACTIVITY_SYNC_FAILED`	`error`	`Internal server error` 重新提交前，请查询订单和钱包活动。

授权

x-builder-api-key

string

header

必填

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

请求体

application/json

tokenId

string

必填

复制准备响应顶层的 tokenId，保留十进制字符串格式。其 uint256 数值必须与 bidData.tokenId 相同。

Pattern: ^\d+$

示例:

"9007199254740993"

bidData

object

必填

从同一次准备响应复制 payload.bidData。请原样保留签名字段，包括以 Unix 秒数字符串表示的截止时间。

Show child attributes

bidSignature

string

必填

响应

成功

operation

enum<string>

必填

可用选项:

ask,

bid,

buy,

sell

orderId

string

必填

status

enum<string>

必填

可用选项:

ACTIVE,

EXECUTED

executed

boolean

必填

executionTxHash

string

matchedOrderId

string

入门

抽卡

交易市场

钱包收藏

实物兑换与配送

开发资源

合作伙伴接入

请求

响应

错误码

授权

请求体

响应