@tatumio / wallet-sdk

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

安装

npm install @tatumio/wallet-sdk

使用

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 的完整指南和完整的API参考。

托管和客户端操作

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

// 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密钥或客户端会话令牌：

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上下文：

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 })

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

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

备份和恢复

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

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：

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)使用客户端令牌和需求 否 泰特姆关键。

开发

npm install
npm test
npm run typecheck
npm run build