💻 Nansen CLI：终端数据分析与自动化实战
Nansen CLI 是一款专为 AI Agent（智能体）及开发者设计的命令行界面工具（Built by agents, for agents）。它允许你直接在终端中调用 Nansen 强大的数据 API，从而将数据分析融入到你的日常自动化工作流中。
无论你是想快速查询聪明钱流向，还是希望让你的 AI 助手自动进行链上调研，Nansen CLI 都是最直接、最高效的入口。本篇教程将带你从零基础开始，一步步掌握 Nansen CLI 的使用方法。
🛠️ 第一步：环境配置 (Environment Setup)
在开始使用之前，你需要确保本地环境中已安装了 Node.js (推荐 v18 及以上版本)。
1. 安装 CLI 工具
打开终端（Terminal），运行以下命令全局安装 Nansen CLI：
npm install -g nansen-cli
如果你是在 AI Agent 环境中使用，还可以加载专用的技能文件：
npx skills add nansen-ai/nansen-cli
2. 账号认证 (Auth)
你需要一个 Nansen API Key 来获取数据权限。可以在 app.nansen.ai/auth/agent-setup 申请。
获取后，通过以下几种方式进行认证配置：
# 方式一：直接登录并保存到本地 (~/.nansen/config.json)
nansen login --api-key <你的_API_Key>
# 方式二：交互式输入密码登录
nansen login --human
# 方式三：设置环境变量（优先级最高，推荐在服务器或脚本中使用）
export NANSEN_API_KEY=你的_API_Key
如果你想清除本地保存的凭证，可以使用 nansen logout。
⚙️ 第二步：命令行参数详解
Nansen CLI 采用主命令 + 子命令的结构，功能主要分为四大模块：
核心主命令
nansen research <类别> <子命令>：核心的数据分析指令。类别包括聪明钱(smart-money或sm)、代币(token或tgm)、地址画像(profiler或prof)、投资组合(portfolio或port)、预测市场(pm)、搜索(search)、合约(perp) 和 积分(points)。nansen trade <子命令>：链上交易执行，支持 Solana 和 Base 网络的 DEX 兑换（Swap）。nansen wallet <子命令>：本地钱包管理（创建、列表、导出、发送等），支持 EVM 与 Solana。nansen schema [命令] [--pretty]：查询完整的命令参考和可用字段（无需 API Key 即可使用，非常适合探索可用数据）。
常用附加参数 (Key Options)
在调用查询命令时，可以附加以下参数来精准控制输出：
| 参数 | 说明 | 示例 |
|---|---|---|
--chain <chain> | 指定查询的区块链网络 | --chain solana (支持 ethereum, base, bnb, arbitrum 等) |
--limit <n> | 限制返回结果的数量 | --limit 10 |
--timeframe <tf> | 时间窗口设置 | --timeframe 24h (可选: 5m, 1h, 6h, 24h, 7d, 30d) |
--fields <list> | 筛选要返回的字段，以逗号分隔（可大幅减小体积） | --fields token_symbol,net_flow_usd |
--sort <field:dir> | 结果排序 | --sort value_usd:desc |
--labels <label> | 根据聪明钱标签进行过滤 | --labels "Smart DEX Trader" |
--smart-money | 仅筛选被标记为“聪明钱”的地址 | --smart-money |
--pretty | 输出易于人类阅读的 JSON 格式 | --pretty |
--table | 以表格形式输出数据，更直观 | --table |
--stream | 对于海量数据，采用 NDJSON 格式流式输出 | --stream |
🚀 第三步：常用数据分析场景演示
让我们通过几个实战案例，看看如何用一行命令获取关键的链上洞察。
场景一：查询 Solana 上的聪明钱净流入 (Smart Money Netflow)
假设你想知道过去 24 小时内，Solana 链上聪明钱都在买什么。
输入命令：
nansen research smart-money netflow --chain solana --timeframe 24h --limit 5 --table
解读： 使用 --table 参数可以直接在终端中渲染出清晰的表格，帮助你快速发现当前 Solana 链上的热门资产。
场景二：分析特定地址的代币持仓 (Portfolio)
你可以直接使用以太坊域名 (ENS) 进行查询，非常方便。
输入命令：
nansen research portfolio show --address vitalik.eth --pretty
解读： 了解 Vitalik 钱包中的当前资产分布情况。使用 --pretty 将返回排版优美的 JSON 结构。
场景三：极致精简数据提取（减少 Token 消耗）
如果你将 CLI 嵌入到 AI 脚本中，只需要获取符号和美元价值，不希望返回冗余数据。
输入命令：
nansen research smart-money netflow --chain solana --fields token_symbol,net_flow_usd --limit 10
📊 第四步：结果解读方法
当你使用 JSON 格式（默认）输出时，Nansen CLI 会返回一个标准化的响应体。你需要关注外层的 success 状态：
成功响应：
{
"success": true,
"data": {
// 具体的 API 数据结果列表
}
}
失败响应：
{
"success": false,
"error": "The API key is invalid",
"code": "UNAUTHORIZED",
"status": 401
}
关键错误代码解读 (Critical Error Codes):
CREDITS_EXHAUSTED：你的 API 额度已耗尽。需要立即停止调用，并前往 Nansen App 查看账户状态。UNAUTHORIZED：API Key 错误或丢失。需要重新运行nansen login认证。RATE_LIMITED：请求频率过高。CLI 通常会自动尝试重试，如果不成功请稍微降低调用频率。UNSUPPORTED_FILTER：使用了不支持的过滤条件。请移除对应的 Filter 参数后重试。
🔧 第五步：常见错误排查 (Troubleshooting)
如果在运行中遇到问题，可以参考以下快速解决方案：
| 故障现象 (Symptom) | 解决办法 (Fix) |
|---|---|
command not found: nansen | 全局安装失败。请检查 Node 环境，并重新运行 npm install -g nansen-cli |
登录后仍提示 UNAUTHORIZED | 检查配置文件 cat ~/.nansen/config.json 或直接使用 export NANSEN_API_KEY=... 设置环境变量 |
| 合约 (Perp) 查询结果为空 | 确保使用 --symbol BTC 而不是 --token。注意：目前合约数据仅支持 Hyperliquid |
查询代币持有者时出现 UNSUPPORTED_FILTER | 请移除 --smart-money 参数。并非所有的代币数据都支持该标签过滤 |
| 返回的 JSON 结果体积过大 | 强制使用 --fields 参数指定需要的列，例如 --fields address,balance |
💡 第六步：最佳实践建议 (Agent Tips)
先查 Schema 再请求： 遇到不熟悉的命令或不知道该用哪个链时，先运行
nansen schema查看完整的支持列表和字段说明。这是不消耗 API 额度的。巧用
--fields节省成本与算力： 当你把 CLI 给大语言模型 (LLM) 使用时，庞大的 JSON 可能会超出上下文限制 (Token Burn)。永远记得使用--fields限制返回的字段。海量数据请用
--stream： 如果你查询的数据量极大（如数千条交易记录），使用--stream参数将结果输出为 NDJSON（换行符分隔的 JSON），避免一次性将整个巨型数组加载到内存中导致程序崩溃。无缝对接 ENS： 任何需要输入
--address的地方，都可以直接输入.eth结尾的 ENS 域名，CLI 会自动进行解析。
🎁 订阅与积分福利
想要获取更高 API 额度或解锁更多 Nansen 高级功能？立即前往：https://nsn.ai/7LOuQVx1Jvh