AP2 x402 USDC payments: 2026 setup guide

A new technical guide describes how developers can combine Google’s Agent Payments Protocol (AP2) with the a2a-x402 extension to record user consent and settle USDC on-chain in six steps. The guide covers declaring the extension, returning payment-required A2A tasks, capturing mandates, signing a PaymentPayload, verifying and settling on-chain, and running Google’s samples.

Google announced AP2 on September 16, 2025. AP2 provides cryptographically signed Checkout and Payment Mandates that document what a user authorized. The a2a-x402 extension defines how a merchant agent requests an on-chain USDC payment and how a client agent submits a signed PaymentPayload inside an A2A task. The extension is versioned v0.1 and the guide notes an AP2-native x402 variant is not yet available.

The guide instructs merchants to declare the x402 extension in an AgentCard by including the extension URI in the extensions array and marking it required so incompatible clients are rejected. Clients must activate the extension per request with an X-A2A-Extensions header and the server must echo the URI to confirm activation.

When a request requires payment, the merchant returns an A2A Task in state input-required and sets task metadata such as x402.payment.status equal to payment-required. The task metadata carries an x402.payment.required object that lists accepted assets, network, payTo address and maxAmountRequired. The extension uses task metadata rather than an HTTP 402 status code to indicate payment is required.

AP2 Payment Mandates provide the consent mechanism. Open mandates can include payment.amount_range in minor fiat units, payment.budget as a total cap, and payment.agent_recurrence to limit frequency and occurrences. Open mandates include the agent’s public key so only that agent can use them. The guide highlights unit differences: AP2 mandates use fiat minor units (for example, USD cents) while x402 expects token base units (for USDC, six decimals). Developers must convert between units and log the exchange rate used before comparing mandate limits.

After a client agent verifies a mandate, a wallet or signing service creates and signs a PaymentPayload. The client sends the signed payload in a task message that includes the original taskId. The merchant uses the taskId to look up the original requirements and confirm the signed payload matches them. The guide reiterates the spec requirement that private keys must never be provided directly to any large language model in an agent path.

The merchant sends the PaymentPayload to a facilitator that verifies the signature and submits the on-chain transaction. Task state transitions move from payment-submitted to payment-verified to payment-completed. All settlement attempts are appended to x402.payment.receipts; receipts are not overwritten.

The guide lists common error conditions and the expected responses for each: INSUFFICIENT_FUNDS, INVALID_SIGNATURE, EXPIRED_PAYMENT, DUPLICATE_NONCE and NETWORK_MISMATCH among others. It describes the merchant’s options for handling each failure and notes the spec’s recommended responses.

A worked example in the guide shows a user signing an open mandate with a $200 budget and a per-payment cap that allows purchases priced at 48.24 USDC each. The example runs five sequential purchases, where the fifth attempt exceeds the $200 budget and triggers an unresolved_constraint response that returns control to the user for approval.

Google’s Human Present and Human Not Present x402 samples implement the flows and can be run locally. The human-not-present scenario requires a Google API key from AI Studio and starts services for the agent, merchant trigger and PSP simulator on defined ports. The samples mock payment providers, and the guide advises testnet pilots with small budgets and verification of Circle’s published USDC contract addresses before any live settlement.

The guide explains that teams building simple pay-per-call APIs may use plain HTTP x402 patterns, while teams building multi-call shopping or procurement agents can combine AP2 mandates with a2a-x402 to keep an auditable record of consent separate from settlement. The guide repeats that the x402 extension is v0.1 and that developers must implement unit conversion, mandate tracking and receipt reconciliation themselves before moving to production.