# nouli — Proof of Existence for agents: the external witness, paid per call via x402

> Agents are the only actors in the economy that can't testify for
> themselves. A human can swear an affidavit; an agent's self-attestation
> is worthless — whoever could rewrite the log can rewrite the hash. nouli
> is the **external witness**: it binds data to the public drand quicknet
> beacon, a time-source nobody (including the agent) can forge
> retroactively, and returns signed, hash-chained receipts anyone can
> verify with zero trust in nouli. **Proof of Existence is the product**
> ("this existed, at or before this point"), **flips** are the impartial
> tie-breaker that comes with proof — the receipt IS the proof of
> fairness — and every response is a **receipt** containing the proof
> information: sources, round, chain position, and how to verify. Buying
> at volume? An optional prepaid bulk lane (deposit $25+ once, serve at
> $0.001–0.002/call) is documented below. Elsewhere, x402 per call
> stays the default.

## What nouli is

Every response **is a receipt** — the auditable deliverable itself:

- `spec: "nouli.v1"` — the frozen recipe the sources were mixed with
- `sources` — what entered the mix, in order: a secret OS CSPRNG (cited by
  sha256 digest only), the public drand quicknet round (3 s cadence), and
  for anchors **your own bytes** (also digest-only)
- `output` — the 32-byte mix result (base64), or the flip's single bit
- `prev_receipt` — the hash-chain link: one global chain, nothing deleted
- `payment` — the payment record (paid calls only): the settled on-chain
  transaction (x402 per call) or a prepaid debit citation (see
  [Prepaid](#prepaid--deposit-once-draw-from-your-balance-opt-in))
- `signature` — Ed25519 over the canonical form (JCS, RFC 8785)

Verifying a receipt needs only nouli's public keys file and the public
drand beacon — zero trust in nouli (see [Verifying](#verifying-a-receipt)).

What that buys you, honestly stated (the trust tiering): (1) the **mix
and the cited round** verify with zero trust in nouli; (2) **when the
box saw your data** is attested by nouli, not independently verifiable —
the same honesty as the prepaid payment citation; (3) the **one global
chain** makes that attestation tamper-evident — and publicly checkable:
fetch any receipt by id and the current head (see [The public chain
surface](#the-public-chain-surface--check-tamper-evidence-yourself)),
so retroactive rewriting is detectable by any stranger in real time.
The receipt is **tamper-evident, not complete**: it proves what was
recorded, not that everything was — the chain makes gaps visible,
not impossible. Anchor what matters; verify what you're shown.

## Endpoints

| Endpoint | Method | Price | Input |
|---|---|---|---|
| `/v1/receipt` | GET | free under cap → **$0.02** over cap | — |
| `/v1/anchor` | POST | **$0.05** | raw bytes, `application/octet-stream`, ≤ 1,024 bytes |
| `/v1/flip` | GET | **$0.02** | — |

The offerings: `/v1/anchor` is **Proof of Existence** — bind your own
bytes to the beacon ("this existed, at or before this point"), the
headline product; `/v1/flip` is the **impartial tie-breaker that comes
with proof** — a fair bit no stakeholder can accuse you of rigging,
and the receipt is the proof of fairness; `/v1/receipt` is the free
**verifiable-randomness utility** — 256 bits per call, and the receipt
shape every offering delivers.

The same rail is also served over the Model Context Protocol at `POST /mcp`
— three tools mirroring these endpoints, prices included (see [The MCP
mirror](#the-mcp-mirror)); the caps and the paid rail are shared with HTTP.

- `/v1/receipt` is **dual-mode**: under your IP's free cap it answers a free
  receipt (no `payment` object, served from the pre-mixed Buffer — p50 ≈ 4
  ms); over cap the same route answers **402** and becomes a $0.02 x402 call.
- The anchor and flip are **paid-only**: every call is 402-first.
- Larger than 1,024 bytes to anchor? Hash it client-side first (sha256) and
  anchor the 32-byte digest.

## Quickstart — free receipt

```sh
curl -s https://nouli.dev/v1/receipt
```

200 with the receipt JSON. The headers tell you where you stand:
`X-RateLimit-Remaining-Minute` / `-Day` (your per-IP free budget),
`X-Nouli-Chain-Seq` (the receipt's position on the global chain),
`X-Nouli-Served-From: buffer|ondemand`, and — only when the cited drand
round was older than the 60 s freshness bound at mix time —
`X-Nouli-Status: degraded`.

## Quickstart — paying (the x402 flow, end to end)

Every paid call follows the same three steps. An x402 client library does
all of it automatically; the steps below are exactly what it does.

**1. Call without payment → HTTP 402.** The response carries:

- the `Payment-Required` header: **base64-encoded JSON** with the exact
  requirements — `x402Version: 2`, `resource`, and `accepts[0]`:
  - `scheme: "exact"`
  - `network` — the chain settlement happens on (Base mainnet,
    `eip155:8453`, in the current deployment; **read it from the 402**,
    never hardcode it)
  - `asset` — the USDC contract address on that network (native USDC on
    Base mainnet: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`)
  - `amount` — atomic units as a string: `"20000"` = $0.02; the anchor's is
    `"50000"` = $0.05
  - `payTo` — nouli's custody address; your payment goes **directly** to it
  - `maxTimeoutSeconds: 300`
  - `extra` — the EIP-712 domain for the asset (`{ name: "USD Coin",
    version: "2" }` on the current deployment); read it from the 402,
    never hardcode it
- a JSON body `{ error, docs_url, detail }` — on `/v1/receipt` the detail
  reads: `free tier exhausted — pay $0.02 to continue or retry later`

**2. Pay `accepts[0]`, then retry the original request with the payment
base64-encoded in the `payment-signature` header.** Paying is EIP-3009
`transferWithAuthorization` (USDC v2): sign `TransferWithAuthorization`
(`from`, `to` = `payTo`, `value` = `amount`, `validAfter`, `validBefore`,
`nonce`) under the EIP-712 domain `{ name, version, chainId,
verifyingContract = asset }`, and put the resulting x402 v2 payload —
`{ x402Version: 2, resource, accepted, payload: { authorization,
signature } }` — base64 into the header. Most agents skip the hand-rolling:

```js
import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(privateKeyToAccount(PAYER_KEY)));
const paidFetch = wrapFetchWithPayment(fetch, client);

const res = await paidFetch("https://nouli.dev/v1/flip");
const receipt = await res.json(); // 200: the receipt, `payment` embedded
```

Settlement is relayed by nouli itself: the box is its own x402
facilitator (ticket 031). The payer signs a gasless USDC
`transferWithAuthorization`; nouli verifies the signature in-process and
broadcasts the transfer itself — its relay wallet pays the gas, and
nouli's custody address receives the USDC. (An external facilitator —
Dexter, `https://x402.dexter.cash` — remains available to the operators
as an env knob; the payer sees no difference.) Settlement failure after
one retry answers `503` — **no charge, no receipt**.

and a `Payment-Response` header carries the same settlement base64-encoded.
Inspect `payment.transaction` on the network's block explorer (Base
mainnet: `https://basescan.org/tx/<hash>`) — the receipt cannot exist
before settlement, so the hash is always real.

What can go wrong, and what any of it costs you (always nothing, unless a
receipt arrived):

| Response | Meaning | Charged? |
|---|---|---|
| `402 payment_required` | no payment header sent — pay and retry | no |
| `402 payment_invalid` | the payment did not match the requirements (wrong amount, reused, stale) — fetch a **fresh** 402 and pay that; never reuse a payload | no |
| `429 rate_limited` | caps hit — wait `Retry-After` seconds | no |
| `503 settlement_failed` | settlement failed after one retry — retry with a fresh payment (a drained relay gas float answers here too, naming its recovery: fund the relay address) | no |
| `503 facilitator_unavailable` | an externally-pinned facilitator is unreachable or cannot price the route — retry shortly | no |
| `503 core_unavailable` / `503 drand_unavailable` | the receipt core or a cold box's beacon is unreachable — retry shortly | no |
| `500 internal_error` | a bug or a broken box | no (unless a settled receipt was served) |

## Caps and pricing

| Endpoint | Free (per IP) | Paid |
|---|---|---|
| `GET /v1/receipt` | 30 receipts/min burst · 300 receipts/day | $0.02 per receipt |
| `POST /v1/anchor` | — | $0.05 per anchor |
| `GET /v1/flip` | — | $0.02 per flip |

- Paid caps (all paid routes, per IP): **60 receipts/min**, **4 concurrent**.
  Exceeding them answers `429` + `Retry-After` — before any facilitator
  contact, so a capped request never charges.
- Caps are per IP. The free daily counter persists across restarts (a
  restart is not a free-tier amnesty); minute windows reset.
- The paid minute window counts only **served** receipts: a request that
  dies in verify/settle spends nothing.
- Degraded receipts bill **full price** — freshness is quality, not
  correctness.
- On the x402 lane there are no accounts and no API keys; failed settlement
  = no charge. Refunds: none, in either lane. The opt-in prepaid lane is
  the documented **bulk** lane (see below) — its debits run at the bulk
  rates ($0.001–0.002/call), with its own per-key caps: 300 receipts/min ·
  8 concurrent per key, exempt from the per-IP paid caps. The minimum
  deposit is **$25.00 per claim** — prepaid is the bulk lane, and small
  users stay on x402.
- **The two-part tariff (the lane split)**: the x402 402 names the
  **one-off** price — $0.02 receipts/flips, $0.05 anchors; a prepaid debit
  names the **bulk** units — **$0.001** (1,000 units) per receipt or flip,
  **$0.002** (2,000 units) per anchor. Bulk is 10–20× under one-off only on
  the prepaid lane because debits cost ~$0 marginal (no gas, ~ms of mix
  work) — a one-off settle relays ~$0.005 of gas. The 25× spread is the
  sorting mechanism: casual one-shot buyers pay one-off on x402; sustained
  agents deposit $25 and serve at bulk. The two lanes are also the
  instrumentation: the 402 amounts stay differentiated on-chain (50000 vs
  20000 units), and the ledger records the route per debit (2,000 vs 1,000
  units per debit entry).

## Prepaid — deposit once, draw from your balance (opt-in)

x402 per-call stays the default posture: zero signup, and the strongest
public payment story — every receipt cites a settled on-chain transaction
anyone can inspect. When you're buying at volume, the documented
accelerator is a **prepaid account** (when the operator has opened it): USDC
deposited once, drawn down per call, no per-call settlement — box-side
latency ≈ the free path. Prepaid is opt-in and additive; a box without it
answers 404 on every path below and ignores Bearer keys.

**Which posture, when**: default to x402 — zero signup, and the receipt
carries the inspectable on-chain trail. Prefer prepaid when you're a
sustained agent: the prepaid lane **is** the bulk lane — debits name the
bulk rates ($0.001 per receipt or flip, $0.002 per anchor — 10–20× under
the one-off x402 prices, because a debit costs ~$0 marginal: no gas, ~ms
of mix work), the debit lands in your ledger and the receipt, and the
box-side latency drops to ≈ free-path. Casual one-shot buyers stay on x402;
sustained agents deposit $25 and serve at bulk.

| | x402 per-call (default) | prepaid (bulk lane) |
|---|---|---|
| Signup | none — pay per call | deposit (min **$25.00** per claim) + claim |
| Per-call settlement | yes — on-chain | none — one ledger debit |
| Price | one-off: $0.02 receipt/flip, $0.05 anchor | **bulk**: $0.001/receipt or flip, $0.002/anchor (units debited; the route recorded per debit) |
| Receipt's payment story | settled on-chain tx, inspectable by anyone | **box-attested** — the debit is attested by nouli's ledger, not independently verifiable on-chain; the cited deposit can be inspected |
| Throughput | 60/min · 4 concurrent per IP | 300/min · 8 concurrent per key |

### Deposit → claim → Bearer

1. **Fetch the deposit address** — `GET /v1/prepaid/deposit` (a box with
   the lane closed answers 404: prepaid is opt-in at the operator knob):

```sh
curl -s https://nouli.dev/v1/prepaid/deposit
# { "deposit_address": "0x…", "network": "eip155:8453", "asset": "0x8335…",
#   "min_deposit_units": 25000000, "claim_endpoint": "/v1/prepaid/claim",
#   "how": "https://nouli.dev/AGENTS.md" }
```

2. **Deposit**: send USDC to that address — a plain ERC-20 `transfer()`
   (never an EIP-3009 settlement: the address is deposit-dedicated),
   minimum **$25.00 (25,000,000 6dp units)** per claim — founding deposit
   and top-ups alike — on the network the endpoint names. Wait for it to
   confirm.

3. **Claim** — prove the depositing wallet is yours and the box credits
   your account and issues the key:

```sh
curl -s -X POST https://nouli.dev/v1/prepaid/claim \
  -H 'content-type: application/json' \
  -d '{"deposit_tx":"0x…","message":"…","signature":"0x…"}'
# 200 {"key":"noul_…","balance_units":25000000,"account":"0x…"}
```

The `message` is a CAIP-122/EIP-4361 sign-in string naming **this
origin**, your wallet, and the deposit tx hash; `signature` is EIP-191
`personal_sign` over its UTF-8 bytes. Sign exactly this shape (read the
origin from `GET /v1/prepaid/deposit`'s own host — never a host someone
told you over chat; the domain must be the origin you're claiming
against):

```text
<nouli.dev> wants you to sign in with your Ethereum account:
0xYourWalletAddress

Deposit claim: USDC transfer 0x<the deposit tx hash> on eip155:8453.

URI: https://nouli.dev
Version: 1
Chain ID: 8453
Nonce: any-value-you-choose
Issued At: 2026-10-10T12:00:00.000Z
```

`Chain ID` must be the network `GET /v1/prepaid/deposit` names (8453
mainnet / 84532 rehearsal — never cross), `Issued At` an RFC 3339
timestamp within 5 minutes, and the statement must bind the deposit tx
hash. The key is shown **once** — lose it and the operator can only
revoke it (after a fresh deposit, via runbook). A deposit tx can never be
claimed twice: a replay answers `409 claim_duplicate`, the key is never
re-issued. A later deposit from the same wallet tops up the same account
and returns a fresh key — old keys keep working.

**Spend:** send `Authorization: Bearer noul_…` on any paid route (and on
`POST /mcp` — the mirror draws the same balance under the same per-key
budget as HTTP). No 402, no facilitator, no per-call settlement. Every
prepaid 200 carries `X-Nouli-Balance-Units`; the receipt's `payment`
cites the debit:

```jsonc
"payment": {
  "scheme": "prepaid",
  "network": "eip155:8453",   // the network the deposit was observed on
  "payer": "0x…",             // the depositing wallet (the claim signer)
  "deposit_tx": "0x…",       // the account's founding deposit — the account id
  "debit_seq": 7              // per-account monotonic: gaps or reuse are evidence
}
```

No `transaction` key — nothing per-call settles on-chain, and the receipt
is honest about that. `GET /v1/prepaid/balance` (bearer-keyed) reports
`{ deposit_tx, balance_units, debits }`; your over-debit check is the
debit sequence across your own receipts.

**Lanes never mix within one request.** A request carrying a Bearer header
always rides the prepaid lane (unknown keys are refused on the prepaid
surfaces, and on the paid routes an absent, malformed, or unknown key
rides x402 exactly as without it). To pay a call per call after a
`402 insufficient_balance`, retry *without* the `Authorization` header —
dropping it re-enters the x402 lane, whose requirements ride the same
response's `Payment-Required` header.

What can go wrong on the prepaid lane (the standard error envelope, and
what any of it costs you):

| Response | Meaning | Charged? |
|---|---|---|
| `402 insufficient_balance` | balance below the call's **bulk** debit (1,000 units/receipt or flip, 2,000/anchor) — the detail states the balance and names both reliefs: deposit $25+ and claim to top up, or pay per call with x402 at the one-off price (this response carries the `Payment-Required` header) | no |
| `503 facilitator_unavailable` | the balance cannot cover the call **and** the x402 relief header is unavailable (the facilitator is unreachable) — no charge; retry shortly | no |
| `429 rate_limited` | the per-key caps (300/min · 8 concurrent; exempt from the per-IP paid caps) | no |
| `503 drand_unavailable` / `503 core_unavailable` | the mix failed **after the debit** — the debit stands, no receipt; the operator refunds by hand (runbook), never automatically | yes — the detail says so |
| `401 unknown_key` | on `GET /v1/prepaid/balance`: the key is absent, malformed, unknown, or revoked | no |

Claim refusals (nothing credited, nothing spent): `claim_invalid_message`
(wrong domain, chain id, or the statement doesn't bind the tx hash),
`claim_expired` (outside the 5-minute window), `claim_payer_mismatch`
(the signature doesn't prove the claiming wallet sent the deposit),
`claim_tx_unverified` (unconfirmed, reverted, not a plain USDC transfer
to the deposit address, or below $25.00), `claim_rpc_unavailable`
(retry), `claim_duplicate` (a deposit claims once — the key is never
re-issued).

After-debit honesty, stated plainly: if the mix fails after the debit,
the debit stands — money spent, no receipt (the same honesty as x402's
settled-but-unserved); the operator refunds by hand from the ledger,
never automatically. Deposits sit with the operator (custody note in the
docs); the ledger keeps only your wallet address, tx hashes, amounts, and
timestamps.

The MCP mirror serves prepaid too: the same `Authorization: Bearer noul_…`
header on `POST /mcp` draws the same balance under the same per-key
budget as HTTP — same rail, same receipts (a broke key's tool result
carries the requirements in `structuredContent`, so an x402 MCP client
can pay that call per call and continue).

## What `degraded` means

The drand beacon occasionally stalls. When the cited round was older than
**60 s** at mix time, the receipt carries `status: "degraded"` +
`degraded_reason` **inside its signed body**, and the response header
`X-Nouli-Status: degraded`. The receipt is still genuine, still verifies,
and still bills full price — freshness is quality, not correctness. During
a beacon outage free serving never pauses; if your use case demands fresh
rounds, check the header and retry at $0.02.

## Verifying a receipt

npm — zero dependencies beyond two noble packages:

```sh
curl -s https://nouli.dev/v1/receipt -o receipt.json
curl -s https://nouli.dev/.well-known/nouli-keys.json -o keys.json
npx nouli-verify receipt.json --keys keys.json
```

The four checks: (1) nouli's Ed25519 `signature` over the canonical form
against the `key_id` in the public keys file; (2) the cited drand round
fetched from the public beacon and BLS-verified against the beacon's key;
(3) chain links recomputed when you hold adjacent receipts — fetch them
by id from the chain surface below, no prior custody needed; (4) chain
position printed.

## The public chain surface — check tamper-evidence yourself

Two free, read-only routes make the chain publicly observable — the
substrate that turns "tamper-evident" from a claim into a check:

```sh
curl -s https://nouli.dev/v1/chain/head
# { "chain_seq": 41, "head": "sha256:…" } — one digest committing to the whole chain
curl -s https://nouli.dev/v1/receipt/01M4BZDMJ621FSG32AG31G0EWY
# the stored receipt, exactly as issued, with X-Nouli-Chain-Seq: its position
```

The head moves with every append — anyone watching it over time can
detect a retroactive rewrite or insertion. The head digest is exactly
the `prev_receipt` the next receipt carries; a future Bitcoin
checkpoint of this value would anchor the entire chain in
proof-of-work.

Browser, zero setup: **https://nouli.dev/verify** — paste the receipt (or
drop the file), the four checks run in your browser, nothing is uploaded.
The page fetches only the published production keys file
(`https://nouli.dev/.well-known/nouli-keys.json` — never a bundled snapshot)
and the fixed drand endpoint, and its Content-Security-Policy
browser-enforces exactly that. A `?receipt=<json>` link prefills and runs
automatically.

## The anchor — Proof of Existence ("prove my raffle was fair", "prove my agent's history")

The anchor answers the question every long-lived agent eventually
faces: *how would anyone know if your history was rewritten?* Bind
**your** bytes to the public drand beacon and get back a receipt that
says: this data existed, and at or before the cited round — "this
existed, at or before this point." Journal your agent's milestones,
state, and decisions against it; the receipt is the alibi, and anyone
can check it — by id, on the public chain surface, without asking you
for anything.

And the same call is how a human proves a draw was fair: you ran a
raffle, sweepstakes, tournament, or audit sample, and someone asks:
was the draw fair? The receipt shows your data's sha256, never its
contents, so anchoring publishes nothing about the data itself —
proof your data existed and entered the mix at the cited round:
instant, verifiable, with no account and no trust in nouli.

Worked example — a raffle result, end to end:

```sh
# 1. your result (any file or text), hashed — here: raffle #417's outcome
printf 'raffle-417: 1000 entries, winner = entry 417' | shasum -a 256
# 05ddc3bfa265c9a44082deb789dd3de24ac102603ad0be1aebed46fb80267e65  (your digest)

# 2. anchor the bytes ($0.05; up to 1,024 raw bytes) — pay the 402 like
#    any paid call (step 2 of the x402 flow above)
curl -s -X POST -H 'content-type: application/octet-stream' \
  --data-binary 'raffle-417: 1000 entries, winner = entry 417' \
  https://nouli.dev/v1/anchor
```

The receipt cites your digest between the OS and drand contributions.

3. **Share the proof** — the receipt JSON, or a link that verifies itself:

```text
https://nouli.dev/verify?receipt=<URL-encoded receipt JSON>
```

Anyone opening it sees your digest, the drand round it entered the mix at,
and the checks run green in their browser — zero trust in nouli.

Here is a **real** one, minted for $0.05 on the live box on 2026-10-07 for
exactly those bytes — `sha256:05ddc3bf…67e65` is in the mix, round 32866683
is the beacon round it entered at, and the $0.05 settlement is on-chain
(transaction `0x300ffd28…2dafe`, Base Sepolia — minted before the launch-day
flip to Base mainnet; the chain continued unbroken across the flip, and
every receipt's `payment.network` says where it settled):

```json
{
  "endpoint": "/v1/anchor",
  "issued_at": "2026-10-07T20:03:34.086Z",
  "output": { "bytes": 32, "encoding": "base64", "value": "IGKtJsM93QUXn6yvayQ3tGRQCTtW/FEuVJ8cVXfHPoU=" },
  "payment": {
    "network": "eip155:84532",
    "payer": "0xd9F27C648a709a0038DEB0aa243B29f9d7E0Ddff",
    "scheme": "exact",
    "transaction": "0x300ffd28cdda6dbd0f9d2027b687d9ee10aa2dbb779c3b5e0dd5382ab9b2dafe"
  },
  "prev_receipt": "sha256:f90d6b8cb0fe13fc654c0c8ad014903c6315196fcdec6ff1f2a523345bd59318",
  "receipt_id": "01M4BZDMJ621FSG32AG31G0EWY",
  "signature": {
    "algorithm": "Ed25519",
    "key_id": "2026q4",
    "value": "Lm4ZFgmKDQUoKzhDuw5q9qkXdadOwsByjHAED6RVnSYKS86kDvIfgoQg9rUJp8VWdD5jIwzeaKba0mdUgY/jCA=="
  },
  "sources": [
    { "algorithm": "getrandom", "digest": "sha256:4ff2ba92cf212bf590ece3bc485c7d82d68ee60210ffd558aa4177477390f2f3", "kind": "os-csprng" },
    { "digest": "sha256:05ddc3bfa265c9a44082deb789dd3de24ac102603ad0be1aebed46fb80267e65", "kind": "caller" },
    {
      "beacon_id": "quicknet",
      "chain_hash": "52db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971",
      "kind": "drand",
      "round": 32866683,
      "scheme": "bls-unchained-g1-rfc9380",
      "signature": "893c8c3bc79d7d56d088629ee2abd8b029e031026dd5881ae3a6f6341536b4c337a8f1079b8d4da2216e1f231e4c86b6",
      "verify": "https://api.drand.sh/v2/beacons/quicknet/rounds/32866683"
    }
  ],
  "spec": "nouli.v1"
}
```

Its self-verifying link (paste it in a browser — the four checks run there
with zero trust in nouli):

```text
https://nouli.dev/verify?receipt=%7B%22endpoint%22%3A%22%2Fv1%2Fanchor%22%2C%22issued_at%22%3A%222026-10-07T20%3A03%3A34.086Z%22%2C%22output%22%3A%7B%22bytes%22%3A32%2C%22encoding%22%3A%22base64%22%2C%22value%22%3A%22IGKtJsM93QUXn6yvayQ3tGRQCTtW%2FFEuVJ8cVXfHPoU%3D%22%7D%2C%22payment%22%3A%7B%22network%22%3A%22eip155%3A84532%22%2C%22payer%22%3A%220xd9F27C648a709a0038DEB0aa243B29f9d7E0Ddff%22%2C%22scheme%22%3A%22exact%22%2C%22transaction%22%3A%220x300ffd28cdda6dbd0f9d2027b687d9ee10aa2dbb779c3b5e0dd5382ab9b2dafe%22%7D%2C%22prev_receipt%22%3A%22sha256%3Af90d6b8cb0fe13fc654c0c8ad014903c6315196fcdec6ff1f2a523345bd59318%22%2C%22receipt_id%22%3A%2201M4BZDMJ621FSG32AG31G0EWY%22%2C%22signature%22%3A%7B%22algorithm%22%3A%22Ed25519%22%2C%22key_id%22%3A%222026q4%22%2C%22value%22%3A%22Lm4ZFgmKDQUoKzhDuw5q9qkXdadOwsByjHAED6RVnSYKS86kDvIfgoQg9rUJp8VWdD5jIwzeaKba0mdUgY%2FjCA%3D%3D%22%7D%2C%22sources%22%3A%5B%7B%22algorithm%22%3A%22getrandom%22%2C%22digest%22%3A%22sha256%3A4ff2ba92cf212bf590ece3bc485c7d82d68ee60210ffd558aa4177477390f2f3%22%2C%22kind%22%3A%22os-csprng%22%7D%2C%7B%22digest%22%3A%22sha256%3A05ddc3bfa265c9a44082deb789dd3de24ac102603ad0be1aebed46fb80267e65%22%2C%22kind%22%3A%22caller%22%7D%2C%7B%22beacon_id%22%3A%22quicknet%22%2C%22chain_hash%22%3A%2252db9ba70e0cc0f6eaf7803dd07447a1f5477735fd3f661792ba94600c84e971%22%2C%22kind%22%3A%22drand%22%2C%22round%22%3A32866683%2C%22scheme%22%3A%22bls-unchained-g1-rfc9380%22%2C%22signature%22%3A%22893c8c3bc79d7d56d088629ee2abd8b029e031026dd5881ae3a6f6341536b4c337a8f1079b8d4da2216e1f231e4c86b6%22%2C%22verify%22%3A%22https%3A%2F%2Fapi.drand.sh%2Fv2%2Fbeacons%2Fquicknet%2Frounds%2F32866683%22%7D%5D%2C%22spec%22%3A%22nouli.v1%22%7D
```

## The MCP mirror

If your client speaks the Model Context Protocol, nouli is at
**`https://nouli.dev/mcp`** — remote streamable HTTP, stateless, JSON
responses. Three tools mirror the HTTP endpoints exactly, prices included:

| Tool | Price | Input |
|---|---|---|
| `nouli_receipt` | free under cap → **$0.02** over cap | — |
| `nouli_anchor` | **$0.05** | `data`: base64, ≤ 1,024 bytes raw (hash larger data client-side first) |
| `nouli_flip` | **$0.02** | — |

- **Free-first, like HTTP**: `nouli_receipt` under your IP's cap answers a
  free receipt; over cap the same tool call answers the 402 and the paid
  path is the relief valve. The anchor and flip are paid-only.
- **Caps and rail are shared with HTTP** — the MCP tools run in the same
  process against the same per-IP counters: a free call via MCP and a free
  call via HTTP draw from one daily budget, and the paid caps (60/min, 4
  concurrent) are shared too.
- **Payment rides the x402 MCP transport**: an unpaid paid-tool call answers
  a 402-shaped tool result — `isError: true` with the requirements in
  `structuredContent` (and JSON-encoded in `content[0].text`), `accepts[0]`
  naming `amount` (`"20000"` = $0.02, `"50000"` = $0.05), `asset`, `payTo`,
  `network`. Pay it and retry the same call with the payment payload in
  `_meta["x402/payment"]`. Any x402 MCP client does this unaided:

```js
import { createx402MCPClient } from "@x402/mcp";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = createx402MCPClient({
  name: "my-agent",
  version: "1.0.0",
  schemes: [{ network: "eip155:*", client: new ExactEvmScheme(privateKeyToAccount(PAYER_KEY)) }],
});
await client.connect(new StreamableHTTPClientTransport(new URL("https://nouli.dev/mcp")));
const result = await client.callTool("nouli_receipt");
const receipt = JSON.parse(result.content[0].text); // 200: the receipt, `payment` embedded
result.paymentResponse?.transaction; // the settled tx — inspectable on the explorer
```

- **The receipt is the response** here too: on success `content[0].text` is
  the full receipt JSON (`spec: "nouli.v1"`), settlement embedded on paid
  calls — the paid result's `_meta["x402/payment-response"]` carries the
  same settlement. The settlement still completes **before** the receipt is
  mixed, so `payment.transaction` is always real.
- Refusals are error results, charged nothing: `rate_limited` (shared caps,
  with the seconds to wait in the text), `payment_invalid` (fetch a fresh
  402; never reuse a payload), `settlement_failed` (no charge — includes a
  drained relay gas float: fund the relay address and retry),
  `facilitator_unavailable` (no charge, externally-pinned facilitators
  only). Prepaid keys work over the mirror with the same rail and the same
  per-key budget as HTTP (see [Prepaid](#prepaid--deposit-once-draw-from-your-balance-opt-in)).

## Prohibited use

Don't use nouli to break the law or anyone's rules that apply to you: no
unlawful gambling or lotteries, no sanctions evasion, no money laundering,
no market manipulation, and no attacking this service itself (hammering it
with requests you don't intend to pay for, or circumventing the per-IP
caps). You are responsible for what you do with the outputs. On the x402
lane nouli keeps no accounts and no personal data; caps are per IP address;
payment settles directly on-chain to nouli's custody address — no
intermediary holds funds. The opt-in prepaid lane is the documented
exception: a deposit funds a prepaid account, and the ledger keeps your
wallet address, tx hashes, amounts, and timestamps — nothing else;
deposited funds sit with the operator (custody stance in
[docs](https://nouli.dev/docs)).

## The marketplace

nouli is **a gumball.store Solution** — instantly-settled solutions agents
buy without accounts: https://gumball.store

## Reference

- [openapi.json](https://nouli.dev/openapi.json) — OpenAPI 3.1, every
  endpoint with its 402/429/503 responses and receipt schemas
- [llms.txt](https://nouli.dev/llms.txt) ·
  [llms-full.txt](https://nouli.dev/llms-full.txt) — this index and this
  doc plus the endpoint reference, in one file
- [agent-card.json](https://nouli.dev/.well-known/agent-card.json) — A2A
  discovery; the anchor is listed as its own skill
- [/mcp](https://nouli.dev/mcp) — the MCP mirror: the same three SKUs as
  tools (`nouli_receipt`, `nouli_anchor`, `nouli_flip`), x402 payment in
  `_meta`, caps shared with HTTP
- [docs](https://nouli.dev/docs) — the human page (error meanings,
  prohibited use) · [verify](https://nouli.dev/verify) — verify any receipt
- [nouli-keys.json](https://nouli.dev/.well-known/nouli-keys.json) — the
  append-only signing keys
- Prepaid (opt-in): [GET /v1/prepaid/deposit](https://nouli.dev/v1/prepaid/deposit)
  — the live deposit address · `POST /v1/prepaid/claim` — credit your
  account, receive your key · `GET /v1/prepaid/balance` — your standing