Trade

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.

Execute

nansen trade execute --quote <quote-id>

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

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

Token	Chain	Address
SOL	Solana	So11111111111111111111111111111111111111112
USDC	Solana	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
ETH	Base	0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
USDC	Base	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

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

Token	Decimals	1 token =
SOL	9	1000000000
ETH	18	1000000000000000000
USDC	6	1000000

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

Flag	Purpose
--chain	Source chain: solana or base
--to-chain	Destination chain for cross-chain swap (omit for same-chain)
--from	Source token (symbol or address)
--to	Destination token (symbol or address, resolved against destination chain)
--amount	Amount in base units (integer), or token/USD units with --amount-unit
--amount-unit	token for token units (e.g. 0.5 SOL), usd for USD (e.g. 50), base = default
--wallet	Wallet name (default: default wallet)
--to-wallet	Destination wallet address (auto-derived for cross-chain if omitted)
--slippage	Slippage tolerance as decimal (e.g. 0.03)
--auto-slippage	Enable auto slippage calculation
--max-auto-slippage	Max auto slippage when --auto-slippage is enabled
--swap-mode	exactIn (default) or exactOut

trade execute flags

Flag	Purpose
--quote	Quote ID from trade quote
--wallet	Wallet name (default: default wallet)
--quote-index	Pin a specific quote by index (0-based) when multiple quotes were returned
--no-simulate	Skip pre-broadcast simulation

trade bridge-status flags

Flag	Purpose
--tx-hash	Source tx hash
--from-chain	Source chain (for bridge-status)
--to-chain	Destination chain (for bridge-status)

Environment Variables

Var	Purpose
NANSEN_WALLET_PASSWORD	Required for trade execute. Wallet encryption password — persisted in ~/.nansen/.env. Source before executing: source ~/.nansen/.env && nansen trade execute ...
NANSEN_API_KEY	API key (also set via nansen login)

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).
• ERC-20 swaps may require an approval step — execute handles this automatically.

Source

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