名称： zerion-api
描述： >
通过 Zerion API 的 MCP 连接器查询区块链钱包数据、代币价格和交易历史。
当用户询问以下内容时使用此技能：加密货币钱包余额、投资组合价值、代币持仓或头寸、DeFi 头寸（质押、借贷、流动性提供）、钱包盈亏、交易历史、代币/同质化资产价格或图表、NFT 持仓或 NFT 投资组合价值，或任何 Web3 钱包分析。触发词包括：钱包地址（0x...）、ENS 名称、代币名称/符号、“portfolio”、“positions”、“PnL”、“transactions”、“balance”、“holdings”、“NFTs”或任何加密/DeFi 分析查询。
在构建展示钱包或代币数据的工件或仪表板时也可使用。

Zerion API 技能

通过 Zerion MCP 连接器查询 Web3 钱包数据、代币价格、NFT 和交易历史。

认证

Zerion API 要求每个请求都提供密钥。该密钥不会存储在 MCP 连接器设置中——用户必须在每次聊天会话中提供。

工作流程

1. 在开始任何 Zerion 相关任务时，如果尚未提供 API 密钥，请询问：
   “要查询 Zerion，我需要您的 API 密钥。您可以在 https://dashboard.zerion.io/ 找到它。请在此处粘贴。”
2. 在对话期间将密钥存储在内存中。切勿将其写入文件、在工件中显示或记录它。
3. 将密钥传递给 MCP 服务器或 REST 调用，如下所述。

认证格式

Zerion 使用 HTTP 基本认证：API 密钥作为用户名，密码为空。

Authorization: Basic <base64(API_KEY + ":")>

示例：密钥 zk_dev_abc123 → zk_dev_abc123: 的 base64 编码 → emtfZGV2X2FiYzEyMzo=

MCP 连接

Zerion API MCP 服务器位于 https://developers.zerion.io/mcp。

当直接使用 MCP 工具时（在工件之外），根据工具参数要求传递 API 密钥。

当构建通过 MCP 调用 Anthropic API 的工件时，请将密钥包含在内部提示中，以便内部 Claude 进行认证：

mcp_servers: [
  { type: "url", url: "https://developers.zerion.io/mcp", name: "zerion-mcp" }
]

重要提示：在工件中，将 API 密钥作为属性或状态变量接收——切勿硬编码。示例模式：

// 用户通过安全输入字段（type="password"）输入密钥
const [apiKey, setApiKey] = useState("");

// 将密钥传递给内部 Claude 提示，以便 MCP 调用进行认证
const prompt = `使用 Zerion API 密钥：${apiKey}，获取钱包 0x... 的投资组合`;

快速参考：常见工作流程

1. 钱包投资组合概览

提示内部 Claude 调用 Zerion API 获取钱包的投资组合：

获取钱包 {address} 以美元计价的投资组合。包括总价值、每日变化以及按链和头寸类型的分布。

端点： GET /v1/wallets/{address}/portfolio
- currency: usd（默认）、eth、btc、eur 等。
- filter[positions]: only_simple（默认）、only_complex（DeFi）、no_filter（全部）

2. 钱包代币头寸

列出钱包 {address} 的所有同质化代币头寸，按价值降序排序。

端点： GET /v1/wallets/{address}/positions/
- filter[positions]: only_simple | only_complex | no_filter
- filter[chain_ids]: 逗号分隔的链 ID（例如：ethereum,polygon）
- filter[position_types]: wallet、deposit、staked、loan、locked、reward、investment
- sort: -value（最高优先）或 value
- filter[trash]: only_non_trash（默认）

3. 交易历史

获取钱包 {address} 的近期交易，仅筛选交易类型。

端点： GET /v1/wallets/{address}/transactions/
- filter[operation_types]: trade、send、receive、deposit、withdraw、mint、burn、claim、approve 等。
- filter[chain_ids]: 按链筛选
- filter[min_mined_at] / filter[max_mined_at]: 时间戳（毫秒）
- page[size]: 最大 100

4. 盈亏（PnL）

获取钱包 {address} 的盈亏。显示已实现收益、未实现收益、费用和净投入。

