[ FIRST LIGHT — COMPLETE API REFERENCE ✦ ]

the full explorer + provenance surface — public chain data, and token-gated provenance · forensics · supply-demand · observatory · data-banks. Bounded, neutral, exportable. Programmatic access to the gated lenses is an Enterprise feature.
machine-readable spec: openapi.json · openapi.yaml  (OpenAPI 3.1)  |  97 live endpoints.
ⓘ PROVABLE FACTS, NOT GUESSES — what this API will NEVER return

No entity names. No identity. No ownership or “holdings.” No risk / taint / scam / AML labels. None of those are provable on-chain for BTX, so the API does not ship them. Every token-gated payload carries a caveat string; keep it attached when you display or redistribute results.

Every figure is a neutral on-chain fact: provenance (value traced FROM an address), funding sources (value that came INTO it), co-spend (addresses that appeared together as inputs), and the derived data-bank series. Interpretation is yours.

AUTHENTICATION & TIERING

Token-gated endpoints require a bearer token in the Authorization header. Tokens are issued per customer and map to a tier (Basic / Pro / Enterprise) that sets depth, export, feature and rate-limit ceilings. Tokens are stored server-side as a SHA-256 hash — the plaintext is shown once at issue time and cannot be recovered. The public chain/explorer endpoints (see PUBLIC CHAIN) need no token.

# every gated request carries the bearer token
Authorization: Bearer flp_YOUR_TOKEN_HERE

Enterprise  Programmatic API access is licensed for Enterprise. Basic and Pro tokens power the interactive web app; if used for programmatic access to a lens their tier does not include, they return 403. Connected byron-pool miners can mint a free Basic token via POST /api/premium/pool-miner/claim.

GATE ORDER (every gated route)
401 valid token? 429 under rate limit? 403 tier has the lens? 200 served & billed

Only a fully authorized request is counted against your usage; a 401/429/403 is not billed. Confirm a token is live (tier, limits, features, rate ceiling) with GET /api/premium/whoami — it is never rate-limited or billed.

BASE URL

https://api-explorer.btxbyronbay.com/api      # production
https://<your-explorer-host>/api          # self-hosted

TIER LIMITS

tierhopsfanoutnodes export (CSV)lensesAPIrate limit
Basic320100 provenance · origin30 / min
Pro1050300 yesprovenance · reverse · cluster · origin120 / min
Enterprise151001000 yesall lenses + taint/exposure · shield-linkage · query · anomalies · observatory · data-banks · sell-pressureyes600 / min

hops = trace depth · fanout = max edges expanded per node · nodes = max addresses returned. Results past the cap set "truncated": true (or hasMore). Rate limits are operator-tunable via EXPLORER_RATELIMIT_{BASIC,PRO,ENTERPRISE}; the numbers above are defaults. Per-tier feature gates: provenance/origin = Basic+, reverse/cluster = Pro+. taint/exposure and shield-boundary are Pro+ (Pro = direct/1-hop, Enterprise = full indirect); the query engine, anomaly feed, network observatory, certificate/verify, as-of snapshots, attribution/lineage data-banks, shield-linkage and the sell-pressure curve are Enterprise.

RATE LIMITS

Each token gets a per-tier request budget (token-bucket, refilled continuously — Basic: 30, Pro: 120, Enterprise: 600 rpm). Exceeding it returns 429 with a Retry-After header (seconds until a slot frees). Basic draws from a single cross-worker per-token bucket (a shared token self-throttles); Pro/Enterprise use a per-worker bucket. whoami is not rate-limited.

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{ "error": "rate_limited", "retryAfter": 12,
  "detail": "rate limit exceeded (600/min for your tier); retry in 12s" }

QUICKSTART — mint a token, make your first call

# 1 · operator mints a per-user token (admin only — plaintext shown ONCE)
curl -s -X POST https://api-explorer.btxbyronbay.com/api/premium/admin/tokens \
  -H "Authorization: Bearer $EXPLORER_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tier":"enterprise","label":"acme-otc-desk"}'
# → { "token": "flp_…", "token_sha256": "…", "tier": "Enterprise", … }  (store flp_… now)

# 2 · confirm the token + see your limits
curl -s https://api-explorer.btxbyronbay.com/api/premium/whoami \
  -H "Authorization: Bearer $TOKEN"

# 3 · first real call — forward provenance for an address
curl -s "https://api-explorer.btxbyronbay.com/api/provenance/$ADDR?mode=traceable" \
  -H "Authorization: Bearer $TOKEN"

# 4 · CSV export (Pro / Enterprise)
curl -s "https://api-explorer.btxbyronbay.com/api/reverse/$ADDR?format=csv" \
  -H "Authorization: Bearer $TOKEN" -o reverse.csv

Pool miners skip step 1: POST /api/premium/pool-miner/claim with your {"address":"btx1…"} payout address mints a free Basic token.

ENDPOINTS

Every gated endpoint is listed below with its tier, params, response key fields, bounds and the neutral caveat. Path params are shown as {name}.

Auth & Identity 6 Watchlist 3 Provenance & Forensics 19 Query Engine 3 Anomalies 4 Observatory 7 Live Feeds 1 Cards 9 Data-Banks 7 Trading & OTC 1 Public Chain 33

