Back to Details

defi-portfolio-scanner

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

defi-portfolio-scanner

defi-portfolio-scanner

Cross-protocol DeFi position aggregator for Stacks wallets. Scans four major Stacks DeFi protocols and produces a unified portfolio view with aggregate totals and risk scoring.
面向Stacks钱包的跨协议DeFi持仓聚合器。扫描四大Stacks DeFi协议，生成带有汇总总额和风险评分的统一投资组合视图。

What it does

功能介绍

defi-portfolio-scanner
queries four Stacks DeFi protocols in parallel and returns a single, normalized JSON report for any given STX address:
ProtocolWhat is scanned
Bitflow HODLMMLP positions across all active HODLMM pools — token pair, share amount, estimated USD value
Zest ProtocolLending deposits (collateral supplied) and active borrows — asset, principal, LTV ratio
ALEX DEXPool token balances representing LP shares in ALEX liquidity pools
Styx BridgePending and completed bridge deposits between Bitcoin L1 and Stacks
The skill also queries the Hiro API for baseline token balances so the portfolio view includes idle wallet holdings alongside active DeFi positions.
defi-portfolio-scanner
并行查询四大Stacks DeFi协议，为任意给定的STX地址返回一份标准化的JSON报告：
协议扫描内容
Bitflow HODLMM所有活跃HODLMM池中的LP持仓——代币对、份额数量、预估USD价值
Zest Protocol借贷存款（提供的抵押品）和活跃借贷——资产、本金、LTV比率
ALEX DEX代表ALEX流动性池LP份额的池代币余额
Styx BridgeBitcoin L1与Stacks之间的待处理及已完成桥接存款
本技能还会查询Hiro API获取基准代币余额，使投资组合视图同时包含闲置钱包资产和活跃DeFi持仓。

Why agents need it

智能体为何需要它

Autonomous agents managing DeFi strategies need a consolidated view of where capital is deployed before they can make allocation decisions. Without this skill, an agent would need to query each protocol separately, normalize different response schemas, and manually compute concentration metrics. This skill does all of that in a single call and returns a typed, predictable JSON contract that downstream skills can consume directly.
Common agent workflows:
  • Pre-trade check: Before entering a new HODLMM position, scan existing exposure to avoid over-concentration.
  • Risk monitoring: Periodic scans detect when Zest LTV ratios approach liquidation thresholds.
  • Rebalancing triggers: Summary risk scores can feed into rebalancing logic when concentration exceeds target bounds.
  • Reporting: Generate human-readable portfolio snapshots for dashboards or Discord alerts.
管理DeFi策略的自主智能体在做出分配决策前，需要一个资金部署位置的统一视图。如果没有本技能，智能体需要分别查询每个协议、标准化不同的响应格式，并手动计算集中度指标。本技能通过单次调用完成所有操作，返回类型明确、可预测的JSON契约，供下游技能直接使用。
常见智能体工作流：
  • 交易前检查：在进入新的HODLMM持仓前，扫描现有风险敞口以避免过度集中。
  • 风险监控：定期扫描可检测Zest LTV比率是否接近清算阈值。
  • 再平衡触发：当集中度超过目标范围时，汇总风险评分可触发再平衡逻辑。
  • 报告生成：为仪表盘或Discord警报生成人类可读的投资组合快照。

Safety notes

安全说明

  • Read-only — This skill makes zero on-chain transactions. Every call is either an HTTP GET or a Clarity 
    call-read
    via Hiro API.
  • No private keys — The skill never requests, accepts, or stores private keys or seed phrases.
  • No wallet mutation — Token balances and positions are observed, never modified.
  • Rate-limit aware — Requests include timeouts and the skill gracefully degrades if any single protocol API is unavailable, returning partial results with clear error flags.
  • Mainnet only — All endpoints target Stacks mainnet. Testnet addresses will return empty results without error.
  • 只读模式——本技能不会发起任何链上交易。所有调用均为HTTP GET请求，或通过Hiro API执行Clarity 
    call-read
    操作。
  • 无私钥要求——本技能从不请求、接受或存储私钥或助记词。
  • 不修改钱包——仅观测代币余额和持仓，不会进行任何修改。
  • 支持速率限制——请求包含超时设置，若任一协议API不可用，技能会优雅降级，返回带有明确错误标记的部分结果。
  • 仅主网——所有端点均指向Stacks主网。测试网地址将返回空结果，不会报错。

