# First Light — BTX chain-intelligence API

> Neutral, provable on-chain facts for the BTX (Byron Bay pool) chain: blocks, transactions, addresses, supply, market price, wrapped-BTX backing, and bounded provenance. Auto-generated from the live API catalog.

- API base: https://api-explorer.btxbyronbay.com/api
- OpenAPI: https://explorer.btxbyronbay.com/openapi.json  (also live: https://api-explorer.btxbyronbay.com/api/_catalog/openapi.json)
- Catalog (source of truth): https://api-explorer.btxbyronbay.com/api/_catalog
- Docs: https://explorer.btxbyronbay.com/pro-api
- Native MCP server: `npx first-light-mcp` (tools auto-discovered from this catalog)

## Auth
Free endpoints need no key. Enterprise endpoints need `Authorization: Bearer <flp_token>`; gate order 401 (no/invalid token) -> 403 (tier too low) -> 429 (rate limit).

## Neutral-facts contract
Every result is a provable on-chain observation with a `caveat` string — never an identity, ownership, holdings, counterparty, risk verdict, or advice. Keep the caveat attached when you display or redistribute results.

## Wallet integration (Esplora / electrs)
A standard Esplora-compatible REST endpoint for wallets, indexers and agents: `https://esplora.btxbyronbay.com`. Paths: `/blocks/tip/height`, `/block/{hash}`, `/tx/{txid}` (+`/hex`, `/status`), `/address/{addr}` (+`/utxo`, `/txs`), `/fee-estimates`, and `POST /tx` (broadcast). Values are integer satoshis (1 BTX = 1e8). BTX addresses are post-quantum witness-v2 P2MR so `scriptpubkey_type` = `v2_p2mr` (key on `scriptpubkey_address`+`value`); fee-estimates are floor-dominated (empty mempool); blocks carry an extra `btx` object (`nonce64`, `matmul_digest`, seeds) that standard wallets ignore. No API key for reads; broadcast is public + rate-limited.

## Endpoints

### Analytics
- `GET /api/pro/liquidity` — Liquidity / float funnel  _(Enterprise)_
- `GET /api/pro/usage` — Usage mix  _(Enterprise)_
- `GET /api/pro/coin-age` — Coin-age (network)  _(Enterprise)_
- `GET /api/pro/coin-age/{address}` — Coin-age (address)  _(Enterprise)_
- `GET /api/pro/miner-conviction` — Miner conviction  _(Enterprise)_
- `GET /api/pro/miner-first-spend` — Miner first-spend feed  _(Enterprise)_
- `GET /api/pro/mining-centralization` — Mining centralization  _(Enterprise)_
- `GET /api/pro/realized-price` — Realized price  _(Enterprise)_
- `GET /api/pro/sell-pressure` — Sell pressure  _(Enterprise)_
- `GET /api/pro/supply-walls` — Supply walls  _(Enterprise)_
- `GET /api/pro/wallet-profile/{address}` — Wallet profile  _(Enterprise)_
- `GET /api/pro/otc/{addr}` — Pre-OTC address check  _(Enterprise)_
- `GET /api/pro/otc/report/{rid}` — Pre-OTC frozen report
- `GET /api/pro/as-of/balance/{address}` — Point-in-time balance  _(Enterprise)_
- `GET /api/pro/as-of/{lens}/{root}` — Point-in-time lens snapshot  _(Enterprise)_
- `GET /api/pro/otc-radar` — OTC radar  _(Enterprise)_
- `GET /api/pro/signals` — Signals workspace  _(Enterprise)_

### Anomalies
- `GET /api/pro/anomalies` — Anomaly feed  _(Enterprise)_
- `GET /api/pro/anomalies/summary` — Anomaly summary  _(Enterprise)_
- `GET /api/pro/anomalies/types` — Anomaly types  _(Enterprise)_
- `GET /api/pro/anomalies/{event_uid}` — Anomaly detail  _(Enterprise)_

### Chain
- `GET /api/network/glance` — Network glance
- `GET /api/network/supply` — Supply & emission
- `GET /api/block/{ident}` — Block by height or hash
- `GET /api/tx/{txid}` — Transaction detail
- `GET /api/address/{addr}` — Address page
- `GET /api/blocks/latest` — Latest blocks
- `GET /api/txs/latest` — Latest transactions
- `GET /api/search` — Universal search
- `GET /api/mempool` — Mempool
- `GET /api/blocks` — Recent blocks list
- `GET /api/chaintips` — Chain tips / forks
- `GET /api/address/{addr}/flows` — Address fund flows
- `GET /api/address/{addr}/signals` — Address neutral signals
- `GET /api/entities` — Entity catalogue
- `GET /api/entity/{addr}` — Entity lookup
- `GET /api/exchange-flow` — Exchange in/out flow
- `GET /api/originate` — Origination view
- `GET /api/orphans` — Recent orphan blocks
- `GET /api/reorgs` — Recent reorgs
- `GET /api/stats/census` — Address census
- `GET /api/stats/comparison` — Comparison stats
- `GET /api/stats/series` — Stats time series
- `GET /api/tip` — Chain tip

### Forensics
- `GET /api/pro/certificate/{address}` — Provenance certificate  _(Enterprise)_
- `GET /api/pro/dusting/address/{address}` — Dusting (address)  _(Enterprise)_
- `GET /api/pro/dusting/scan` — Dusting scan  _(Enterprise)_
- `GET /api/pro/entity-cluster` — Entity cluster  _(Enterprise)_
- `GET /api/pro/label/{addr}` — Attribution label  _(Enterprise)_
- `GET /api/pro/labels` — Attribution label directory  _(Enterprise)_

