Agent Evidence API

Agent Evidence API

Cited, source-grounded web evidence and claim verification, plus US weather from the National Weather Service, for AI agents — over both HTTP and MCP. Paid per call in USDC on Base over x402 — $0.01 a call, and nothing at all when nothing is retrieved. No API key and no account for either service.

Discovery is free on every MCP route (tools/list, initialize, ping, and a health tool), so an agent can read the schemas and probe for liveness before paying for anything.

Optional: semantic ranking

Ranking is deterministic lexical matching by default, and it has a measured ceiling. Asked *"What is the population of Tokyo?"* it returns passages that mention "population" and "Tokyo" — 1603 history, wartime declines, municipal taxes — and misses the sentence that answers the question, because that sentence says *"the city proper"* instead of repeating "Tokyo". Two lexical heuristics were tried and reverted; no keyword trick bridges it.

An optional Laya sidecar closes it. Laya is an open-weight (Apache-2.0) typed-decision model: it scores a passage with noul, P(this passage directly answers the question). No vendor, no API key, no per-call fee, and your content never leaves the host.

python services/laya/server.py                 # ~2 GB resident, ~35 s cold load

REASONING_PROVIDER=laya REASONING_URL=http://127.0.0.1:8077 ...

Measured on the case above, single source:

The model is engaged only when the budget can afford the full pool. Cost is ~800 ms per candidate (a single call measures ~420 ms, but the sidecar serialises, so ~700 ms under real concurrency). The budget is divided across sources, so 1–2 sources can afford a 12-wide pool and larger requests cannot. A narrower pool was measured to be worthless — it can only reshuffle passages that already excluded the answer — so rather than spend ~20 s on that, those requests fall back to lexical and stay fast. Lower REASONING_POOL_SIZE to engage on larger requests, trading recall.

The budget is a hard ceiling, not a target: it is *reserved* before each call, so concurrent sources cannot collectively overshoot it. (An earlier version checked and then awaited, which let five sources each pass the check before any decremented it — an 8 s budget produced a 50 s request.)

The trade is latency, not accuracy: ~420 ms per candidate, so a 12-candidate pool costs ~5 s of inference per source. That is why it is off by default. Enabling it changes only the ORDER of evidence — every excerpt, source, URL and hash is identical — and if the sidecar is missing, slow, or returns anything unexpected the service silently keeps its lexical result. The raw model probability is never exposed (SPEC §21).

Note the pool matters: the first version of this ranked only the 5 candidates lexical had already chosen, and the answer had been ranked 8th–20th, so it was never available to promote. The wider pool is what makes it work.

Running the backend in Docker? The sidecar must be reachable from the container: --add-host=host.docker.internal:host-gateway and point REASONING_URL at http://host.docker.internal:8077, or put both on one Docker network.

You are only charged when the service delivers

The x402 middleware settles a payment only when the handler returns a status below 400, so the service is built so that every way it can fail is a 4xx or 5xx:

• If no source could be retrieved — all 404s, all SSRF-blocked, all unsupported content types — the request fails with NO_SOURCES_RETRIEVED (502) and no payment is taken. An earlier version returned 200 inconclusive here, which would have billed a buyer $0.03 for an empty result.
• Partial success still settles. If one of five sources was retrieved, real evidence was delivered and the per-source warnings explain the rest.
• On the MCP transport, a failed tool call is reported as isError: true inside an HTTP 200 — correct MCP behaviour, but invisible to the payment middleware. The Worker rewrites that to 502 so the payment is not taken; the JSON-RPC body is passed through unchanged.

Verified against the live deployment: a request whose sources all fail returns 502 NO_SOURCES_RETRIEVED, and a request with one good source plus one dead one returns 200.

Try it without paying

Every paid route has a free preview that returns a real, unedited result — not a mock:

curl -s -X POST https://agent-evidence.thx93.dev/v1/evidence/preview \

-H 'content-type: application/json' \ -d '{"question":"What is a centrifugal pump used for?", "url":"https://en.wikipedia.org/wiki/Centrifugal_pump"}'

curl -s 'https://agent-evidence.thx93.dev/v1/weather/alerts/preview?state=TX' curl -s 'https://agent-evidence.thx93.dev/v1/weather/forecast/preview?latitude=37.7749&longitude=-122.4194'

The evidence preview returns one source and up to three excerpts with source URL, retrieval time and content hash, but no assessment. The paid call takes up to five sources and adds the supported / contradicted / mixed / inconclusive verdict.

