Wallet

Auth Setup

CODEBLOCK0

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

CODEBLOCK1

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.

CODEBLOCK2

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. 1. NANSEN_WALLET_PASSWORD env var (if set)
2. OS keychain (saved automatically on wallet create)
3. INLINECODE17 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)

CODEBLOCK3

Requires PRIVY_APP_ID + PRIVY_APP_SECRET env vars. No password needed.

Local (encrypted on disk, password required)

CODEBLOCK4

List & Show

CODEBLOCK5

Send

CODEBLOCK6

Export & Delete

CODEBLOCK7

Forget Password

CODEBLOCK8

Migrate to Secure Storage

CODEBLOCK9

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

Flags

Environment Variables