Smart Wallets for Wallet App

Use Tatum Smart Wallets to give your app's users a real blockchain wallet the moment they sign up, without asking them to write down a seed phrase or install a separate app, while your backend keeps control over wallet creation, signing, backup, and recovery through a typed TypeScript SDK.

Tatum Smart Wallets are designed for applications where one organization manages wallet access for many end users. For a wallet app, that means you can give every user a multi-chain wallet inside your own product, whether you're building a self-custody style mobile wallet, a Bitcoin-only app, a multi-asset wallet, or a wallet feature embedded inside a broader consumer app.

SDK resources

• GitHub repository: tatumio/wallet-sdk
• NPM package page: @tatumio/wallet-sdk

The GitHub repository documents the package as @tatumio/wallet-sdk, a TypeScript SDK for Tatum MPC wallets. It supports wallet generation, signing, sending assets, backup and recovery, and custodian/client management.

What a wallet app product should include

A wallet app needs more than a "create wallet" button. Design the product around onboarding speed, everyday send and receive flows, device-level security, recovery the user can actually complete on their own, and visibility into what's happening with their funds.

Common wallet app use cases

Self-custody style mobile wallet

Give each user a wallet that feels self-custodial from the app, with biometric or PIN confirmation on every send, while your backend handles MPC wallet generation and signing-share coordination behind the scenes.

Bitcoin-only or single-chain wallet apps

Focus the entire onboarding and send and receive experience around one chain, using the SDK's chain support to keep the integration simple while leaving room to add chains later without redesigning the wallet layer.

Multi-asset consumer wallets

Let users hold, receive, and send several assets across multiple chains from one balance screen, using client-scoped operations per user to keep each wallet's activity isolated and auditable.

Embedded wallet inside a non-wallet app

Add a wallet feature to an app that isn't primarily a wallet, such as a rewards app, a social app, or a marketplace, by creating a wallet client per user in the background and only surfacing wallet actions when the user needs them.

Device-bound recovery flows

Build recovery around the device and identity checks your app already has, such as re-verifying a phone number or re-authenticating with biometrics, rather than relying on the user safeguarding a written seed phrase.

How the SDK model works

Tatum Smart Wallets use a custodian and client model:

1. Custodian: your wallet app's backend. The custodian creates wallet clients and manages client sessions, typically one client per app user.
2. Client: an end user of your app. The client performs wallet generation, signing, sending, backup, and recovery through client-scoped SDK calls.
3. Enclave operations: MPC-related actions, including wallet generation, backup, recovery, signing, raw signing, and sending assets.

The SDK entry point is TatumWalletsSdk. You initialize it with a Tatum API key, create or manage clients with wallets.custodian, and initialize client-scoped operations with wallets.initClient({ token }).

Architecture diagram

Use this minimal flow to place Tatum Smart Wallets inside an app-controlled wallet architecture.

flowchart LR
A[Mobile or web wallet app] --> B[Auth and device check layer]
B --> C[Wallet orchestration service]
C --> D[Tatum Smart Wallet SDK]
D --> E[User wallet]
C --> F[Encrypted backup storage]
C --> G[Activity feed and notifications]

The wallet app collects the user's intent to send, receive, or recover, while your auth and device check layer confirms the user is who they say they are. Your backend wallet orchestration service then calls the Tatum Smart Wallet SDK, stores encrypted backup material, and feeds confirmed activity back into the app's transaction history and notifications.

Prerequisites

1. Install Node.js 18 or later.

2. Create or retrieve your Tatum API key.

3. Install the SDK:

   Bash

   npm install @tatumio/wallet-sdk

4. Store your API key as an environment variable:

   Bash

   export TATUM_API_KEY="your-api-key"

Basic implementation flow

Follow this flow when building a wallet app with Tatum Smart Wallets.

