nansen-agent-guide

身份验证

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

Agent 与 CLI 路由

公开的 Agent fast/expert 命令和直接 API 命令，可使用已选定的 nansen:api 浏览器会话或常规 API 密钥，并遵循相同的账户权限。

需要……	使用
分析结论（分析、解读）	nansen agent
表格（原始数据、特定指标）	直接 CLI 命令
报告（两者兼需）	使用 Agent 生成叙述内容，使用 CLI 获取数据

在以下情况下使用 nansen agent

• 问题需要跨多个数据源进行解读或综合
• 开放式研究，例如：“分析这个钱包”“ETH 智能资金正在发生什么？”

nansen agent "What are top smart money tokens on Solana today and why?"
nansen agent "Analyse wallet 0x123... -- is this a smart trader?"
nansen agent "..." --expert   # deeper analysis, 750 credits

费用：200 个积分（fast）/ 750 个积分（expert）

在以下情况下使用直接 CLI 命令

• 需要特定结构化数据，例如价格、交易量、持有者、资金流
• 确定性问题，例如：“ethereum 上净流入量最高的 10 种代币”
• 需要通过管道传递输出或构建数据表

nansen research token screener --chain ethereum --smart-money --limit 10
nansen research smart-money netflow --chain solana
nansen research profiler balance --address 0x123... --chain ethereum

每次调用费用：5-50 个积分

反模式

• 不要用 nansen agent 获取简单数据——费用高出 40 倍
• 不要用原始 CLI 进行开放式分析——它只返回数据，不提供解读
• 不要连续调用 Agent 3 次或更多——通过 CLI 获取原始数据，然后只调用一次 Agent 进行综合

浏览器会话范围

普通的 nansen login 会请求新的浏览器授权；--no-browser 会打印链接/代码，以便在另一台设备上授权，并且仍要求使用相同的原生存储。NANSEN_API_KEY 会覆盖唯一保存的凭据。使用 nansen auth status 离线查看缓存/未验证的选择详情，使用 nansen account 进行免费的实时检查。显式使用 login --human 或 login --api-key 可保留旧版密钥设置方式。已选定的浏览器会话会自动续期；续期状态不确定时，必须重新登录，不能重放请求，也不能回退到其他账户/付款方式。

浏览器 nansen:api 授权具备与 API 密钥相当的账户权限，但须通过已启用的准入检查，并受相同的端点限制。此授权不会授予内部服务身份或钱包签名权限。浏览器会话不能用于授权钱包签名，也不能导出为 MCP 密钥。CLI 2.0.0 已发布；但仍受上述预览平台限制。

产品反馈

当 Nansen 任务暴露出有用的产品缺口时，请撰写一份简洁的报告，不包含机密或不必要的对话细节。自行发送前，请使用 nansen feedback preferences --json 读取当前账户保存的反馈偏好。每次提交新报告前，都要重新读取。如果已启用，你可以无需再次询问就发送，但仍须遵守主机的控制规则。如果已关闭、未设置或无法获取，请展示拟提交的报告并询问用户。如果用户拒绝，或你无法询问，则不要发送。

报告是一个 JSON 对象。category 和 description 为必填项。 category 必须是 bug、data_quality、documentation、 missing_capability、usability 或 other 之一。功能请求或产品缺口属于 missing_capability；不要自行编造类别。description 应说明发生了什么以及需要什么，最多 2,000 个字符。你还可以添加 endpoint、tool、goal、expected_behavior、 observed_behavior、workaround、request_ids（最多填写 10 个你自己的请求 ID）以及 client （{"name": ..., "version": ...}）。其他任何字段（例如 title、summary 或 component）都会导致 422 错误。如果已生成 ID，该 422 错误还会清除已保存的报告，因此你需要使用 --new。请使用普通句子，不要使用 Markdown 或代码格式。nansen feedback submit --help 会列出限制。

{"category": "missing_capability", "description": "There is no command to list my past feedback receipts.", "goal": "Check the status of reports I sent earlier."}

如果读取偏好失败，请先询问用户。用户明确提出请求或表示同意，即可提交该报告；这不会更改已保存的偏好。绝不要自动启用该偏好，也不要在报告中添加同意字段。请引导用户前往 Superapp 设置，以作出长期选择。主机或本地拒绝控制仍适用于已启用的偏好以及单次报告的批准。

用户请求提交报告或偏好允许提交后，请使用 nansen feedback submit --file feedback.json --submission-id <new-id> --json 提交。 该命令为非交互式。结果不确定时，恢复操作请使用相同 ID 和未更改的报告；使用 nansen feedback get <feedback-id> --json 读取已保存的回执。提交和读取回执均免费。账户每个 UTC 周可提交 7 份已接受的报告，每周一 00:00 UTC 重置。

发布前或服务中断期间可能会暂停接收新提交。reason: feedback_admissions_paused 对应的 503 错误表示此次尝试未接受任何新报告，也未占用每周限额。请告知用户反馈功能不可用，然后停止操作；不要继续重试，也不要在同一会话中再次请求批准。保留 ID 和未更改的报告，以便稍后重试。如果此 CLI 版本没有反馈命令，请告知用户该功能不可用，然后停止操作。在暂停期间，已接受 ID 的重复提交和回执读取仍可用。

reason: feedback_not_enabled 对应的 403 错误表示此账户未启用反馈功能。请停止自动重试并告知用户。批准和已启用的偏好都不能绕过发布限制。保留已保存的 ID 和未更改的报告。先前结果不确定的尝试仍然不确定；在功能恢复后，使用相同 ID 恢复操作。绝不要切换账户或付费绕过拒绝。