@harpd/agent-transaction-audit-schema

A canonical, protocol-agnostic audit record for agent payments. Every payment an agent makes or receives — over x402, MPP, or AP2 — should reduce to one AuditRecord, so dashboards, alerts, and compliance reports all agree. Comes with normalizePayment() (convert any protocol into the canonical shape) and validateAuditRecord() (a tiny, zero-dependency validator).

Part of Harpd's open-source agent-commerce toolkit. Pairs with @harpd/x402-logging-middleware (the event shape is compatible) and @harpd/mcp-paid-tool-starter (emit an audit record when a paid tool runs).

Install

npm install @harpd/agent-transaction-audit-schema

Normalize any protocol into one record

import { normalizePayment } from '@harpd/agent-transaction-audit-schema'

// x402
const rec = normalizePayment({
  protocol: 'x402',
  direction: 'outbound',
  actor: { id: 'weather-agent', type: 'agent' },
  counterparty: { id: 'paid-weather-api', type: 'service' },
  raw: { accepts: [{ asset: 'eip155:8453/erc20:0xUSDC', price: '10000' }], payment: { asset: 'eip155:8453/erc20:0xUSDC', amount: 10000, transaction: '0xabc' } },
  status: 'settled',
})

// MPP / AP2 work the same way — pass protocol: 'mpp' | 'ap2' and the raw payload.

Validate before you store

import { validateAuditRecord, AUDIT_RECORD_SCHEMA } from '@harpd/agent-transaction-audit-schema'

const result = validateAuditRecord(rec)
if (!result.ok) {
  console.error('dropped bad audit record:', result.errors)
}

The schema requires: id, protocol (x402|mpp|ap2|other), direction (outbound|inbound), actor.id, counterparty.id, asset, amount, status, timestamp. amountUnit is one of usd|micro-usd|wei|raw.

Why a shared schema

Agent payments are fragmented across protocols, each with its own wire format. Without a canonical record, every consumer re-implements parsing and they drift apart — one service counts micro-usd, another usd, audits silently disagree. This package is the single source of truth; the Harpd collector and dashboard are built on exactly this shape.

License

MIT © Harpd. Issues and PRs welcome at github.com/harpd-dev/agent-transaction-audit-schema.