tatumio-wallets-sdk

TypeScript SDK for Tatum-hosted Portal wallets — MPC wallet creation, signing, sending, backup/recovery, and custodian/client management.

Installation

npm install tatumio-wallets-sdk

Usage

import { TatumWalletsSdk } from "tatumio-wallets-sdk";

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

All Portal methods accept the same options shape:

{
  path?: Record<string, string | number | boolean>;
  query?: Record<string, string | number | boolean | null | undefined | Array<string | number | boolean>>;
  body?: unknown;
  headers?: Record<string, string>;
  signal?: AbortSignal;
}

For lower-level or not-yet-modeled Tatum calls, use wallets.api.request(...) directly.

Portal Custodian and Client Operations

Portal partner functionality is exposed as part of the Tatum Wallets SDK. Custodian-scoped Portal calls are authenticated through Tatum:

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

const portalClients = 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: portalClient.id! },
  body: { isAccountAbstracted: false },
});

Client-scoped calls use the Portal client API key or client session token for the selected client:

import { WalletChain } from "tatumio-wallets-sdk";

const client = wallets.initClient({
  token: portalClient.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",
  },
});

Portal chain fields (chain / chainId on sign, sendAssets, evaluate, and the {chain} path on build-transaction) take the WalletChain enum rather than raw strings. Each value is the chain's Portal CAIP-2 id, and PORTAL_CHAINS[chain] / getPortalChainConfig(chain) expose its curve and requiresRpcUrl. Primary chains: Monad, Ethereum, Solana, Stellar, Tron, Bitcoin, Arbitrum, Avalanche, Base, Optimism, Polygon, Celo (all _MAINNET), plus ETHEREUM_SEPOLIA (testnet).

Signing

sign accepts any Portal RPC method (eth_sendTransaction, personal_sign, sol_signTransaction). rawSign signs a hex digest directly with a given curve, with no chain/RPC context:

const signed = await client.sign({
  body: {
    share: shares.SECP256K1.share,
    method: "personal_sign",
    params: ["0x48656c6c6f"],
    chainId: WalletChain.ETHEREUM_MAINNET,
    to: "0x...",
  },
});

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

Before signing, you can simulate/validate a transaction (balance changes, risk score):

const evaluation = await client.evaluateTransaction({
  query: { chainId: WalletChain.ETHEREUM_MAINNET },
  body: {
    network: "ethereum",
    transaction: { toAddress: "0x...", value: "10000000000000000" },
  },
}); // typed as EvaluateTransactionResponse

Backup and recovery (Portal-Managed)

Back up the signing shares, encrypt each curve's share yourself, store the ciphertext with Portal, then mark the pairs stored:

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",
  },
});

To recover, fetch and decrypt each curve's stored ciphertext, rebuild the backup response shape ({ SECP256K1: { share, id }, ED25519: { share, id } }), then pass it to 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

Custodian-scoped Portal calls are authenticated through Tatum: the SDK resolves the Portal custodian token from your Tatum x-api-key via GET /v4/wallets/custodian-api-key (throwing if your key isn't authorized for Portal). Enclave operations that need an RPC URL get one automatically — the SDK builds https://<network>.gateway.tatum.io/<your-api-key> from the chain's tatumRpcNetwork (see PORTAL_CHAINS) — unless you pass an explicit rpcUrl in the body.

Development

npm install
npm test
npm run typecheck
npm run build

Publishing

The package is configured for public npm publishing under the scoped package name:

npm publish --access public