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

# TypeScript SDK

> 安装已发布的 EOA 测试版，配置客户端并核对与 v2 HTTP API 的兼容性。

`@renaiss-protocol/client` 包含供外部账户（EOA）使用的抽卡、市场和兑换客户端。不同版本自带各自的响应校验器。部署实际提供的接口见 [HTTP 参考](https://docs.renaiss.xyz/cn/api-reference.md)。

## 版本兼容性

`0.1.0-beta.4` 预期较早版本的目录响应结构。即使 HTTP 请求成功，卡包列表和市场列表方法也可能返回 `INVALID_SCHEMA`。如需读取当前卡包目录，请直接调用[卡包列表接口](https://docs.renaiss.xyz/cn/api-reference/gacha/list-packs.md)。分档回购、按请求 ID 轮询、[钱包收藏](https://docs.renaiss.xyz/cn/wallet-collections.md)及包含当前 RIX 估值字段的兑换响应也请直接使用 HTTP。RIX 估值就是卡牌的预估公允市价（FMV）。

挂牌、出价、购买和接受买单时，请使用[市场 HTTP 接口](https://docs.renaiss.xyz/cn/marketplace.md#交易操作)。`0.1.0-beta.4` 提交交易时会转发准备响应中的整个 `payload`。提交接口要求使用准备响应顶层的 `tokenId`，并会拒绝额外的 `collectibleId` 字段。

购买或结账后解析失败时，交易结果仍待确认。先查询原请求或订单的状态，再决定是否重新签名。

## 安装

使用 Node.js 24 或以上版本并锁定测试版版本号。使用下面的钱包适配器时还需安装 `viem`。

```bash theme={null}
npm install --save-exact @renaiss-protocol/client@0.1.0-beta.4
npm install viem
```

## 客户端

| 工厂函数 | 用途 |
| - | - |
| `createGachaClient` | 卡包、抽卡及回购 |
| `createMarketplaceClient` | 卡牌、买卖单、购买及撤单 |
| `createRedemptionClient` | 配送会话、报价及结账 |

将 `baseUrl` 设为 API 来源或后端代理前缀，省略 `/v2`，并显式传入对应的 `network`。只在后端保管 `builderApiKey`。浏览器可以调用自己的后端，由后端逐条授权并添加所需的请求头。

## 使用已有钱包

```ts theme={null}
import { BNB_TESTNET, createRedemptionClient } from '@renaiss-protocol/client';
import { signerFrom } from '@renaiss-protocol/client/viem';
import type { WalletClient } from 'viem';

export function shippingForWallet(walletClient: WalletClient) {
  return createRedemptionClient({
    network: BNB_TESTNET,
    baseUrl: '/api/renaiss',
    walletSessionIssuer: 'https://dev-api.renaiss.xyz/v2/auth/wallet',
    signer: signerFrom(walletClient),
  });
}
```

调用 `signInRedemptionWallet({ origin })` 开始[配送会话](https://docs.renaiss.xyz/cn/authentication.md#验证配送钱包)。用户退出或切换钱包时调用 `signOutRedemptionWallet()`。

## 处理结果

```ts theme={null}
import { getError, getValue, isFailed, type RedemptionClient } from '@renaiss-protocol/client';

export async function regionsForWallet(shipping: RedemptionClient) {
  const result = await shipping.fetchRedemptionRegions();
  if (isFailed(result)) throw new Error(getError(result).detail);
  return getValue(result).counts;
}
```

SDK 错误包含 `code`、`status` 和 `detail`，底层 HTTP 错误可能位于 `error` 中。列表方法返回按需加载的分页器。调用 `.firstPage()` 读取一页或使用 `for await` 迭代。通过 `.from(nextCursor)` 继续读取时应保留原筛选条件。

## 金额与标识符

| 值 | 表示方式 |
| - | - |
| SDK 金额输入 | 以代币最小单位表示的 `bigint` |
| USDT 金额 | 在两个受支持的 BNB 网络上均有 18 位小数 |
| 美元估值 | 整数美分，例如 `"1000"` 表示 10 美元 |
| HTTP 代币 ID 与大额数值 | 十进制字符串 |

例如，viem 的 `parseUnits('10', 18)` 返回 10 USDT 对应的最小单位数量。卡牌没有估值时，应保留 null。


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