Module ap2 

AP2 (Agent Payments Protocol) signed-Mandate pre-call spend gate.

This is the second payment rail on the same pre-call spend gate the x402 module added on 2026-07-24. Where x402 gates a payment quoted inline as an HTTP 402 Payment Required challenge, Google AP2 gates a payment authorized ahead of time by a signed Mandate chain:

• an Intent Mandate — the user (or their key) pre-authorizes an agent to spend, within a scope: which merchants/categories, up to a max amount (Ap2IntentMandate); and
• a Cart Mandate — the concrete cart the agent assembled, bound to that intent by intent_id and signed (Ap2CartMandate).

Before an autonomous payment is authorized, evaluate_ap2_payment:

1. verifies the signature chain — the Intent and the Cart are each signed by a key in the trusted Ap2Keyring, and the Cart is cryptographically bound to the Intent it claims (real Ed25519, RFC 8032);
2. checks the cart total against the per-task ceiling the policy already enforces for x402 — the very same Budget::has_cost_headroom (crate::budget::Budget::has_cost_headroom); and
3. checks the cart stays within the Intent’s authorized scope (merchant, category, the user’s own max amount).

It is deny-by-default: a missing or invalid signature, an unknown signing key, a Cart not bound to its Intent, a cart total over the budget ceiling, an amount over the user’s intent max, or a merchant/category outside the intent scope all return an Ap2GateOutcome::Deny and authorize nothing.

Like the x402 gate, this module never moves money. It verifies mandates and returns an authorize/deny decision; executing the payment (card rail, bank transfer, stablecoin settlement) lives entirely outside FerrumDeck. An authorized payment normalizes to an Ap2CostEvent that folds into the same cost_cents ledger as x402 and token cost, so a run’s cost slope covers both payment rails.

Structs

Ap2CartMandate

A parsed AP2 Cart Mandate: the concrete cart the agent assembled, bound to an Intent by intent_id and signed.

Ap2CostEvent

A verified, authorized AP2 payment normalized to cents — a first-class cost event that folds into the same cost_cents ledger as x402 and token cost.

Ap2IntentMandate

A parsed AP2 Intent Mandate: the user’s pre-authorization for an agent to spend within Ap2Scope, signed by a key in the Ap2Keyring.

Ap2Keyring

A registry of trusted Ed25519 verifying keys, keyed by key_id. A mandate signed by a key_id absent here is denied (Ap2DenyKind::UnknownKey).

Ap2Money

A money amount on the AP2 rail, normalized to the common budget unit (cents).

Ap2Scope

The scope an Ap2IntentMandate authorizes — what the user actually consented to. An empty merchants/categories list means “unconstrained on that axis”; max_amount always binds.

Enums

Ap2DenyKind

Why an AP2 payment was denied. Every variant is a hard stop — the payment is not authorized.

Ap2GateOutcome

The pre-call spend-gate decision for an AP2 payment, produced by evaluate_ap2_payment before any payment is authorized.

Constants

AP2_ANCHOR

Stable anchor recorded alongside an AP2 decision so audit consumers can cite the protocol without re-reading docstrings.

Functions

evaluate_ap2_payment

The AP2 pre-call spend gate: verify the signed mandate chain, the intent scope, and the per-task budget ceiling before authorizing an autonomous payment.