API Reference

All paths below are relative to this base. No authentication is required. When rate limits are active, the API returns HTTP 429 Too Many Requests with Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Provenance envelope present on every response. Carry these fields in integration logs for post-mortems and audit trails.

oracle_chain_id identifies the proof network where the commitment was anchored. 8453 = canonical live commitments on Base mainnet. 84532 = historical beta commitments on Base Sepolia. In both cases the underlying payload domain is Base mainnet liquidity and execution context.

Token-level rollup derived strictly from pool data. Useful for routing or eligibility gates without iterating individual pools.

Individual pool evidence object. Found in payload.pools[] from /latest and as pool from the pool detail endpoint. Interpret outputs in conjunction with spec_version, meta.policy_version, and meta.oracle_tx_hash. A computation field showing not_modeled or not_computed does not automatically make a pool ineligible; read the reason before acting.

Lightweight pool item returned from the /pools list endpoint. All fields may be null if not yet computed.

Depth is designed for integrations that fail closed under uncertainty. If a pool lacks observation coverage, treat its liquidity metrics as unknown. If execution eligibility is false, do not treat that pool as an execution surface. If TVL is null, do not impute it.

The payloads are structured to make these conditions explicit rather than hiding them behind defaults. An unknown is returned as null with a reason, not as zero or an estimate.

The API payload is a qualification layer, not an execution instruction. These notes describe how to interpret the key signals.

Inspect eligibility directly. execution_policy.is_execution_eligible is the oracle's deterministic eligibility gate for a pool. A pool with is_execution_eligible = false has failed at least one policy condition; inspect ineligibility_reasons for the specific cause.

Read coverage as evidence scope. coverage.has_observation_coverage tells you whether bounded, recent execution evidence exists for a pool. A pool without coverage has no bounded evidence window; its liquidity metrics may be absent or stale.

Read computation as a disclosure, not a gate. computation.liquidity_state.computed = false means that section was not computed; it does not make the pool ineligible. A pool can be structurally supported, observed, and execution-eligible while liquidity_state remains unmodeled. Inspect computation.liquidity_state.reason to understand why.

Treat null as explicit missingness. Null and uncomputed values are returned as null with a reason field, not as zero or an estimate. Do not impute them.

Use state changes as monitoring signals. is_execution_eligible flipping false on a primary pool, pools_with_execution_coverage dropping to 0, or computation.tvl.computed changing true → false are factual state changes worth alerting on. These are disclosures, not predictions.

Depth is in beta. Pool discovery is best-effort; the pools array in a payload is not guaranteed to enumerate every pool on Base for a given token. Uptime guarantees are intentionally absent. Coverage is intentionally partial.

spec_version refers to the payload contract version; it is not the same thing as the REST API version. Treat it as a hard compatibility boundary. Treat unknown response fields as non-fatal. If you integrate during beta, pin to spec_version: "0.8" and test forward compatibility explicitly before adopting future versions.