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
CODEBLOCK0
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): INLINECODE6
- USDC (Base): INLINECODE7
- Native SOL: INLINECODE8
- Native ETH: INLINECODE9
For cross-chain swaps, each token is checked against its own chain (from vs --chain, to vs --to-chain).
Execute
CODEBLOCK1
Cross-Chain Swap
Bridge tokens between Solana and Base using --to-chain:
CODEBLOCK2
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:
CODEBLOCK3
Agent pattern
CODEBLOCK4
Common Token Addresses
| Token | Chain | Address |
|---|
| SOL | Solana | INLINECODE14 |
| 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.
CODEBLOCK5
| Token | Decimals | 1 token = |
|---|
| SOL | 9 | INLINECODE21 |
| 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 |
|---|
| INLINECODE26 | Source chain: solana or INLINECODE28 |
| INLINECODE29 |
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 |
|---|
| INLINECODE48 | Quote ID from INLINECODE49 |
| INLINECODE50 |
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 |
|---|
| INLINECODE54 | Source tx hash |
| INLINECODE55 |
Source chain (for bridge-status) |
|
--to-chain | Destination chain (for bridge-status) |
Environment Variables
| Var | Purpose |
|---|
| INLINECODE57 | Required for trade execute. Wallet encryption password — persisted in ~/.nansen/.env. Source before executing: INLINECODE60 |
| INLINECODE61 |
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
交易
两步流程：报价后执行。交易一旦上链即不可逆。
前置条件： 您需要先拥有一个钱包。交易前请运行 nansen wallet create。
报价
bash
nansen trade quote \
--chain solana \
--from SOL \
--to USDC \
--amount 1000000000
代币符号会自动解析：SOL、ETH、USDC、USDT、WETH。也支持使用原始地址。注意：至少有一方必须是 USDC 或原生代币——详见下方约束条件。
约束条件
交换约束： 每笔交换中至少有一方必须是 USDC 或该链的原生代币（Solana 链上为 SOL，Base 链上为 ETH）。任意代币对代币的交换（例如 WETH→USDT、BONK→JUP）将被拒绝。
- - USDC（Solana）：EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
- USDC（Base）：0x833589fcd6edb6e08f4c7c32d4f71b54bda02913
- 原生 SOL：So11111111111111111111111111111111111111112
- 原生 ETH：0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
对于跨链交换，每个代币将根据其所在链进行校验（from 对应 --chain，to 对应 --to-chain）。
执行
bash
nansen trade execute --quote <报价ID>
跨链交换
使用 --to-chain 在 Solana 和 Base 之间桥接代币：
bash
nansen trade quote \
--chain base \
--to-chain solana \
--from USDC \
--to USDC \
--amount 1000000
对于 Solana↔Base 桥接，目标钱包地址将从您的钱包（同时存储 EVM 和 Solana 密钥）自动派生。如有需要，可使用 --to-wallet <地址> 覆盖。
注意：您需要在源链上拥有 Gas 费以提交初始交易（例如 Solana→Base 需要 SOL，Base→Solana 需要 ETH）。
桥接状态
执行跨链交换后，CLI 会自动轮询桥接状态。如需手动检查：
bash
nansen trade bridge-status --tx-hash <哈希> --from-chain base --to-chain solana
代理模式
bash
将报价 ID 直接传递给执行命令
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
常见代币地址
| 代币 | 链 | 地址 |
|---|
| SOL | Solana | So11111111111111111111111111111111111111112 |
| USDC |
Solana | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v |
| ETH | Base | 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee |
| USDC | Base | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
金额
默认情况下，--amount 接受整数基础单位（lamports、wei 等）。使用 --amount-unit token 可接受人类可读的代币数量，或使用 --amount-unit usd 指定美元价值——CLI 会自动解析价格和小数位数。
bash
基础单位（默认）
nansen trade quote --chain solana --from SOL --to USDC --amount 1000000000
代币单位（0.5 SOL = 500000000 lamports，自动解析）
nansen trade quote --chain solana --from SOL --to USDC --amount 0.5 --amount-unit token
美元金额（价值 50 美元的 SOL，通过 Nansen 搜索 API 解析价格）
nansen trade quote --chain solana --from SOL --to USDC --amount 50 --amount-unit usd
| 代币 | 小数位数 | 1 个代币 = |
|---|
| SOL | 9 | 1000000000 |
| ETH |
18 | 1000000000000000000 |
| USDC | 6 | 1000000 |
如果用户说价值 20 美元的 X，请直接使用 --amount-unit usd——无需手动转换。CLI 会获取当前价格并为您转换。
标志
trade quote 标志
| 标志 | 用途 |
|---|
| --chain | 源链：solana 或 base |
| --to-chain |
跨链交换的目标链（同链交换时省略） |
| --from | 源代币（符号或地址） |
| --to | 目标代币（符号或地址，根据目标链解析） |
| --amount | 基础单位（整数）中的金额，或与 --amount-unit 配合使用的代币/美元单位 |
| --amount-unit | token 表示代币单位（例如 0.5 SOL），usd 表示美元（例如 50），base 为默认值 |
| --wallet | 钱包名称（默认：默认钱包） |
| --to-wallet | 目标钱包地址（跨链时如省略则自动派生） |
| --slippage | 滑点容忍度，以小数表示（例如 0.03） |
| --auto-slippage | 启用自动滑点计算 |
| --max-auto-slippage | 启用 --auto-slippage 时的最大自动滑点 |
| --swap-mode | exactIn（默认）或 exactOut |
trade execute 标志
| 标志 | 用途 |
|---|
| --quote | 来自 trade quote 的报价 ID |
| --wallet |
钱包名称（默认：默认钱包） |
| --quote-index | 当返回多个报价时，按索引（从 0 开始）固定特定报价 |
| --no-simulate | 跳过广播前模拟 |
trade bridge-status 标志
| 标志 | 用途 |
|---|
| --tx-hash | 源交易哈希 |
| --from-chain |
源链（用于桥接状态） |
| --to-chain | 目标链（用于桥接状态） |
环境变量
| 变量 | 用途 |
|---|
| NANSENWALLETPASSWORD | trade execute 必需。 钱包加密密码——持久化存储在 ~/.nansen/.env 中。执行前请先 source：source ~/.nansen/.env && nansen trade execute ... |
| NANSENAPIKEY |
API 密钥（也可通过 nansen login 设置） |
代理： 切勿将会话内存中的钱包密码仅保存在会话中。如果 NANSENWALLETPASSWORD 不在 ~/.nansen/.env 中，请先按照 nansen-wallet-manager 技能中的密码策略设置流程生成并持久化一个密码，然后再继续操作。
备注
- - 报价大约在 1 小时后过期。如果执行失败，请获取新的报价。
- 即使仅进行报价也需要钱包（API 会构建特定于发送者的交易）。
- ERC-20 交换可能需要授权步骤——执行命令会自动处理。
来源
- - npm：https://www.npmjs.com/package/nansen-cli
- GitHub：https://github.com/nansen-ai/nansen-cli
