Wallet

Auth Setup

# Save API key interactively
nansen login --human
# Or use NANSEN_API_KEY after provisioning it through your environment/secret manager
nansen login

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

Wallet Providers

The CLI supports two wallet providers:

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:

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](#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. NANSENWALLETPASSWORD 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 PRIVYAPPID + PRIVYAPPSECRET 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

Environment Variables