1. Create a wallet client for the new user during signup.
2. Initialize the client session with the client API key or session token.
3. Generate the user's wallet with the client-scoped SDK.
4. Encrypt and store backup shares according to your app's key-management policy.
5. Run app-level checks before each transaction, such as device verification, PIN or biometric confirmation, and spending limits.
6. Sign or send assets only after your checks approve the request.
7. Update the user's activity feed and support recovery through your app's own support flow.

Example: create a user wallet and send assets

The following example shows the basic custodian-to-client flow from a backend service. Use it as a starting point for an internal service, not directly from a browser or mobile client.

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

const apiKey = process.env.TATUM_API_KEY;

if (!apiKey) {
  throw new Error("Set TATUM_API_KEY before running this script.");
}

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

async function createUserWalletAndSendAssets() {
  try {
    const newClient = await wallets.custodian.createClient({
      body: {
        isAccountAbstracted: false,
      },
    });

    if (!newClient.clientApiKey) {
      throw new Error(
        "Client was created, but no client API key was returned."
      );
    }

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

    const shares = await client.generateWallet();

    if (!shares.SECP256K1?.share) {
      throw new Error(
        "Wallet generation did not return a SECP256K1 signing share."
      );
    }

    const result = await client.sendAssets({
      body: {
        share: shares.SECP256K1.share,
        chain: WalletChain.ETHEREUM_MAINNET,
        to: "0x0000000000000000000000000000000000000000",
        token: "NATIVE",
        amount: "0.01",
      },
    });

    console.log("Transaction submitted:", result);
  } catch (error) {
    console.error("Wallet operation failed:", error);
    process.exitCode = 1;
  }
}

createUserWalletAndSendAssets();

The exact response depends on the chain and transaction type. In production, store the returned transaction identifier, link it to the user's activity feed, and monitor it through your transaction-status workflow.

Security responsibilities for wallet apps

Tatum Smart Wallets provide wallet and signing workflows, but your app remains responsible for the controls around those workflows.

Implement the following controls before production launch:

1. Protect API keys and client tokens in backend systems. Do not expose custodian credentials in browsers or mobile apps.
2. Encrypt backup shares before storage. The SDK supports backup-share workflows, but your application must encrypt backup shares before storing ciphertext.
3. Require strong user authentication before transaction approval, wallet recovery, or key-eject workflows, such as biometrics, PIN, or device-bound checks.
4. Apply policy checks before signing, including spending limits, velocity rules, destination screening, and step-up confirmation for large transfers.
5. Log wallet operations with user ID, wallet ID, request ID, device ID, timestamp, chain, asset, amount, and transaction result.
6. Separate duties between support, operations, and engineering teams for recovery and exception handling.

Recommended architecture

Use a backend-controlled architecture for wallet app deployments:

1. Wallet app: collects the user's intent, shows balances, and starts wallet actions.
2. Auth and device check layer: authenticates the user and verifies the device before sensitive actions.
3. Wallet orchestration service: calls @tatumio/wallet-sdk, manages client sessions, and coordinates wallet actions.
4. Key and backup storage: stores encrypted backup material according to your internal security model.
5. Activity feed and notifications: records every wallet operation and surfaces it back to the user in real time.

This architecture keeps wallet operations behind your app's own authentication, device security, and monitoring systems, while giving each user a wallet that feels native to your product.

Optional: Add DeFi API features

You can also use the DeFi API alongside Tatum Smart Wallets when your wallet app needs DeFi-related functionality. Place DeFi API calls behind the same wallet orchestration service, authentication checks, and activity logging you use for wallet creation, signing, backup, and recovery.

Use the DeFi API to add features such as:

• DeFi event monitoring: track on-chain DeFi activity such as swaps, liquidity changes, lending events, and staking actions.
• DeFi block data: retrieve historical DeFi blocks or the latest available DeFi block for protocol activity views.
• Time-based lookups: fetch DeFi block data for a specific timestamp when you need audit, compliance, or historical portfolio context.
• Swap quotes: get the best available swap rate or compare rates across supported protocols before showing a swap option in your wallet app.
• Analytics and dashboards: power in-app DeFi activity feeds, protocol dashboards, alerting, and monitoring tools.