nansen-trading

身份验证

Nansen 账户 API 调用可使用选定的 nansen:api 浏览器会话，或使用权限相同的常规 API 密钥。NANSEN_API_KEY 优先；可选的 primaryEnv 用于保留已配置密钥注入。运行 nansen auth status 可离线查看选择结果。仅当访问凭据缓存过期时，才允许在已授权任务期间自动续期。若选择匿名、状态无效、续期受阻或结果不确定，或实际身份验证失败，则停止；绝不丢弃凭据，也不回退到匿名 x402 付款。浏览器登录不会授予钱包签名权限、特权服务身份或持久的 MCP 集成密钥。请遵守下文所有确认、签名、制裁和地理区域检查。浏览器登录在 CLI 2.0.0 中可用，但仅限于 macOS arm64 预览范围。

交易

对于买入、卖出、兑换、跨链转移或创建 Solana 限价单等用户请求，请使用内置的 nansen trade 命令。在建议使用外部 DEX 工具之前，优先使用 Nansen CLI 的内置交易路径。

子命令：quote、execute、bridge-status、limit-order。

两步流程：先报价，再执行。交易一旦上链便不可逆。

前提条件： 你需要先有一个钱包。交易前运行 nansen wallet create。

报价

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

跨链兑换时，每种代币都会根据其所属链进行检查（来源代币对应 --chain，目标代币对应 --to-chain）。

执行

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 会使用缓存的报价、公开的签名者地址和只读 RPC 调用，运行所有可用的免签名前置检查；打印将会发送的交易（链、代币、数量、接收方、授权、费用）；并在访问钱包凭据或签名前停止。无需钱包密码，不会消耗报价，命令以退出码 0 结束。实际执行仍会解析并重新验证实时签名者。在 Base 上，预览还会读取当前代币授权额度，并在没有待处理授权时运行广播前回退模拟。

确认。 当标准输入是交互式终端时，execute 会打印交易计划，并在广播前询问 Broadcast this transaction? [y/N]。输入 y/yes 以外的任何内容都会中止，退出码为 1，且不会签名。传入 --yes（-y）或设置 NANSEN_YES=1，即可跳过询问。

Agent 和 CI 不受影响： 当标准输入不是终端（例如管道、CI 任务或 Agent Shell）时，命令会像之前一样直接继续执行，不会提示。此时接受 --yes，但该选项不起作用，因此始终传入该选项也是安全的。相同的标志和规则也适用于 nansen bridge execute。

退出码（trade execute、bridge execute）

代码	含义
0	广播成功，或试运行已完成
1	在确认提示处拒绝，或执行失败

跨链兑换

使用 --to-chain 在 Solana 和 Base 之间跨链转移代币：

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

对于 Solana↔Base 跨链转移，目标钱包地址会从你的钱包自动推导得出（该钱包同时存储 EVM 和 Solana 密钥）。如有需要，可使用 --to-wallet <address> 覆盖。

注意：提交初始交易需要在来源链上有 Gas（例如，Solana→Base 需要 SOL，Base→Solana 需要 ETH）。

桥接状态

执行跨链兑换后，CLI 会自动轮询桥接状态。要手动检查：

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

限价单

创建和管理 Solana 限价单：

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 的单位是基点（300 = 3%，100 = 1%）；省略时将自动设置。

Agent 模式

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

常见代币地址

代币	链	地址
SOL	Solana	So11111111111111111111111111111111111111112
USDC	Solana	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
ETH	Base	0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee
USDC	Base	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

金额

默认情况下，--amount 接受整数基本单位（lamports、wei 等）。使用 --amount-unit token 指定便于阅读的代币金额，或使用 --amount-unit usd 指定美元金额 — CLI 会自动解析价格和小数位数。

# 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

