oxfrancesco/crossmint-wallets

Crossmint Wallet Management

Create programmable wallets for users, AI agents, and treasury operations using the Crossmint API.

Setup

Requires API key in Doppler. The scripts will check for WALLET_API_KEY first (from your Doppler mao-mao/prd config), then fall back to CROSSMINT_API_KEY.

Get your API key from Crossmint Console and add it to Doppler:

doppler secrets set WALLET_API_KEY sk_staging_... --project mao-mao --config prd

Scripts

All scripts use Bun runtime. Each script asks for confirmation before executing API calls. Use -y or --yes to skip confirmation (for automation).

1. Create Wallet

Create a new smart wallet for an agent or user.

# Using Doppler (recommended - picks up WALLET_API_KEY automatically)
doppler run --project mao-mao --config prd --command 'bun scripts/create-wallet.ts'

# Create wallet with custom user ID
doppler run --project mao-mao --config prd --command 'bun scripts/create-wallet.ts --userId AGENT01'

# Create non-custodial wallet (for production)
doppler run --project mao-mao --config prd --command 'bun scripts/create-wallet.ts --signer evm-passkey-signer'

# Specify chain
doppler run --project mao-mao --config prd --command 'bun scripts/create-wallet.ts --chain base-sepolia'

# Skip confirmation prompt (for automation)
doppler run --project mao-mao --config prd --command 'bun scripts/create-wallet.ts --userId AGENT01 --yes'

2. Get Wallet

Retrieve wallet details by address or user ID.

doppler run --project mao-mao --config prd --command 'bun scripts/get-wallet.ts --address 0x1234...'
doppler run --project mao-mao --config prd --command 'bun scripts/get-wallet.ts --userId AGENT01'

3. Fund Wallet (Testnet)

Fund a testnet wallet with USDC for testing.

doppler run --project mao-mao --config prd --command 'bun scripts/fund-wallet.ts --address 0x1234... --amount 100'

4. Transfer Tokens

Transfer tokens from one wallet to another.

# Basic transfer (default: base-sepolia, USDC)
doppler run --project mao-mao --config prd --command 'bun scripts/transfer.ts --from 0x1234... --to 0x5678... --amount 10 --token usdc'

# ETH transfer on Sepolia (note: use "ethereum-sepolia" not "sepolia")
doppler run --project mao-mao --config prd --command 'bun scripts/transfer.ts --from 0x1234... --to 0x5678... --amount 0.01 --token eth --chain ethereum-sepolia --yes'

Important: Both wallets must be Crossmint-managed for transfers to work. Check with get-wallet.ts first.

Wallet Types

| Type | Description | Use Case | |------|-------------|----------| | evm-smart-wallet | EVM-compatible smart wallet | Agents, users on Base, Polygon, etc. | | solana-custodial-wallet | Solana custodial wallet | Solana-based agents |

Signer Types

| Signer | Custody | Use Case | |--------|---------|----------| | evm-fireblocks-custodial | Custodial | Development/testing | | evm-passkey-signer | Non-custodial | Production apps | | evm-keypair-signer | Non-custodial | Server-side agents |

Supported Chains

Important: Use full chain names in API calls, not short names:

| Common Name | API Chain Name | |-------------|----------------| | Sepolia | ethereum-sepolia | | Base Sepolia | base-sepolia | | Ethereum | ethereum | | Base | base | | Polygon | polygon |

Full list: EVM chains (ethereum, base, polygon, arbitrum, optimism, avalanche) + testnets (-sepolia suffix), plus solana and stellar.

Gotcha: --chain sepolia will fail. Use --chain ethereum-sepolia.

Environment Variables

The scripts automatically use your Doppler secrets. Configured in mao-mao/prd:

WALLET_API_KEY=sk_staging_...       # Your Crossmint API key (from Doppler)
CROSSMINT_ENV=staging               # "staging" or "www" for production (optional)

Note: Scripts check for WALLET_API_KEY first (Doppler), then CROSSMINT_API_KEY (fallback).

Testing

Run unit tests:

bun test

Run E2E test (requires CROSSMINT_API_KEY):

bun tests/e2e.test.ts

The E2E test will:

1. Create a wallet with a unique test user ID
2. Retrieve the wallet by address
3. Retrieve the wallet by user ID
4. Fund the wallet with testnet USDC
5. Create a second wallet
6. Transfer tokens between wallets

API Reference

• Create Wallet
• Get Wallet
• Fund Wallet
• Create Transaction

Example: Agent Wallet Flow

// 1. Create wallet for agent
const wallet = await createWallet({ userId: 'AGENT_001' });

// 2. Fund wallet (testnet)
await fundWallet(wallet.address, 100);

// 3. Agent can now make purchases via Orders API

Quick Reference: Common Workflows

Check if a wallet is Crossmint-managed

doppler run --project mao-mao --config prd --command 'bun scripts/get-wallet.ts --address 0xYOURADDRESS --yes'

If it returns wallet details (Type, User, Created), it's Crossmint-managed. If error, it's external.

Transfer ETH on Sepolia (working example)

doppler run --project mao-mao --config prd --command 'bun scripts/transfer.ts \
  --from 0xc54f836CBb4299B828b696Ef56f42edd898b3486 \
  --to 0x289155723B5d8F685D49446b2d9a4F7Bfa7606E3 \
  --amount 0.01 \
  --token eth \
  --chain ethereum-sepolia \
  --yes'

Known Wallets

| Address | Owner | Chain | Notes | |---------|-------|-------|-------| | 0xc54f836CBb4299B828b696Ef56f42edd898b3486 | userId:francesco | ethereum-sepolia | Francesco's main testnet wallet | | 0x289155723B5d8F685D49446b2d9a4F7Bfa7606E3 | - | ethereum-sepolia | Created 2026-01-31 | | 0xf422bF82C48925edcb134f2a2927B8C9826A4723 | - | base-sepolia | Created 2026-01-31 |