nansen-trading

Execute DEX swaps on Solana or Base (including cross-chain bridges) and Hyperliquid perpetual trades. Use when buying or selling a token, getting a swap quote, executing a trade, or opening/closing/managing a perp position.

Nansen AI@nansen-devops

Install

openclaw skills install @nansen-devops/nansen-trading

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

bash

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

bash

nansen trade execute --quote <quote-id>

Cross-Chain Swap

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

bash

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:

bash

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

Limit Orders

Create and manage Solana limit orders:

bash

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

bash

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

bash

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

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

bash

# 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

bash

# 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

bash

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

nansen-trading

Install

Trade

Quote

Constraints

Execute

Cross-Chain Swap

Bridge Status

Limit Orders

Agent pattern

Common Token Addresses

Amounts

Flags

trade quote flags

trade execute flags

trade bridge-status flags

Environment Variables

Notes

Perp Trading

Open a position

Close / cancel

Leverage, transfers & account

Source

Related skills

`trade quote` flags

`trade execute` flags

`trade bridge-status` flags