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.
What it does
queries four Stacks DeFi protocols in parallel and returns a single, normalized JSON report for any given STX address:
| Protocol | What is scanned |
|---|
| Bitflow HODLMM | LP positions across all active HODLMM pools — token pair, share amount, estimated USD value |
| Zest Protocol | Lending deposits (collateral supplied) and active borrows — asset, principal, LTV ratio |
| ALEX DEX | Pool token balances representing LP shares in ALEX liquidity pools |
| Styx Bridge | Pending 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.
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.
Safety notes
- Read-only — This skill makes zero on-chain transactions. Every call is either an HTTP GET or a Clarity 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.
Commands
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.
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:
- — base token balances (STX, sBTC, stablecoins)
- — array of HODLMM LP positions
- — lending/borrowing positions with LTV
- — pool token balances and estimated underlying
- — bridge deposit records
- — aggregate estimated USD value across all protocols
- — ISO-8601 timestamp
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:
- — the scanned address
- — aggregate portfolio value
- — per-protocol USD allocation and percentage
- — numeric score 0-100 (higher = riskier)
- — array of human-readable risk observations
- — top 5 positions by value
- — ISO-8601 timestamp
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"
}
Data sources
| Source | Endpoint | Purpose |
|---|
| Bitflow API | https://bff.bitflowapis.finance/api/app/v1/pools
| HODLMM pool list and position data |
| Zest Protocol | Hiro on SP2VCQJGH7PHP2DJK7Z0V48AGBHQAW3R3ZW1QF4N.pool-borrow-v2-3
| Lending/borrowing user data via |
| 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 |
Cross-protocol DeFi portfolio scanners
This skill aggregates positions from the following protocol-specific scanners:
| # | Protocol | Scanner | What it detects |
|---|
| 1 | Bitflow HODLMM | | LP bin positions across all active HODLMM pools via /users/{addr}/positions/{pool}/bins
|
| 2 | Zest Protocol | | Supply collateral and borrow balances via Hiro on pool-borrow-v2-3.get-user-reserve-data
|
| 3 | ALEX DEX | | Pool token balances from ALEX API, with Hiro fallback for ALEX LP tokens in wallet |
| 4 | Styx Bridge | | Pending and completed BTC→sBTC bridge deposits from Styx API |
| 5 | Wallet base | | STX, sBTC, and all fungible token balances from Hiro API — provides the idle-capital baseline |
All five scanners run in parallel via
. Each returns a typed
with
,
, and
. USD estimation uses CoinGecko STX and BTC spot prices.
Known constraints
- 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.
- Zest user-data requires active position. Addresses that have never interacted with Zest will return an empty Zest section, not an error.
- 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.
- 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 rather than failing the entire scan.
- 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.
- 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.
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