defi-portfolio-scanner

defi-portfolio-scanner

适用于 Stacks 钱包的跨协议 DeFi 仓位聚合器。扫描四个主要的 Stacks DeFi 协议，并生成包含总计和风险评分的统一投资组合视图。

功能

defi-portfolio-scanner 会并行查询四个 Stacks DeFi 协议，并针对任意 STX 地址返回一份统一、规范化的 JSON 报告：

协议	扫描内容
Bitflow HODLMM	所有活跃 HODLMM 池中的 LP 仓位——代币对、份额数量、预估 USD 价值
Zest Protocol	借贷存款（提供的抵押品）和活跃借款——资产、本金、LTV 比率
ALEX DEX	代表 ALEX 流动性池 LP 份额的池代币余额
Styx Bridge	Bitcoin L1 与 Stacks 之间待处理和已完成的桥接存款

该工具还会查询 Hiro API，获取基础代币余额，因此投资组合视图会同时包含钱包中的闲置资产和活跃 DeFi 仓位。

Agent 为何需要它

管理 DeFi 策略的自主 Agent 需要先汇总资金的部署情况，才能做出资产配置决策。如果没有此工具，Agent 就必须分别查询每个协议、规范化不同的响应架构，并手动计算集中度指标。此工具只需一次调用即可完成所有这些工作，并返回类型明确、格式稳定的 JSON 契约，下游工具可直接使用。

常见的 Agent 工作流：

• 交易前检查：在建立新的 HODLMM 仓位前，扫描现有敞口，避免过度集中。
• 风险监控：定期扫描，检测 Zest 的 LTV 比率是否接近清算阈值。
• 再平衡触发：当集中度超出目标范围时，将汇总风险评分用于再平衡逻辑。
• 报告：为仪表板或 Discord 提醒生成易读的投资组合快照。

安全注意事项

• 只读——此工具不会执行任何链上交易。每次调用都是 HTTP GET 请求，或通过 Hiro API 执行 Clarity call-read。
• 无私钥——此工具绝不会请求、接收或存储私钥或助记词。
• 不修改钱包——仅查看代币余额和仓位，不会进行修改。
• 考虑速率限制——请求包含超时设置；如果任何单个协议 API 无法访问，此工具会优雅降级，返回带有清晰错误标记的部分结果。
• 仅限主网——所有端点均指向 Stacks 主网。测试网地址将返回空结果，但不会报错。

命令

doctor

检查所有上游依赖项的运行状况。返回各端点的延迟和可达状态。

bun run defi-portfolio-scanner.ts doctor

输出：JSON 对象，包含各端点的 status: "ok" | "degraded" | "down"，以及系统总体状态。

scan --address <stx-address>

扫描全部四个协议中的完整仓位，并获取 Hiro 代币余额。

bun run defi-portfolio-scanner.ts scan --address SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KR9

输出：JSON 对象，包含：

• wallet — 基础代币余额（STX、sBTC、稳定币）
• protocols.bitflow — HODLMM LP 仓位数组
• protocols.zest — 包含 LTV 的借贷仓位
• protocols.alex — 池代币余额和预估底层资产
• protocols.styx — 桥接存款记录
• totals — 所有协议的预估 USD 价值总计
• scannedAt — ISO-8601 时间戳

summary --address <stx-address>

提供精简的投资组合概览，并计算风险评分。

bun run defi-portfolio-scanner.ts summary --address SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KR9

输出：JSON 对象，包含：

• address — 扫描的地址
• totalEstimatedUsd — 投资组合预估总价值
• protocolBreakdown — 各协议的 USD 配置金额和占比
• riskScore — 0-100 的数值评分（数值越高，风险越大）
• riskFactors — 易于理解的风险观察结果数组
• topHoldings — 按价值排序的前 5 个仓位
• scannedAt — ISO-8601 时间戳

输出契约

每条命令都会返回符合以下封装格式的 JSON：

{
  "success": true,
  "skill": "defi-portfolio-scanner",
  "command": "<command-name>",
  "data": { ... },
  "timestamp": "2026-03-31T12:00:00.000Z"
}

出错时：

{
  "success": false,
  "skill": "defi-portfolio-scanner",
  "command": "<command-name>",
  "error": "Human-readable error message",
  "details": { ... },
  "timestamp": "2026-03-31T12:00:00.000Z"
}

数据源

来源	端点	用途
Bitflow API	https://bff.bitflowapis.finance/api/app/v1/pools	HODLMM 池列表和仓位数据
Zest Protocol	Hiro call-read on SP2VCQJGH7PHP2DJK7Z0V48AGBHQAW3R3ZW1QF4N.pool-borrow-v2-3	通过 get-user-reserve-data 获取借贷用户数据
ALEX DEX	https://api.alexlab.co/v1/pool_tokens/balances/<address>	池代币余额
Styx Bridge	https://app.styxfinance.com/api	桥接存款记录
Hiro API	https://api.hiro.so/extended/v1/address/<addr>/balances	代币余额、合约读取

跨协议 DeFi 投资组合扫描器

此技能会汇总以下各协议专用扫描器的仓位：

#	协议	扫描器	检测内容
1	Bitflow HODLMM	scanBitflow()	通过 /users/{addr}/positions/{pool}/bins 扫描所有活跃 HODLMM 池中的 LP bin 仓位，并在必要时回退到 Hiro 检测 LP 收据代币
2	Zest Protocol	scanZest()	通过 Hiro call-read 调用 pool-borrow-v2-3.get-user-reserve-data 获取供应的抵押品和借款余额，并通过 Hiro 余额检测 Zest 收据代币
3	ALEX DEX	scanAlex()	通过 ALEX /pool_tokens/balances API 获取池代币余额，并在必要时回退到 Hiro 检测钱包中的 ALEX LP 代币
4	Styx Bridge	scanStyx()	通过 Styx /deposits API 获取待处理和已完成的 BTC→sBTC 桥接存款
5	钱包基础数据	scanWalletBalances()	通过 Hiro API 获取 STX、sBTC 和所有同质化代币余额，作为闲置资金基准

所有五个扫描器都通过 Promise.all 并行运行。每个扫描器都会返回包含 status、positions 和 estimatedUsd 的类型化 ProtocolResult<T>。美元估值使用 CoinGecko 的 STX 和 BTC 现货价格。

已知限制

1. 美元估值为近似值。 此技能使用池比例和协议 API 提供的最近价格，不会查询专用价格预言机。在高波动期间，数值可能偏离真实市场价格。
2. Zest 用户数据要求存在活跃仓位。 从未与 Zest 交互过的地址会返回空的 Zest 部分，而非错误。
3. ALEX 池代币映射为尽力而为。 ALEX 池代币会通过 ALEX 公共 API 映射到底层交易对。在 ALEX API 更新之前，新上线的池可能不会被映射。
4. Styx API 可用性。 历来 Styx 桥接 API 的稳定性不如其他三个 API。此技能设置了较短的超时时间，并将 Styx 标记为 "status": "unavailable"，而不是导致整个扫描失败。
5. 速率限制。 频繁轮询（每分钟超过约 10 次扫描）可能触发 Hiro API 速率限制。Agent 应缓存结果，并遵守同一地址扫描间至少 30 秒的间隔。
6. 无历史数据。 每次扫描都是某个时间点的快照。此技能不会存储或比较之前的扫描结果。需要趋势数据的 Agent 应在外部持久化结果。

来源

AIBTC x Bitflow Skills Pay the Bills 竞赛获胜者。 原作者：@azagh72-creator 竞赛 PR：https://github.com/BitflowFinance/bff-skills/pull/121