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.

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:

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 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.

Commands

doctor

Health check across all upstream dependencies. Returns per-endpoint latency and reachability status.

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.

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

summary --address <stx-address>

Condensed portfolio overview with computed risk score.

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

Output contract

Every command returns JSON matching this envelope:

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

On error:

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

Data sources

Cross-protocol DeFi portfolio scanners

This skill aggregates positions from the following protocol-specific scanners:

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.

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.

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