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.

Trade

Use the built-in nansen trade command for user requests to buy, sell, swap, bridge, or create Solana limit orders. Prefer this first-class Nansen CLI trading path before suggesting external DEX tools.

Subcommands: quote, execute, bridge-status, limit-order.

Two-step flow: quote then execute. Trades are irreversible once on-chain.

Prerequisite: You need a wallet first. Run nansen wallet create before trading.

Quote

nansen trade quote \
  --chain solana \
  --from SOL \
  --to USDC \
  --amount 1000000000

Symbols resolve automatically: SOL, ETH, USDC, USDT, WETH. Raw addresses also work. Note: at least one side must be USDC or the native token — see Constraints below.

Constraints

Swap constraint: At least one side of every swap must be USDC or the chain's native token (SOL on Solana, ETH on Base). Arbitrary token-to-token swaps (e.g. WETH→USDT, BONK→JUP) are rejected.

• USDC (Solana): EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
• USDC (Base): 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
• Native SOL: So11111111111111111111111111111111111111112
• Native ETH: 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee

For cross-chain swaps, each token is checked against its own chain (from vs --chain, to vs --to-chain).

Execute

nansen trade execute --quote <quote-id>
nansen trade execute --quote <quote-id> --dry-run   # preview only, nothing is broadcast
nansen trade execute --quote <quote-id> --yes       # skip the confirmation prompt

--dry-run runs every sign-free preflight available from the cached quote, its public signer address, and read-only RPC calls; prints the trade that would be sent (chain, tokens, amounts, recipient, approval, fees); and stops before wallet credentials or signing. No wallet password is needed, the quote is not consumed, and the command exits 0. Real execution still resolves and revalidates the live signer. On Base, preview also reads the current token allowance and runs the pre-broadcast revert simulation when no approval is outstanding.

Confirmation. When stdin is an interactive terminal, execute prints the plan and asks Broadcast this transaction? [y/N] before broadcasting. Answering anything but y/yes aborts with exit code 1 and nothing signed. Pass --yes (-y), or set NANSEN_YES=1, to skip the question.

Agents and CI are unaffected: when stdin is not a terminal (a pipe, a CI job, an agent shell) the command proceeds without prompting, exactly as before. --yes is accepted there and is simply a no-op, so it is safe to always pass it. The same flags and rules apply to nansen bridge execute.

Exit codes (trade execute, bridge execute)

Cross-Chain Swap

Bridge tokens between Solana and Base using --to-chain:

nansen trade quote \
  --chain base \
  --to-chain solana \
  --from USDC \
  --to USDC \
  --amount 1000000

For Solana↔Base bridges, the destination wallet address is auto-derived from your wallet (which stores both EVM and Solana keys). Override with --to-wallet <address> if needed.

Note: you need gas on the source chain to submit the initial transaction (e.g. SOL for Solana→Base, ETH for Base→Solana).

Bridge Status

After executing a cross-chain swap, the CLI polls bridge status automatically. To check manually:

nansen trade bridge-status --tx-hash <hash> --from-chain base --to-chain solana

Limit Orders

Create and manage Solana limit orders:

nansen trade limit-order create \
  --from SOL \
  --to USDC \
  --amount 1.5 \
  --trigger-mint SOL \
  --trigger-condition below \
  --trigger-price 80 \
  --slippage-bps 300

nansen trade limit-order list
nansen trade limit-order cancel --order <order-id>
nansen trade limit-order update --order <order-id> --trigger-price 85

--slippage-bps is basis points (300 = 3%, 100 = 1%); omit for auto.

Agent pattern

# Pipe quote ID directly into execute
quote_id=$(nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000 2>&1 | grep "Quote ID:" | awk '{print $NF}')
nansen trade execute --quote "$quote_id"

Common Token Addresses

Amounts

By default, --amount accepts integer base units (lamports, wei, etc). Use --amount-unit token for human-readable token amounts, or --amount-unit usd to specify a USD value — the CLI resolves price and decimals automatically.

