# @crossmint/rest-js 中文文档

规范地址：https://npmcn.com/package/%40crossmint/rest-js/

版本：0\.2\.0
npm 元数据更新时间：2026-11-05T22:32:49.317Z
中文译文更新时间：2026-11-14T10:34:37.427Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40crossmint/rest-js
原文对照：https://npmcn.com/package/%40crossmint/rest-js/?lang=original
项目主页：https://docs.crossmint.com/

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：5.7 MB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-10-07T07:54:04.585Z
- 最新版本发布：2026-10-08T20:48:56.729Z
- 近 30 天下载量：2073（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

用于 JavaScript 和 TypeScript 的 Crossmint REST SDK

## 安装

```sh
npm install @crossmint/rest-js
```

也可以使用：`pnpm add @crossmint/rest-js`、`yarn add @crossmint/rest-js`、`bun add @crossmint/rest-js`

## README

# 用于 JavaScript 和 TypeScript 的 Crossmint REST SDK

输入客户端 [十字薄荷 REST API](https://docs.crossmint.com/)支持 节点.js 18+ 和浏览器,带本地抓取器, 并带有无害环境管理和普通JS导出并不存在 运行时间依赖.

## 安装

```sh
npm install @crossmint/rest-js
```

## 创建客户端

```ts
import { createCrossmintSdk } from "@crossmint/rest-js";

const crossmint = createCrossmintSdk({
    environment: "staging",
    apiKey: process.env.CROSSMINT_API_KEY,
});

const { data: wallet } = await crossmint.wallets.create({
    body: { chainType: "evm", type: "mpc" },
    throwOnError: true,
});
```

默认环境是 `staging`设置 `environment: "production"` 用于使用 生产API。 客户端将每个操作自动引导到它的 API 主机, 包括断层操作。 仅在发送拒绝请求时可用的终点 在生产中.

要通过您的后端代理或本地 API 调用, 设置 `baseUrl` 改为: 绝对URL. 它取代 API 主机及其 `/api` 每个操作的路径 除故障操作外:

```ts
const crossmint = createCrossmintSdk({ baseUrl: "https://your-app.example/api/crossmint" });
```

故障操作(付款方法创建)发送原始卡和银行细节,以及 只有Vault主机表示它们。 你准备好后,他们就留在地窖主机上 `baseUrl`要移动它们,设置 `vaultBaseUrl`。接收这些软件的服务器 请求会收到原始卡片数据,所以它会进入您的PCI DSS范围.

在服务器上保留服务器 API 密钥 。 在浏览器中,使用带有 API 的客户端密钥 适当范围和供应 `userJwt` 当终点需要用户时 认证。 对于接受命令的终端客户端秘密,使用 `clientSecret`。每个请求都使用已宣布的完整认证选项 由API;明确提供的请求头优先.

## 请求和答复

方法按资源分类,例如: `crossmint.wallets.create(...)` 财务报告和审定财务报表 `crossmint.orders.get(...)`。请求选项保留 `body`, (中文(简体) ), `path`, (中文(简体) ), `query`,以及 `headers` 分开。 通过一个 `AbortSignal` 结束 `signal` 取消一项请求, 或创建客户端时提供自定义获取执行.

```ts
const { data, error, response } = await crossmint.orders.get({
    path: { orderId: "your-order-id" },
});

if (error !== undefined) {
    console.error(response?.status, error);
} else {
    console.log(data);
}
```

HTTP 失败返回 `error` 默认。 与 `throwOnError: true`,客户端 舍弃错误。 网络失败也返回 `error` 除非 `throwOnError` 已启用. 返回的错误不一定是 JavaScript `Error` 实例.

一些API明确曝光多个版本,例如: `crossmint.paymentMethods.v20260916.create(...)` 财务报告和审定财务报表 `crossmint.paymentMethods.unstable.create(...)`。使用文档中的版本 您的集成; 不稳定的 API 可能会改变.

## 流线

流出方法返回同步延时器 :

```ts
const abortController = new AbortController();
const { stream } = await crossmint.agentCheckouts.messages.stream({
    path: { id: "your-checkout-id" },
    signal: abortController.signal,
});

for await (const event of stream) {
    console.log(event);
}
```

## 响应查询

在查询函数和突变中使用SDK方法. 包括环境和 在您的缓存范围内的工程或用户身份, 因此来自不同客户的请求 不共享缓存结果。 从不将 API 密钥或令牌放入查询密钥中 .

```ts
import { useQuery } from "@tanstack/react-query";

const walletQuery = useQuery({
    queryKey: ["crossmint", cacheScope, "wallet", walletLocator],
    queryFn: async ({ signal }) => {
        const { data } = await crossmint.wallets.get({
            path: { walletLocator },
            signal,
            throwOnError: true,
        });
        return data;
    },
});
```

React 查询单独安装 。 SDK不依赖于反应.

## 兼容性

SDK由Crossmint的公开OpenAPI规格所出. 它的终点 范围、请求和答复类型都遵循这一规定。 类型脚本 类型不执行运行时响应验证.

该软件包支持采用无害环境管理和 `sideEffects: false`。 。 。 . 可以删除完全未使用的导入; 当前创建资源客户端 包括整个业务登记册。 资源捆绑拆分不是 提供。 React 本地和其他 Freach 兼容的运行时间尚未实现 验证.

见 [API 参考](https://docs.crossmint.com/) 对于端点行为, 权限,和 API 限制.

在Apache 2.0下获得许可. 见 `THIRD_PARTY_NOTICES` 用于捆绑的 Hey API 运输的麻省理工学院执照.

## 常见问题

### @crossmint/rest-js 是什么？

用于 JavaScript 和 TypeScript 的 Crossmint REST SDK

### 如何安装 @crossmint/rest-js？

在项目目录运行 npm install @crossmint/rest-js，或使用 pnpm add / yarn add / bun add。

### @crossmint/rest-js 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @crossmint/rest-js 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @crossmint/rest-js 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @crossmint/rest-js 可以商用吗？

@crossmint/rest-js 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @crossmint/rest-js 的下载量有多少？

根据 npm 官方下载统计，@crossmint/rest-js 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,073 次，日均约 69 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @crossmint/rest-js 还在维护吗？

最新版本 0\.2\.0 发布于 2026/10/09（1 个月前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/10/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。