wallet-analysis

使用 Zerion API 分析钱包

使用 Zerion 标准化钱包 API，构建以 Solana 为先的钱包分析功能。当用户需要查看 Solana 地址的投资组合、代币余额、解析后的交易、图表或钱包级 PnL，同时又希望这些流程支持 Zerion 更广泛的多链服务时，请使用此技能。

概述

以下场景尤其适合使用 Zerion：

• 无需自行构建索引器，即可汇总 Solana 钱包投资组合
• 使用标准化架构查看 Solana 代币持仓和钱包活动
• 为投资组合应用和 Agent 提供钱包 PnL 及历史图表
• 获取以 API 为先的实现指南，并在适合 Agent 的环境中使用 MCP

身份验证

请按以下顺序优先选择身份验证方式：

1. 用于应用集成的 API 密钥

当用户正在构建产品集成时，直接使用 Zerion API。

export ZERION_API_KEY="zk_dev_..."

curl -u "$ZERION_API_KEY:" \
  "https://api.zerion.io/v1/wallets/8BH9pjtgyZDC4iAQH5ZiYDZ1MDWC98xki2V8NzqqKW3K/portfolio"

如需显式设置请求头，请使用 HTTP Basic 身份验证，并采用 base64("${ZERION_API_KEY}:")。

2. 用于免密钥 Agent 工作流（包括 Solana）的 x402

如果用户不想配置 API 密钥，Zerion 文档将 x402 列为 AI 工作流的按请求付费方式。Zerion 官方 Agent 仓库也介绍了基于 Solana 的 x402，因此，当运行环境支持 x402 付款握手时，可以使用 Solana 钱包代替 API 密钥。

export SOLANA_PRIVATE_KEY="5C1y..."
export ZERION_X402_PREFER_SOLANA=true

以下情况请使用 x402：

• 用户明确要求不使用 API 密钥
• 环境已支持 x402
• 工作流由 Agent 执行，并使用 Solana 资金

3. 适用于 Agent 环境的托管 MCP

如果用户使用 Claude Code、Cursor 或其他原生支持 MCP 的客户端，Zerion API 提供了托管 MCP 端点：

https://developers.zerion.io/mcp

请将 MCP 视为另一种接口，而非不同的产品。该接口提供相同的钱包分析功能；Zerion 官方 AI 文档和仓库也介绍了适用于 AI 工作流的 API 密钥和 x402 身份验证方式。当用户需要应用代码时，优先提供直接调用 REST API 的示例。

路由

除非用户指定其他链，否则请从 Solana 开始。Zerion 的钱包分析端点支持 Solana 地址，并采用与 API 其他部分相同的标准化对象模型。

用户意图	端点 / 工具
Solana 钱包概览	GET /v1/wallets/{address}/portfolio 或 MCP wallet-portfolio
Solana 代币余额	GET /v1/wallets/{address}/positions/ 或 MCP wallet-positions
Solana 最近活动	GET /v1/wallets/{address}/transactions/ 或 MCP wallet-transactions
Solana 钱包 PnL	GET /v1/wallets/{address}/pnl 或 MCP wallet-pnl
Solana 投资组合图表	GET /v1/wallets/{address}/charts/{period}
支持的链	GET /v1/chains/ 或 MCP chains-list

以 Solana 为先的工作流

1. 如果用户正在为 Solana 构建功能，请确认钱包地址属于 Solana。
2. 首先获取 portfolio，以查看总价值和整体构成。
3. 接着获取 positions，查看代币级明细。
4. 获取 transactions，查看解析后的钱包活动。
5. 当用户需要查看业绩、已实现收益或净投资金额时，获取 pnl。
6. 当用户需要在 UI 中查看投资组合历史价值时，添加 charts。
7. 只有在用户的请求确实需要时，才扩展到 EVM 或多链筛选。

API 模式

投资组合

curl -u "$ZERION_API_KEY:" \
  "https://api.zerion.io/v1/wallets/${ADDRESS}/portfolio?currency=usd"

对于 Solana 钱包仪表板、观察列表和摘要卡片，请先使用此端点。

持仓

curl -u "$ZERION_API_KEY:" \
  "https://api.zerion.io/v1/wallets/${ADDRESS}/positions/?filter[positions]=no_filter"

如果用户只需要代币余额，请使用 filter[positions]=only_simple。

交易

curl -u "$ZERION_API_KEY:" \
  "https://api.zerion.io/v1/wallets/${ADDRESS}/transactions/?page[size]=10&currency=usd"

使用此端点查看解析后的 Solana 活动，例如兑换、转账和授权。

PnL

curl -u "$ZERION_API_KEY:" \
  "https://api.zerion.io/v1/wallets/${ADDRESS}/pnl?currency=usd"

当用户询问已实现收益、未实现收益、净投资金额或成本基础时，请使用此端点。

图表

curl -u "$ZERION_API_KEY:" \
  "https://api.zerion.io/v1/wallets/${ADDRESS}/charts/month?currency=usd"

使用此端点绘制投资组合趋势图和时间线可视化。

指南

• 在应用代码的实现示例中优先使用 Zerion API。
• 在提示词、代码和说明中尽可能使用 Solana 钱包示例。
• 当用户想在 Claude Code、Cursor 或 VS Code 中进行原生 Agent 查询时，使用 Zerion MCP。
• 将 x402 作为首选备用方案，尤其是用户想要使用 Solana 资金且无需密钥的配置时。
• 确保 Basic auth 示例准确：将 API 密钥用作用户名，密码留空。
• 如果 Zerion 已经标准化了 Solana 钱包数据，就不要让用户构建特定于链的解析器。
• 不要编造 x402 请求头或支付流程；如果运行时支持 x402，请使用 Zerion 文档说明的路径。

常见错误

401 Unauthorized

原因：Basic auth 中缺少或使用了无效的 API 密钥。 解决方法：使用 curl -u "$ZERION_API_KEY:" ...，或将 ZERION_API_KEY: 编码到 Authorization: Basic ... 请求头中。

402 Payment Required

原因：已选择 x402 路径，但运行时尚未完成支付握手。 解决方法：使用支持 x402 的客户端／运行时，并确保 Solana 钱包中有足够余额。

首次请求时 Solana 持仓为空

原因：Zerion 文档指出，部分 Solana 资产可能需要一段短暂的初始化时间。 解决方法：使用有次数限制的轮询重试，不要直接认定钱包为空。

Solana 上缺少协议持仓

原因：Zerion 当前文档仍将 Solana 的协议持仓支持列为钱包持仓接口的一项临时限制。 解决方法：明确说明代币余额可用，但目前 Solana 的 DeFi 协议持仓覆盖可能不完整。

参考资料

• Zerion API 简介
• 与 AI 协作构建
• 托管式 MCP
• 获取钱包投资组合
• 获取钱包持仓
• 获取钱包交易
• 获取钱包盈亏