端点： GET /v1/wallets/{address}/pnl
- 返回：realized_gain、unrealized_gain、total_fee、net_invested、received_external、sent_external
- 使用先进先出（FIFO）方法
- filter[chain_ids]、filter[fungible_ids]: 缩小范围

5. 钱包余额图表

获取钱包 {address} 过去一个月的余额图表。

端点： GET /v1/wallets/{address}/charts/{chart_period}
- chart_period: hour、day、week、month、3months、6months、year、5years、max
- 返回 [timestamp, balance] 点数组

6. 代币价格与搜索

搜索同质化资产 "ethereum" 并返回其价格和市场数据。

端点： GET /v1/fungibles/
- filter[search_query]: 文本搜索（例如："ethereum"、"USDC"）
- sort: -market_data.market_cap、-market_data.price.last 等。
- 返回：name、symbol、price、market_cap、circulating_supply、changes（1d/30d/90d/365d）

7. 代币价格图表

获取同质化资产 {fungible_id} 过去一周的价格图表。

端点： GET /v1/fungibles/{fungible_id}/charts/{chart_period}
- 图表周期与钱包图表相同
- 返回 [timestamp, price] 点数组

8. NFT 头寸

列出钱包 {address} 的所有 NFT 头寸，按地板价降序排序。

端点： GET /v1/wallets/{address}/nft-positions/
- sort: -floor_price、floor_price、created_at、-created_at
- filter[chain_ids]: 按链筛选
- include: nfts、nft_collections、wallet_nft_collections 以获取更丰富的数据

9. NFT 投资组合价值

端点： GET /v1/wallets/{address}/nft-portfolio
- 返回 NFT 投资组合总价值

使用 Zerion 数据构建工件

当构建显示 Zerion 数据的 React/HTML 工件时：

1. 通过 type="password" 输入字段安全地收集 API 密钥
2. 切勿在 UI 中显示或记录密钥
3. 通过 MCP 提示传递它，以便内部 Claude 进行认证

// apiKey 来自密码输入，切勿硬编码
const response = await fetch("https://api.anthropic.com/v1/messages", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1000,
    messages: [
      {
        role: "user",
        content: `使用 Zerion API 和密钥 "${apiKey}" 获取钱包 ${walletAddress} 以美元计价的投资组合概览。
                  仅返回包含以下字段的 JSON 对象：totalValue, dailyChangePercent,
                  dailyChangeAbsolute, topChains (数组，元素为 {chain, value}),
                  positionBreakdown (wallet, deposited, staked, borrowed, locked).`
      }
    ],
    mcp_servers: [
      { type: "url", url: "https://developers.zerion.io/mcp", name: "zerion-mcp" }
    ]
  })
});

处理 MCP 响应

MCP 响应包含多个内容块。按类型提取数据：

const data = await response.json();

// 获取工具结果（实际的 Zerion 数据）
const toolResults = data.content
  .filter(item => item.type === "mcp_tool_result")
  .map(item => item.content?.[0]?.text || "")
  .join("\n");

// 获取 Claude 的文本分析
const textResponses = data.content
  .filter(item => item.type === "text")
  .map(item => item.text)
  .join("\n");

关键注意事项

• 地址格式：支持 EVM 地址（0x...）和 Solana 地址。ENS 名称可能需要先解析。
• Solana 限制：Solana 地址不支持协议头寸或 NFT 交易。
• 货币选项：usd、eth、btc、eur、krw、rub、gbp、aud、cad、inr、jpy、nzd、try、zar、cny、chf
• 分页：使用响应中的 links.next 进行分页；切勿手动构造 page[after]。
• 速率限制：API 在限流时返回 429。在工件中实现带退避的重试机制。
• 将 ID 视为不透明字符串：切勿假设 ID 的格式；它们可能会更改。
• DeFi 头寸：使用 filter[positions]=no_filter 以包含协议头寸和钱包头寸。
• LP 分组：流动性池头寸共享一个 group_id 属性——按此分组以正确显示池。

详细端点参考

有关完整参数详情、响应模式和边缘情况，请参阅：
- 钱包端点：references/wallet-endpoints.md
- 同质化代币和 NFT 端点：references/fungible-nft-endpoints.md