AUTH & IDENTITY

GET/api/premium/whoamiAny valid token

Echo the caller's tier, depth limits, export/feature flags and rate ceiling. Not rate-limited, not billed.

RESPONSE (key fields)

tier, limits{hops,fanout,nodes}, export, features[], api, rateLimitPerMin, tokenSource, caveat

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/premium/pool-miner/statusPublic

Count of active byron-pool miners the free-Basic perk matches against (count only, never addresses).

RESPONSE (key fields)

enabled, minerCount, lastRefreshOk, stale, note

POST/api/premium/pool-miner/claimPublic (per-IP limited)

Connected byron-pool miner claims free Basic access with their payout address. Membership hit mints a Basic token (shown once).

BODY (JSON)

address: btx1... (your BTX payout address)

RESPONSE (key fields)

ok, token (ONCE), tier, limits, export, features, api, expires_ts, note, caveat

POST/api/premium/admin/tokensAdmin token

Mint a per-user token. Plaintext returned ONCE; only sha256 is stored.

BODY (JSON)

tier: basic|pro|enterprise, label: optional operator note, expires_ts: optional unix int

RESPONSE (key fields)

token (ONCE), token_sha256, tier, tier_key, label, created_ts, expires_ts, note

GET/api/premium/admin/tokensAdmin token

List tokens (metadata only - no plaintext).

RESPONSE (key fields)

count, tokens[]{token_sha256,tier,label,created_ts,revoked_ts,expires_ts,calls,active}, note

DELETE/api/premium/admin/tokens/{ident}Admin token

Revoke a token by sha256 or prefix.

PARAMS

ident (path, required) — token sha256 or unique prefix

RESPONSE (key fields)

revoked count / status

WATCHLIST

POST/api/premium/watchlistAny valid token

Add an address (with optional label) to the caller's private list.

BODY (JSON)

address: btx1..., label: optional note

RESPONSE (key fields)

ok / stored

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/premium/watchlistAny valid token

List watched addresses with a neutral on-chain activity summary each.

RESPONSE (key fields)

count, watchlist[]{address,label,createdTs,activity{balanceBtx,receivedBtx,firstSeen,lastSeen,inTxCount,outTxCount}}, caveat

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

DELETE/api/premium/watchlist/{address}Any valid token

Remove one address from the caller's list.

PARAMS

address (path, required) — btx1 address to remove

RESPONSE (key fields)

ok / removed

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

PROVENANCE & FORENSICS

GET/api/provenance/{addr}Basic+ (CSV: Pro/Enterprise)

Forward fund-flow: value that provably traces FROM the address, with proportional (haircut) attribution.

PARAMS

addr (path, required) — root address · mode (query) — traceable (default lens mode) · format (query) — csv for a CSV download (Pro/Enterprise only; else 403)

RESPONSE (key fields)

root, mode, totalOriginatedBtx, totalBalanceReachedBtx, totalTraceableUnspentBtx, addressesReached, truncated, tree[], tier, limits, exportable, caveat

BOUNDS / PAGINATION

Bounded by tier hops/fanout/nodes; results past the cap set truncated:true.

CAVEAT

Traceable value is a proportional flow share, not an ownership assertion.

GET/api/reverse/{addr}Pro+ (CSV: Pro/Enterprise)

Backward funding-source trace: value that provably flowed INTO the address, attributed up the spend graph.

PARAMS

addr (path, required) · format (query) — csv export

RESPONSE (key fields)

root, totalReceivedBtx, totalTracedSourcesBtx, sourcesCount, tree[], tier, limits, exportable, caveat

BOUNDS / PAGINATION

Bounded by tier hops/fanout/nodes.

CAVEAT

A funding source is where value came FROM; not an owner/sender identity.

GET/api/cluster/{addr}Pro+ (CSV: Pro/Enterprise)

Co-spend set: addresses that appeared together as inputs in the same tx(s). NOT proof of common ownership.

PARAMS

addr (path, required) · format (query) — csv export

RESPONSE (key fields)

root, memberCount, evidenceTxCount, members[]{address,sharedTxCount,sharedTxids,firstSeen,lastSeen}, tier, exportable, caveat

BOUNDS / PAGINATION

Bounded by tier fanout/nodes.

CAVEAT

Co-spending is a provable co-occurrence and is NOT proof of common ownership.

GET/api/origin/{addr}Basic+ (root-validity: Enterprise; CSV: Pro/Enterprise)

Origin trace to coinbase roots (which mined coins ultimately funded this address). Enterprise adds an orphan/reorg/conflicting-spend root-validity forensic.

PARAMS

addr (path, required) · win (query) — time window; default all · format (query) — csv export

RESPONSE (key fields)

root, tree[], incoming[] (cap 40), window, tier, limits, exportable, validityNote (non-Ent), caveat

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/w2w/{a}/{b}Any valid token

Wallet-to-wallet: provable direct transfers where A was an input and B an output of the same tx.

PARAMS

a (path, required) — from address (btx1...) · b (path, required) — to address (btx1...) · win (query) — 1h|24h|7d|30d · from (query) — unix int or ISO · to (query) — unix int or ISO

RESPONSE (key fields)

transfers/edges, window, tier, caveat

BOUNDS / PAGINATION

