nansen-ai/nansen-wallet-manager

Wallet

Auth Setup

# Save API key (non-interactive)
nansen login --api-key <key>
# Or via env var:
NANSEN_API_KEY=<key> nansen login

# Verify
nansen research profiler labels --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --chain ethereum

Wallet Providers

The CLI supports two wallet providers:

| | Local (default) | Privy (server-side) | |---|---|---| | Key storage | Encrypted on disk | Server-side via Privy API | | Password required | Yes (min 12 chars) | No | | Export private keys | Yes (wallet export) | No — keys are managed by Privy | | Best for | Human users, manual trading | Agents, automated workflows | | Flag | --provider local (default) | --provider privy | | Required env vars | NANSEN_WALLET_PASSWORD | PRIVY_APP_ID + PRIVY_APP_SECRET |

Privy Wallet Creation

Privy wallets are server-side wallets managed by the Privy API. No password is needed — keys never touch the local machine.

Prerequisites

The following environment variables must be set:

| Var | Purpose | |-----|---------| | PRIVY_APP_ID | Privy application ID | | PRIVY_APP_SECRET | Privy application secret |

Create a Privy wallet

nansen wallet create --provider privy
# Or with a custom name:
nansen wallet create --name agent-wallet --provider privy

Critical rules for agents (Privy)

• No password needed — Privy manages keys server-side
• Cannot export keys — wallet export only works for local wallets
• All other operations (list, show, send, delete, default) work identically for both providers

Local Wallet Creation (Two-Step Agent Flow)

This section covers local wallet creation. For Privy server-side wallets, see the Privy Wallet Creation section above — no password is needed.

Wallet creation requires a password from the human user. The agent must NOT generate or store the password itself.

Step 1 (Agent → Human): Ask the user to provide a wallet password (minimum 12 characters).

Step 2 (Agent executes): Run the create command with the password the user gave you.

NANSEN_WALLET_PASSWORD="<password_from_user>" nansen wallet create

After creation, the CLI automatically saves the password:

• OS keychain (macOS Keychain, Linux secret-tool, Windows Credential Manager) — secure, preferred
• ~/.nansen/wallets/.credentials file — insecure fallback when no keychain is available (e.g. containers, CI)

All future wallet operations retrieve the password automatically — no env var or human input needed.

If the .credentials file fallback is used, the CLI prints a warning on every operation. To migrate to secure storage later, run nansen wallet secure.

Password resolution order (automatic)

1. NANSEN_WALLET_PASSWORD env var (if set)
2. OS keychain (saved automatically on wallet create)
3. ~/.nansen/wallets/.credentials file (insecure fallback, with warning)
4. Structured JSON error with instructions (if none available)

Critical rules for agents

• NEVER generate a password yourself — always ask the human user
• NEVER store the password in files, memory, logs, or conversation history
• NEVER use --human flag — that enables interactive prompts which agents cannot handle
• After wallet creation, you do NOT need the password for future operations — the keychain handles it
• If you get a PASSWORD_REQUIRED error, ask the user to provide their password again

Create

Privy (server-side, no password)

nansen wallet create --provider privy
# Or with a custom name:
nansen wallet create --name trading --provider privy

Requires PRIVY_APP_ID + PRIVY_APP_SECRET env vars. No password needed.

Local (encrypted on disk, password required)

# Ask the user for a password first, then:
NANSEN_WALLET_PASSWORD="<password_from_user>" nansen wallet create
# Or with a custom name:
NANSEN_WALLET_PASSWORD="<password_from_user>" nansen wallet create --name trading

List & Show

nansen wallet list
nansen wallet show <name>
nansen wallet default <name>

Send

# Send native token (SOL, ETH) — password auto-resolved from keychain
nansen wallet send --to <addr> --amount 1.5 --chain solana

# Send entire balance
nansen wallet send --to <addr> --chain evm --max

# Dry run (preview, no broadcast)
nansen wallet send --to <addr> --amount 1.0 --chain evm --dry-run

Export & Delete

# Password auto-resolved from keychain
nansen wallet export <name>
nansen wallet delete <name>

Forget Password

# Remove saved password from all stores (keychain + .credentials file)
nansen wallet forget-password

Migrate to Secure Storage

nansen wallet secure

For detailed migration steps (from ~/.nansen/.env, .credentials, or env-var-only setups), see the nansen-wallet-migration skill.

Flags

| Flag | Purpose | |------|---------| | --to | Recipient address | | --amount | Amount to send | | --chain | evm or solana | | --max | Send entire balance | | --dry-run | Preview without broadcasting | | --provider | Wallet provider: local (default, encrypted on disk) or privy (server-side via Privy API) | | --human | Enable interactive prompts (human terminal use only — agents must NOT use this) | | --unsafe-no-password | Skip encryption (keys stored in plaintext — NOT recommended) |

Environment Variables

| Var | Purpose | |-----|---------| | NANSEN_WALLET_PASSWORD | Wallet encryption password — only needed for initial wallet create. After that, the OS keychain handles it. | | NANSEN_API_KEY | API key (also set via nansen login --api-key <key>) | | PRIVY_APP_ID | Privy application ID (required for --provider privy) | | PRIVY_APP_SECRET | Privy application secret (required for --provider privy) | | NANSEN_WALLET_PROVIDER | Default provider for wallet create — local or privy | | NANSEN_EVM_RPC | Custom EVM RPC endpoint | | NANSEN_SOLANA_RPC | Custom Solana RPC endpoint |