Smart Wallets for Payments

Use Tatum Smart Wallets to build blockchain payment flows where your platform can create wallets, sign transactions, send assets, and support recovery through a typed TypeScript SDK.

Tatum Smart Wallets are designed for applications that manage wallet access for many users or businesses. For payments, that means you can create wallet-backed checkout, merchant payouts, treasury transfers, embedded payments, or customer-to-customer transfers while keeping signing, backup, and recovery behind controlled backend 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.

What a smart wallet payment product should include

A production payment product needs more than a wallet and a send button. Design the flow around payer intent, transaction approval, settlement tracking, retries, recovery, and auditability.

Common payment use cases

Wallet-backed checkout

Create a wallet for a customer or business and let them approve blockchain payments from your checkout experience. Your application collects payment intent, validates the payment request, and calls the SDK only after the payer confirms the transfer.

Merchant and marketplace payouts

Use smart wallets to send assets to merchants, sellers, creators, or service providers. Your payout service can approve transfers, batch operational tasks, and submit payments through client-scoped wallet operations.

Embedded payments

Add blockchain payments to an existing app without requiring users to install and manage an external wallet. Your platform can create wallet clients for users and expose payment actions through your own interface.

Treasury and internal transfers

Use controlled wallet flows for operational payments between internal accounts, business wallets, or treasury wallets. Your internal approval system should approve each transfer before the SDK signs or sends assets.

Recovery-focused payment account

Build recovery workflows for users or merchants who lose account access. The SDK supports backup and recovery capabilities, but your product must define how encrypted backup shares are stored, accessed, approved, and audited.

How the SDK model works

Tatum Smart Wallets use a custodian and client model:

1. Custodian: your payment platform or wallet operator. The custodian creates wallet clients and manages client sessions.
2. Client: a customer, merchant, 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 backend-controlled payment architecture.

flowchart LR
A[Checkout or payment app] --> B[Payment orchestration service]
B --> C[Identity and risk layer]
C --> D[Wallet orchestration service]
D --> E[Tatum Smart Wallet SDK]
E --> F[Payment wallet]
D --> G[Encrypted backup storage]
B --> H[Audit and settlement monitoring]

The checkout or payment app collects payer intent, while your payment orchestration service creates the payment record and coordinates approval state. Your wallet orchestration service calls the Tatum Smart Wallet SDK only after identity, risk, limit, and approval checks pass.

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 payments with Tatum Smart Wallets.

1. Create a wallet client for the payer, merchant, or internal payment account.
2. Initialize the client session with the client API key or session token.
3. Generate the wallet with the client-scoped SDK.
4. Encrypt and store backup shares according to your security policy.
5. Create a payment intent in your application before any blockchain signing happens.
6. Run payment controls such as authentication, balance checks, fraud checks, limits, and approvals.
7. Sign or send assets only after the payment is approved.
8. Store the transaction result and monitor the payment through settlement, failure, or retry handling.

Example: Create a payment 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 a payment orchestration 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 createWalletAndSubmitPayment() {
  try {
    const newClient = await wallets.custodian.createClient({
      body: {
        isAccountAbstracted: true,
      },
    });

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

    // Run your payment checks here before signing: payer authentication,
    // amount validation, limits, fraud screening, and approval status.
    const paymentApproved = true;

    if (!paymentApproved) {
      throw new Error(
        "Payment was rejected by the payment approval workflow."
      );
    }

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

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

createWalletAndSubmitPayment();

The exact response depends on the chain and payment type. In production, store the returned transaction identifier, link it to the payment record, and monitor the transaction until it reaches its final state.

Security responsibilities for payment platforms

Tatum Smart Wallets provide wallet and signing workflows, but your application remains responsible for payment authorization and operational security.

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 payer authentication before payment approval, wallet recovery, or key-eject workflows.
4. Apply payment checks before signing, including amount validation, velocity rules, destination screening, and approval status.
5. Log payment operations with payer ID, merchant ID, wallet ID, payment ID, request ID, timestamp, chain, asset, amount, destination, and transaction result.
6. Separate duties between support, operations, compliance, and engineering teams for recovery and exception handling.

Recommended architecture

Use a backend-controlled architecture for payment deployments:

1. Payment app or checkout UI: collects payer intent and displays payment status.
2. Payment orchestration service: creates payment records, validates amounts, and coordinates approval state.
3. Identity and risk layer: authenticates the payer and applies fraud, limit, and velocity controls.
4. Wallet orchestration service: calls @tatumio/wallet-sdk, manages client sessions, and coordinates wallet actions.
5. Key and backup storage: stores encrypted backup material according to your internal security model.
6. Audit and monitoring: records every wallet operation, payment decision, and transaction result.

This architecture keeps signing and wallet recovery behind your payment platform’s authentication, authorization, fraud, and monitoring systems.