← Back to blog

Signed Receipts API for AI Agents: Audit Trails for Autonomous Work

Your agent just spent money on credits, claimed a public identity handle, requested an approval, or completed a multi-step job for a client. Hours later someone asks: what actually happened? Log files lie, screenshots can be faked, and a plain database row proves nothing to anyone outside your own system.

The Agent Media Tools Signed Receipts API gives AI agents a server-verifiable audit trail. Every receipt gets a SHA-256 content hash and an HMAC-SHA256 signature at write time, plus a verify_url that anyone — no API key required — can open to ask Agent Media Tools to confirm the stored record is intact.

Why autonomous agents need receipts

Once an agent runs unattended — buying credits, completing purchases with a saved payment method, updating its own spend policy, or coordinating with other agents — you stop being present for each action. An audit trail is how you answer three questions after the fact:

• What happened? A structured record of the action, subject, and metadata.
• When and by whom? Every receipt is tied to the agent key (and linked user) that triggered it.
• Does the stored record still verify? The public verification endpoint re-checks the record against the server-held HMAC secret.

Receipts are not a replacement for logs or payment confirmations. They are a compact, signed ledger layer on top of them — the proof-of-work record your agent can point to when a human asks for evidence.

When receipts are written automatically

You do not have to remember to create most receipts. The platform signs one for you whenever a key does something important:

• identity — claiming or updating an agent handle (identity.claim, identity.update)
• mailbox — claiming a mailbox (mailbox.claim)
• policy — spend policy or notification channel updates (policy.update, notify_channels.update)
• approval — approval requests and decisions (approval.request, approval.approved, approval.denied)
• purchase — autonomous purchases, including amount in cents and the Stripe payment intent ID
• custom — anything you sign yourself via the create endpoint

Every receipt returns a verify_url, so the record can be handed off as evidence immediately after it is written.

Endpoint overview

Endpoint	Auth	What it does
POST /api/agent/receipts	Bearer agent key	Create a signed custom receipt
GET /api/agent/receipts	Bearer agent key	List receipts for your key, filter by kind
GET /api/agent/receipts/:id	Public	Fetch a receipt with live signature verification
POST /api/agent/receipts/verify	Public	Verify by id, or offline via content_hash + signature

Create a signed receipt with curl

Agent keys are Bearer tokens that start with mt_. Create one from the toolbox after signing in, then write your first receipt:

curl -X POST https://agentmediatools.com/api/agent/receipts \
  -H "Authorization: Bearer mt_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "task.completed",
    "subject": "pdf-pipeline/run-4821",
    "meta": {
      "pages": 14,
      "output": "https://example.com/runs/4821/report.md",
      "duration_seconds": 212
    }
  }'

The API responds with 201 Created and the signed record:

{
  "success": true,
  "receipt": {
    "id": "a1b2c3d4-...",
    "kind": "custom",
    "action": "task.completed",
    "subject": "pdf-pipeline/run-4821",
    "meta": { "pages": 14, "output": "https://example.com/runs/4821/report.md", "duration_seconds": 212 },
    "content_hash": "9f86d081884c7d65...",
    "signature": "6d9f...",
    "created_at": "2026-08-22T12:00:00.000Z",
    "verify_url": "https://agentmediatools.com/api/agent/receipts/a1b2c3d4-..."
  }
}

Notes on the create endpoint: action defaults to custom.event if omitted (the MCP tool requires it), subject is capped at 200 characters, and meta must be a JSON object no larger than 8 KB.

Verify a receipt without a key

This is the part that makes receipts useful as evidence: verification is public. Pass the receipt ID to GET /api/agent/receipts/:id:

curl https://agentmediatools.com/api/agent/receipts/a1b2c3d4-...

The response includes valid and signature_ok flags computed fresh from the stored hash path:

{
  "success": true,
  "receipt": {
    "valid": true,
    "signature_ok": true,
    "id": "a1b2c3d4-...",
    "kind": "custom",
    "action": "task.completed",
    "subject": "pdf-pipeline/run-4821",
    "meta": { "pages": 14, "duration_seconds": 212 },
    "content_hash": "9f86d081884c7d65...",
    "signature": "6d9f...",
    "created_at": "2026-08-22T12:00:00.000Z"
  }
}

Or ask the server to verify a stored content_hash and signature pair without fetching the record:

curl -X POST https://agentmediatools.com/api/agent/receipts/verify \
  -H "Content-Type: application/json" \
  -d '{
    "content_hash": "9f86d081884c7d65...",
    "signature": "6d9f..."
  }'

List receipts with Python (requests)

For dashboards, reconciliation scripts, or an agent auditing its own history, list receipts for your key — optionally filtered by kind:

import requests

API = "https://agentmediatools.com/api/agent/receipts"
HEADERS = {"Authorization": "Bearer mt_YOUR_KEY"}

# All receipts for this key
r = requests.get(API, headers=HEADERS, params={"limit": 30})
print(r.status_code, r.json().get("count"))

# Only purchase receipts
r = requests.get(API, headers=HEADERS, params={"kind": "purchase", "limit": 100})
for receipt in r.json().get("receipts", []):
    print(receipt["id"], receipt["action"], receipt["subject"],
          receipt["meta"].get("amount_cents"))

# Verify a single receipt by ID (no auth needed)
v = requests.get(f"{API}/{receipt_id}").json()
assert v["receipt"]["valid"], "receipt failed verification"

The list endpoint returns newest-first with count and a receipts array; limit caps at 100 per call. The example above is a complete audit loop: fetch, filter, then assert integrity on each record.

A realistic workflow: prove what your agent shipped

Put it together with a concrete scenario. Your agent runs a document pipeline: it downloads an invoice PDF, converts it to markdown, extracts key fields, and posts the result to a client mailbox. At each step it writes a signed receipt — one for the conversion, one for the extraction, one for the delivery. Later, the client asks whether the numbers in their report actually came from the PDF they sent. Instead of re-running the whole pipeline or digging through logs, you hand them two things: the receipt IDs and the output file. They open GET /api/agent/receipts/:id for each ID, confirm valid: true on every record, and see the exact metadata the agent recorded at run time.

For paid actions the pattern is even more important. When an agent completes an autonomous purchase, the platform writes a purchase receipt containing the amount in cents and the payment intent ID. A daily reconciliation script lists kind=purchase receipts and cross-checks them against the Stripe dashboard. Any mismatch is visible in minutes instead of at invoice time.

The same habit applies to single-agent work. Sign a receipt when a long job finishes, and you get a stable identifier you can paste into tickets, chat threads, or client emails — one that resolves to a verifiable record instead of a vague "it ran".

Same tools over MCP

If your agent runs inside an MCP host (Claude Desktop, Hermes, or any MCP client), the same operations are exposed as create_receipt and list_receipts. create_receipt takes action, optional subject and meta; list_receipts takes an optional kind filter (purchase|identity|approval|mailbox|policy|custom) and limit (default 30). That makes the pattern one tool call inside a workflow: sign work as you go, and let the host audit itself.

Honest boundaries

• Retention is 90 days. The platform prunes receipts older than 90 days to keep storage small. Archive critical records (the content_hash and signature pair) if you need them longer.
• Server-side integrity, not independent notarization. Verification depends on Agent Media Tools retaining the HMAC secret. It is not a public-key signature, third-party timestamp, or blockchain anchor.
• Write and list need a key. Creating receipts and listing them requires a Bearer agent key; only fetching and verifying by ID are public.

That is the whole loop: sign work when it happens, hand over the verify_url as evidence, and let anyone re-check the record later. It is a small API, but it is the difference between "trust me, my agent did it" and a record that can be checked.