x402-hedera-receipts

Verifiable receipts for x402 on Hedera. Signed offers, price schedules and meter readings, anchored to HCS — so an overcharge is arithmetic anyone can check.

x402's upto scheme lets a seller decide, after the work, how much to charge. Nothing in x402 makes that decision checkable: the canonical offer-receipt payloads carry no meter reading, so an upto receipt is unverifiable by construction. This package makes it evidence.

What it does

The seller signs four documents and anchors them to a Hedera Consensus Service topic:

• before the work — the canonical x402 offer (commits the ceiling) and a price schedule (commits the unit price the canonical offer has no field for)
• after the work — the canonical receipt, and a meter reading carrying the token count and a hash of what was delivered

Then anyone can audit any settlement using only the public Mirror Node — no key, no account, no cooperation from the seller:

captured_amount  ≠  units × unit_price_from_the_signed_offer     ⇒  provable fraud

At $0.0001 a message, Hedera is the only chain where a per-call receipt costs less than the call.

The CLI — audit anything, trusting nobody

npx x402-hedera-receipts audit --topic 0.0.9557142
npx x402-hedera-receipts audit --topic 0.0.9557142 --tx 0.0.X@169...  # one settlement, in full

Reads the public Hedera Mirror Node and the chain. It has no key, no account, and no access to any server. Delete every machine the seller owns and it returns the same verdict.

Library

import { auditSettlement, buildLedger, auditSettlementLogic } from 'x402-hedera-receipts';

// audit one settlement from HCS + the chain
const verdict = await auditSettlement(bundle, 'hedera:testnet');
//   → { ok, violations: ['arithmetic_fraud', ...], checks, captured, claimed, units, unitPrice }

// score every seller on a topic, purely from public data
const ledger = await buildLedger({ receiptsTopicId: '0.0.9557142', network: 'hedera:testnet' });

// the verdict as a PURE function of what the chain already told us — no I/O, unit-testable
const v = auditSettlementLogic(bundle, sellerPublicKey, onChainCapture);

Key resolution needs no infrastructure. A receipt's kid is did:hedera:testnet:0.0.X#key-1, and the Mirror Node serves the account's public key. The seller signs receipts with the same key it holds funds with — it cannot disown a signature without disowning the account being paid.

What it proves — and what it does not

Proves: the seller signed these numbers; the terms on HCS are the terms the buyer signed on-chain; the charge equals units × the signed unit price; the chain took exactly what the receipt admits; nothing exceeded the ceiling.

Does not prove: that the token count itself is truthful. The seller counts the tokens; a consistent liar passes every check. What changes is that the count is now signed, timestamped, and bound to a hash of what was delivered — the buyer holds the response, can recount, and then holds the seller's signature on a false number. That is the difference between a dispute and a complaint.

Bonded disputes (HIP-991)

createDisputeTopic / postDispute file an accusation on a fee-gated HCS topic, so making a claim costs a bond charged by consensus — a rival cannot flood the reputation ledger for free. There is no equivalent on any other chain.

License

Apache-2.0