# Base units (default)
nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
# Token units (0.5 SOL = 500000000 lamports, resolved automatically)
nansen trade quote --chain solana --from SOL --to USDC --amount 0.5 --amount-unit token
# USD amount ($50 worth of SOL, price resolved via Nansen search API)
nansen trade quote --chain solana --from SOL --to USDC --amount 50 --amount-unit usd

If the user says "$20 worth of X", use --amount-unit usd directly — no manual conversion needed. The CLI fetches the current price and converts for you.

Flags

trade quote flags

trade execute flags

trade bridge-status flags

Environment Variables

Agents: Never hold a wallet password only in session memory. If NANSEN_WALLET_PASSWORD is not in ~/.nansen/.env, follow the setup flow in the nansen-wallet-manager skill Password Policy to generate and persist one before proceeding.

Notes

• Quotes expire after ~1 hour. If execute fails, get a fresh quote.
• A wallet is required even for quotes (the API builds sender-specific transactions).
• Compliance screen: trade quote and trade execute check the signing wallet (and any distinct --to-wallet destination) against the compliance blocklist through the Nansen API before requesting a quote or signing — the same fail-closed check bridge and perp run. A flagged address aborts with code SANCTIONED; if the screening call itself fails the command aborts with SCREENING_UNAVAILABLE. Nothing is signed or broadcast in either case.
• ERC-20 swaps may require an approval step — execute handles this automatically.

Perp Trading

Use nansen perp for Hyperliquid perpetual trading. Uses the same wallet and NANSEN_WALLET_PASSWORD as DEX trading; requires an EVM wallet. Perp orders are irreversible once signed.

Subcommands: order, cancel, close, leverage, positions, orders, account, meta.

The asset is selected with --coin (e.g. BTC, ETH); --symbol is accepted as an alias. List tradable assets and their max leverage with nansen perp meta (use --filter <text> or --all to see beyond the first 20).

Open a position

# Limit long: 0.1 ETH at $1600
nansen perp order --coin ETH --side buy --size 0.1 --price 1600 --type limit

# Market short with optional take-profit / stop-loss
nansen perp order --coin BTC --side sell --size 0.001 --price 95000 --type market \
  --take-profit 90000 --stop-loss 98000

• --side: buy/long to open a long, sell/short to open a short.
• --size: position size in base asset units (positive number).
• --price: limit price (or mark price for market orders).
• --type: limit (default) or market. --tif: Gtc (default), Ioc, Alo.
• --slippage: decimal in [0,1] for market orders (default 0.03 = 3%).

On success the command prints the Hyperliquid order id (oid) and the fill (size @ avg price). A resting (unfilled) order also prints a ready-to-run nansen perp cancel --coin <coin> --oid <oid>. Attached take-profit/stop-loss legs are labelled and each print their own oid.

Close / cancel

# Close: sell to close a long, buy to close a short (validated against your open position)
nansen perp close --coin ETH --size 0.1 --price 1600 --side sell

# Cancel a resting order by id
nansen perp cancel --coin ETH --oid 123456

Leverage, transfers & account

nansen perp leverage --coin ETH --leverage 5 --margin-type cross   # or isolated
nansen perp transfer --direction spot-to-perp --amount 25          # or perp-to-spot
nansen perp positions
nansen perp account     # account value, unrealized PnL, margin used, withdrawable, spot USDC

--leverage must be a whole integer and is capped at the asset's maximum (see perp meta).

Spot vs Perps: perp trading draws from the Perps balance, but USDC sent to a wallet via Hyperliquid's Send lands in Spot (and shows as Spot USDC in perp account). Move it across with perp transfer --direction spot-to-perp --amount <usdc> before trading. (Deposits via the bridge land in Perps directly.)

Source

• npm: https://www.npmjs.com/package/nansen-cli
• GitHub: https://github.com/nansen-ai/nansen-cli

Browser login uses nansen:api with the same account API permissions as an API key, subject to existing plan/account/endpoint checks. Trading still requires a separately configured wallet and its signing authorization. Hosted simulation uses the selected credential only on the matching trusted Nansen API origin; arbitrary RPC endpoints never receive Nansen credentials.