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 rollout acceptance is still pending.

Wallet Migration — Old Flow to Secure Keychain

Use this skill when a user already has a nansen-cli wallet set up with the old password storage method and wants to migrate to the new secure flow.

When to use

• User mentions they stored their password in ~/.nansen/.env, a .env file, or memory.md
• User gets the stderr warning: ⚠ Password loaded from insecure .credentials file
• User asks to "secure my wallet" or "migrate to keychain"
• User created a wallet before the keychain update was released

Detect current state

wallet show only displays addresses and does NOT load or check the password. To detect the actual password situation, check the stored password source directly:

# 1. Where is the password stored? Offline, decrypts nothing, prints no secrets
nansen auth status --pretty     # → x402.password.source: "env" | "keychain" | "file" | null

# 2. Full setup check — flags the insecure .credentials file with a fix
nansen doctor --offline

# 3. Legacy pattern doctor does not cover: password written to ~/.nansen/.env
ls -la ~/.nansen/.env 2>/dev/null && echo "FOUND: ~/.nansen/.env (insecure)"

Interpret x402.password.source:

• "file" → password in .credentials file, needs migration (Path B)
• "keychain" → already secure, no migration needed
• null → password not persisted anywhere (Path C or D)
• "env" → NANSEN_WALLET_PASSWORD is set; check where it is being exported from (a .env file → Path A)

Do NOT use nansen wallet export to probe the password state — the default is redacted and never loads the password, so it proves nothing (and --reveal prints private keys).

Migration paths

Path A: Password in ~/.nansen/.env (old skill pattern)

The previous wallet skill told agents to write the password to ~/.nansen/.env.

Step 1 — Ask the human for their password:

"Your wallet password is currently stored in ~/.nansen/.env, which is insecure. I can migrate it to your OS keychain. Please confirm the password you used when creating the wallet, or I can read it from ~/.nansen/.env if you authorize it."

Step 2 — Migrate:

The source and nansen wallet secure MUST run in the same shell so the env var is available to the node process:

source ~/.nansen/.env 2>/dev/null && nansen wallet secure

Step 3 — Verify the password actually decrypts the wallet:

# Unset env var to prove keychain works, then run a decrypting export with
# all output discarded — the exit code alone is the signal, so no key
# material can land in a transcript or log
unset NANSEN_WALLET_PASSWORD
if nansen wallet export default --reveal > /dev/null 2>&1; then echo "decryption OK"; else echo "decryption FAILED"; fi

If the export exits 0 (decryption OK), the migration worked. If it fails, the wrong password was migrated — run nansen wallet forget-password and retry with the correct password.

Step 4 — Clean up the insecure file:

rm -f ~/.nansen/.env

Path B: Password in .credentials file (auto-saved fallback)

This happens when wallet create couldn't access the OS keychain (containers, CI).

nansen wallet secure

If the keychain is still unavailable (e.g. containerized Linux without D-Bus), nansen wallet secure will explain the situation and suggest alternatives.

After migrating, verify decryption works (output discarded on purpose — branch on the exit code):

if nansen wallet export default --reveal > /dev/null 2>&1; then echo "decryption OK"; else echo "decryption FAILED"; fi

Path C: Password only in NANSEN_WALLET_PASSWORD env var

# Persist the env var password to keychain
nansen wallet secure

Then verify without the env var (exit code is the signal; output is discarded so no keys are disclosed):

unset NANSEN_WALLET_PASSWORD
if nansen wallet export default --reveal > /dev/null 2>&1; then echo "decryption OK"; else echo "decryption FAILED"; fi

Path D: Password lost entirely

The password cannot be recovered. The wallet's private keys are encrypted with AES-256-GCM and the password is not stored anywhere recoverable.

Tell the human:

"Your wallet password cannot be recovered. If you have funds in this wallet, they may be inaccessible. You can create a new wallet and transfer any remaining accessible funds."

# Create a fresh wallet (human must provide a new password)
NANSEN_WALLET_PASSWORD="<new_password_from_user>" nansen wallet create --name new-wallet

Post-migration verification

After any migration, confirm the password was migrated correctly by proving the keychain password can actually decrypt the wallet:

# Unset env var to prove keychain works
unset NANSEN_WALLET_PASSWORD

# This MUST exit 0 — it proves the keychain password decrypts the wallet.
# Output is discarded on purpose: the exit code alone is the signal.
if nansen wallet export default --reveal > /dev/null 2>&1; then echo "decryption OK"; else echo "decryption FAILED"; fi

If the export fails, the wrong password was saved to the keychain. Fix with:

nansen wallet forget-password
NANSEN_WALLET_PASSWORD="<correct_password>" nansen wallet secure

If stderr still shows the .credentials warning, the keychain migration did not succeed — check if the OS keychain service is running (secret-tool on Linux, security on macOS).

Forget password (all stores)

If the user wants to remove their persisted password entirely:

nansen wallet forget-password

This clears the password from both OS keychain and .credentials file. Future wallet operations will require NANSEN_WALLET_PASSWORD env var or re-running nansen wallet secure.

Critical rules for agents

• NEVER generate a password — always ask the human
• NEVER store the password in files, memory, logs, or conversation history
• NEVER use --human flag — interactive prompts break agents
• If the human authorizes reading ~/.nansen/.env, read it in the same command (source ~/.nansen/.env && nansen wallet secure) — do not echo or log the value
• ALWAYS verify after migration with nansen wallet export default --reveal > /dev/null 2>&1 (branch on the exit code; never let the output print) — wallet show does NOT prove the password works (it never loads the password)