准备购买卡牌

按展示的挂牌价准备购买

curl --request POST \
  --url https://dev-api.renaiss.xyz/v2/marketplace/buy/prepare \
  --header 'Content-Type: application/json' \
  --header 'x-builder-api-key: <api-key>' \
  --data '
{
  "tokenId": "9007199254740993",
  "walletAddress": "0x1111111111111111111111111111111111111111",
  "expiresAt": null,
  "expectedTotalPriceInUsdt": "102000000000000000000"
}
'

const options = {
  method: 'POST',
  headers: {'x-builder-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tokenId: '9007199254740993',
    walletAddress: '0x1111111111111111111111111111111111111111',
    expiresAt: null,
    expectedTotalPriceInUsdt: '102000000000000000000'
  })
};

fetch('https://dev-api.renaiss.xyz/v2/marketplace/buy/prepare', 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/prepare"

payload = {
    "tokenId": "9007199254740993",
    "walletAddress": "0x1111111111111111111111111111111111111111",
    "expiresAt": None,
    "expectedTotalPriceInUsdt": "102000000000000000000"
}
headers = {
    "x-builder-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "operation": "bid",
  "tokenId": "<string>",
  "buyerWalletAddress": "<string>",
  "quote": {
    "amountInUsdt": "<string>",
    "expiresAt": "2023-11-07T05:31:56Z"
  },
  "typedData": {
    "domain": {},
    "types": {},
    "primaryType": "<string>",
    "message": {}
  },
  "payload": {
    "collectibleId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "bidData": {
      "bidder": "<string>",
      "feeBps": "<string>",
      "tokenId": "<string>",
      "amount": "<string>",
      "nonce": "<string>",
      "deadline": "<string>"
    }
  }
}

Malformed JSON in request body

{
  "error": "Required authentication credential is missing",
  "code": "API_AUTH_MISSING_CREDENTIAL"
}

{
  "error": "Credential is not allowed by this policy",
  "code": "API_AUTH_CREDENTIAL_NOT_ALLOWED"
}

{
  "error": "Collectible not found",
  "code": "COLLECTIBLE_NOT_FOUND"
}

{
  "error": "Ask price changed",
  "code": "WRONG_REQUEST_PARAMS"
}

Payload Too Large

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

Internal Server Error

POST

marketplace

buy

prepare

按展示的挂牌价准备购买

curl --request POST \
  --url https://dev-api.renaiss.xyz/v2/marketplace/buy/prepare \
  --header 'Content-Type: application/json' \
  --header 'x-builder-api-key: <api-key>' \
  --data '
{
  "tokenId": "9007199254740993",
  "walletAddress": "0x1111111111111111111111111111111111111111",
  "expiresAt": null,
  "expectedTotalPriceInUsdt": "102000000000000000000"
}
'

const options = {
  method: 'POST',
  headers: {'x-builder-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tokenId: '9007199254740993',
    walletAddress: '0x1111111111111111111111111111111111111111',
    expiresAt: null,
    expectedTotalPriceInUsdt: '102000000000000000000'
  })
};

fetch('https://dev-api.renaiss.xyz/v2/marketplace/buy/prepare', 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/prepare"

payload = {
    "tokenId": "9007199254740993",
    "walletAddress": "0x1111111111111111111111111111111111111111",
    "expiresAt": None,
    "expectedTotalPriceInUsdt": "102000000000000000000"
}
headers = {
    "x-builder-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "operation": "bid",
  "tokenId": "<string>",
  "buyerWalletAddress": "<string>",
  "quote": {
    "amountInUsdt": "<string>",
    "expiresAt": "2023-11-07T05:31:56Z"
  },
  "typedData": {
    "domain": {},
    "types": {},
    "primaryType": "<string>",
    "message": {}
  },
  "payload": {
    "collectibleId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "bidData": {
      "bidder": "<string>",
      "feeBps": "<string>",
      "tokenId": "<string>",
      "amount": "<string>",
      "nonce": "<string>",
      "deadline": "<string>"
    }
  }
}

Malformed JSON in request body

{
  "error": "Required authentication credential is missing",
  "code": "API_AUTH_MISSING_CREDENTIAL"
}

{
  "error": "Credential is not allowed by this policy",
  "code": "API_AUTH_CREDENTIAL_NOT_ALLOWED"
}

{
  "error": "Collectible not found",
  "code": "COLLECTIBLE_NOT_FOUND"
}

{
  "error": "Ask price changed",
  "code": "WRONG_REQUEST_PARAMS"
}

Payload Too Large

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

Internal Server Error

提交买家确认过的挂牌价。若价格已变化，请刷新订单簿并展示新价格。买家签名后，提交购买。在测试网上，发送 expiresAt: null 可使用默认到期时间。主网更新前，请同时省略 expiresAt 和 expiresInSeconds 以使用主网默认值。提交购买请求时，买家授予 Permit2 的 USDT 额度必须足以支付订单金额。

请求

需要开发者密钥

响应

错误码

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

HTTP	错误码	文本字段	响应文本与处理方式
`400`	`MATCHING_ASK_NOT_FOUND`	`error`	`Ask 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: expiresAt: Required` `expiresAt must be null or a future UTC timestamp within 180 days` 检查报错中提到的字段。要使用默认有效期，请传入 `"expiresAt": null`。
`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`	`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 重试。
`409`	`WRONG_REQUEST_PARAMS`	`error`	`Ask price changed` 传入价格与当前挂牌价不同。请刷新价格并重新准备购买。
`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`	`error`	`Internal server error` 若问题持续出现，请将 `x-request-id` 提供给 Renaiss。

授权

x-builder-api-key

string

header

必填

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

请求体

application/json

tokenId

string

必填

卡牌的链上 ID，以十进制 uint256 字符串传入。

Pattern: ^\d+$

示例:

"9007199254740993"

walletAddress

string

必填

expiresAt

string<date-time> | null

必填

传入 JSON null 表示从准备交易时起 30 天后到期，也可指定未来 180 天内、以 Z 结尾的 UTC 时间戳。每次准备交易都必须传入此字段。

Pattern: Z$

示例:

null

expectedTotalPriceInUsdt

string

必填

买家已确认的挂牌总价，以 USDT 的最小单位表示（18 位小数）。若挂牌价已变化，接口返回 HTTP 409。

Pattern: ^0*[1-9][0-9]*$

响应

成功

operation

enum<string>

必填

可用选项:

bid,

buy

tokenId

string

必填

Pattern: ^\d+$

buyerWalletAddress

string

必填

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

quote

object

必填

Show child attributes

typedData

object

必填

Show child attributes

payload

object

必填

Show child attributes

入门

抽卡

交易市场

钱包收藏

实物兑换与配送

开发资源

合作伙伴接入

准备购买卡牌

请求

响应

错误码

授权

请求体

响应