Commands

命令

doctor

doctor

Health check across all upstream dependencies. Returns per-endpoint latency and reachability status.
bash
bun run defi-portfolio-scanner.ts doctor
Output: JSON object with 
status: "ok" | "degraded" | "down"
per endpoint plus overall system status.
对所有上游依赖项进行健康检查。返回每个端点的延迟和可达性状态。
bash
bun run defi-portfolio-scanner.ts doctor
输出：JSON对象，包含每个端点的
status: "ok" | "degraded" | "down"
状态，以及整体系统状态。

scan --address <stx-address>

scan --address <stx-address>

Full position scan across all four protocols plus Hiro token balances.
bash
bun run defi-portfolio-scanner.ts scan --address SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KR9
Output: JSON object containing:
  • wallet
    — base token balances (STX, sBTC, stablecoins)
  • protocols.bitflow
    — array of HODLMM LP positions
  • protocols.zest
    — lending/borrowing positions with LTV
  • protocols.alex
    — pool token balances and estimated underlying
  • protocols.styx
    — bridge deposit records
  • totals
    — aggregate estimated USD value across all protocols
  • scannedAt
    — ISO-8601 timestamp
扫描所有四大协议及Hiro代币余额的完整持仓。
bash
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>

summary --address <stx-address>

Condensed portfolio overview with computed risk score.
bash
bun run defi-portfolio-scanner.ts summary --address SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KR9
Output: JSON object containing:
  • address
    — the scanned address
  • totalEstimatedUsd
    — aggregate portfolio value
  • protocolBreakdown
    — per-protocol USD allocation and percentage
  • riskScore
    — numeric score 0-100 (higher = riskier)
  • riskFactors
    — array of human-readable risk observations
  • topHoldings
    — top 5 positions by value
  • scannedAt
    — ISO-8601 timestamp
包含计算后风险评分的精简投资组合概览。
bash
bun run defi-portfolio-scanner.ts summary --address SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KR9
输出：JSON对象，包含：
  • address
    — 被扫描的地址
  • totalEstimatedUsd
    — 投资组合总估值
  • protocolBreakdown
    — 各协议的USD分配及占比
  • riskScore
    — 0-100的数值评分（分数越高风险越高）
  • riskFactors
    — 人类可读的风险观测数组
  • topHoldings
    — 按价值排序的前5大持仓
  • scannedAt
    — ISO-8601时间戳

Output contract

输出规范

Every command returns JSON matching this envelope:
json
{
  "success": true,
  "skill": "defi-portfolio-scanner",
  "command": "<command-name>",
  "data": { ... },
  "timestamp": "2026-03-31T12:00:00.000Z"
}
On error:
json
{
  "success": false,
  "skill": "defi-portfolio-scanner",
  "command": "<command-name>",
  "error": "Human-readable error message",
  "details": { ... },
  "timestamp": "2026-03-31T12:00:00.000Z"
}
每个命令返回的JSON均符合以下格式：
json
{
  "success": true,
  "skill": "defi-portfolio-scanner",
  "command": "<command-name>",
  "data": { ... },
  "timestamp": "2026-03-31T12:00:00.000Z"
}
错误情况下的输出：
json
{
  "success": false,
  "skill": "defi-portfolio-scanner",
  "command": "<command-name>",
  "error": "Human-readable error message",
  "details": { ... },
  "timestamp": "2026-03-31T12:00:00.000Z"
}

Data sources

数据源

SourceEndpointPurpose
Bitflow API
https://bff.bitflowapis.finance/api/app/v1/pools
HODLMM pool list and position data
Zest ProtocolHiro 
call-read
on 
SP2VCQJGH7PHP2DJK7Z0V48AGBHQAW3R3ZW1QF4N.pool-borrow-v2-3
Lending/borrowing user data via 
get-user-reserve-data
ALEX DEX
https://api.alexlab.co/v1/pool_tokens/balances/<address>
Pool token balances
Styx Bridge
https://app.styxfinance.com/api
Bridge deposit records
Hiro API
https://api.hiro.so/extended/v1/address/<addr>/balances
Token balances, contract reads
来源端点用途
Bitflow API
https://bff.bitflowapis.finance/api/app/v1/pools
获取HODLMM池列表和持仓数据
Zest ProtocolHiro 
call-read
调用
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
获取代币余额、执行合约读取

