Wallet
Auth Setup
nansen login --api-key <key>
NANSEN_API_KEY=<key> nansen login
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
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)
NANSEN_WALLET_PASSWORD env var (if set)- OS keychain (saved automatically on wallet create)
~/.nansen/wallets/.credentials file (insecure fallback, with warning)- 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
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)
NANSEN_WALLET_PASSWORD="<password_from_user>" nansen wallet create
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
nansen wallet send --to <addr> --amount 1.5 --chain solana
nansen wallet send --to <addr> --chain evm --max
nansen wallet send --to <addr> --amount 1.0 --chain evm --dry-run
Export & Delete
nansen wallet export <name>
nansen wallet delete <name>
Forget Password
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 |
