Wallets Server Quickstart

Docs | See all quickstarts

Introduction

Headless TypeScript scripts demonstrating Crossmint wallets with server signers via @crossmint/wallets-sdk. No browser, no React — just Node.js.

This quickstart uses the V1 SDK's two-tier signer architecture with server signers for both recovery and operational signing, ideal for backend services and AI agents.

Learn how to:

• Create a wallet with server recovery + server operational signer
• View balances and fund with staging tokens
• Transfer tokens to a recipient
• View transfer activity history
• List, add, and manage signers
• Prepare-only transactions and approve them separately
• Run the complete wallet lifecycle in one script

SDK Version

• @crossmint/wallets-sdk: 1.0.7

Setup

1. Clone the repository:

git clone https://github.com/crossmint/wallets-server-quickstart.git && cd wallets-server-quickstart

2. Install dependencies:

pnpm install

3. Set up environment variables:

cp .env.template .env

4. Fill in your .env:

Variable	Required	Notes
CROSSMINT_SERVER_API_KEY	Yes	Server-side API key (sk_...). Get one here. Scopes: wallets.read, wallets.create, wallets:transactions.create, wallets:transactions.sign, wallets:balance.read, wallets.fund.
RECOVERY_SIGNER_SECRET	Yes	Secret for the recovery signer. Get one using our generation tool here
WALLET_SIGNER_SECRET	Yes	Secret for the wallet (operational) signer. Get one using our generation tool here
CHAIN	No	Default: base-sepolia
WALLET_ADDRESS	Individual scripts only	Set after running create-wallet. Not needed for full-flow.

Running

Full Flow (recommended)

Run the complete wallet lifecycle in one execution:

pnpm full-flow

This creates a wallet, lists signers, funds it, checks balances, transfers tokens, loads activity, tests prepare-only + approve, and verifies wallet retrieval.

Individual Scripts

For targeted testing, run individual scripts. Most require WALLET_ADDRESS to be set in .env (run create-wallet first).

pnpm create-wallet                                    # Create a new wallet
pnpm get-wallet                                       # Retrieve existing wallet
pnpm wallet-info                                      # Show wallet details + signers
pnpm balance                                          # Check balances
pnpm balance --fund                                   # Fund with staging tokens first
pnpm transfer <recipient> [token] [amount]            # Send tokens
pnpm activity                                         # View transfer history
pnpm signers                                          # List registered signers
pnpm signers add-server <secret>                      # Add a server signer
pnpm signers use <locator>                            # Switch active signer
pnpm signers check-recovery                           # Check if recovery is needed
pnpm approval prepare <recipient> [token] [amount]    # Prepare unsigned transaction
pnpm approval approve-tx <transactionId>              # Approve a transaction
pnpm approval approve-sig <signatureId>               # Approve a signature

Snippet Map

#	File	Purpose
00	00-config.ts	Shared SDK init, env var loading, getExistingWallet() helper
01	01-create-wallet.ts	Create wallet with server recovery + server operational signer
02	02-get-wallet.ts	Retrieve existing wallet by address
03	03-wallet-display.ts	Show wallet details and registered signers
04	04-balance.ts	Check balances, optionally fund with --fund
05	05-transfer.ts	Send tokens to a recipient
06	06-activity.ts	View successful transfer history
07	07-signers.ts	List/add/use signers, check recovery
08	08-approval.ts	Prepare-only transactions and approve them
09	09-full-flow.ts	Complete lifecycle in one execution

Architecture

This quickstart uses server signers — deterministic key pairs derived from a secret string, managed entirely server-side. The V1 SDK's two-tier signer model provides:

• Recovery signer (RECOVERY_SIGNER_SECRET): High-security signer for wallet recovery
• Operational signer (WALLET_SIGNER_SECRET): Day-to-day transaction signing

Both signers are server-type, meaning no browser or user interaction is required. This makes it ideal for:

• Backend services and APIs
• AI agents that need to manage wallets programmatically
• Automated payment flows
• Testing and development scripts

Using in production

1. Create a production API key.
2. Use strong, unique secrets for RECOVERY_SIGNER_SECRET and WALLET_SIGNER_SECRET.
3. Store secrets securely (e.g., environment variables, secrets manager).