# @crossmint/wallets-sdk 中文文档

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

版本：1\.22\.3
npm 元数据更新时间：2026-11-10T15:56:59.355Z
中文译文更新时间：2026-11-11T01:39:36.549Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40crossmint/wallets-sdk
原文对照：https://npmcn.com/package/%40crossmint/wallets-sdk/?lang=original
项目主页：https://github.com/Crossmint/crossmint-sdk#readme
源码仓库：https://github.com/Crossmint/crossmint-sdk

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

- 包体积（解压后）：3.9 MB，553 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：14 个
- peer 依赖：@solana/web3\.js ^1\.98\.1
- 首次发布：2025-03-03T14:05:09.219Z
- 最新版本发布：2026-11-10T15:56:59.034Z
- 近 30 天下载量：200503（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：165（近 12 个月 81 个）

## 中文简介

用于创建和管理的打字机 SDK [十字薄荷钱包](https://docs.crossmint.com/) 在EVM,索拉纳,和斯特拉勒链.

## 安装

```sh
npm install @crossmint/wallets-sdk
```

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

## README

# @ crossmint/ 钱包- sdk

用于创建和管理的打字机 SDK [十字薄荷钱包](https://docs.crossmint.com/) 在EVM,索拉纳,和斯特拉勒链.

## 先决条件

从中获取 Crossmint API 密钥 [开发者控制台](https://docs.crossmint.com/introduction/platform/api-keys)。确保您的键有 **钱包 API** 启用范围,包括 `wallets.fund` 页:1 `stagingFund`。 。 。 .

-   **客户端** (浏览器):使用客户端 API 密钥
-   **服务器侧** (节点:js): 使用服务器 API 密钥

## 安装

```bash
npm install @crossmint/wallets-sdk
# or
pnpm add @crossmint/wallets-sdk
# or
yarn add @crossmint/wallets-sdk
```

## 快速启动

### 服务器侧 (Node.js)

```ts
import { createCrossmint, CrossmintWallets } from "@crossmint/wallets-sdk";

const crossmint = createCrossmint({ apiKey: "<YOUR_SERVER_API_KEY>" });
const wallets = CrossmintWallets.from(crossmint);

// Create a wallet with a server signer
const wallet = await wallets.createWallet({
  chain: "base-sepolia",
  recoveryMethods: [{ type: "server", secret: "<RECOVERY_SECRET>" }],
});

console.log(wallet.address);

// Staging only: mint USDXM, Crossmint's test stablecoin, into the wallet
await wallet.stagingFund(10);

// Send tokens
const tx = await wallet.send("0xRecipientAddress", "usdxm", "10");
console.log(tx.explorerLink);
```

### 客户端( 无头)

对于客户端不用React的用法,可以直接与用户JWT使用SDK. 在进行中,从 Crossmint Auth 获得它(`@crossmint/client-sdk-auth`);在生产中,或当您的应用程序已经有认证提供者时,使用该提供者的JWT:

```ts
import { createCrossmint, CrossmintWallets } from "@crossmint/wallets-sdk";

const crossmint = createCrossmint({ apiKey: "<YOUR_CLIENT_API_KEY>" });
crossmint.setJwt("<USER_JWT>");

const wallets = CrossmintWallets.from(crossmint);

const wallet = await wallets.getWallet({ chain: "base-sepolia" });
console.log(wallet.address);
```

> 用于反应应用程序, 使用 [`@crossmint/client-sdk-react-ui`](https://www.npmjs.com/package/@crossmint/client-sdk-react-ui) 规定 `CrossmintWalletProvider`钩子和内置的UI 用于检察官办公室和密码流通.

## 创建钱包

### 服务器签名器

以服务器密钥创建钱包作为恢复方法 :

```ts
import { createCrossmint, CrossmintWallets } from "@crossmint/wallets-sdk";

const crossmint = createCrossmint({ apiKey: "<YOUR_SERVER_API_KEY>" });
const wallets = CrossmintWallets.from(crossmint);

const wallet = await wallets.createWallet({
  chain: "base-sepolia",
  recoveryMethods: [{ type: "server", secret: "<RECOVERY_SECRET>" }],
});

console.log(wallet.address);
```

### 外部钱包签名器

自带钥匙( MetaMask, KMS等) :

```ts
const wallet = await wallets.createWallet({
  chain: "base-sepolia",
  recoveryMethods: [
    {
      type: "external-wallet",
      address: "0xYourWalletAddress",
      onSign: async (message: string) => {
        // Sign the message with your wallet/KMS and return the signature
        return await yourWallet.signMessage({ message: { raw: message as `0x${string}` } });
      },
    },
  ],
});
```

### 设备签名器( 浏览器 / React Introduction)

设备签名者使用由硬件支撑的P256键进行无摩擦客户端-侧签名. 它们必须在客户端上创建,并且可以在钱包创建时间被传递到服务器:

```ts
// Client: generate a device signer descriptor
const { createDeviceSigner } = useWallet();
const deviceSigner = await createDeviceSigner();
// Send deviceSigner to your server
```

```ts
// Server: create the wallet with the device signer pre-registered
const wallet = await wallets.createWallet({
  chain: "base-sepolia",
  owner: "email:user@example.com",
  recoveryMethods: [{ type: "email", email: "user@example.com" }],
  signers: [deviceSigner],
});
```

> 设备签名器是 **仅浏览器和回放本地** ——Node.js没有. 见 [带有设备签名器的服务器- Side 钱包](https://docs.crossmint.com/wallets/guides/signers/device-signer-server-wallet) 用于完整图案的指南.

### 获取已存在的钱包

```ts
// Client-side
const wallet = await wallets.getWallet({ chain: "base-sepolia" });
```

```ts
// Server-side — requires a wallet locator
const wallet = await wallets.getWallet("0xWalletAddress", {
  chain: "base-sepolia",
});
```

## 核心概念

### 签名人

钱包 SDK 使用两级标志模型:

-   **回收方法** ——高安全性,用于钱包回收并添加新的签注. 支持电子邮件OTP,电话OTP,外部钱包或服务器密钥.
-   **操作标志** ——低平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平平 支持服务器密钥,外部钱包,密码,以及设备(仅浏览/移动). 对于服务器侧(Node.js)的使用,使用a **服务器** 或者说 **外墙** 签名者.

在没有可操作的签名器时,恢复方法自动成为签名的倒计时.

## 使用量

### 余额

```ts
const balances = await wallet.balances();

console.log(balances.nativeToken.amount);
console.log(balances.usdc.amount);
```

对于有卡片的钱包,每个信使也会报告其余额的分割情况:

-   `available`: 现在可以花多少
-   `locked`:待付卡费
-   `inTransit`:在钱包和卡片之间移动的资金,但卡片提供者尚未反映
-   `accounts`:钱包和每张卡的分数相同。 只有信用卡账户 `inTransit`。每张卡都报告 `creditLimit`: 按卡片提供者的设置, 它能花的最多

`available + inTransit` 是用户在资金流动时持有的总数.

```ts
const { usdc } = await wallet.balances();
console.log(usdc.available?.amount, usdc.inTransit?.amount);
```

### 发送托肯斯

```ts
const tx = await wallet.send("0xRecipient", "usdc", "100");
console.log(tx.explorerLink);
```

### 转账

```ts
const transfers = await wallet.transfers({
  tokens: "usdc",
  status: "successful",
});
```

### 无

```ts
const nfts = await wallet.nfts({ perPage: 10, page: 1 });
```

### 链状交易

```ts
import { EVMWallet, SolanaWallet, StellarWallet } from "@crossmint/wallets-sdk";

// EVM — smart contract interaction
const evmWallet = EVMWallet.from(wallet);
const tx = await evmWallet.sendTransaction({
  to: "0xContractAddress",
  abi: contractAbi,
  functionName: "mint",
  args: [1],
  value: 0n,
});

// EVM — sign a message
const sig = await evmWallet.signMessage({ message: "Hello" });

// EVM — viem public client
const client = evmWallet.getViemClient();

// Solana
const solWallet = SolanaWallet.from(wallet);
const solTx = await solWallet.sendTransaction({
  serializedTransaction: "<base64-encoded-transaction>",
});

// Stellar
const stellarWallet = StellarWallet.from(wallet);
const stellarTx = await stellarWallet.sendTransaction({
  contractId: "C...",
  method: "transfer",
  args: { to: "G...", amount: "1000000" },
});
```

### 签名管理

```ts
// Add a new signer
await wallet.addSigner({ type: "server", secret: "<SECRET>" });

// List signers
const signers = await wallet.signers();
console.log(signers); // [{ type: "server", locator: "server:...", status: "success" }, ...]

// Set the active signer (required after getWallet server-side)
await wallet.useSigner({ type: "server", secret: "<SECRET>" });
```

### 交易核准( 仅预留模式)

对于需要多步骤批准的流动:

```ts
// Create a transaction without auto-approving
const pendingTx = await wallet.send("0xRecipient", "usdc", "10", {
  prepareOnly: true,
});
console.log(pendingTx.transactionId);

// Approve later
const result = await wallet.approve({
  transactionId: pendingTx.transactionId,
});
```

## 签名类型

| 类型 | 使用大小写 | 平台 |
| --- | --- | --- |
| `device` | 硬件支持,没有检察官办公室. **浏览器和只反应本地** ——Node.js没有. | 浏览器, 反应原生 |
| `server` | 服务器侧自动操作(AI代理,后端). | 节点.js |
| `email` | 检察官办公室的回收方法. | 全体 |
| `phone` | 检察官办公室的回收方法. | 全体 |
| `passkey` | 在EVM,索拉纳和斯泰拉尔的WebAuthn/FIDO2生物鉴别标志. 在索拉纳岛,它可以是一种标志,但不能是一种恢复方法. | 浏览器, React 本地(设置 `passkeys` 打开道具 `CrossmintWalletProvider`(中文(简体) ) |
| `external-wallet` | 带上你的钥匙(MetaMask、KMS等). | 全体 |

## 反应/ 反应原生

对于反应应用程序, 使用 [`@crossmint/client-sdk-react-ui`](https://www.npmjs.com/package/@crossmint/client-sdk-react-ui) 提供钱包提供者、 钩子( t)`useWallet`, (中文(简体) ), `useWalletOtpSigner`用于检察官办公室和密码流通的内置UI.

原始反应,见 [`@crossmint/client-sdk-react-native-ui`](https://www.npmjs.com/package/@crossmint/client-sdk-react-native-ui)。 。 。 .

## 文档

-   [交叉薄荷钱包文档](https://docs.crossmint.com/)
-   [SDK 参考](https://docs.crossmint.com/sdk-reference/wallets)

## 许可证

阿帕奇 - 2.0

## 常见问题

### @crossmint/wallets-sdk 是什么？

用于创建和管理的打字机 SDK 十字薄荷钱包 在EVM,索拉纳,和斯特拉勒链\.

### 如何安装 @crossmint/wallets-sdk？

在项目目录运行 npm install @crossmint/wallets-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@solana/web3\.js（^1\.98\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @crossmint/wallets-sdk 支持 TypeScript 吗？

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

### @crossmint/wallets-sdk 支持 ESM 还是 CommonJS？

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

### @crossmint/wallets-sdk 可以商用吗？

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

### @crossmint/wallets-sdk 的下载量有多少？

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

### @crossmint/wallets-sdk 还在维护吗？

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