> ## 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.

# API 参考

> 通过 Renaiss v2 HTTP API 开包、交易卡牌、读取钱包收藏并申请实物配送。

## 发送第一个请求

在 BNB 测试网上查询公开卡包，无需凭据。

1. 打开[卡包列表调试面板](https://docs.renaiss.xyz/cn/api-reference/gacha/list-packs.md?playground=open)，选择测试网地址 `https://dev-api.renaiss.xyz`。
2. 展开**查询**下的可选字段。将 `stage` 设为 `active`、`limit` 设为 `1`，然后点击**发送**。
3. 查看响应中的 `cardPacks`。如果返回了卡包，可复制其 `slug` [查询卡包详情](https://docs.renaiss.xyz/cn/api-reference/gacha/get-pack.md)。若数组为空，表示当前没有在售卡包。

如果你使用 TypeScript 客户端，请参阅 [SDK 快速入门](https://docs.renaiss.xyz/cn/quickstart.md#读取在售卡包)。

## 浏览接口

选择要接入的功能，按调用顺序查看步骤及对应的接口文档。

> [card] [卡包与抽卡](https://docs.renaiss.xyz/cn/gacha.md)
>
> 浏览卡包和内容，准备开包并查询抽卡结果。

> [card] [回购](https://docs.renaiss.xyz/cn/gacha.md#回购与交付)
>
> 查询钱包可接受的回购报价，跟踪已提交的回购。

> [card] [交易市场](https://docs.renaiss.xyz/cn/marketplace.md)
>
> 查找卡牌、读取订单簿，并准备需要钱包签名的订单。

> [card] [钱包收藏](https://docs.renaiss.xyz/cn/wallet-collections.md)
>
> 查看钱包持有的卡牌、收藏估值和链上活动。

> [card] [钱包访问令牌](https://docs.renaiss.xyz/cn/authentication.md#验证配送钱包)
>
> 获取登录消息、验证钱包并管理配送会话。

> [card] [实物兑换与配送](https://docs.renaiss.xyz/cn/redeem.md)
>
> 查找可兑换藏品、获取运费报价、提交订单并跟踪物流。

## 选择环境

| 环境 | 基础 URL | 在线规范 |
| - | - | - |
| BNB 测试网 | `https://dev-api.renaiss.xyz` | [测试网 OpenAPI JSON](https://dev-api.renaiss.xyz/v2/openapi.json) |
| BNB 智能链主网 | `https://api.renaiss.xyz` | [主网 OpenAPI JSON](https://api.renaiss.xyz/v2/openapi.json) |

凭据、钱包签名和[合约地址](https://docs.renaiss.xyz/cn/contracts.md)必须对应同一环境。公开目录可以直接读取。访问受保护接口时，从后端发送 `x-builder-api-key` 请求头。实物兑换还需要在 `Authorization` 请求头中提供钱包访问令牌。[身份验证](https://docs.renaiss.xyz/cn/authentication.md)列出了各类操作的凭据要求。

## 处理响应和错误

每个接口页面列出适用的参数、请求体、响应结构和 HTTP 状态码。代币 ID 和 USDT 金额等大整数以十进制字符串返回。保留原始字符串，需要计算时再转为 `bigint`。详见[金额与标识符](https://docs.renaiss.xyz/cn/typescript-sdk.md#金额与标识符)。

请在[错误码参考](https://docs.renaiss.xyz/cn/api-reference/errors.md)中按错误码查找原因、纯文本响应及恢复方式。各接口页面也会按 HTTP 状态列出错误码。签名提交后如遇超时，先按[抽卡](https://docs.renaiss.xyz/cn/gacha.md)或[实物兑换](https://docs.renaiss.xyz/cn/redeem.md)指南查询状态，再决定是否重试。

字段更名、新增接口和修复记录见 [API 更新日志](https://docs.renaiss.xyz/cn/changelogs.md)。


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