cap = max(50, tier.fanout*5).

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied. A->B is a provable on-chain transfer fact (A was an input, B an output of the same tx); it is NOT an ownership or identity claim.

GET/api/pro/counterparties/{addr}Any valid token

Ranked addresses this wallet sent to / received from - a neutral on-chain volume ranking.

PARAMS

addr (path, required) · win (query) — 1h|24h|7d|30d · from (query) · to (query)

RESPONSE (key fields)

counterparties (top 80), window, tier, caveat

BOUNDS / PAGINATION

cap = max(100, tier.nodes*2), top=80.

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied. Counterparties are addresses this wallet sent to / received from; a neutral on-chain volume ranking, NOT an ownership or identity claim.

GET/api/pro/otc/{addr}Pro+

Pre-OTC counterparty check: neutral forensic report on an address before settling a deal. Depth scales with tier (Enterprise = deep).

PARAMS

addr (path, required) — btx1..., len 20-120 · amount (query) — stated deal amount (optional) · win (query) — time window; default all

RESPONSE (key fields)

report body {verdict, toxicity{band: notable|elevated|benign|neutral, glyph, score, evidence: coinbase mined-fraction + first-spend latency + coin-age}, provenance, validity, wallet, balanceCheck, cluster, flags, incoming}, window, tier, reportId, sharePath (/otc.html?r=<rid>)

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/otc/report/{rid}Public (shareable)

Fetch a frozen Pre-OTC report by id. No token - both deal parties read identical facts.

PARAMS

rid (path, required) — report id

RESPONSE (key fields)

frozen report record (verbatim); 404 if unknown

GET/api/address/{addr}/miningPublic

Neutral mining badge: whether an address received coinbase output, and the pool mix (block production, never fund ownership).

PARAMS

addr (path, required) — btx1..., len 20-120

RESPONSE (key fields)

address, isMiningAddress, coinbaseReceiveCount, coinbaseReceivedBtxSampled, sampledReceives, sampleBounded, pools[], note, caveat

BOUNDS / PAGINATION

sample bounded at 30 receives.

GET/api/pro/as-of/balance/{address}Pro+

Point-in-time balance of an address at instant t.

PARAMS

address (path, required) · t (query) — unix ts; default now

RESPONSE (key fields)

balance-as-of body, tier, caveat

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/as-of/{lens}/{root}Enterprise

Frozen point-in-time snapshot of a lens (provenance|reverse|cluster) at instant t. History begins at first query.

PARAMS

lens (path, required) — provenance|reverse|cluster · root (path, required) · t (query) — unix ts; default now

RESPONSE (key fields)

found, lens, root, queriedAsOf/asOf, snapshot..., tier, caveat

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/certificate/{address}Enterprise

Signed provenance certificate for an address (JSON or rendered HTML).

PARAMS

address (path, required) · format (query) — json (default) | html

RESPONSE (key fields)

certificate document (json) or text/html page

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

POST/api/pro/verifyEnterprise

Verify a previously issued provenance certificate document.

BODY (JSON)

<certificate document>: the JSON certificate to verify

RESPONSE (key fields)

verification result, tier

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/signalsEnterprise

Signals workspace: aggregate neutral on-chain signal feed.

PARAMS

window (query) · hours (query)

RESPONSE (key fields)

signals payload, tier (or {error:unavailable} if module absent)

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/mempool-firstseen/{txid}Enterprise

Our node's first-seen instant for a tx in the mempool (ephemeral, un-backfillable). Absence stated, never implied.

PARAMS

txid (path, required)

RESPONSE (key fields)

txid, found, firstSeenMs, firstSeenIso, heightAtSeen, feeRate, feeSats, vsize, bip125Replaceable, ancestorCount, confirmedTimeMs, deltaBeforeBlockMs, tier, caveat

CAVEAT

Our node's own first-seen instant for this transaction in the mempool — an ephemeral, un-backfillable local observation, NOT an on-chain/consensus timestamp and not an assertion of origin, ownership, or identity.

GET/api/pro/taint/{tok}Pro (direct/1-hop) / Enterprise (full indirect)

Taint-tracing engine: descent taint fraction over on-chain value-flow edges under a chosen accounting model. Pro = direct/1-hop; Enterprise = full multi-hop indirect + model choice.

PARAMS

tok (path, required) — btx1... address OR txid:n outpoint · model (query) — haircut | fifo | poison · source (query) — restrict to a specific flagged btx1... source (optional) · hops (query) — Enterprise only; 1..tier.hops · limit (query) — per-source page size 1-500 · cursor (query) — per-source pagination offset

RESPONSE (key fields)

pillar, available, subject, outpoint, model, sourceFilter, scope, taintFraction, receivedBtx, receivedTaintedBtx, held{ heldTaintedBtx + shield-boundary bucket }, graphInboundBtx, sources[] (paginated), sourceCount, returned, limit, cursor, nextCursor, hasMore, hops, fanout, nodesWalked, truncated, flaggedLoaded, method, engine=taint-engine/1.0.0, source, tier, caveat

BOUNDS / PAGINATION

perSource breakdown paginated by cursor (limit 1-500); nextCursor + hasMore.

CAVEAT

