Turn an action into a verifiable fact

Step one: decide what to notarize

Do not "record everything." Receipts are public and cannot be deleted — noise stays forever.

The three interop rules

🔴 Violating one of these shows up as "receipt rejected," not a code error— which makes it hard to diagnose. The client library below already blocks all three locally.

The metadata naming trap

The easiest one to trip over. The Registry keeps a private-keyword blocklist, and itsplits field names on underscores and matches each segment — so the instinct of "just add a suffix" is wrong here.

# ❌ any of these gets the WHOLE receipt rejected
prompt_hash      # splits out prompt ⇒ blocked
user_email       # splits out email ⇒ blocked
raw_count        # splits out raw ⇒ blocked
session_id       # splits out session ⇒ blocked

# ✅ just rename it — meaning is unchanged
content_digest   text_digest   actor_ref   order_ref   tenant_ref

This is deliberate, not a bug. It blocks accidentally notarizing customer data. Full blocklist (28 keys — blocked at any level, any segment, anywhere in the receipt):

api_key   api_keys   access_token   auth_token   authorization   cookie   cookies   credential   credentials   email   full_receipt   html   image   messages   ocr_text   password   private_key   prompt   raw   raw_content   request_body   response   secret   screenshot   session   token   transcript   user_content

Only put in irreversible values

Receipts are public, and there is no delete API.

What this guarantees, and what it does not

🔴 See where the line is before you rely on this.The "guarantees" column below is mathematics — anyone can verify it independently; the "does not guarantee" column is a current implementation limit, not a promise.

Need a trusted timestamp or non-deletion? Both gaps already have a ready-made fix, and it ships in the package:

# only the hash is sent — the receipt and the file never leave your machine
pip install "agentoath[timestamps]"

from agentoath.timestamps import stamp_receipt, verify, upgrade

proof = stamp_receipt(receipt)
report = verify(proof)
report["any_valid"]          # a timestamp authority signed this hash together with its own clock
report["bitcoin_confirmed"]   # …and it is already written into a Bitcoin block

proof = upgrade(proof)        # a few hours later: pending → confirmed

Both mechanisms are used deliberately, because they fail differently. RFC 3161 has a timestamp authority sign with its own clock — instant, and a format courts and eIDAS recognize; you trust that authority, not us. OpenTimestamps writes the hash into Bitcoin — no party to trust, at the cost of waiting a few hours for it to land in a block.

🔴 Once you hold an OpenTimestamps proof plus your own copy of the receipt, even if every receipt here were deleted, you can still prove the thing happened, and when. It does not make the database undeletable — it makes the database **not matter** — which is the property you actually want.

The JavaScript package does not have this module: the only long-lived OpenTimestamps library on that side stopped being maintained in 2019, and the newer alternatives are all v0.x, unknown authors, published less than two months ago. A package other people install should not carry that kind of dependency. targetOfReceipt() gives you the hash to stamp; do the actual stamping with the Python package or the ots CLI — the proof format is language-neutral JSON.

Attesting a document

There is no "document receipt" type, and that is the point: a document is an ordinary receipt plus one metadata convention, so signing, the cross-language byte-identical canonical form, the privacy blocklist, and the Registry's validation all keep working unchanged. A new type would mean re-earning all of that from scratch.

# Python
from agentoath.documents import build_document_receipt
receipt = build_document_receipt(identity, "scans/book-0417.pdf",
    refs={"source_ref": "isbn:9780000000001", "acquired_ref": "po-2026-0817"})

// JavaScript
import { buildDocumentReceipt } from 'agentoath/documents';

receipt_id is derived from the file's hash, so attesting the same file twice produces the same receipt, not two unrelated ones. The file is read as a stream — a multi-gigabyte scan does not have to fit in memory.

🔴 The file itself never leaves your machine — only its sha256 goes into the receipt. The hash proves "this is the same one" to someone who already has the file, and proves nothing to anyone who does not — which is exactly the property you want when the thing you are attesting is a scan you cannot redistribute.

Reference fields must end in _ref and stay under 128 characters. Receipts are public and permanent — a sentence you paste in cannot be taken back.

🔴 A receipt is a side effect, not a precondition

If the Registry is down, the key is not set, or the network is unreachable, your main function must still complete normally. The reverse must never happen.

// ✅ the correct shape
const result = await doTheActualWork();      // do the real work first
try {
  recordReceipt(result);                     // async — don't make the user wait on the network
} catch { /* a recording failure must never touch the line above */ }
return result;                               // return it exactly as-is

Three more things worth doing in practice: off by default (not a single byte is sent until it is explicitly turned on); if it cannot send, sign it and land it in an outbox to retry later — the receipt id is fixed at signing time, so a retry goes through the idempotent path and never becomes two records; catch at both layers — the caller wraps it in try/catch, and the recording function itself never throws either.

Client libraries

Both official packages build this in. Zero extra dependencies (Python adds onlycryptography; JS uses Node's built-in crypto), canonical JSON byte-identical to the Registry, all three interop rules enforced locally first, the blocklist scanned locally first, off by default.

# Python
pip install agentoath
from agentoath.hosted import Identity, build_signed_receipt

// JavaScript (ESM; use await import for CJS)
npm install agentoath
import { Identity, buildSignedReceipt } from 'agentoath/hosted';

Don't want the dependency, or not using either language? This is the same thing as a single zero-dependency file you can drop straight into your project:

⬇ Download agentoath-client.mjs

// save as lib/agentoath.mjs and import it directly
import { Identity, RegistryClient, buildSignedReceipt, sha256Json } from "./lib/agentoath.mjs";

// 1. generate an identity (store the private key in an env var, never commit it)
const id = Identity.generate();
console.log(id.did, id.privateKey);

// 2. register once (idempotent — rerunning never creates a second identity)
const c = new RegistryClient({ apiKey: process.env.AGENTOATH_KEY, enabled: true });
await c.registerIdentity(id, { name: "my-service", platform: "my-platform" });

// 3. every action worth notarizing
const receipt = buildSignedReceipt(id, {
  receiptId: `verdict-$${orderId}`,
  action: "compliance.verdict.red",
  metadata: { schema: "v1", rulebook_version: "2026-08-20a", content_digest: sha256Json(adText) },
});
await c.publishReceipt(receipt);

🔴 Do not rewrite canonical JSON yourself. One bit of difference between the two sides and the signature never verifies, and the symptom is "receipt rejected," not an error. Use the file above, or implement the spec at GET /api/v1/registryliterally, byte for byte. The Python-side equivalent is json.dumps(v, ensure_ascii=False, sort_keys=True, separators=(",", ":")).

How to prove it actually worked

🔴 Do not look at "no errors" — that is not evidence. Evidence looks like a state flip.

# before
curl -s $REGISTRY/api/v1/agents/$DID/status
# → receipt_count: 0

# trigger one REAL action (do not use fake test data)

# after
curl -s $REGISTRY/api/v1/agents/$DID/status
# → receipt_count: 1   ← this 0→1 is the evidence

# negative control: change any one field in the same receipt, it must flip to valid=false
curl -s -X POST $REGISTRY/api/v1/receipts/verify \
  -H "Content-Type: application/json" \
  -d '{"receipt": <receipt with one field changed>, "from_public_key": "<your public key>"}'
# → {"valid": false, ...}

Verify both directions. Checking only that the valid case passes is not enough — it might just say pass to everything. Only when the negative control actually flips to false is the signature proven to be protecting the content.

Common snags