# @tatumio/wallet-sdk 中文文档

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

版本：0\.7\.1
npm 元数据更新时间：2026-11-02T14:56:23.183Z
中文译文更新时间：2026-11-02T15:34:23.643Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40tatumio/wallet-sdk
原文对照：https://npmcn.com/package/%40tatumio/wallet-sdk/?lang=original
项目主页：https://tatum.io/
源码仓库：https://github.com/tatumio/wallet-sdk

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

- 包体积（解压后）：187 kB，111 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：2 个
- 首次发布：2026-06-03T15:44:00.935Z
- 最新版本发布：2026-11-02T14:56:22.745Z
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

用于tatum托管的MPC钱包的TypeScript SDK——钱包生成、签名、发送、备份/恢复以及托管/客户端管理。

## 安装

```sh
npm install @tatumio/wallet-sdk
```

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

## README

# @tatumio / wallet-sdk

用于Tatum MPC钱包的TypeScript SDK——钱包创建、签名、发送、备份/恢复、托管/客户端管理。

## 安装

```sh
npm install @tatumio/wallet-sdk
```

## 使用

```ts
import { TatumWalletsSdk } from "@tatumio/wallet-sdk";

// Backend: pass your Tatum API key to use custodian operations.
const wallets = new TatumWalletsSdk({
  apiKey: process.env.TATUM_API_KEY!,
  baseUrl: "https://api.tatum.io",
});

// Client-side (browser/mobile): no apiKey — authenticate with a client token only.
const clientSide = new TatumWalletsSdk();
const client = clientSide.initClient({ token: clientSessionToken });
```

这个 `apiKey` 是 **只需要为保管人/ `sdk.api` 操作** (后端)。Client-scoped 操作(`initClient`)使用客户端令牌进行身份验证，并且不需要Tatum密钥，因此 SDK在客户端运行是安全的。对于较低级或尚未建模的Tatum调用，使用 `wallets.api.request(...)` 直接。

