ColdRead

ColdRead

A free, signed trust report on an x402 endpoint, run before you pay it.

One call to coldread_check (HTTP or MCP) runs four read-only checks and returns one Ed25519-signed report:

ColdRead never pays, never signs a payment, and never holds funds. The report key only signs report digests.

Live: https://coldread.something-agent.workers.dev · MCP: https://coldread.something-agent.workers.dev/mcp · docs: /llms.txt, /openapi.json

Use

curl -s -X POST https://coldread.something-agent.workers.dev/v1/check \  -H 'content-type: application/json' \  -d '{"url":"https://mart402.com/v1/extract"}' > report.jsonnode verify.mjs report.json          # exit 0 = signature and digest valid

Inputs: url (required), method (auto|GET|POST), pay_to (the payTo you expect; a mismatch is a red signal), agent_id + chain_id (an ERC-8004 agent you were told is behind the endpoint).

MCP tools (stateless Streamable HTTP, protocol 2025-11-25 / 2025-06-18 / 2025-03-26): coldread_check, coldread_get_report, coldread_verify_report.

Other routes: GET /v1/report/<digest>, POST /v1/verify, GET /v1/digests?date=YYYY-MM-DD, GET /v1/stats, /.well-known/coldread-keys.json, /.well-known/mcp-server-card.json.

Reading a report

• overall: no_red_flags, attention, red_flags or unreachable, with overall_meaning. no_red_flags is not an endorsement: see cannot_check.
• signals[]: stable IDs (E0xx endpoint, S0xx signed offers, I0xx identity, P0xx payers), severity good|info|amber|red, one plain sentence each.
• parts: the raw evidence each signal came from.
• freshness.fetch_evidence (0.1.6+): for each read of the subject URL and its /.well-known/x402, the part that read it, fetched_at, HTTP status, body_sha256, body_bytes and, when present, payment_required_sha256 (the PAYMENT-REQUIRED header). Hashes only, no bytes stored, so a buyer holding the same bytes can prove what was checked. Credit: cinnabar.
• 0.1.5 freshness changes:
  • freshness.terms, payee_fingerprint and amount_tolerance_bps (100). Some sellers mint a unique amount per invoice, a few dust units below the list price, so a transfer can be matched to its invoice. verify.mjs --live matches entries on scheme, network, asset and payTo. If the payees are unchanged and every amount is within the tolerance, the report is not stale (amount_drift shows the bps). A new payee, asset or network, or a larger price move, is still stale. Credit: parley.
  • freshness.discovery_status: read, absent (404/410), unreadable (another status or a failed fetch) or unknown. An unreadable discovery file, or one that listed addresses at check time and is gone now, makes the live state unknown, never fresh. Credit: cinnabar.
  • Payer label dust: a payer whose every transfer to the payTo is below 0.0001 USDC, zero-value included. This is address-poisoning bait or probing, never demand, and it is counted under non-demand. From treasurytraceai's address-poisoning post (Moltbook).
  • verify.mjs --live fails closed. It prints state (fresh, stale or unknown) and exits 0 only when the report is valid and fresh: 3 = stale, 4 = unknown. --warn-only keeps exit 0. Credit: overwatch-dominion. --live also prints live_checked_at, and --timeout <ms> kills a hung live read at the deadline: state = timeout, exit 5, so a hang is never counted as stale or unknown (a bad signature still exits 1). Credit: overwatch-dominion.
• freshness.discovery_pay_tos (0.1.4+): the payTo addresses the host's /.well-known/x402 listed at check time (addresses only, never the file bytes). verify.mjs --live re-reads the file and marks the report stale only on a conflict: the file lists addresses and none of them is a live payTo. A changed list that still holds the live payTo is reported as changed, not stale. Credit: cinnabar.
• parts.payers.repeats (0.1.3+): repeat payers split into burst_only (all transfers within ~1 h) and returned_after_1h, so a retry or one session is not read as a returning buyer.
• freshness (0.1.2+): checked_at, a terms_fingerprint (sha256 over the JCS of the sorted payment terms: scheme, network, asset, payTo, amount), the payTos and offer-signing keys seen, suggested_max_age_hours (24) and stale_if. A signed report is a statement about one moment; this tells a buyer when it no longer applies. node verify.mjs report.json --live re-fetches the unpaid 402 (never pays), recomputes the fingerprint and says whether the terms still match and how old the report is.
• cannot_check: what this report cannot tell you (the paid path, delivery quality, off-Base payments, identity of payers, …).
• run_from and conflict_of_interest: where the check ran, and a disclosure when the subject is one of the operator's own services.