### Market
- `GET /api/market/summary` — Market summary (SafeTrade)  _(Enterprise)_
- `GET /api/market/orderbook` — Order book  _(Enterprise)_
- `GET /api/market/trades` — Trade tape  _(Enterprise)_
- `GET /api/market/candles` — OHLC candles  _(Enterprise)_
- `GET /api/btx-value` — Modeled valuation scenario quote
- `GET /api/address/{addr}/value` — Address balance valued
- `GET /api/price` — Model price (banked)
- `GET /api/value` — Value an amount (model)
- `GET /api/tx/{txid}/value` — Transaction valued
- `GET /api/pro/slippage` — Slippage model  _(Enterprise)_

### Mempool
- `GET /api/pro/mempool-dashboard` — Mempool dashboard  _(Enterprise)_
- `GET /api/pro/mempool-stream` — Mempool stream  _(Enterprise)_
- `GET /api/pro/mempool/floor` — Mempool fee floor  _(Enterprise)_
- `GET /api/pro/mempool-firstseen/{txid}` — Mempool first-seen  _(Enterprise)_

### MintCert
- `GET /api/mint-certificate/cert/{cert_id}` — Fetch mint certificate
- `GET /api/mint-certificate/pubkey` — Certificate signing pubkey
- `GET /api/mint-certificate/verify` — Verify mint certificate
- `GET /api/pro/mint-certificate` — Signed mint certificate (self)  _(Enterprise)_
- `GET /api/pro/mint-certificate/{target}` — Mint certificate (target)  _(Enterprise)_

### Network
- `GET /api/network/difficulty` — Difficulty over time
- `GET /api/network/economics` — Network economics
- `GET /api/network/health` — Network health
- `GET /api/network/blocktimes` — Block-time distribution
- `GET /api/network/concentration` — Miner concentration
- `GET /api/network/forks` — Fork / orphan stats
- `GET /api/network/series` — Network time series

### Observatory
- `GET /api/pro/observatory/summary` — Observatory summary  _(Enterprise)_
- `GET /api/pro/observatory/propagation` — Observatory propagation  _(Enterprise)_
- `GET /api/pro/observatory/block-propagation` — Block propagation  _(Enterprise)_
- `GET /api/pro/observatory/feemarket` — Observatory fee market  _(Enterprise)_
- `GET /api/pro/observatory/composition` — Block composition  _(Enterprise)_
- `GET /api/pro/observatory/orphan-rate` — Orphan rate per pool  _(Enterprise)_
- `GET /api/pro/observatory/peer-topology` — Peer topology  _(Enterprise)_
- `GET /api/pro/propagation` — Propagation stats  _(Enterprise)_

### Ops
- `GET /api/_health` — Collector data-health
- `GET /api/_catalog` — API catalog + drift report
- `GET /api/_catalog/fields` — Field dictionary (evidence classes)
- `GET /api/_catalog/evidence-schema/{version}` — Frozen evidence-envelope schema
- `GET /api/methods/{dataset}` — Method card for a dataset
- `GET /api/tiers` — Access tiers + limits
- `GET /api/health` — API health

### Pool
- `GET /api/miners` — Miner leaderboard
- `GET /api/minermap` — Miner geo distribution
- `GET /api/address/{addr}/mining` — Address mining badge
- `GET /api/miner/{tag}` — Miner / finder detail
- `GET /api/pro/pool-distribution` — Pool distribution  _(Enterprise)_

### Premium
- `GET /api/premium/pool-miner/status` — Pool-miner perk status
- `GET /api/premium/watchlist` — Watchlist (list)  _(Enterprise)_
- `GET /api/premium/whoami` — Token / tier introspection  _(Enterprise)_

### Provenance
- `GET /api/trace/{txid}` — Bounded fund tracer
- `GET /api/cluster/{addr}` — Co-spend set  _(Enterprise)_
- `GET /api/origin/{addr}` — Origin-of-funds badge  _(Enterprise)_
- `GET /api/provenance/{addr}` — Address provenance  _(Enterprise)_
- `GET /api/reverse/{addr}` — Reverse fund flow  _(Enterprise)_
- `GET /api/pro/counterparties/{addr}` — Counterparty set  _(Enterprise)_
- `GET /api/pro/exposure/{addr}` — Transaction-path exposure  _(Enterprise)_
- `GET /api/pro/w2w/{a}/{b}` — Wallet-to-wallet path  _(Enterprise)_
- `GET /api/pro/settlement/{target}` — Settlement trace  _(Enterprise)_
- `GET /api/pro/shield-boundary` — Shield boundary  _(Enterprise)_
- `GET /api/pro/shield-linkage/{target}` — Shield linkage  _(Enterprise)_
- `GET /api/pro/exposure-lineage/{tok}` — Transaction-path exposure (lineage)  _(Enterprise)_
- `GET /api/pro/taint/{tok}` — Transaction-path exposure (lineage) — DEPRECATED alias  _(Enterprise)_
- `GET /api/pro/lineage/{tok}` — Coin lineage  _(Enterprise)_
- `GET /api/pro/spend-graph/{addr}` — Spend graph  _(Enterprise)_

### Supply
- `GET /api/supply-demand` — Supply & demand map
- `GET /api/supply-demand/cohort/{tier}` — Supply cohort drilldown

### wBTX
- `GET /api/wbtx/summary` — wBTX bridge summary
- `GET /api/wbtx/reserve` — wBTX reserve vs supply
- `GET /api/wbtx/ledger` — wBTX mint/redeem ledger
- `GET /api/wbtx/reconcile` — wBTX peg reconciliation (Walk)