Skip to main content
Every time a buyer successfully pays for a request, your seller automatically writes a Receipt to an HCS topic. Receipts are append-only, publicly readable Hedera Consensus Service messages that record what was paid, who paid it, what was delivered, and how much compute was consumed. Any party — the buyer, a third-party auditor, or an automated agent — can read the receipts topic from the public mirror node and verify every line of your billing history against the actual on-chain transactions.

​
What a Receipt Contains

Each receipt is written as a JSON message to the HCS receipts topic. The table below describes every field:

​
How Receipts Are Written

Your seller writes receipts automatically — you do not take any manual action. The flow is:
1

Buyer submits a paid request

The buyer attaches a signed TransferTransaction to the request. Your middleware forwards it to Blocky402 for verification.
2

Handler runs successfully

Your endpoint handler (e.g. /v1/infer) processes the request and returns a 2xx response. A 4xx or 5xx cancels settlement — failed requests are never charged and no receipt is written.
3

Blocky402 settles the transaction

The middleware calls Blocky402 /settle. Blocky402 co-signs the transaction as fee payer and submits it to Hedera. The response carries the final transaction ID.
4

Seller assembles and writes the receipt

After settlement is confirmed, the seller reads the x-agora-usage header (token counts or unit counts) from the buffered response and computes the SHA-256 hash of the response body. It assembles the completed receipt and submits it to the HCS receipts topic.
Receipts are written to the HCS topic identified by RECEIPTS_TOPIC_ID in your .env. Run npm run setup:topics to create this topic before starting the seller for the first time.

​
Read Recent Receipts via the API

Your seller also keeps an in-memory list of recent receipts for quick inspection. Query it with:
  • limit — number of receipts to return (default 50, maximum 200)
Example response:
GET /receipts response
The in-memory receipt list is cleared when the seller restarts. For a complete, persistent audit trail, read receipts directly from the HCS topic using the CLI described below.

​
Audit Receipts with the CLI

The agora receipts command reads every receipt from the HCS topic, cross-checks each transactionId against the Hedera mirror node, and reports whether the on-chain transfer matches what the receipt claims:
Terminal
Example output:
Each line prefixed OK means the mirror node confirms a successful TransferTransaction with the payer, payee, asset, and amount matching what the receipt records. A FAIL prefix indicates a discrepancy — along with a description of what did not match.
Pass --seller-account <0.0.x> to verify receipt authorship. The audit checks that each receipt message was submitted to HCS by the expected seller account. Any receipt written by a different account is flagged, protecting buyers from tampered receipts injected into the topic by a third party.

​
Verifying a Single Receipt Manually

You can also verify any individual receipt by taking its transactionId to HashScan directly. Look up the transaction and confirm that the HBAR (or HTS token) transfer matches the payer, payTo, and amount fields in the receipt.