Installation & Quick Start

Get started with the Tatum Wallet SDK. Create MPC wallets, securely manage signing shares, and send transactions across supported blockchains.

Installation

npm install @tatumio/wallet-sdk

Requirements

Node.js 18 or higher
A Tatum API key

Get API key For free. No commitment.

Don't have an API key?

Initialise the SDK

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

const wallets = new TatumWalletsSdk({
  apiKey: process.env.TATUM_API_KEY!,
});

The baseUrl defaults to https://api.tatum.io. You can override it for staging:

const wallets = new TatumWalletsSdk({
  apiKey: process.env.TATUM_API_KEY!,
  baseUrl: "https://api.tatum.io",
});

Quick Start

1. Create a Client

Each end user maps to a Portal client. Create one when a user signs up:

const newClient = await wallets.custodian.createClient({
  body: { isAccountAbstracted: true },
});

// Store newClient.id and newClient.clientApiKey in your database
console.log(newClient.id);          // "cli_..."
console.log(newClient.clientApiKey); // permanent key for this client

2. Initialise a Client-Scoped API

Use the clientApiKey (permanent) or a short-lived clientSessionToken to scope operations to one client:

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

3. Generate a Wallet

const shares = await client.generateWallet();
// shares.SECP256K1 → EVM + Tron + Bitcoin
// shares.ED25519   → Solana + Stellar

Store these shares now. Encrypt them and persist them server-side or in your user's secure storage. They are never recoverable from Tatum.

4. Confirm Shares Stored

After storing, tell Portal the shares are safely held client-side:

const details = await client.getClientDetails();
const signingSharePairIds = details.wallets!.flatMap(w =>
  (w.signingSharePairs ?? []).map(sp => sp.id!)
);

await client.updateSigningSharePairs({
  body: {
    signingSharePairIds,
    status: "STORED_CLIENT",
  },
});

5. Send Your First Transaction

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

const result = await client.sendAssets({
  body: {
    share: shares.SECP256K1.share,   // the share you stored in step 3
    chain: WalletChain.ETHEREUM_MAINNET,
    to: "0xRecipientAddress",
    token: "NATIVE",                  // "NATIVE" for ETH, or ERC-20 contract address
    amount: "0.01",                   // human-readable amount
  },
});

console.log(result.transactionHash); // "0x..."

Full End-to-End Example

import { TatumWalletsSdk, WalletChain } from "@tatumio/wallet-sdk";

const wallets = new TatumWalletsSdk({ apiKey: process.env.TATUM_API_KEY! });

// 1. Create client
const newClient = await wallets.custodian.createClient({
  body: { isAccountAbstracted: false },
});

// 2. Scope to this client
const client = wallets.initClient({ token: newClient.clientApiKey! });

// 3. Generate wallet — STORE THE SHARES
const shares = await client.generateWallet();
await db.saveShares(newClient.id!, {
  secp256k1: encrypt(shares.SECP256K1.share),
  ed25519: encrypt(shares.ED25519.share),
});

// 4. Confirm stored
const details = await client.getClientDetails();
const signingSharePairIds = details.wallets!.flatMap(w =>
  (w.signingSharePairs ?? []).map(sp => sp.id!)
);
await client.updateSigningSharePairs({
  body: { signingSharePairIds, status: "STORED_CLIENT" },
});

// 5. Send ETH
const tx = await client.sendAssets({
  body: {
    share: shares.SECP256K1.share,
    chain: WalletChain.ETHEREUM_MAINNET,
    to: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    token: "NATIVE",
    amount: "0.001",
  },
});

console.log("Sent:", tx.transactionHash);