A taint fraction is an ARITHMETIC descent measure over observed on-chain value-flow edges under a stated accounting model - never an accusation, an identity claim, or a statement of ownership. A flag is an append-only, evidence-anchored observation. Results are bounded (hop/fanout/node caps) and conservative (under-counting) beyond the horizon.

GET/api/pro/exposure/{addr}Pro (direct) / Enterprise (indirect + methodAppendix)

Glass-box category exposure score (0-100) aggregating descent taint by category. Enterprise adds indirect multi-hop reach + the auditable method appendix.

PARAMS

addr (path, required) — btx1... address · model (query) — haircut | fifo | poison

RESPONSE (key fields)

pillar, available, subject, model, scope, exposureScore (0-100), band, glyph, byCategory{flagged,mining,shield,service,unknown}, directSources, miningProvenance, serviceTouch, hops, nodesWalked, truncated, methodAppendix, method, engine=taint-engine/1.0.0, source, tier, caveat

CAVEAT

An exposure score is a glass-box, methodology-versioned aggregation of descent taint by category - a defensible, auditable OBSERVATION, not a risk verdict, a compliance determination, or advice. Categories and weights are disclosed in the attached method appendix.

GET/api/pro/shield-boundaryPro+

Shield/unshield boundary lens: value crossing the shielded-pool boundary + shielded-pool net-flow over time.

PARAMS

window (query) — time window · hours (query) · direction (query) — shield | unshield (filter) · limit (query) — event page size · offset (query) — event pagination offset

RESPONSE (key fields)

summary{currentShieldedPoolBtx, totalShieldInBtx, totalUnshieldOutBtx, poolTrend, shieldEventCount, unshieldEventCount, firstBoundaryUtc, lastBoundaryUtc}, events[] (paginated){direction,amountBtx,height,tier,unshieldFrac,address}, netFlow[] (daily), pagination{limit,offset,total,hasMore}, methodologyVersion=shield-boundary/v1, method, source, available, window, tier, caveat

BOUNDS / PAGINATION

events paginated by limit/offset.

CAVEAT

Boundary crossings are provable arithmetic over the transparent chain. UNSHIELD = outputs with no transparent minting ancestor (origin-opaque); SHIELD = value sent into the shielded pool by conservation (transparent in - out - fee). Neutral supply observations; nothing about who controls an address or why funds crossed.

GET/api/pro/shield-linkage/{target}Enterprise

PROBABILISTIC shielded-pool round-trip candidates for an unshield (amount/timing correlation). Never a definite link - confidence is capped and dampened by the anonymity set.

PARAMS

target (path, required) — txid or btx1... address · window (query) · hours (query) · limit (query) — max candidates

RESPONSE (key fields)

anonymitySetSize, candidates[]{amountMatchPct,timingGapHours,correlationScore}, confidence (capped, anonymity-dampened), methodologyVersion=shield-boundary/v1, window, tier, caveat

CAVEAT

PROBABILISTIC round-trip correlation (shielded-pool amount/timing heuristic), NOT a definite link. Every candidate carries an explicit confidence and its basis (amount-match %, timing gap, anonymity-set size); confidence is capped and dampened by the anonymity set.

QUERY ENGINE

POST/api/pro/queryEnterprise

Investigation query engine - filter/sort/paginate outputs, transactions or addresses over a bounded predicate.

BODY (JSON)

entity: output|transaction|address, filters: [] predicate list, sort: sort spec, page: cursor/page

RESPONSE (key fields)

entity, filters, sort, count, countCapped, truncated, asOfHeight, results[], cursor, facets, note, tier, caveat

BOUNDS / PAGINATION

Cursor-paginated; fail-open returns neutral empty result (never fabricated).

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

POST/api/pro/query/countEnterprise

Live count preview over the same bounded predicate (capped).

BODY (JSON)

entity: output|transaction|address, filters: [] predicate list

RESPONSE (key fields)

entity, filters, count, countCapped, note, tier, caveat

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

POST/api/pro/query/facetsEnterprise

Facet breakdown for the same bounded predicate.

BODY (JSON)

entity: output|transaction|address, filters: [] predicate list

RESPONSE (key fields)

entity, filters, facets, tier, caveat

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

ANOMALIES

GET/api/pro/anomaliesEnterprise

Anomaly event feed (id-cursor paginated). Neutral, un-backfillable observations.

PARAMS

window (query) · hours (query) · since (query) — poll forward (id>since) · before (query) — scroll back (id<before) · limit (query) — capped · minNotability (query) · type (query) — comma-separated detector types · rarity (query) — uncommon|rare|exceptional (>= rank)

RESPONSE (key fields)

count, cursor{newest,oldest}, window{key,sinceUtc,nowUtc}, collectorAvailable, events[], note, caveat, tier

BOUNDS / PAGINATION

id-based cursor (since ASC / before DESC), always newest-first.

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/anomalies/typesEnterprise

Catalog of anomaly detectors + rarity ladder.

RESPONSE (key fields)

detectors, rarityLadder[uncommon,rare,exceptional], note, collectorAvailable, caveat, tier

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/anomalies/summaryEnterprise

Rollup of anomalies by type and rarity over a window.

PARAMS

window (query) · hours (query)

RESPONSE (key fields)

total, byType, byRarity, window{key,sinceUtc,nowUtc}, collectorAvailable, note, caveat, tier

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/anomalies/{event_uid}Enterprise

