Prove what the source actually said

An agent can call NOAA or the European Central Bank itself, free, and we will tell you exactly where. What it cannot do is prove, an hour or a year later, that a particular value is what the source returned at a particular moment.

That is what these endpoints sell. We fetch, hash the exact bytes the source returned, stamp the time we read them, and sign all of it with a published Ed25519 key. The data is free. The proof is the product.

What comes back

{
  "value":      { … the source's figures, unmodified … },
  "source":     { "name": "…", "url": "…", "licence": "…" },
  "provenance": {
    "resource":        "https://soren.com/v1/oracle/fx",
    "upstream_sha256": "<hash of the exact bytes we received>",
    "observed_at":     "<when WE read it, ISO-8601 UTC>",
    "signature":       { "algorithm": "Ed25519", "value": "<base64>" }
  }
}

Verifying a reading

Two independent checks, neither of which requires trusting us:

1. Authenticity. Rebuild resource|upstream_sha256|observed_at and verify signature.value over its ASCII bytes with the key at /oracle-key.json.
2. Integrity. If you hold the upstream bytes, hashing them must reproduce upstream_sha256.

This key is deliberately different from the feed signing key at /signing-key.json. That one lives on the collector; this one lives at the edge. Separating them means a compromise of the edge cannot forge a published feed.

The endpoints

Bad input is refused with a 400 before any payment is taken, and we only call the source after settlement — so an unpaid request never costs a free public API a request.

Did that transaction actually land?

This is the one that pairs with the conformance suite. An agent that paid over x402 and got back settlement_pending holds a transaction hash and no way to resolve it — the transfer may still confirm, or may never have existed. Re-signing risks paying twice; assuming success risks getting nothing.

/v1/oracle/onchain?q=tx&hash=… answers it, signed. And it distinguishes the two cases that matter:

Also q=balance for ETH and USDC at an address, and q=block for height and gas price. Three allowlisted queries rather than raw JSON-RPC: exposing eth_call would make us a general-purpose proxy for anything a caller cares to send.

Randomness nobody can rig

A random number we generated is worth nothing to a counterparty: they cannot tell it from one we picked after seeing the stakes. So we do not generate one.

/v1/oracle/random returns a round from the drand League of Entropy beacon — a distributed network that publishes one signed value every 30 seconds. No single participant, including Soren, can choose or predict it. We verify it before signing: drand defines its randomness as SHA-256 of the round's BLS signature, and we recompute that and refuse to attest to a round which does not match.

You get the raw 32 bytes plus ready-made as_uint53 and as_float forms, so a fair draw does not require you to do bit manipulation.

You can check us completely. Fetch the same round from api.drand.sh and compare, and recompute SHA-256 of the signature yourself. Both were verified against three independent operators before this shipped. What you are buying is not the number — it is the signed evidence that Soren committed to this value at this moment, which is the part you cannot reconstruct later.

Sources, and what their licences require of us

Only sources whose terms permit redistribution are used, and each one's conditions are honoured in the response rather than in a footnote.

NOAA / US National Weather Service

Public domain. Three binding constraints, all of which we follow: we do not claim ownership, we do not imply endorsement or affiliation, and we never present modified content as official government material. Values are returned exactly as the station reported them. Soren is the signer, not the originator.

US Bureau of Labor Statistics

A US Government work, public domain under 17 U.S.C. §105 — free for commercial use and redistribution without permission. BLS asks to be cited as the source, which every response does.

Why this matters more than it looks: BLS revises its series. A figure published today may not be the figure you see next month, so “what did the source actually say at the time” is a real question with a real answer, and that is precisely what the signature fixes in place.

Five named series rather than raw BLS codes: unemployment_rate, cpi, nonfarm_payroll, labor_force_participation, avg_hourly_earnings. BLS ids are opaque — LNS14000000 is unemployment — and an open passthrough would sell you a 404 for a mistyped character.

Base mainnet

On-chain data is public by construction, so there is no licence question about the data itself. The question is how it is read: Base's own documentation says the public RPC endpoint is “rate-limited and not suitable for production traffic” and directs commercial users to a node provider. We therefore read through a commercial Coinbase Developer Platform node rather than building a paid product on an endpoint its operator asks us not to use this way.

drand / League of Entropy

A public randomness beacon, Apache-2.0 / MIT licensed and published for public consumption. Cloudflare is one of the operating participants. The same round is free from api.drand.sh and we say so in every response.

European Central Bank

Free reuse with attribution, and modifications must be disclosed. It also carries a condition that binds us specifically because we charge: buyers must be told, before purchase and on each access, that the information is available free of charge from the ECB. That notice is in the 402 challenge and in every paid response — it is not optional and we do not remove it to tidy the payload.

These rates are indicative. The ECB publishes them once per working day around 16:00 CET and states they are not intended for transaction purposes. Non-EUR pairs are crossed via EUR by us, and every response says so, because that cross is our calculation and not an ECB figure.

What is deliberately not here

Sources whose terms are unclear do not ship. Market data feeds commonly forbid redistribution of derived values, so equities are absent. FRED, BLS and Census are all public domain and are good candidates, but they need an API key we do not yet hold. We would rather have two endpoints we can defend than seven we cannot.