PEAC Protocol

Portable signed records for agent, API, MCP, and cross-runtime interactions.

PEAC is the open standard for verifiable interaction records across APIs, MCP servers, x402-powered payment flows, paymentauth / MPP, ACP, A2A workflows, runtime governance, and other cross-runtime systems.

Use PEAC when local logs are not enough and another party needs a signed, portable record of what happened. Do not use PEAC when local logs inside one system are sufficient and no external party needs to verify those records. PEAC does not replace auth, payment rails, observability, or transport protocols; it adds portable signed records across them.

Keep auth, keep payments, keep observability. Add /.well-known/peac.txt, return PEAC-Receipt, and verify records offline across organizational boundaries.

The PEAC loop

1. Publish terms at /.well-known/peac.txt
2. Return PEAC-Receipt with a signed interaction record
3. Verify offline with the issuer's public key

Why PEAC

• Logs are local. PEAC records are portable.
• Traces correlate systems. PEAC records survive organizational boundaries.
• Auth and payments authorize actions. PEAC records prove what happened.

Quick start

In under a minute, you can verify a PEAC receipt offline.

Requirements: Node 24 tested, Node 22+ compatible. Go middleware and examples are supported (Go 1.26+). Python is available through API-first examples and OpenAPI-driven flows.

pnpm add @peac/protocol @peac/crypto

import { verifyLocal } from '@peac/protocol';

const receipt = response.headers.get('PEAC-Receipt');
const result = await verifyLocal(receipt, publicKey, {
  issuer: 'https://api.example.com',
});

if (result.valid) {
  console.log(result.claims.iss, result.claims.kind, result.claims.type);
}

A governed HTTP response looks like:

HTTP/1.1 200 OK
PEAC-Receipt: eyJhbGciOiJFZERTQSIsInR5cCI6ImludGVyYWN0aW9uLXJlY29yZCtqd3QifQ...
Link: </.well-known/peac-issuer.json>; rel="issuer"

Try PEAC in 5 minutes

• Verify a receipt locally with verifyLocal() or pnpm dlx @peac/cli verify.
• Start the MCP server: npx -y @peac/mcp-server.
• Run the x402 settlement mapping demo: pnpm install && pnpm build && pnpm --filter @peac/example-x402-upto-evidence demo.
• Open an editor plugin-pack surface under surfaces/plugin-pack/ (Cursor, Codex, Claude Code, VS Code, Continue, Windsurf, OpenCode).
• Run the minimal example: pnpm --filter @peac/example-minimal demo.
• Follow the API Provider Quickstart or Agent Operator Quickstart.

Choose your path

• I run an API. API Provider Quickstart with Express middleware.
• I run an MCP server. MCP Integration Kit or npx -y @peac/mcp-server; editor surfaces under surfaces/plugin-pack/.
• I verify receipts. Agent Operator Quickstart.
• I build A2A agents. A2A Integration Kit.
• I build x402, paymentauth / MPP, ACP, or metered API flows. x402, paymentauth, ACP; coverage at docs/compatibility/commerce-protocol-coverage.md.
• I operate governed runtimes. @peac/adapter-runtime-governance records decisions from managed runtimes (for example Microsoft Agent Governance Toolkit).
• I need portable audit evidence. Core use-case coverage and governance mappings.
• I want editor or plugin integration. Cursor, Codex, Claude Code, VS Code, Continue, Windsurf, and OpenCode under surfaces/plugin-pack/; canonical Smithery deployment config.

See docs/START_HERE.md for the full decision tree.

Where PEAC fits

• Attach signed records to metered or paid API responses so consumers can verify what was offered, measured, charged, or delivered.
• Carry verifiable receipts across MCP and agent workflows instead of relying on local execution logs.
• Preserve evidence for audit, dispute, and reconciliation across system and organizational boundaries.
• Record governance and control-plane decisions from managed runtimes such as Microsoft Agent Governance Toolkit.
• Map commerce and payment events into verifiable records across x402, paymentauth (draft-ryan-httpauth-payment-01; MPP), Agentic Commerce Protocol (ACP), and Stripe SPT.

Implementations and surfaces

• TypeScript core — issuance, verification, CLI, middleware (this repo).
• Go SDK — sdks/go/ with production HTTP middleware.
• MCP tools — packages/mcp-server/ evidence tools.
• Editor and plugin-pack surfaces — Cursor, Codex, Claude Code, VS Code, Continue, Windsurf, OpenCode under surfaces/plugin-pack/; canonical Smithery config.
• Express middleware — packages/middleware-express/.
• Commerce mappings — packages/adapters/x402/ (v1 + v2), packages/mappings/paymentauth/ (paymentauth and MPP), packages/mappings/acp/ (ACP delegated payment).
• Runtime governance — packages/adapters/runtime-governance/ records from Microsoft Agent Governance Toolkit and other managed runtimes.
• Supply-chain mappings — packages/mappings/intoto/ and packages/mappings/slsa/.

Long tail (A2A, gRPC, DID, managed agents, and more): docs/README_LONG.md.

Artifacts

Artifact	Role
/.well-known/peac.txt	Machine-readable terms
PEAC-Receipt	Signed interaction record on governed responses
verifyLocal()	Offline verification once issuer keys are available
peac-bundle/0.1	Portable audit/dispute package

CLI

Use the CLI to verify receipts, run conformance checks, reconcile bundles, validate policy artifacts, and run installability diagnostics without writing integration code first.

# One-off
pnpm dlx @peac/cli verify 'eyJhbGc...'

# Installed in your workspace
pnpm add -D @peac/cli
pnpm exec peac verify 'eyJhbGc...'

# From this repo
pnpm --filter @peac/cli exec peac verify 'eyJhbGc...'

Other commands: peac conformance run, peac reconcile a.bundle b.bundle, peac policy init|validate|generate, peac doctor. Full reference: packages/cli/README.md.

Security

• JWS signature verification required before trusting any receipt claim.
• Key discovery via /.well-known/peac-issuer.json JWKS with SSRF guards.
• Kernel constraints enforced at issuance and verification (fail-closed).
• No silent network fallback for offline verification.
• Errors mapped to RFC 9457 Problem Details.

See SECURITY.md, docs/specs/PROTOCOL-BEHAVIOR.md, docs/COMPATIBILITY_MATRIX.md, and docs/specs/VERSIONING.md.

Versioning

• Current default format: interaction-record+jwt.
• Legacy: peac-receipt/0.1 is frozen and legacy-only; verifyLocal() returns E_UNSUPPORTED_WIRE_VERSION on legacy input.

Full doctrine: docs/specs/VERSIONING.md.

Documentation

• Spec Index — normative specifications.
• Interaction Record Spec — envelope, kinds, extensions.
• Architecture — kernel-first design.
• Developer Guide — package catalog, extended examples.

Contributing and license

Contributions are welcome. For substantial changes, please open an issue first. See docs/SPEC_INDEX.md for normative specifications.

Apache-2.0. See LICENSE.

---

PEAC Protocol is an open-source project stewarded by Originary and community contributors.

Docs · GitHub · Discussions