> ## Documentation Index
> Fetch the complete documentation index at: https://docs.renaiss.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 市场接入指南

> 通过 v2 API 浏览卡牌，准备、签署、提交或取消市场订单。

市场 API 提供公开目录和订单簿。目录支持匿名读取。交易时由后端提供开发者密钥，由执行操作的钱包签署订单。以下简写路径均相对于 `/v2/marketplace`。

## 查询卡牌与价格

1. [浏览市场目录](https://docs.renaiss.xyz/cn/api-reference/marketplace/list-cards.md)时省略凭据。用户选定卡牌后，用 `tokenId` [查询详情](https://docs.renaiss.xyz/cn/api-reference/marketplace/get-card.md)。
2. [读取订单簿](https://docs.renaiss.xyz/cn/api-reference/marketplace/get-orders.md)查看卖家当前的挂牌价和买家资金充足的出价。展示交易确认页前，刷新订单簿。
3. 交易价格、手续费和卖家实收金额以准备交易时返回的报价为准。RIX 估值就是卡牌的预估公允市价（FMV）。

## 交易操作

### 准备交易

将卡牌的 `tokenId` 作为十进制字符串传入，并在 `walletAddress` 中填写签名钱包的地址。每次准备交易都要传入 `expiresAt`。传入 JSON `null` 表示从准备时起 30 天后到期，也可指定未来 180 天内、以 `Z` 结尾的 UTC 时间戳。

| 操作 | 准备交易 | 提交签名 |
| - | - | - |
| 挂牌出售 | 用买家支付的含手续费总价 `totalPriceInUsdt` [准备卖单](https://docs.renaiss.xyz/cn/api-reference/marketplace/prepare-ask.md)。 | [提交卖单](https://docs.renaiss.xyz/cn/api-reference/marketplace/submit-ask.md)。 |
| 出价 | 用 `amountInUsdt` [准备买单](https://docs.renaiss.xyz/cn/api-reference/marketplace/prepare-bid.md)，最低出价为 1 USDT。 | [提交买单](https://docs.renaiss.xyz/cn/api-reference/marketplace/submit-bid.md)。 |
| 按挂牌价买入 | 用已展示的 `expectedTotalPriceInUsdt` [准备购买](https://docs.renaiss.xyz/cn/api-reference/marketplace/prepare-purchase.md)。 | [买入卡牌](https://docs.renaiss.xyz/cn/api-reference/marketplace/buy-card.md)。 |
| 接受买家出价 | 用选中的 `bidOrderId` [准备出售](https://docs.renaiss.xyz/cn/api-reference/marketplace/prepare-sale.md)。 | [接受买单](https://docs.renaiss.xyz/cn/api-reference/marketplace/accept-bid.md)。 |

价格以 USDT 的最小单位表示（18 位小数）。例如，挂牌总价 102 USDT 应写为 `"102000000000000000000"`。请向卖家展示报价中的实收金额 `quote.sellerReceivesInUsdt` 和手续费 `quote.platformFeeInUsdt`。每个钱包最多可持有 250 笔有效买单。

### 签名并提交

钱包签署 `typedData` 前，请核对链、合约、卡牌、钱包、费用、金额及到期时间。如果价格变化，请用户重新确认。

使用同一次准备响应构造提交请求。例如，卖家签署挂牌订单后，将以下请求体发送至 `POST /v2/marketplace/asks`。

```js theme={null}
const body = {
  tokenId: prepared.tokenId,
  askData: prepared.payload.askData,
  askSignature: signature,
};
```

出价或购买时，使用 `payload.bidData` 和 `bidSignature`。接受买单时，使用 `payload.askData`、`askSignature` 和 `payload.bidOrderId`。请原样复制已签名的订单数据，包括以 Unix 秒数表示的截止时间。将 `tokenId` 保留为字符串，以免大整数丢失精度。

准备响应仍会返回 `payload.collectibleId`。只复制提交接口接受的字段。直接转发整个 `payload` 会包含这个额外字段，导致接口返回 HTTP `400`。

## 合约授权

买家和出价方需要充足的 USDT 余额及对 Permit2 的授权额度。对照[网络常量](https://docs.renaiss.xyz/cn/contracts.md)核对代币及支出方，等待授权交易确认。卖家签署卖单即授权转移卡牌。卖家接受出价前，买方的余额或授权额度仍可能变化。

## 撤销订单

调用 `POST /orders/cancel/prepare`，传入订单 ID 及其所有者的钱包地址。由该钱包核对并签名，再调用 `POST /orders/cancel`。撤单会从 API 订单簿移除订单，但原卖单签名或 Permit2 签名在链上仍然有效。使买单的 Permit2 nonce 失效需要另发钱包交易。

## 确认超时后的成交状态

请求超时后，如有交易哈希，请查询该交易，并核对链上持有人和最新订单簿。已提交的订单可能已经成交。在结果明确前，暂停再次提交。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.