/nansen-wallet-manager

name: nansen-wallet-manager
description: Wallet management — create (local or Privy server-side), list, show, export, send, delete. Use when creating wallets, checking balances, or sending tokens.
metadata:
  openclaw:
    requires:
      bins:
        - nansen
    primaryEnv: NANSEN_API_KEY
    install:
      - kind: node
        package: nansen-cli
        bins: [nansen]
allowed-tools: Bash(nansen:*)

Authentication

Nansen account API calls accept a selected `nansen:api` browser session or conventional API key with the same permissions. `NANSEN_API_KEY` takes precedence; optional `primaryEnv` preserves configured-key injection. Run `nansen auth status` for offline selection. Cached access expiry alone permits automatic renewal during an authorized task. Stop on anonymous selection, invalid state, blocked/uncertain renewal or actual auth failure; never drop a credential or fall back to anonymous x402 payment. Browser login does not grant wallet signing, privileged service identity or a persistent MCP integration key. Preserve all confirmation, signing, sanctions and geographic checks below. Browser login is available in CLI 2.0.0 within the [macOS arm64 preview scope](https://github.com/nansen-ai/nansen-cli/blob/main/docs/browser-login.md#preview-platform-scope).

Wallet

Auth Setup

Use a selected nansen:api browser session or conventional API key for Nansen account API calls. Agents should inject `NANSEN_API_KEY` through their environment or secret manager and use commands directly; no login is needed to persist it. Human terminal users can use explicit `nansen login --human` for legacy key setup. With an already injected environment key, that explicit mode saves it without prompting and requires the native auth lock binding.

# Free live check of the effective API credential
nansen account

Plain `nansen login` instead requests fresh browser approval. It does not save an environment key or grant wallet signing/RPC authority. Wallet custody and provider credentials below remain separate.

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](#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 keychai