nansen-trading

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.

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

--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:

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:

Limit Orders

Create and manage Solana limit orders:

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

Agent pattern

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.

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

• --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

Leverage, transfers & account

--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.