How Agent Receipts Works

Logs are internal, mutable, developer-only, and unverifiable. Anyone can edit a log entry after the fact.

Receipts are cryptographically signed, immutable, shareable, and independently verifiable. Once signed, tampering is detectable by anyone with the public key.

{
  receipt_id:    "rcpt_abc123"         // unique identifier
  agent_id:      "my-agent"           // who acted
  action:        "generate_code"      // what they did
  input_hash:    "sha256:..."         // what they received (hashed)
  output_hash:   "sha256:..."         // what they produced (hashed)
  status:        "completed"          // outcome
  timestamp:     "2026-04-02T..."     // when
  signature:     "ed25519:..."        // cryptographic proof
}

The full schema has 29 fields covering identity, timing, performance metrics, constraints, judgments, and cryptographic proof.

Every receipt is signed with Ed25519 — the same algorithm used by SSH, Signal, and TLS 1.3.

How signing works:
1. Generate a key pair (private + public) — stored locally
2. When an action completes, 12 fields are extracted into a signable payload
3. Fields are sorted alphabetically and JSON-serialized (canonical form)
4. The payload is signed with your private key using Ed25519
5. Signature stored on receipt as "ed25519:<base64>"

The 12 signed fields:
  action, agent_id, chain_id, completed_at, environment,
  input_hash, org_id, output_hash, receipt_id,
  receipt_type, status, timestamp

To verify: anyone with your public key can re-canonicalize the same 12 fields and check the signature — no server required.

Input and output data is never stored — only SHA-256 hashes. Prove what was processed without exposing the data itself.

Multi-step workflows are linked together as chains. Each step references the previous via parent_receipt_id.

Benefits: full history of complex workflows, identify which step caused a failure, total cost/duration across the workflow, track which agents were involved at each stage.

Define rules that receipts must satisfy. Evaluated at creation/completion time. Results stored on the receipt — no re-evaluation needed.

constraints: [
  { type: "max_latency_ms", value: 5000 },
  { type: "max_cost_usd", value: 0.10 },
  { type: "min_confidence", value: 0.8 }
]

An AI model can evaluate receipt outputs against a rubric — and the evaluation itself is stored as a signed receipt.

Judgment flow:
1. Define a rubric (criteria with weights and thresholds)
2. Call judge_receipt with the receipt ID and rubric
3. A pending judgment receipt is created
4. An AI model evaluates the output against each criterion
5. Judgment completed with verdict (pass/fail/partial) and score (0-1)

Example rubric:
  Accuracy      weight: 0.4  threshold: 0.7
  Completeness  weight: 0.3  threshold: 0.6
  Clarity       weight: 0.3  threshold: 0.7

Judgments are stored as receipts themselves (receipt_type: "judgment") — signed, immutable, and verifiable.

MCP Server (for Claude, Cursor, VS Code):

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

TypeScript SDK:

import { AgentReceipts } from '@agent-receipts/sdk'

const client = new AgentReceipts()
await client.track({
  action: 'generate_code',
  input: { prompt },
  output: { code },
  model: 'claude-sonnet-4-20250514',
  tokens_in: 1200,
  tokens_out: 400,
  cost_usd: 0.008,
  latency_ms: 2100,
})

CLI:

npx @agent-receipts/cli init
npx @agent-receipts/cli list
npx @agent-receipts/cli verify <receipt-id>
npx @agent-receipts/cli stats

All receipts stored locally in ~/.agent-receipts/. Your private key never leaves your machine.