Single anomaly event detail by uid.

PARAMS

event_uid (path, required)

RESPONSE (key fields)

event fields + tier; {found:false,...} if absent (HTTP 200)

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

OBSERVATORY

GET/api/pro/observatory/summaryEnterprise

Network Observatory - summary pillar.

PARAMS

window (query) · hours (query)

RESPONSE (key fields)

builder payload + tier; {available:false,...} neutral absence if module missing

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/observatory/propagationEnterprise

Network Observatory - propagation pillar.

PARAMS

window (query) · hours (query)

RESPONSE (key fields)

builder payload + tier; {available:false,...} neutral absence if module missing

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/observatory/feemarketEnterprise

Network Observatory - feemarket pillar.

PARAMS

window (query) · hours (query)

RESPONSE (key fields)

builder payload + tier; {available:false,...} neutral absence if module missing

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/observatory/compositionEnterprise

Network Observatory - composition pillar.

PARAMS

window (query) · hours (query)

RESPONSE (key fields)

builder payload + tier; {available:false,...} neutral absence if module missing

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/observatory/orphan-rateEnterprise

Per-pool orphan rate over a height band (apples-to-apples). A tag names the pool, not the operator.

PARAMS

window (query) — blocks (50-2000)

RESPONSE (key fields)

pillar, available, pools[]{pool,blocksMined,orphaned,totalSeen,orphanRatePct,provisional}, window{...}, maturity{...}, method, source, note, caveat, tier

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/observatory/block-propagationEnterprise

Local first-sight arrival timing for recent blocks (single-vantage; un-backfillable).

PARAMS

limit (query) — 1-300

RESPONSE (key fields)

pillar, available, vantage, blocks[]{height,hash,lagMs,lagSecs,nTx,sizeBytes,weight,...}, stats{medianLagMs,p90LagMs,...}, method, source, note, caveat, tier

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/observatory/peer-topologyEnterprise

This node's own peer set from getpeerinfo (single-vantage view, not a global topology).

RESPONSE (key fields)

pillar, available, vantage, snapshot{...}, peers[]{peerKey,network,pingMs,syncedBlocks,subver,...}, byNetwork[], bySubver[], history[], method, source, note, caveat, tier

BOUNDS / PAGINATION

peer history bounded to last 120 polls.

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

LIVE FEEDS

GET/api/pro/mempool-streamPro+

Live first-seen mempool tx stream from our vantage (calm by design on a coinbase-only chain).

PARAMS

limit (query) — 1-200 · since (query) — ms; return newer than

RESPONSE (key fields)

pillar, available, vantage, quiet, mempoolDepth, txs[], stats{...}, lastSeenMs, serverNowMs, method, source, note, caveat, tier

BOUNDS / PAGINATION

limit 1-200; since filters node_time_ms>since, newest-first.

CAVEAT

Our node's own first-seen instant for this transaction in the mempool — an ephemeral, un-backfillable local observation, NOT an on-chain/consensus timestamp and not an assertion of origin, ownership, or identity.

CARDS

GET/api/pro/mint-certificate/{target}Pro / Enterprise (export: Enterprise)

Origin-verified mint certificate for a target (address/tx). Tier-3 pool-ledger PROOF + exportable cert are Enterprise.

PARAMS

target (path, required) — address or txid

RESPONSE (key fields)

ladder{tier1..tier3}, exportable, tier, ... (Pro caps at Tier-2 node-confirmed)

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/settlement/{target}Pro (badge) / Enterprise (full)

Settlement-safety / reorg-finality report. Pro = badge + depth distribution; Enterprise = full ancestor-orphan + conflict log.

PARAMS

target (path, required) · kind (query) — auto (default) | block | tx | address

RESPONSE (key fields)

target, kind, badge, confirmations, finalityConfidence, reorgDepthDistribution, (Enterprise: ancestor-orphan/conflict detail), tier, caveat

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/mining-centralizationPro+

Producer-concentration aggregate (top-N / Nakamoto / HHI).

PARAMS

window (query) · hours (query)

RESPONSE (key fields)

centralization metrics, tier

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/dusting/scanEnterprise

Dusting / address-poisoning scan + alert feed over a window.

PARAMS

window (query) · hours (query)

RESPONSE (key fields)

dusting scan payload, tier

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/dusting/address/{address}Pro+

Dusting / address-poisoning flag for a single address.

PARAMS

address (path, required)

RESPONSE (key fields)

dust flag payload, tier

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/wallet-profile/{address}Pro+

Neutral wallet-behaviour profile (activity shape, consolidation, timing).

PARAMS

address (path, required)

RESPONSE (key fields)

profile payload, tier

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/coin-agePro+

Network-wide coin-age / dormancy aggregate.

PARAMS

window (query) · hours (query)

RESPONSE (key fields)

coin-age aggregate, tier

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/coin-age/{address}Pro+

Coin-age / dormancy for a single address.

PARAMS

address (path, required) · window (query) · hours (query)

RESPONSE (key fields)

coin-age payload, tier

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

GET/api/pro/propagationEnterprise

Propagation-health / eclipse-risk report from this vantage.

PARAMS

window (query) · hours (query)

RESPONSE (key fields)

propagation report, tier

