BTC Sovereign Tracker

Track and verify your Bitcoin self-custody setup. This skill monitors COLDCARD Q vault health, fetches real-time mempool fees, inspects UTXOs, and verifies on-chain balances — all read-only. Never exposes private keys. Trust, but verify (Gebud 3).

Prerequisites

• curl and jq on PATH
• Bitcoin address(es) to monitor (watch-only, no private keys)
• Optional: local Bitcoin Core or Electrum server for full privacy

Core Commands

Mempool Fee Estimation

Get current fee rates from mempool.space:

curl -s https://mempool.space/api/v1/fees/recommended | jq .

Response: {"fastestFee": N, "halfHourFee": N, "hourFee": N, "economyFee": N, "minimumFee": N}

Fees are in sat/vB. Multiply by tx size (~140 vB for segwit) to get total fee in sats.

Address Balance & UTXOs

Check balance and UTXOs for a watch-only address:

ADDR="bc1q..."  # watch-only address
curl -s "https://mempool.space/api/address/$ADDR" | jq '{balance: .chain_stats.funded_txo_sum - .chain_stats.spent_txo_sum, tx_count: .chain_stats.tx_count}'
curl -s "https://membpool.space/api/address/$ADDR/utxo" | jq '.[] | {txid: .txid, vout: .vout, value: .value}'

Privacy note: mempool.space is a third party. For maximum sovereignty, run your own mempool instance or use a local Bitcoin Core node with bitcoin-cli.

Block Height & Network Health

curl -s https://mempool.space/api/blocks/tip/height

Compare against your local node to verify chain sync.

Price Oracle (CoinGecko)

curl -s "https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd,eur,sek" | jq .

COLDCARD Vault Health (via ZK-Bankir)

Query the ZK-Bankir treasury endpoint for BTC vault status:

ZK_HOST="${ZK_BANKIR_HOST:-http://localhost:3000}"
curl -s "$ZK_HOST/api/v1/treasury/btc" -H "Accept: application/json" | jq .

Expected:

{
  "asset": "BTC",
  "balance": "1.5",
  "address": "bc1q...",
  "vault": "COLDCARD Q",
  "type": "watch-only"
}

UTXO Consolidation Planning

List all UTXOs and identify dust or consolidation candidates:

ADDR="bc1q..."
curl -s "https://mempool.space/api/address/$ADDR/utxo" | jq '
  [.[] | {
    txid: .txid[0:8],
    vout: .vout,
    value_sats: .value,
    value_btc: (.value / 100000000),
    dust: (.value < 10000)
  }] | sort_by(.value_sats)
'

UTXOs below 10,000 sats (~$10) are dust and may cost more to spend than they're worth during high-fee periods.

Usage Patterns

Daily Sovereignty Check

When the user asks for a BTC sovereignty status:

1. Mempool fees — current fee environment (low/medium/high)
2. Address balance — confirmed balance vs expected
3. Block height — chain tip verification
4. BTC price — current fiat value
5. Vault health — COLDCARD status from ZK-Bankir

Pre-Transaction Fee Planning

When the user considers a transaction:

1. Fetch current recommended fees
2. Calculate fee ranges: economy (~0.5h), hour (~2h), half-hour (~30min), fastest (~next block)
3. Show fee in sats and fiat equivalent
4. Flag if any UTXOs would become dust after spending

UTXO Management Audit

When the user asks about UTXO health:

1. List all UTXOs sorted by value
2. Flag dust UTXOs (value < fee to spend)
3. Recommend consolidation targets (fewer UTXOs = lower future fees)
4. Warn if address reuse detected

Sovereignty Principles

This skill follows ZK-Bankir's Gebuden:

• §1 Sovereignty First — prefers local node over third-party APIs when available
• §3 Trust, but Verify — cross-checks mempool.space with CoinGecko and ZK-Bankir
• §5 Watch-Only by Default — never requires, stores, or transmits private keys
• §7 Privacy Per Design — warns when using third-party APIs, recommends local alternatives

Configuration

| Variable | Default | Description | |----------|---------|-------------| | BTC_WATCH_ADDRESS | (required) | Bitcoin address to monitor (watch-only) | | MEMPOOL_API | https://mempool.space/api | Mempool API base (change for self-hosted) | | COINGECKO_API | https://api.coingecko.com/api/v3 | Price API base | | ZK_BANKIR_HOST | http://localhost:3000 | ZK-Bankir server for vault status |

Troubleshooting

| Symptom | Likely Cause | Fix | |---------|-------------|-----| | Empty UTXO list | Address has no transactions | Verify address on a block explorer | | Rate limit on mempool.space | Too many requests | Use local mempool instance or add delays | | ZK-Bankir BTC endpoint 404 | Server not running | Start ZK-Bankir or use direct mempool queries | | Dust warnings on all UTXOs | High fee environment | Wait for lower fees before consolidating |

Security

• Read-only — queries on-chain data, never signs transactions
• No key exposure — all addresses are watch-only public keys
• Third-party aware — clearly labels when using external APIs vs local node
• COLDCARD Q remains air-gapped — this skill queries balances through ZK-Bankir's watch-only API