看到 [文档/ USAGE.md](https://npmcn.com/package/%40tatumio/wallet-sdk/docs/USAGE.md) 的完整指南和完整的API参考。

## 托管和客户端操作

托管范围内的调用通过您的Tatum API密钥进行身份验证：

```ts
// Response is typed as CreateClientResponse ({ id, clientApiKey, clientSessionToken, ... }).
const newClient = await wallets.custodian.createClient({
  body: {
    isAccountAbstracted: false,
  },
});

const clients = await wallets.custodian.listClients({
  query: {
    take: 100,
  },
});

// Mint a Client Session Token (CST) for an existing client.
const session = await wallets.custodian.createClientSession({
  path: { clientId: newClient.id! },
  body: { isAccountAbstracted: false },
});
```

客户端范围的调用使用所选客户端的客户端API密钥或客户端会话令牌：

```ts
import { WalletChain } from "@tatumio/wallet-sdk";

const client = wallets.initClient({
  token: newClient.clientApiKey ?? session.clientSessionToken!,
});

const details = await client.getClientDetails(); // typed as ClientDetails
const shares = await client.generateWallet(); // typed as GenerateWalletResponse

await client.sendAssets({
  body: {
    share: shares.SECP256K1.share,
    chain: WalletChain.ETHEREUM_MAINNET,
    to: "0x...",
    token: "NATIVE",
    amount: "0.01",
    rpcUrl: "https://ethereum-mainnet.gateway.tatum.io/<your-key>", // required — see RPC URL below
  },
});
```

链域(`chain` / `chainId` on sign, sendAssets， evaluate等 `{chain}` 路径（构建-事务） `WalletChain` 枚举而不是原始字符串。每个值是链的cip -2 id，和 `WALLET_CHAINS[chain]` / `getWalletChainConfig(chain)` 公开其 `curve` 和 `requiresRpcUrl`． 主链：Monad， Ethereum, Solana, Stellar, Tron, Bitcoin, Arbitrum, Arbitrum Nova, Avalanche, Base, Optimism, Polygon, Celo， BSC, Gnosis, Fantom, Rootstock, zkSync, Chiliz, Cronos, Ronin, Lisk, Litecoin（全部） `_MAINNET`)，再加上测试网 `ETHEREUM_SEPOLIA`， `SOLANA_DEVNET`， `STELLAR_TESTNET`， `BITCOIN_TESTNET`， `ARBITRUM_SEPOLIA`， `BASE_SEPOLIA`， `OPTIMISM_SEPOLIA`， `POLYGON_AMOY`， `BSC_TESTNET`， `MONAD_TESTNET`， `AVALANCHE_FUJI`， `GNOSIS_CHIADO`， `ROOTSTOCK_TESTNET`， `ZKSYNC_SEPOLIA`， `CHILIZ_TESTNET`， `TRON_NILE`, `TRON_SHASTA`． 看到 `docs/USAGE.md` 全桌的。

### 签署

`sign` 接受任何支持的RPC签名方法(`eth_sendTransaction`， `personal_sign`， `sol_signTransaction`）。 `rawSign` 直接用给定的曲线签署十六进制摘要，没有链/RPC上下文：

```ts
const signed = await client.sign({
  body: {
    share: shares.SECP256K1.share,
    method: "personal_sign",
    params: ["0x48656c6c6f"],
    chainId: WalletChain.ETHEREUM_MAINNET,
    to: "0x...",
    rpcUrl: "https://ethereum-mainnet.gateway.tatum.io/<your-key>", // required
  },
});

const raw = await client.rawSign({
  path: { curve: "SECP256K1" },
  body: { params: "7369676e2074686973", share: shares.SECP256K1.share },
}); // typed as RawSignResponse ({ data })
```

在签名之前，您可以模拟/验证事务（余额更改，风险评分）：

```ts
const evaluation = await client.evaluateTransaction({
  query: { chainId: WalletChain.ETHEREUM_MAINNET },
  body: { to: "0x...", value: "0x2386f26fc10000", operationType: "all" },
}); // typed as EvaluateTransactionResponse ({ chain, validation?, simulation? })
```

### 备份和恢复

备份签名共享，自己加密每个曲线共享，通过SDK存储密文，然后标记存储对：

```ts
const backup = await client.backupWallet({
  body: { generateResponse: JSON.stringify(shares) },
}); // typed as BackupWalletResponse (per-curve shares)

for (const curve of ["SECP256K1", "ED25519"] as const) {
  const { id, share } = backup[curve];
  await client.storeEncryptedBackupShare({
    path: { backupSharePairId: id },
    body: { clientCipherText: await yourEncrypt(share) },
  });
}

await client.updateBackupSharePairs({
  body: {
    backupSharePairIds: [backup.SECP256K1.id, backup.ED25519.id],
    status: "STORED_CLIENT_BACKUP_SHARE",
  },
});
```

恢复，获取和解密每条曲线存储的密文，重建备份 响应形状(`{ SECP256K1: { share, id }, ED25519: { share, id } }`)，然后通过 它 `recoverWallet`：

```ts
const restore = async (
  curve: "SECP256K1" | "ED25519",
  backupSharePairId: string,
) => {
  const { cipherText } = await client.getBackupShareCipherText({
    path: { backupSharePairId },
  });
  return { share: await yourDecrypt(cipherText), id: backupSharePairId };
};

const backupResponse = {
  SECP256K1: await restore("SECP256K1", secpBackupSharePairId),
  ED25519: await restore("ED25519", edBackupSharePairId),
};

const recovered = await client.recoverWallet({
  body: { backupResponse: JSON.stringify(backupResponse) },
}); // typed as RecoverWalletResponse
```

### RPC的URL

触及链的飞地操作(`sign`， `sendAssets`） **需要一个明确的 `rpcUrl`** 在 身体

**特隆例外:** Tron事务通过gRPC广播，因此HTTP(S) RPC url(包括 不支持Tatum网关。为 `tron:mainnet`， `tron:nile`, `tron:shasta` SDK总是 路线 `sign`/`sendAssets` 通过被管理的Tron网关，忽略 `rpcUrl` 你通过。

身份验证说明：托管范围的调用使用您的Tatum `x-api-key`． Client-scoped调用 （`initClient`)使用客户端令牌和需求 **否** 泰特姆关键。

## 开发

```sh
npm install
npm test
npm run typecheck
npm run build
```

## 常见问题

### @tatumio/wallet-sdk 是什么？

用于tatum托管的MPC钱包的TypeScript SDK——钱包生成、签名、发送、备份/恢复以及托管/客户端管理。

### 如何安装 @tatumio/wallet-sdk？

在项目目录运行 npm install @tatumio/wallet-sdk，或使用 pnpm add / yarn add / bun add。

### @tatumio/wallet-sdk 支持 TypeScript 吗？

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

### @tatumio/wallet-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @tatumio/wallet-sdk 需要什么版本的 Node\.js？

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

### @tatumio/wallet-sdk 可以商用吗？

@tatumio/wallet-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @tatumio/wallet-sdk 还在维护吗？

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