Cross-protocol DeFi portfolio scanners

跨协议DeFi投资组合扫描器

This skill aggregates positions from the following protocol-specific scanners:
#ProtocolScannerWhat it detects
1Bitflow HODLMM
scanBitflow()
LP bin positions across all active HODLMM pools via 
/users/{addr}/positions/{pool}/bins
, with Hiro fallback for LP receipt tokens
2Zest Protocol
scanZest()
Supply collateral and borrow balances via Hiro 
call-read
on 
pool-borrow-v2-3.get-user-reserve-data
, plus Zest receipt token detection from Hiro balances
3ALEX DEX
scanAlex()
Pool token balances from ALEX 
/pool_tokens/balances
API, with Hiro fallback for ALEX LP tokens in wallet
4Styx Bridge
scanStyx()
Pending and completed BTC→sBTC bridge deposits from Styx 
/deposits
API
5Wallet base
scanWalletBalances()
STX, sBTC, and all fungible token balances from Hiro API — provides the idle-capital baseline
All five scanners run in parallel via 
Promise.all
. Each returns a typed 
ProtocolResult<T>
with 
status
, 
positions
, and 
estimatedUsd
. USD estimation uses CoinGecko STX and BTC spot prices.
本技能聚合了以下协议专属扫描器的持仓数据：
序号协议扫描器检测内容
1Bitflow HODLMM
scanBitflow()
通过
/users/{addr}/positions/{pool}/bins
检测所有活跃HODLMM池中的LP仓位，同时通过Hiro fallback获取LP收据代币
2Zest Protocol
scanZest()
通过Hiro 
call-read
调用
pool-borrow-v2-3.get-user-reserve-data
获取供应抵押品和借贷余额，同时从Hiro余额中检测Zest收据代币
3ALEX DEX
scanAlex()
从ALEX 
/pool_tokens/balances
API获取池代币余额，同时通过Hiro fallback获取钱包中的ALEX LP代币
4Styx Bridge
scanStyx()
从Styx 
/deposits
API获取待处理及已完成的BTC→sBTC桥接存款
5钱包基准
scanWalletBalances()
从Hiro API获取STX、sBTC及所有 fungible代币余额——提供闲置资金基准
所有5个扫描器通过
Promise.all
并行运行。每个扫描器返回带有
status
、
positions
和
estimatedUsd
的类型化
ProtocolResult<T>
对象。USD估值使用CoinGecko提供的STX和BTC现货价格。

Known constraints

已知限制

  1. USD estimates are approximate. The skill uses pool ratios and last-known prices from protocol APIs. It does not query a dedicated price oracle. Values may drift from true market price during high volatility.
  2. Zest user-data requires active position. Addresses that have never interacted with Zest will return an empty Zest section, not an error.
  3. ALEX pool token mapping is best-effort. ALEX pool tokens are mapped to underlying pairs using the ALEX public API. Newly launched pools may not be mapped until the ALEX API updates.
  4. Styx API availability. The Styx bridge API has historically been less stable than the other three. The skill sets a shorter timeout and flags Styx as 
    "status": "unavailable"
    rather than failing the entire scan.
  5. Rate limits. Heavy polling (more than ~10 scans per minute) may trigger Hiro API rate limits. Agents should cache results and respect a minimum 30-second interval between scans of the same address.
  6. No historical data. Each scan is a point-in-time snapshot. The skill does not store or compare previous scans. Agents that need trend data should persist results externally.
  1. USD估值为近似值：本技能使用池比率和协议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的速率限制。智能体应缓存结果，同一地址的两次扫描间隔至少保持30秒。
  6. 无历史数据：每次扫描均为时间点快照。本技能不存储或对比过往扫描结果。需要趋势数据的智能体应自行持久化结果。

Origin

来源

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