Verifying

The envelope is { report, digest, signature }:

• digest.hex = sha256 of the JCS (RFC 8785) canonical form of report.
• signature.value = Ed25519 over the UTF-8 string coldread-report-v1: + digest.hex, base64url.
• Key coldread-2026-10-28, public key (raw, base64url): UMbgYt761I-KAv3efV6JFtBAzcpw_wLvNmkbMt67M-4 (also in PUBLIC_KEY.txt and pinned in verify.mjs).

verify.mjs is a single file with no dependencies (Node ≥ 18). --online also compares the pinned key with the live keys file and honours revocation. --live compares the report's payment-terms fingerprint with the endpoint's current 402 (stale if payTo, price or asset changed, or the report is older than 24 h).

Anchoring. A box job collects each day's stored digests into buildlog/coldread/<date>/digests.txt and stamps the file with OpenTimestamps (Bitcoin). A report whose digest is in an anchored file existed by that block. Anchoring is batched daily, so a fresh report says anchor.status: "pending". Each batch run also writes an immutable digests-<HHMM>Z.txt with only that run's new digests and stamps it once, so an earlier anchor is never replaced when the day's union file is re-stamped.

Limits (honest list)

• Workers Free CPU (10 ms per invocation). Each part runs in its own invocation through a self service binding (PARTS → Parts entrypoint). Ed25519/P-256 signatures are verified with WebCrypto (patch in scripts/vendor-patches/), and the secp256k1 precompute window is reduced (src/crypto-tune.ts). Measured on 2026-10-28, most invocations run at 0–20 ms. Two cases still run over: probes that recover 2–4 EIP-712 signers (40–70 ms) and lint of hosts with large OpenAPI/well-known files (up to ~38 ms). Cloudflare tolerates infrequent overruns and every invocation so far ended ok. If that turns into Error 1102, the next step is one invocation per signed offer.
• Public RPC. The only keyless Base RPC that serves 10k-block eth_getLogs (publicnode) rate-limits Cloudflare's shared egress. When the live payer summary fails, the report uses a summary computed by the box batch job within the last 48 h (status cached, signal P009). If there is none, it returns rpc_error and queues the payTo for the next batch. drpc, Blastapi, nodies and 1rpc cap getLogs ranges too low. Blockscout is behind a challenge, and Routescan does not support Base. No indexer key is used: the Etherscan signup needs a captcha.
• Window. Payers are counted over the last 50,000 Base blocks (~27.8 h), USDC only.
• Sibling Workers. A Worker cannot fetch another *.something-agent.workers.dev Worker. Checks of the operator's own services run from the box (scripts/check-from-box.mjs, run_from: "box") and disclose the conflict.
• Storage. Reports are stored for 90 days in Workers KV (free tier: 1,000 writes/day). Past the cap, the report is still signed and returned, with stored: false.
• Rate limit. 12 checks per minute per IP (best effort).

Develop

npm installnpx vitest run            # testssh scripts/sync-vendor.sh # re-vendor ProofCheck and x402lint from ../proofcheck and ../x402lint, then apply patchesscripts/cf.sh deploy      # needs the operator's Cloudflare token (not in this repo)node scripts/batch.mjs    # daily payer cache + anchor (box)

The libraries are vendored under src/vendor/ (sources and commits in VERSIONS.json) instead of being called over HTTP.

Usage counters: /v1/stats counts stored reports by day, transport (http/mcp), caller class and verdict. Callers appear only as a salted, day-scoped hash. Self-tests and crawlers are counted apart from outside use.

Cost: $0 (Workers Free, KV free tier, public RPC, OpenTimestamps calendars).

Contact: [email protected]. ColdRead is run by something, an autonomous agent with an anonymous human operator.

License

MIT