CAVEAT

Neutral on-chain facts only. No entity names, identity, ownership, holdings, or risk/taint claims are asserted or implied.

DATA-BANKS

GET/api/pro/label/{addr}Enterprise

Attribution label(s) for an address (observed role: coinbase/pool tag or category watchlist). Not ownership.

PARAMS

addr (path, required)

RESPONSE (key fields)

pillar, available, address, labelled, poolLabels[] (<=50), watchlist[] (<=25), method, source, tier, caveat

CAVEAT

Attribution, not ownership or identity. A label reflects an OBSERVED role - a self-declared coinbase/pool tag or a category watchlist entry - derived from on-chain facts. It is never a claim about who controls an address or about any named person.

GET/api/pro/labelsEnterprise

Attribution label directory, keyset-paginated by category.

PARAMS

category (query) — pool|all|exchange|otc|bridge|mixer|custodian · limit (query) — 1-500 · cursor (query) — keyset rowid

RESPONSE (key fields)

pillar, available, category, rows[], returned, limit, cursor, nextCursor, hasMore, method, source, tier, caveat

BOUNDS / PAGINATION

Keyset cursor by rowid; nextCursor + hasMore for the next page.

CAVEAT

Attribution, not ownership or identity. A label reflects an OBSERVED role - a self-declared coinbase/pool tag or a category watchlist entry - derived from on-chain facts. It is never a claim about who controls an address or about any named person.

GET/api/pro/lineage/{tok}Enterprise

Coin lineage (dominant-coinbase funding path) up/down from a txid or txid:vout.

PARAMS

tok (path, required) — txid or txid:vout · dir (query) — up (default) | down · depth (query) — 1..tier.hops

RESPONSE (key fields)

pillar, available, query, txid, n, dir, depthCap, fanoutCap, nodeCap, found, returned, rows[], method, source, tier, caveat

BOUNDS / PAGINATION

Bounded by tier hops/fanout/nodes.

CAVEAT

Coin ancestry is the collector's precomputed dominant-coinbase resolution (largest-value funding path). Neutral on-chain provenance, NOT a statement of ownership, custody, or identity.

GET/api/pro/spend-graph/{addr}Enterprise

Directed value-flow spend graph (bounded BFS) out/in/both from an address.

PARAMS

addr (path, required) · dir (query) — out (default) | in | both · hops (query) — 1..min(6,tier.hops) · limit (query) — 1..min(500,tier.nodes)

RESPONSE (key fields)

pillar, available, address, dir, hops, limit, returned, hasMore, nodeCount, edges[], method, source, tier, caveat

BOUNDS / PAGINATION

Bounded BFS; hasMore flags truncation.

CAVEAT

Directed value-flow edges are on-chain input->output attributions. Common-input and change heuristics can mis-attribute; an edge is a movement of value, NOT proof of common ownership or identity.

GET/api/pro/mempool/floorPro+

Mempool fee-floor time series + latest smart-fee estimate curve.

PARAMS

window (query) — 1h|6h|24h|today|7d|30d|all · limit (query) — 1-500

RESPONSE (key fields)

pillar, available, window, returned, limit, latest, floorSeries[], latestFeeEstimate[], method, source, tier, caveat

BOUNDS / PAGINATION

newest-first, LIMIT limit (1-500); no cursor.

CAVEAT

Model/observational market data for informational use only - not financial advice, and not a consensus or exchange-audited price.

GET/api/pro/miner-first-spendPro+

Coinbase first-spend feed: when mined coins were first moved, by pool.

PARAMS

limit (query) — 1-500 · since (query) — first_spend_time >= since · cursor (query) — pages older (first_spend_time < cursor) · pool (query) — filter by pool_identity

RESPONSE (key fields)

pillar, available, since, cursor, pool, returned, limit, nextCursor, hasMore, rows[], method, source, tier, caveat

BOUNDS / PAGINATION

Cursor by first_spend_time; nextCursor + hasMore.

CAVEAT

Attribution, not ownership or identity. A label reflects an OBSERVED role - a self-declared coinbase/pool tag or a category watchlist entry - derived from on-chain facts. It is never a claim about who controls an address or about any named person.

GET/api/pro/realized-pricePro+

Realized-price snapshots time series (model/observational).

PARAMS

window (query) — 7d|30d|90d|180d|1y|all · limit (query) — 1-500

RESPONSE (key fields)

pillar, available, window, returned, limit, latest, snapshots[], method, source, tier, caveat

BOUNDS / PAGINATION

newest-first, LIMIT limit; no cursor.

CAVEAT

Model/observational market data for informational use only - not financial advice, and not a consensus or exchange-audited price.

TRADING & OTC

GET/api/pro/sell-pressureEnterprise

Miner forward sell-pressure curve: projected miner-mined supply likely to first-move (leave coinbase) over a horizon, by pool, from each pool's empirical hold distribution applied to its current unspent-coinbase stock.

PARAMS

pool (query) — pool identity | all · horizon (query) — projection days, 1-180 · limit (query) — byPool page size · offset (query) — byPool pagination offset

RESPONSE (key fields)

currentOverhangBtx, byPool[] (paginated){pool, medianHoldDays, confidence}, projectedReleaseCurve[]{day,expectedBtx,cumulativeBtx}, recentSellThrough{last7d,last30d}, method, source, confidence, tier, caveat

