x402 Work Receipts

Demo

About

When two companies let agents act for them — one ordering work, one accepting and doing it — the record of what was ordered, agreed and delivered ends up inside one company's system, which can edit it, lose it, or simply be believed less than the other when the two accounts differ. x402-work-receipts is a working instance of the alternative: no single party owns the authoritative audit trail; a shared ledger records signed evidence of which agent, holding which mandate, received, accepted and executed which command. A customer agent turns a story card into a signed work order and pays an intake fee; a contractor agent verifies the signature, anchors the order's fingerprint on a Hedera consensus topic, and returns a signed acceptance. When the work exists, the customer pays the balance and collects a signed delivery receipt carrying both payments. Six anchors go on the topic — only hashes, no content — and a stand-alone verifier reaches the same verdict either party would, reading nothing but the public mirror node. Built for two organizations that already argue about what was agreed — an agency and its client — and, longer term, for any pair of agents transacting without a platform both of them trust. What the chain proves (wording taken from the source protocol spec §4.2): a sealed mandate with envelope hash `eh` existed at the sender no later than consensus time T1 and was accepted by the contractor, whose receipt with hash `eh2` is fixed no later than T2; the counterparty's signature verifies independently. It does **not** prove the mandate's content (only its fingerprint), the quality or the fact of the work, or that a key belongs to a person. The `payment` profile adds: the intake and balance transfers exist on the ledger with the stated payer, payee and amounts. Try it without installing anything: https://x402-work-receipts.zeabur.app/verify loads the demo run and re-checks it against the public mirror node in the browser, with links to every anchor and payment on HashScan. This is not only a hackathon demo: two real companies have run the same signed work-order and receipt format in a private pilot since 8 September 2026 (their public audit topic on Hedera testnet: 0.0.10226839). The hackathon build is the open, self-contained slice of that format with x402 payment added.

How it's made

Node/TypeScript. Both agents speak x402 with the `exact` scheme on `hedera:testnet`, settled by the Blocky402 facilitator (`api.testnet.blocky402.com`) — not a payment demo, a real settled HBAR transfer per paid route, using the `upfront` flow so the handler can anchor the payment id inside the receipt it signs. Every step — order received, both payments, acceptance, delivery, receipt — is anchored as a hash-only message on a Hedera Consensus Service topic; a stand-alone verifier (`verifier/`) reads only the public mirror node, seven checks, three exit codes (0 verified, 1 failed, 2 could not check). The contractor publishes an agent card at /.well-known/agent.json, so a customer agent discovers the service and pays for it with x402 without any API key. Envelopes are Ed25519-signed RFC 8785 canonical JSON; `mandate.v1` and `receipt.v1` are byte-identical copies of a pre-existing protocol (drift-tested by sha256), so the project extends a schema it does not own rather than inventing its own. Extras shipped after the base flow verified end to end: HCS-14 `uaid` identifiers so the verifier can tie a signature to a stable id instead of only a handle; a Scheduled Transaction retainer the customer authorises up front and the contractor releases after delivering; an MCP server exposing `order`/`collect`/`verify` as tools for any MCP-speaking agent runtime. The hacky bit: the base protocol schemas forbid any field that looks like money (`hour`, `rate`, `amount`, `usd`, `price`, `cost`), so `payment.v1` is generated by a Python script that flattens the base schema's keywords into a new, self-contained schema, because JSON Schema 2020-12's `unevaluatedProperties: false` makes a plain `allOf`+`$ref` extension impossible. Claude Code wrote the modules under `protocol/`, `anchor/`, `contractor/`, `customer/`, `verifier/` and `demo/` from a written design and task-by-task plan kept in the repo; every task was reviewed, tested and checked against the public mirror node by hand before merging (see the "AI collaboration" section of the README).