Twenty-five previews per caller address per day, no account, no wallet. The paid routes are deliberately separate: they must keep answering 402, because that is what every x402 catalogue and validator checks, so previewing them in place would make the service unlistable.

FAQ

What is Agent Evidence API? An HTTP and MCP service for AI agents that returns cited, source-grounded evidence from public web pages, plus US weather from the National Weather Service. You send a question and up to five URLs; it returns the passages that bear on the question with their source URL, retrieval time and content hash, and an assessment of supported, contradicted, mixed or inconclusive.

Do I need an API key or an account? No. There is nothing to sign up for. Payment is per call in USDC on Base over x402, so an agent with a wallet can pay for exactly what it uses.

How much does it cost? 0.01 USDC per call. Nothing is charged when nothing is retrieved — if a source cannot be fetched or no evidence is delivered, settlement is cancelled.

Can I see the output before paying? Yes. GET /demo (HTML) and GET /demo.json serve one complete, unedited evidence package from a real paid call. The MCP sample tool returns the same thing, free.

How is this different from a search engine or a scraper? It is neither. You supply the URLs; the service does not discover sources for you. What it adds is provenance: every excerpt is tied to a real retrieval, with a timestamp and a content hash, so a claim can be traced back to what the page actually said.

What are its limits? Matching is deterministic and lexical, not semantic. When a question asks more than one thing and only one source contributed a matching passage, the service answers inconclusive rather than guessing. Weather is US only, because the data is the US National Weather Service's.

How do I call it from an agent? Over HTTP (POST /v1/evidence) or MCP (POST /mcp). The buyer CLI is zero-install: curl -fsSL https://agent-evidence.thx93.dev/buy.mjs -o buy.mjs, or npx @thx93/x402-evidence.

Market analysis

[docs/market-analysis.md](./docs/market-analysis.md) — what the x402 economy actually pays for, measured from the only catalogue that publishes real usage data (30-day calls and unique payers per service). It is uncomfortable reading: the category this service sits in is 1% of search by volume, and its price band is the weakest of the five.

Engineering report

[docs/ENGINEERING-REPORT.md](./docs/ENGINEERING-REPORT.md) — the report required by SPEC.md §44: what was built, the architecture, deployment and test commands, x402 and MCP status, registry readiness, remaining manual configuration, and known limitations. It states plainly what is demonstrated and what is not — including that no settlement has been exercised and that one §42 acceptance criterion is unmet. It does not claim the project is production ready.

Actions only you can take

[docs/CHECKLIST.md](./docs/CHECKLIST.md) — every remaining step that needs a human: the first payment, confirming the catalogue listing, posting, and the decisions I deliberately left to you. Everything else is done.

Making the first sale

See [docs/FIRST-SALE.md](./docs/FIRST-SALE.md) — the whole path from an empty wallet to a settled payment and a catalogue entry, in one page.

How to see revenue

Every request the backend serves on a paid route has already passed the backend's own x402 payment gate (the Worker only proxies). The log is append-only on the data volume, so it survives container recreation and redeploys — unlike Docker logs.

A line means a payment proof was verified in this process. It is not proof of settlement. The x402 order is verify → handler → settle, so the backend writes its line *before* the facilitator settles, and a settlement that later fails still appears here. The field is named payment_provided for that reason; it was previously called settled, which was wrong.

docker exec aee-live cat /app/data/usage.jsonl            # the raw record

Buyer traffic: requests that carried an x402 payment proof, so operator and

test calls are excluded. This is NOT a revenue figure - see below.

docker exec aee-live sh -c "grep -c '"payment_provided":true' /app/data/usage.jsonl"

For money, use the on-chain record. The buyer's client prints the settlement transaction, and the authoritative ledger is the recipient address:

https://basescan.org/address/0x9c0e2B44180439294Fa30Ae2B2a94f8655455FD0

Each line carries the timestamp, request id, a salted hash of the question (never the text), how many sources were retrieved, how many evidence items came back, the assessment, and the server-side duration.

{"ts":"2026-09-21T07:53:04.341Z","request_id":"req_2fcc…","question_hash":"725f50fca9fbe049",

"question_chars":32,"sources_requested":1,"sources_retrieved":1,"evidence_items":5, "assessment":"supported","processing_ms":6,"outcome":"ok"}

For the on-chain side, the payment response carries a settlement transaction hash, and the recipient is 0x9c0e2B44180439294Fa30Ae2B2a94f8655455FD0 — ch