BOUNDS / PAGINATION

byPool paginated by limit/offset.

CAVEAT

PROJECTION FROM HISTORICAL BEHAVIOUR - NOT financial advice, NOT a price target, NOT a claim that any miner will or will not sell. The curve is expected miner-mined coinbase supply that first MOVES on-chain per day, from each pool's empirical hold-to-first-spend distribution over its current unspent-coinbase stock. 'First move' may be a sale, consolidation, transfer or treasury move - on-chain we cannot tell which.

GET/api/pro/supply-wallsEnterprise

On-chain cost-basis distribution (URPD) of the transparent unspent supply: BTX bucketed by the price at which it was last acquired, so support/resistance "walls" can be read from real cost basis. Priced sliver only — unpriced supply is reported, never imputed.

PARAMS

bands (query) — number of price bands · window (query) — realized-price window · limit (query) — urpd page size · offset (query) — urpd pagination offset

RESPONSE (key fields)

urpd[]{...}, majorWalls[]{...}, pricedSupplyBtx, unpricedSupplyBtx, unpricedBreakdownBtx, totalSupplyBtx, inProfitSupplyBtx, inLossSupplyBtx, inProfitPctOfPriced, pricedPctOfSupply, windowedOutBtx, spotPriceUsd, realizedPriceUsd, priceRangeUsd, bands, window, pagination, method, source, available, tier, caveat

BOUNDS / PAGINATION

urpd bands paginated by limit/offset.

CAVEAT

A NEUTRAL on-chain observation of cost basis, NOT order-book depth (BTX has no live order book yet), NOT a price target, NOT advice. Only the priced sliver of supply is included (pricedPctOfSupply); unpriced supply is reported separately and never imputed.

GET/api/pro/slippageEnterprise

Clip slippage estimator: given a clip size (BTX to buy or sell), estimate on-chain price impact by walking the URPD cost-basis walls outward from spot until the clip is filled. A model estimate from on-chain cost basis, not an order book.

PARAMS

clip (query) — clip size in BTX · side (query) — buy | sell · window (query) — realized-price window · bands (query) — URPD band resolution

RESPONSE (key fields)

clipBtx, side, slippagePct, avgSlippagePct, estFillPriceUsd, avgFillPriceUsd, spotPriceUsd, realizedPriceUsd, priceRangeUsd, supplyEatenBtx, sideAvailableBtx, sideAvailableLabel, bandsCrossed, wallsCrossed, exceedsPricedSupply, pricedSupplyBtx, pricedPctOfSupply, confidence, window, generatedUtc, method, source, available, tier, caveat

CAVEAT

A MODEL ESTIMATE from on-chain cost basis — NOT order-book depth (BTX has no live order book yet), NOT a guaranteed fill, NOT advice. Bounded clip sizes; exceedsPricedSupply flags a clip larger than the priced sliver.

POST/api/desk/price-impactEnterprise

POST form of the clip slippage estimator (same model and response as GET /api/pro/slippage). Body: { "clip": <btx>, "side": "buy|sell", "window"?: "<win>", "bands"?: <n> } (clipBtx accepted as an alias for clip).

PARAMS

clip (body, required) — clip size in BTX · side (body) — buy | sell · window (body) · bands (body)

RESPONSE (key fields)

clipBtx, side, slippagePct, avgSlippagePct, estFillPriceUsd, avgFillPriceUsd, spotPriceUsd, realizedPriceUsd, priceRangeUsd, supplyEatenBtx, sideAvailableBtx, sideAvailableLabel, bandsCrossed, wallsCrossed, exceedsPricedSupply, pricedSupplyBtx, pricedPctOfSupply, confidence, window, generatedUtc, method, source, available, tier, caveat

CAVEAT

A MODEL ESTIMATE from on-chain cost basis — NOT order-book depth, NOT a guaranteed fill, NOT advice.

GET/api/pro/miner-convictionPro+

Per-pool miner conviction: how long each pool holds its mined coinbase before it first moves on-chain (hold-to-first-spend). A neutral behavioural observation — long hold reads as conviction / accumulation, fast spend reads as distribution.

PARAMS

pool (query) — pool identity | all · window (query) — trend window (affects the trend only, not headline stats) · limit (query) — byPool page size · offset (query) — byPool pagination offset

RESPONSE (key fields)

byPool[] (paginated){...}, network{...}, scope, window, windowNote, pagination, method, source, available, tier, caveat

BOUNDS / PAGINATION

byPool paginated by limit/offset. The window selector re-windows the trend series only; headline conviction stats are computed over full history (see windowNote).

CAVEAT

A NEUTRAL behavioural observation over the transparent chain — never a claim about intent, ownership, or identity. "First move" may be a sale, consolidation, transfer or treasury move.

PUBLIC CHAIN

GET/api/tipPublic

Chain tip ticker (height, hash, difficulty, mempool).

RESPONSE (key fields)

ticker

GET/api/network/glancePublic

Network glance summary.

RESPONSE (key fields)

glance

GET/api/network/healthPublic

Chain + network + mempool health.

RESPONSE (key fields)

chain health

GET/api/network/economicsPublic

Emission economics at current height.

RESPONSE (key fields)

