ProtocolsAP2

AP2 — Agent Payments Protocol

AP2 (Agent Payments Protocol) brings FIDO-style cryptographic authorization to agentic payments. A human (or a delegating system) signs a mandate that proves the agent is authorized to spend on their behalf, and the merchant verifies that signature before charging.

AP2 is opt-in: enable it by passing ap2: true in AgentOptions.

const agent = new ShoppingAgent({
  llm: claude,
  ap2: true,
});

Mandate lifecycle

A mandate moves through three stages:

  1. Intent — what the user wants to do (e.g. “buy headphones under $200”).
  2. Cart — the concrete cart that satisfies that intent.
  3. Signed — the cart mandate, cryptographically signed and ready to present to the merchant.

Ap2Client builds and signs these mandates. The receiver-side structural validator, verifyMandateShape() (exported from the SDK), checks that an inbound signed mandate has the required fields and a non-expired expiresAt before you trust it.

Additional mandate types

  • RefundMandate — authorizes a refund. Create one with createRefundMandate().
  • DelegatedMandate — lets one party delegate signing authority to another, for chained or sub-agent flows.
  • x402 stablecoin extension — an extension for settling mandates over the x402 stablecoin payment rail.

Signature verification

Mandate signatures are verified against JWK public keys using ES256 or EdDSA. The verification primitives live in src/security/mandate-verifier.ts:

import { verifyMandate, createJwkSigner } from '@agorio/sdk/security';
 
// Signer side (e.g. tests, mock merchants, or the delegating party)
const signer = createJwkSigner({ /* private JWK + alg */ });
 
// Receiver side — resolve the signer's public JWK by kid, then verify
const result = await verifyMandate(signedMandate, { /* JwkResolver, options */ });
if (!result.ok) throw new Error(result.reason);
  • verifyMandate(...) — full verification: structural checks plus cryptographic signature verification against the resolved JWK.
  • createJwkSigner(...) — builds a signer over a private JWK, supporting the ES256 and EdDSA algorithms.

For the canonicalization rules (how a mandate is serialized before signing) and the verification design, see ADR docs/adr/0010-ap2-mandate-canonicalization-and-verification.md in the repository.

ACPMCP