# Truth Bear - Verifiable Screening Intelligence for AI Agents (x402, USDC on Base, no API key; GAUGE engine)

> Pay-per-call data signals for AI agents via the x402 protocol (USDC on Base, no API key, no signup). Headline value: (1) pre-joined CROSS-LINE CASCADE — one call surfaces downstream exposure across industries; (2) LEADING signals — the upstream factor before the current state; (3) aggregation / screening convenience over scattered free official sources (USGS/NOAA/EPA/SEC/FDA/EIA/…), pre-cleaned into one schema; (4) verifiable official-source provenance (official timestamp + record_hash) for those who need citable screening evidence. Pure description — no judgment, no prediction; official-source facts + back-testable statistics, the consumer decides.
> Provenance is scoped, not the headline: record_hash (canonical sha256, recomputable offline) + official source_ref timestamp cover verification. Delivered records carry ots_status only as a retired, always-pending compatibility field.

## Read this first if you are an agent

Most endpoints need a query parameter. Calling one **without** its parameter does not fail
because the endpoint is broken - it returns 422 with `no_charge: true` and you are not billed.
The legal values are already machine-readable in three places, so you never have to guess:
`input_required` and `input_example_request` on every /manifest entry (the full JSON Schema with
`properties.<param>.examples` is behind that entry's `inputSchema.$ref`, or inline with /manifest?all=1),
the same `examples` inside `accepts[].outputSchema.input` of every 402 challenge, and a
runnable URL repeated in the `error` string of the 402/422 itself.

Copy any of these and run it as-is (each still requires x402 payment on the retry):

```
GET /gauge?signal_id=hydrology.river-level&entity=07010000&format=thin
GET /gauge/region?loc=us-stlouis&format=thin
GET /trust/precheck?service=api-exa-ai
GET /stable/coin?symbol=basis-cash-bac
GET /resolve?entity=AAPL&form=10-K&cutoff=2025-01-01
```

Full list of every endpoint with its price, required parameters and legal values: /manifest?all=1

## How to pay
x402 (HTTP 402): GET an endpoint; on 402 pay the quoted USDC amount on Base (EIP-3009, gasless) with any x402 client; retry with X-PAYMENT. USDC settles directly to the provider wallet. No accounts, no API keys. Machine-readable discovery: /.well-known/x402 and /manifest.

START HERE IF YOU ARE DECIDING WHETHER TO TRUST THIS SOURCE: /.well-known/verification.json - one document with the catalogue size, protocol versions served, schema-phantom count, paid-response cache policy, and how to recompute any delivered record_hash offline. Every number in it is computed at request time, and every block carries a verify_yourself URL so you can check it without trusting this file. Identity for the ERC-8004 trust layer: /.well-known/agent-registration.json.

Per-channel projections of the same catalogue (pick the shape your stack parses; all three are generated from one source, so they cannot drift apart): /manifest (x402 resources with price + inputSchema + outputSchema) | /manifest?platform=mcp (MCP tool list, identical to POST /mcp tools/list) | /manifest?platform=a2a and /.well-known/agent-card.json (A2A AgentCard; note this agent does NOT implement A2A message transport - skills are plain HTTP GET endpoints paid with x402) | /.well-known/agent.json (legacy Truth Bear capability card, kept unchanged for existing consumers).

IMPORTANT — raise your client's maxValue for endpoints above $0.10: the common x402 client helper (`wrapFetchWithPayment(fetch, account)`) defaults `maxValue` to 100000 atomic units = $0.10 USDC. Endpoints priced above that (the three-leg cross-verification bundles, and the subscription; see /manifest for each current price) are rejected **inside your own client before any request reaches us** — you see a failure with no server-side trace and no 402 to inspect. Pass an explicit cap — `wrapFetchWithPayment(fetch, account, 10000000n)` (= $10) — or read the `client_hint` object attached to the 402 body of those endpoints, which states the required atomic amount and the default cap. Endpoints at or below $0.10 need no change.

IMPORTANT — pay from a plain EOA: the paying wallet must be a plain externally-owned account (EOA) with NO contract code. Smart-contract wallets and EIP-7702-delegated accounts verify signatures via EIP-1271 instead of ecrecover; some implementations reject the EIP-3009 authorization, so payments fail intermittently with the opaque facilitator error "invalid_payload" even though the signature, balance, and network are all correct. If you hit invalid_payload, check `eth_getCode(payer)` — a non-empty result means your wallet is delegated; pay from an un-delegated EOA instead.

## Verifiable citation (offline, zero-trust)
Every paid JSON response carries a "_citation" — a signed, offline-verifiable fact envelope: Ed25519 signature over RFC-8785/JCS canonical bytes, record_hash = sha256, statement_type=description / not_advice=true (pure description, never advice/prediction). Recompute + verify it with the standalone verifier (citation-object/verify.mjs) — zero network, no trust in this endpoint required; tampering with any factual field breaks both hash and signature. Issuer identity is an offline did:key (also in /manifest.citation and /.well-known/agent.json). Issuer DID: did:key:z6MkiGjPjUHhdcFaxe3Na22b2XpFEAc5Deih5fjxzSgHDm7h (kid=kid-2026-08).

MCP (Model Context Protocol): POST /mcp speaks JSON-RPC 2.0 over HTTP (initialize / tools/list / tools/call; no SSE). Two FREE tools — verify_citation (hand it any Truth Bear record_hash; it re-looks-up and recomputes the canonical hash, and tells you in plain language exactly what that hash attests) and find_signal (coverage + freshness manifest, so you can check is-my-entity-covered-and-how-fresh before paying). One payment-pointer tool — get_official_record returns the REAL x402 challenge (accepts[]: network / asset / payTo / amount) for a signal_id+entity; this MCP server never takes payment and never returns paid data, you pay at that URL with your own wallet and receive the record directly. Add it to any MCP host as an HTTP/streamable server pointing at /mcp.

## Response size: ?format=thin (agent-optimised)
Append '&format=thin' to any paid single-record endpoint to receive the ANSWER shape instead of the full record:
'{ signal_id, entity, entity_name, observed_at, current, summary_en, record_hash }' plus the same grade/scope and a
'record_hash_verifiable' computed for THAT payload. It is about 8x smaller than the default projection.
IMPORTANT and deliberate: the thin shape OMITS part of the canonical core, so its 'record_hash_verifiable.mode' is
'via-endpoint', never 'offline' - the hash is a fingerprint you cross-check at the free /gauge/verify, not material you
can recompute offline. Same price as the full shape. Endpoints with no single-record summary (lists, bundles, CSV)
ignore the parameter and return the full payload with an 'X-THIN-UNAVAILABLE' response header.

Channels (x402 is one channel, not the only one — see GET /gauge/channels): x402 (AI-agent micropayment), a stateless subscription token (no account needed; minted by the operator card/fiat rail, not sold over x402 -> Bearer token for /gauge/watch, /gauge/watch-changes, /gauge/manifest-sweep), and - where the operator configures it - a fiat/card rail returning the same JSON (~2% fee; the system never handles the payment secret). RapidAPI / B2B-direct / academic (Zenodo+DOI) are roadmap channels. Every paid JSON response carries a machine-readable "grade: screening-level, not decision-grade" + "scope". In the default (full) shape "scope" is the complete prose; in the thin shape (?format=thin) it is a compact machine-readable object - {monitoring_not_forecast, intelligence_not_command, verifiability, full} - where "verifiability" is true for THAT delivery and "full" links to GET /scope/v1 for the prose. The compact object travels with the goods: it stays valid even if that page is unreachable (monitoring-not-forecast, intelligence-not-command), a "provenance.data_lineage[]" (per-signal source + independent_dimension + uncertainty; uncertainty says "not-provided-in-this-projection" when a projection did not carry the multi-source agreement CV, rather than asserting single-source), "decision_points" (one-tag-swap = one what-if call), and — once a prior call outcome is on record — a "last_fact" (the single objective later official reading; not a prediction/average/hit-rate).

## GAUGE — environmental signals (hydrology × air quality × precipitation)
Flood-risk & river-anomaly check: real-time US river water level (gage height), streamflow (cfs), flood stage / flood category vs official USGS/NOAA thresholds, plus 5-year seasonal statistical anomaly (percentile / strata) and record_hash verifiability. Two rulers per signal (official thresholds + statistical distribution); cross-line corroboration (rain↔river↔air) as material for the consumer to self-verify causal chains.
- Data-acquisition contract: GAUGE serves screening records from STORED snapshots (SQL), never a live upstream call at request time — every paid response that carries a timestamp also carries provenance.data_as_of + provenance.age_hours_now (age computed at request time, not frozen at collection) + provenance.freshness + provenance.freshness_basis (the exact cadence and thresholds used for that label). Freshness is CADENCE-AWARE and uses the SAME function as the free /gauge/coverage manifest, so the label you see before paying is the label you get after paying: monthly/quarterly/annual official lines are not mislabeled stale by a 24h rule, and a line whose upstream froze is labeled stale + dead_source regardless of when it was last collected. Per-cadence thresholds are machine-readable at /gauge/coverage (freshness_thresholds). Real-time-critical lines are collected hourly, others daily/weekly. Stored-serving avoids upstream API latency; use each record within its data cadence.
- Free: /gauge/coverage (coverage + freshness manifest — is-my-entity-covered-and-how-fresh before paying; ?industry=&signal_id=&entity=&summary=1) · /gauge/history-preview?signal_id=&entity= (last 7 snapshots, time-series shape) · /gauge/raw?signal_id=hydrology.river-level&entity=<USGS site id> (base reading) · /gauge/sample · /gauge/preview · /gauge/catalog
- Skill (paid): /gauge?signal_id=&entity= — full flood-risk/anomaly record (price: see /manifest)
- Add-ons (single rulers, cheapest tier — see /manifest for each price): /gauge/ruler · /gauge/calibrated · /gauge/strata · /gauge/history (seasonal percentile/frequency) · /gauge/air?loc= · /gauge/precip?loc=
- History time-series (paid): /gauge/history-series?signal_id=&entity=&days=&format= — full retained time-series (price: see /manifest) (snapshot_date ASC, up to days default 400 cap 1000; columns snapshot_date/observed_at/data_age_hours/current/band/record_hash), format=csv or json, for research/actuarial/base-rate. NOTE: history depth grows over time (data is being accumulated; early records may be sparse); curated/emerging lines snapshot weekly while live lines snapshot daily/hourly, so time-series granularity varies by line.
- Bundle: /gauge/region?loc= (air + precipitation + nearby river, one location) · /gauge/census?signal_id= (cross-station scan). Prices: see /manifest
- Signals: hydrology.river-level, hydrology.streamflow, airquality.aqi, airquality.pm25, precipitation.daily, precipitation.wetness30d
- Sources: USGS Water Services, NOAA NWS/NWPS, US EPA AQI, Copernicus CAMS, ECMWF ERA5

## Subscription / watchlist (stateless one-time token)
The subscription token is a STATELESS signed token (HMAC; no account, no login, no session, no server-side database). The x402 subscription listing is NOT offered - tokens come from the operator card/fiat rail (see the free GET /gauge/channels). Send the token as Authorization: Bearer <token> or ?token= on the token-gated reads below.
- Register: not available over x402. Subscription tokens are minted by the operator card/fiat rail; the per-call paid endpoints below need no token and no account.
- Batch read (free, token-gated): /gauge/watch?items=industry:entity,industry:entity,... — one call returns the whole watchlist state (up to 30 industry:entity items), each with its latest per-signal bundle (signal_id, entity_name, current, band, observed_at, data_age_hours, record_hash) + provenance, served from stored SQL. Example ?items=drug-detail:carboplatin,border-wait:laredo-world-trade,drug-shortage:oncology. Invalid/expired/missing token → 401.
- Poll deltas (free, token-gated): /gauge/watch-changes?items=...&since=<ISO or unix> — for each item returns only signals whose observed_at is newer than ?since (default 24h ago). Webhook-lite monitoring; a true push webhook is a future addition.

## Signal lines (full machine-readable detail per line — price, params, legal values — at /manifest?all=1)

Truth Bear covers ~40 official-source signal lines. GAUGE environmental (above) plus:

Real-time monitoring (current-state vs official thresholds): agriculture drought/heat/crop-VHI (grain belts) · power-grid demand/renewable/energy-inflation · wildfire (FIRMS/VIIRS) · earthquake (USGS) · severe convection/hail (SPC) · grid reliability/outage (EIA-930) · drug shortage & per-drug alternatives (openFDA) · air-transport ground stops (FAA NAS) · land-border waits (CBP).

Lifecycle / death-registry forensics (birth to distress to death + cross-line cascade, emerging industries): SEC filing distress · climate policy · AI tools/MCP · AI model deprecation · product promises · carbon-credit integrity · stablecoin depeg · AI-compute/neocloud · DePIN · ESG funds · RWA · smallsat constellations · LRT restaking · DeFi lending (cascade hub) · AI datasets · medical-device recalls · tariff/customs · biodiversity credits.

Query any line via /gauge, /gauge/ruler, /gauge/strata, /gauge/history (signal_id + entity), or the region/company bundle /gauge/<domain>-region?loc= or ?entity= . Every line exact signal_ids, sources, tracked entities, prices and required parameters are machine-readable at /manifest?all=1 and in each 402 challenge; live coverage + freshness at /gauge/coverage.
Full per-endpoint catalogue (every path + price + a one-line description): /llms-full.txt, or the machine-readable /manifest?all=1 · OpenAPI: /openapi.json
Rate limits: free discovery/preview endpoints are rate-limited per IP (a 429 is retryable and never billed); paid reads are gated by x402 payment.

## Death registries (vanished-data forensics)
Verifiable forensic records of things that died: stablecoins (depeg deaths + x402 service trust scores). Free preview per line; paid per-record + census. (AI-tool / carbon / promise / dependency / policy forensics are now served via the unified GAUGE /gauge/*-region lines above.)
- Free previews: /stablecoin-deaths/preview · /trust/preview

## Verify (zero-trust) — provenance is scoped, not the headline
Every record ships record_hash (canonical sha256 over a versioned canonical core, hash_core_version=3) + official source_ref/timestamp. Recompute it yourself offline from the delivered payload, or cross-check for free: POST /verify (you hold the record) · GET /gauge/verify?hash=&lt;record_hash&gt; (you hold only the hash). Delivered payloads disclose their own recomputability in record_hash_verifiable.
ANCHORING (resumed 2026-08-15): a per-batch Merkle root over that batch's record_hash set is stamped to Bitcoin via OpenTimestamps calendars. It proves the batch set existed no later than the stamp time - it is NOT evidence about the data day itself. Free read surface: /gauge/anchor (list), ?day=YYYY-MM-DD (the day's ots_status + attestation bytes - those bytes are the ORIGINAL pending calendar receipt, so run "ots upgrade" then "ots verify"), ?hash=sha256:... (inclusion proof PLUS the confirmed Bitcoin block number as ots_status:bitcoin, once the batch root is upgraded ~a couple hours after stamping). RETIRED - do not build against these: the old /merkle/proof returns 410 and /merkle/spec is archival only (different contract, superseded by /gauge/anchor); the LEGACY per-record ots_status field stays 'pending' forever and is no longer updated (the live batch confirmation is on /gauge/anchor?hash=, not that legacy field). /proof/:record_hash still returns integrity + official-timestamp provenance, and reports 'undetermined' (503) rather than 'not found' when a lookup cannot complete.

## Keywords
official government data, US federal agency data, government records API, regulatory filing data, official statistics, flood risk, river water level, gage height, streamflow, flood stage, USGS, NOAA, NWS, EPA, SEC EDGAR, openFDA, EIA, BLS, FAA, US CBP, USTR, USITC, Federal Register, IMF PortWatch, air quality, US AQI, PM2.5, precipitation, drought, verifiable data, cryptographic proof, cryptographically signed citation, Ed25519, tamper-evident, auditable offline, provenance, record hash, canonical sha256, cross-source corroboration, leading indicator, x402, pay-per-call, USDC, Base, Solana, AI agent, no API key, no data no charge