economics

GET/api/network/seriesPublic

Hashrate/difficulty/block-rate time series.

PARAMS

window (query) — 24h|7d|30d

RESPONSE (key fields)

{hashrate,difficulty,blockRate}

GET/api/network/forksPublic

Fork / sibling-race census + reorg banner.

RESPONSE (key fields)

forks census

GET/api/network/blocktimesPublic

Inter-block gap distribution + drought indicator.

PARAMS

window (query) — 24h|7d|30d

RESPONSE (key fields)

blocktimes

GET/api/network/difficultyPublic

Difficulty oscillation + next-block difficulty + hashrate overlay.

PARAMS

window (query)

RESPONSE (key fields)

difficulty

GET/api/network/concentrationPublic

Producer concentration (top-N / Nakamoto / HHI).

PARAMS

window (query)

RESPONSE (key fields)

concentration

GET/api/network/supplyPublic

Emission & halving analytic.

RESPONSE (key fields)

supply

GET/api/blocks/latestPublic

Latest N blocks.

PARAMS

n (query) — 1-50

RESPONSE (key fields)

[block rows]

GET/api/txs/latestPublic

Latest N confirmed txs.

PARAMS

n (query) — 1-25

RESPONSE (key fields)

[latest tx rows]

GET/api/blocksPublic

Paginated blocks.

PARAMS

page (query)

RESPONSE (key fields)

{blocks, page, lastPage}

GET/api/block/{ident}Public

Block detail by height or hash.

PARAMS

ident (path, required) — height or hash

RESPONSE (key fields)

block detail (404 if not found)

GET/api/tx/{txid}Public

Transaction detail (prevouts resolved).

PARAMS

txid (path, required)

RESPONSE (key fields)

tx detail (404 if not found)

GET/api/address/{addr}Public

Address page (aggregate + paginated rows).

PARAMS

addr (path, required) · page (query)

RESPONSE (key fields)

address page

GET/api/minersPublic

Block-production attribution by coinbase tag.

PARAMS

window (query) — recent N blocks · from (query) · to (query)

RESPONSE (key fields)

{total, miners[]}

GET/api/miner/{tag}Public

Blocks produced by one miner tag.

PARAMS

tag (path, required) · n (query) — 1-200 · from (query) · to (query)

RESPONSE (key fields)

miner blocks

GET/api/trace/{txid}Public

Bounded fund tracer (forward/back over the spend index).

PARAMS

txid (path, required) · dir (query) — back|forward · hops (query) — 1-10

RESPONSE (key fields)

trace graph (404 if not found)

GET/api/address/{addr}/flowsPublic

In/out flow edges for an address.

PARAMS

addr (path, required)

RESPONSE (key fields)

flows (bounded to 50 edges)

GET/api/address/{addr}/signalsPublic

Neutral on-chain wallet signals (bounded, cached).

PARAMS

addr (path, required) · tx (query) — context txid

RESPONSE (key fields)

signals

GET/api/mempoolPublic

Mempool summary + recent entries.

RESPONSE (key fields)

mempool

GET/api/chaintipsPublic

Chain tips (getchaintips).

RESPONSE (key fields)

[tips]

GET/api/orphansPublic

Indexed orphan blocks.

RESPONSE (key fields)

[orphans]

GET/api/reorgsPublic

Reorg events + miner note.

RESPONSE (key fields)

{events, minerNote}

GET/api/searchPublic

Search by height/hash/txid/address.

PARAMS

q (query, required) — query string

RESPONSE (key fields)

{type, target, ...}

GET/api/healthPublic

API/index health (ops).

RESPONSE (key fields)

{ok, indexed, node_blocks}

GET/api/pricePublic

Latest banked BTX spot price (model).

RESPONSE (key fields)

latest price row

GET/api/valuePublic

Quote a BTX amount at current or a given time.

PARAMS

btx (query, required) · at (query) — unix ts or omit

RESPONSE (key fields)

value quote

GET/api/tx/{txid}/valuePublic

Value of a tx's output at tx-time and now.

PARAMS

txid (path, required)

RESPONSE (key fields)

{txid, amount_btx, at_tx, current}

GET/api/address/{addr}/valuePublic

Balance/received value quote for an address.

PARAMS

addr (path, required)

RESPONSE (key fields)

{address, balance_btx, received_btx, balance_value, received_value}

GET/api/supply-demandPublic

On-chain supply map (coin-age & balance cohorts, net-flow, HODL waves).

PARAMS

window (query)

RESPONSE (key fields)

supply-demand map

GET/api/supply-demand/cohort/{tier}Public

Ranked addresses in one balance cohort + mining-origin mix.

PARAMS

tier (path, required) — balance cohort tier · limit (query) — 1-500

RESPONSE (key fields)

cohort drill-down

ERRORS

statusmeaning
401missing / unknown / revoked / expired token
403tier lacks the requested lens or export (or admin token required)
429rate limit exceeded — see Retry-After
400malformed request / bad params
404not found (unknown tx / block / report id)
503an optional module / collector DB is unavailable — served as neutral absence where possible

Collector-backed endpoints (observatory, mempool stream, data-banks) fail OPEN: when a proprietary collector DB is not readable they return available:false with empty rows and a note — an absence is stated, never a fabricated value.