# Settlement State — API Schema 1.0.0 · generated 2026-07-21T12:17:44Z · as of 2026-07-20 Base URL: `https://sttl.live/v1` (host-independent — also served on `app.sttl.live`). The artifacts are static files: `feed.json`, `history.json`, `ledger.json`, `evidence.json`, `validations.json`. ## API v2 — the resource tree The v2 API mirrors the product's object model: **what object am I acting on, over what horizon.** Every route is an alias slice over the same artifacts v1 already serves — no new data, nothing breaks, v1 stays. What v2 adds is engine-shaped payloads and one **uniform envelope** on every response. ### The envelope (every v2 response) ```json { "data": , "meta": { "unit": "gwei/gas", "as_of": "2026-07-20", "frequency": "daily", "horizon": "24h", // only where a horizon applies "method": "how the number is produced (from the evidence registry)", "evidence_class": "observed | measured | forecast | refused", "coverage": 3836, "freshness_days": 0, "version": "1.0.0", "source_artifact": "feed.json" } } ``` `meta` is populated from the artifacts themselves (evidence.json for unit/class/method where a metric governs the field; frequency, coverage and freshness from the data). **Refusal and pending records pass through verbatim** inside `data` with their `status` intact — a programmatic consumer gets the whole record, not a gap (the refusal charter, generalized to the API). ### Routes All v2 routes sit behind the same key / x402 gate and metering as `/v1/chains` (the free proof tier — `ledger`, `evidence`, `validations` — is unchanged). | method | route | returns | |---|---|---| | GET | `/v1/markets/{btc\|eth\|sol\|l2}/state` | current market state on the venue's native fee margin (+ operating rating) | | GET | `/v1/markets/{btc\|eth\|sol\|l2}/fees` | the fee and where it sits in its trailing-year distribution, plus the 24h forward price | | GET | `/v1/markets/{btc\|eth\|sol\|l2}/forecast` | the 24h forecast + OOS validation (refused/pending venues pass their record through) | | GET | `/v1/markets/{btc\|eth\|sol\|l2}/history` | trailing daily settlement-fee history (native unit) | | GET | `/v1/markets/eth/blobs` | EIP-4844 blob base-fee state (the L2 data-availability input price) | | GET | `/v1/markets/sol/priority` | in-protocol priority-fee rank price + leader-revenue decomposition | | GET | `/v1/markets/sol/failure` | included-but-failed non-vote transaction share | | GET | `/v1/networks/{btc\|eth\|sol}/economics` | security budget (where measured) + operating dimensions | | GET | `/v1/protocols` | the routing-share list (a = R/G) — top by fees + fee-switch candidates | | GET | `/v1/protocols/{name}/claims` | one protocol's a = R/G row (name matched case-insensitively; 404 lists known names) | | GET | `/v1/tokens/{contract}/survival` | the token's observed survival state (every universe searched) | `l2` is the ARB/BASE/OP set: each `l2` sub-route returns a `{arb, base, op}` map. `eth` adds `/blobs`; `sol` adds `/priority` and `/failure` (its scarcity clears in rank and failure, not immediacy). A sub-resource a venue does not support is a 404, never a fabricated cell. ## API v1 — objects & artifacts (compatibility) The v1 surface is unchanged and stays supported. The object routes slice the same artifacts per venue (no envelope): ## Quickstart — one file, zero dependencies ``` curl -O /settlement_client.py python settlement_client.py summary # all venues, unit-labelled python settlement_client.py verify # recompute our hash chain; check us, don't trust us python settlement_client.py receipts # every forecast receipt AND refusal ``` Library use: `from settlement_client import Feed; Feed('').history_df('ETH')` (pandas optional). ## Anchoring The ledger head is anchored externally so history cannot be quietly rewritten, including by us: (1) OpenTimestamps calendar submissions (automated, hash-only); (2) Solana memo transactions carrying `settlement-ledger:` — prepared by the feed, broadcast by the operator's own wallet (keys never touch the data machine), recorded in anchors.jsonl with the tx signature. `settlement_client.py verify` lists both. ## Alerts (headless) `python3 settlement_client.py alerts rules.json ` — evaluate your own threshold/flip rules against the live feed; exit code 2 when fired (cron-friendly); flip-state kept beside the rules file. Rule = {id, path (dotted into feed.json), op: gt|lt|flip, value, note}. Pipe fired lines to Telegram/webhook — recipe in the client's docstring. In-app alerts (browser) are a separate, richer surface. ## Daily brief `feed.json.brief` (also `brief.md`): a rule-generated morning note — the largest measured changes across venues, salience-ranked, max 10 lines. Each line carries the `metric` id it is computed from; every id resolves in `evidence.json`. Generated from measured objects only — no editorial, no forecasts beyond receipted ones. ## Research findings `evidence.json.discoveries`: the results the measured objects operationalize, one sentence each. The full research program (with identification and falsifiers) publishes to a citable venue; the methods that connect it to the data are proprietary and are not described here or in any external artifact. ## History depth `history.json` carries each venue's FULL daily archive (BTC to 2011, ETH to genesis-era panel, SOL ~2y, L2s from first collection) — not a trailing window. ## Status contract Every chain block carries `status` in {ok | accruing | stale | refused | pending}, `stale_days` (per chain; stale when > `stale_after_days`), `sources` (provenance + quorum rule), and machine-readable counters (`days_accrued`/`days_required`) wherever something is accruing. Refused forecasts carry `reason_code`, the failing receipt numbers, and `unlock_criteria` — the refusal is falsifiable. ## Ledger verification History note, disclosed: the ledger schema was migrated once (2026-07-15, pre-launch; the premigration file is preserved in-repo). The current chain verifies from its genesis record. Verify against the RAW `ledger.jsonl` (published in site/), never a re-serialized copy; `ledger_head.json` carries the current head. Each `ledger.json` record: `prev` = SHA256 hex of the previous raw JSONL line (bytes, no trailing newline) in `ledger.jsonl`; first record uses `GENESIS`. Lines are `json.dumps(record, sort_keys=True)`. Forecast/score values are natural logs of the NATIVE unit (`space: log`, `base_unit` fields on records from schema 1.0.0); display reconciliation: `exp(value)/divisor` equals the `history.json` fee for that date (`realized_display` states it). ```python import hashlib, json prev = 'GENESIS' for raw in open('ledger.jsonl','rb'): raw = raw.strip() if not raw: continue rec = json.loads(raw) assert rec['prev'] == prev, 'CHAIN BROKEN' prev = hashlib.sha256(raw).hexdigest() print('chain ok, head', prev) ``` ## Versioning Semver `schema_version` in every artifact. Field additions = minor. Renames/removals = major with a parallel-emission window. Metric ids in `evidence.json` are permanent — never renamed, only deprecated. ## Metrics (from the evidence registry — same source as the data) | id | name | unit | class | chip | |---|---|---|---|---| | `arb.forecast_24h.fee` | ARB next-24h fee forecast | gwei/gas | pending | PENDING | | `arb.stables.usdt_transfer` | ARB stablecoin transfer cost | native units | measured | MEASURED | | `arb.state.fee` | ARB settlement fee | gwei/gas | observed | MEASURED | | `arb.state.fullness` | ARB capacity used | share | observed | MEASURED | | `arb.state.regime` | ARB congestion regime | boolean | measured | MEASURED | | `base.forecast_24h.fee` | BASE next-24h fee forecast | gwei/gas | pending | PENDING | | `base.stables.usdt_transfer` | BASE stablecoin transfer cost | native units | measured | MEASURED | | `base.state.fee` | BASE settlement fee | gwei/gas | observed | MEASURED | | `base.state.fullness` | BASE capacity used | share | observed | MEASURED | | `base.state.regime` | BASE congestion regime | boolean | measured | MEASURED | | `btc.benchmark.state_win_share` | BTC live benchmark win share | share | measured | MEASURED | | `btc.confirmation.p_within_k` | BTC confirmation probability by fee tier | probability | forecast | VALIDATED | | `btc.forecast_24h.fee` | BTC next-24h fee forecast | sat/vB | forecast | VALIDATED | | `btc.forecast_24h.pi` | BTC net-immediacy premium (pi) | sat/vB | measured | MEASURED | | `btc.secbudget.budget` | BTC security budget (B = D + F) | BTC/day | observed | MEASURED | | `btc.secbudget.coverage` | BTC security coverage (annualized B / issued supply) | share/yr | measured | MEASURED | | `btc.secbudget.user_share` | BTC user-funded share (U = F/B) | share | measured | MEASURED | | `btc.state.exit_prob_7d` | BTC regime exit probability (7d) | probability | measured | MEASURED | | `btc.state.fee` | BTC settlement fee | sat/vB | observed | MEASURED | | `btc.state.fullness` | BTC capacity used | share | design | DISPLAY-ONLY | | `btc.state.regime` | BTC congestion regime | boolean | measured | MEASURED | | `eth.benchmark.state_win_share` | ETH live benchmark win share | share | measured | MEASURED | | `eth.blob.base_fee` | ETH blob base fee (the L2 input price) | wei/blob-gas | observed | MEASURED | | `eth.forecast_24h.band` | ETH next-24h fee band (unlocked quantiles) | gwei/gas | forecast | VALIDATED | | `eth.forecast_24h.fee` | ETH next-24h fee forecast | gwei/gas | forecast | VALIDATED | | `eth.forecast_24h.pi` | ETH net-immediacy premium (pi) | gwei/gas | measured | MEASURED | | `eth.nowcast.fee` | ETH hourly nowcast | gwei/gas | design | DISPLAY-ONLY | | `eth.stables.usdt_transfer` | ETH stablecoin transfer cost | native units | measured | MEASURED | | `eth.state.exit_prob_7d` | ETH regime exit probability (7d) | probability | measured | MEASURED | | `eth.state.fee` | ETH settlement fee | gwei/gas | observed | MEASURED | | `eth.state.regime` | ETH congestion regime | boolean | measured | MEASURED | | `eth.state.target_deviation` | ETH capacity vs controller target | share (pp/100) | observed | MEASURED | | `eth.transition_alert.p_entry_7d` | ETH P(congestion entry, 7d) | probability | forecast | VALIDATED | | `op.forecast_24h.fee` | OP next-24h fee forecast | gwei/gas | pending | PENDING | | `op.stables.usdt_transfer` | OP stablecoin transfer cost | native units | measured | MEASURED | | `op.state.fee` | OP settlement fee | gwei/gas | observed | MEASURED | | `op.state.fullness` | OP capacity used | share | observed | MEASURED | | `op.state.regime` | OP congestion regime | boolean | measured | MEASURED | | `sol.execution_success.p_success_by_tier` | SOL included-execution success by priority-fee tier | probability | refused | REFUSED | | `sol.failure.included_failed_share` | SOL included-but-failed share (non-vote) | share | measured | MEASURED | | `sol.forecast_24h.fee` | SOL next-24h fee forecast | lamports/tx | refused | REFUSED | | `sol.rank.m_share` | SOL rank-payment share of leader revenue | share | measured | MEASURED | | `sol.rank.price_p90` | SOL rank price, 90th percentile | lamports/tx | measured | MEASURED | | `sol.stables.usdt_transfer` | SOL stablecoin transfer cost | native units | measured | MEASURED | | `sol.state.exit_prob_7d` | SOL regime exit probability (7d) | probability | measured | MEASURED | | `sol.state.fee` | SOL settlement fee | lamports/tx | observed | MEASURED | | `sol.state.fullness` | SOL capacity used | share | observed | MEASURED | | `sol.state.regime` | SOL congestion regime | boolean | measured | MEASURED | | `sol.tokens.births_7d` | SOL token births (weekly cohort) | tokens/week | observed | MEASURED | | `sol.tokens.circulation` | SOL two-sided circulation (round-tripper share) | share | measured | MEASURED | | `sol.tokens.survival_60d` | SOL cohort survival (7/30/60d, censoring-aware) | share | measured | MEASURED | | `sol.tokens.survival_7d` | SOL token 7d survival | share | measured | MEASURED | | `tron.stables.usdt_transfer` | TRON stablecoin transfer cost | native units | measured | MEASURED | Full definitions, claim boundaries, receipts, and provenance: `evidence.json`. License: (c) Settlement — all rights reserved; commercial terms accompany API keys. Contact: see landing page.