代币	小数位数	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 指定代币/USD 单位
--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	跳过广播前模拟
--dry-run	验证并打印将要发送的内容，然后停止。不进行签名或广播
--yes、-y	跳过确认提示（等同于 NANSEN_YES=1）；stdin 不是终端时无效

trade bridge-status 标志

标志	用途
--tx-hash	源交易哈希
--from-chain	源链（用于 bridge-status）
--to-chain	目标链（用于 bridge-status）

环境变量

变量	用途
NANSEN_WALLET_PASSWORD	trade execute 必需。 钱包加密密码 — 持久保存在 ~/.nansen/.env 中。执行前先加载：source ~/.nansen/.env && nansen trade execute ...
NANSEN_API_KEY	API 密钥（也可通过显式执行 nansen login --human 设置；浏览器会话不是钱包密钥或 RPC 密钥）
NANSEN_YES	设置为 1 可跳过 execute 确认提示，与 --yes 相同

Agents： 切勿只将钱包密码保存在会话内存中。如果 ~/.nansen/.env 中没有 NANSEN_WALLET_PASSWORD，请按照 nansen-wallet-manager skill Password Policy 中的设置流程生成并持久保存密码，然后再继续。

说明

• 报价约 1 小时后过期。如果执行失败，请获取新的报价。
• 即使只获取报价，也需要钱包（API 会构建发送方专属的交易）。
• 合规筛查：trade quote 和 trade execute 会在请求报价或签名前，通过 Nansen API 检查签名钱包（以及任何不同的 --to-wallet 目标地址）是否在合规屏蔽名单中；bridge 和 perp 也会执行相同的失败关闭检查。若地址被标记，命令会以代码 SANCTIONED 中止；若筛查调用本身失败，命令会以 SCREENING_UNAVAILABLE 中止。在这两种情况下，都不会签名或广播任何内容。
• ERC-20 兑换可能需要执行授权步骤，execute 会自动处理。

永续合约交易

使用 nansen perp 进行 Hyperliquid 永续合约交易。使用与 DEX 交易相同的钱包和 NANSEN_WALLET_PASSWORD；需要 EVM 钱包。永续合约订单一经签名便不可撤销。

子命令：order、cancel、close、leverage、positions、orders、account、meta。

使用 --coin 选择资产（例如 BTC、ETH）；也可使用别名 --symbol。使用 nansen perp meta 列出可交易资产及其最大杠杆（使用 --filter <text> 或 --all 查看前 20 项以外的内容）。

开仓

# 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 开多仓，使用 sell/short 开空仓。
• --size：以基础资产为单位的仓位规模（正数）。
• --price：限价价格（市价订单则为标记价格）。
• --type：limit（默认）或 market。--tif：Gtc（默认）、Ioc、Alo。
• --slippage：市价订单的 [0,1] 范围内小数（默认值为 0.03，即 3%）。

成功后，命令会打印 Hyperliquid 订单 ID（oid）和成交信息（成交量 @ 平均价格）。未成交的挂单也会打印可直接运行的 nansen perp cancel --coin <coin> --oid <oid>。附加的止盈/止损订单腿会标明类型，并各自打印其 oid。

平仓 / 取消订单

# 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

杠杆、转账与账户

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 必须是整数，且不得超过该资产的最大值（参见 perp meta）。

现货与永续合约： 永续合约交易使用 Perps 余额，但通过 Hyperliquid 的 Send 发送到钱包的 USDC 会进入 Spot（并在 perp account 中显示为 Spot USDC）。交易前，使用 perp transfer --direction spot-to-perp --amount <usdc> 将其转入 Perps。（通过桥接存入的资金会直接进入 Perps。）

来源

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

浏览器登录使用 nansen:api，其账户 API 权限与 API 密钥相同，但仍受现有套餐、账户和端点限制。交易仍需要单独配置钱包及其签名授权。托管模拟仅会在匹配的可信 Nansen API 源站使用所选凭据；任意 RPC 端点都不会收到 Nansen 凭据。