Smart Wallets for Banks

Use Tatum Smart Wallets to give banking customers blockchain accounts that your platform can create, sign from, recover, and operate through a typed TypeScript SDK.

Tatum Smart Wallets are designed for applications where one organization manages wallet access for many end users. For a bank, that means you can build wallet flows for retail, private banking, treasury, institutional, or embedded finance customers while keeping wallet creation, transaction signing, backup, and recovery behind controlled application workflows.

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.

triangle-exclamation

Verify the @tatumio/wallet-sdk package version from your approved package registry before using it in a production banking environment.

What a bank wallet product should include

A bank-grade smart wallet product should include more than wallet creation. Design the product around customer onboarding, transaction approval, secure recovery, operational controls, and auditability.

Common banking use cases

Create customer wallets inside an existing mobile or web banking app. Customers can hold, receive, and send supported assets while the bank controls onboarding, customer authentication, transaction limits, and support workflows.

Business and treasury wallets

Create wallets for businesses that need controlled blockchain payments. Your application can route transactions through internal approval flows before calling the SDK to sign or send assets.

Embedded wallets for fintech products

Provide wallet infrastructure to partners or fintech programs without asking end users to install a separate wallet app. Your platform can create a client for each partner user and expose wallet actions through your own UI.

Recovery-focused custody workflows

Build wallet recovery into your customer support and operations model. The SDK includes backup and recovery capabilities, but your implementation must define how encrypted backup shares are stored, accessed, and approved for recovery.

How the SDK model works

Tatum Smart Wallets use a custodian and client model:

1. Custodian: your bank or platform operator. The custodian creates wallet clients and manages client sessions.
2. Client: an end customer, business account, or application user. 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 a bank-controlled wallet architecture.

flowchart LR
A[Banking app] --> B[Identity and approval layer]
B --> C[Wallet orchestration service]
C --> D[Tatum Smart Wallet SDK]
D --> E[Customer wallet]
C --> F[Encrypted backup storage]
C --> G[Audit and monitoring]

The banking app collects the customer’s intent, while your identity and approval layer decides whether the action can continue. Your backend wallet orchestration service then calls the Tatum Smart Wallet SDK, stores encrypted backup material, and records wallet activity for audit and monitoring.

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 banking wallet product with Tatum Smart Wallets.

1. Create a wallet client for the bank customer.
2. Initialize the client session with the client API key or session token.
3. Generate the customer wallet with the client-scoped SDK.
4. Encrypt and store backup shares according to your bank’s key-management policy.
5. Run bank controls before each transaction, such as customer authentication, transaction limits, approvals, and fraud checks.
6. Sign or send assets only after your controls approve the request.
7. Monitor and support recovery through your bank’s operational workflow.

Example: create a client 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 createWalletAndSendAssets() {
  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;
  }
}

createWalletAndSendAssets();

The exact response depends on the chain and transaction type. In production, store the returned transaction identifier, link it to the customer action, and monitor it through your transaction-status workflow.

Security responsibilities for banks

Tatum Smart Wallets provide wallet and signing workflows, but your bank 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 customer authentication before transaction approval, wallet recovery, or key-eject workflows.
4. Apply policy checks before signing, including limits, velocity rules, destination screening, and internal approvals.
5. Log wallet operations with customer ID, wallet ID, request ID, approver ID, timestamp, chain, asset, amount, and transaction result.
6. Separate duties between support, operations, compliance, and engineering teams for recovery and exception handling.

shield-halved

Treat signing shares, backup shares, API keys, client API keys, and session tokens as sensitive secrets. Never print them to logs or return them to untrusted clients.

Recommended architecture

Use a backend-controlled architecture for bank deployments:

1. Banking app: collects customer intent, shows balances, and starts wallet actions.
2. Identity and approval layer: authenticates the customer and applies bank approval rules.
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. Audit and monitoring: records every wallet operation and transaction decision.

This architecture keeps wallet operations behind your bank’s authentication, authorization, fraud, and compliance systems.