A2A x402 Tutorial: Build Agent-to-Agent USDC Payments

A runnable, end-to-end a2a x402 tutorial: a seller agent returns a 402-style PaymentRequired, a buyer signs an EIP-3009 USDC payload, and a Coinbase CDP facilitator settles on Base.

What is the A2A x402 extension, and why this tutorial?

This a2a x402 tutorial gives you the one thing the rest of the internet does not: a runnable, end-to-end two-agent payment demo where a seller agent charges, a buyer agent pays in USDC, and a facilitator settles the money on-chain. Every ranking page today is either the raw google-agentic-commerce/a2a-x402 README, a high-level Coinbase announcement, or an HTTP-402-only walkthrough that never touches the actual A2A extension. We are going to walk the whole loop.

The A2A x402 extension brings cryptocurrency payments to the Agent-to-Agent (A2A) protocol, letting one agent monetize a service and another agent pay for it autonomously. It revives the long-dormant HTTP 402 Payment Required status code for the agent economy. The extension lives at github.com/google-agentic-commerce/a2a-x402 under Google’s Agentic Commerce org, and the Python package is published as x402-a2a.

Here is the part the READMEs never diagram clearly, and the reason builders get confused: there are three protocols doing three different jobs. A2A is the transport — how agents discover each other and pass task states. AP2 (the Agent Payments Protocol) is the authorization — a signed mandate that proves a human or principal actually approved the spend. x402 is the settlement — the signed EIP-3009 authorization and the on-chain USDC transfer. Keep those three lanes separate and the whole system suddenly makes sense.

By the end you will have a seller agent that publishes an agent card with a payments extension, returns a 402-style PaymentRequired task, and settles via a Coinbase CDP facilitator — plus a buyer agent that discovers the seller, signs an EIP-3009/USDC payment, and resubmits to collect the service. This is fresh, current as of mid-2026: in May 2026 AWS launched Amazon Bedrock AgentCore Payments built with Coinbase and Stripe on the exact same x402 rails, so the pattern you learn here is the one the hyperscalers are standardizing on.

How do A2A, AP2, and x402 fit together? The three-layer split

A2A carries the conversation, AP2 carries the authorization, and x402 carries the money. An agent uses A2A to discover a service, AP2 to prove the purchase was authorized, and x402 to settle the payment in USDC — three layers that compose but never overlap. The official Google + Coinbase launch describes exactly this division of labor, and it is the mental model you should hold for the rest of this tutorial.

Picture it as a stack. The top layer is your A2A task lifecycle: a request goes in, the task moves through states like input-required and completed, and metadata rides along. The middle layer is AP2: before money moves, the buyer agent attaches a Payment Mandate — a signed credential saying “my principal authorized spending up to $X for this cart.” The bottom layer is x402: the buyer signs an EIP-3009 transferWithAuthorization message over USDC, and a facilitator broadcasts it on-chain.

Why does the separation matter so much? Because each layer fails differently. An A2A failure is a dropped message. An AP2 failure is an unauthorized payment — the agent spent money it had no mandate to spend. An x402 failure is a bounced transaction — bad signature, expired nonce, insufficient funds. If you collapse them into one blob of code, you lose the ability to reason about which one broke, and in agentic commerce that ambiguity is a security hole.

In this tutorial we focus the deepest code on A2A + x402 because that is the runnable money path, and we show where AP2’s mandate slots in. If you want the full mandate-chain implementation, that is a separate build — but the diagram below is the map you should keep open in another tab the entire time.

  Buyer Agent                                  Seller Agent
  ===========                                  ============
      |                                              |
  [A2A]  --- 1. discover via agent-card.json ----->  |   transport
      |                                              |
      |  <-- 2. PaymentRequired task (402-style) --  |   x402 req
      |                                              |
  [AP2]  build + attach signed Payment Mandate       |   authorization
  [x402] sign EIP-3009 transferWithAuthorization      |   settlement
      |                                              |
      |  --- 3. resubmit w/ PaymentPayload -------->  |
      |                                              |--> [facilitator]
      |                                              |     verify + settle
      |                                              |<--  tx hash (receipt)
      |  <-- 4. payment-completed + service -------   |
      v                                              v

  Layer    Protocol   Job
  -----    --------   ---
  top      A2A        envelope: discovery, task states, metadata
  middle   AP2        permission slip: signed spend mandate
  bottom   x402       money: signed USDC authorization + settlement

Prerequisites and project setup for the a2a x402 extension in Python

You need Python 3.10+, the x402-a2a and a2a-sdk packages, an eth-account keypair for the buyer, and a Coinbase Developer Platform (CDP) API key for the facilitator. Everything in this a2a x402 extension python walkthrough runs on the base-sepolia testnet, so you can complete the full loop without spending real USDC.

Create a clean virtual environment and install the dependencies. The x402-a2a package pulls in the core x402 types it builds on; a2a-sdk gives you the AgentExecutor, AgentCard, and task plumbing; eth-account handles the EIP-712 signing on the buyer side.

For the facilitator, sign up at the Coinbase Developer Platform and grab an API key. The CDP-hosted facilitator processes ERC-20 payments on Base, Polygon, Arbitrum, World, and Solana via EIP-3009 (USDC, EURC) with a free tier of 1,000 transactions per month, then $0.001 per transaction. On base-sepolia you can use the public testnet facilitator with no key at all, which is how we will start.

Fund the buyer’s address with test USDC from a Base Sepolia faucet before you run the demo. The buyer’s wallet only needs USDC, not ETH for gas — that is the whole point of EIP-3009: the facilitator submits the transaction and can sponsor gas, so the agent never needs a gas balance.

python -m venv .venv && source .venv/bin/activate

# core libraries for the A2A x402 extension
pip install x402-a2a a2a-sdk eth-account httpx uvicorn

# environment: buyer key + (optional) CDP facilitator creds
export BUYER_PRIVATE_KEY=0x...           # an eth-account private key, testnet only
export SELLER_PAY_TO=0xYourSellerWallet  # where USDC settles to
export CDP_API_KEY_ID=...                # only needed for mainnet / CDP facilitator
export CDP_API_KEY_SECRET=...

# we will run everything on base-sepolia
export X402_NETWORK=base-sepolia

Step 1: The seller agent — publish an agent card with a payments extension

The seller advertises that it charges by adding the x402 extension to its A2A agent card, served at /.well-known/agent-card.json. A2A agents publish capability metadata at that well-known path, and the x402 extension is declared with the URI https://github.com/google-a2a/a2a-x402/v0.1. A buyer agent reads this card during discovery and learns “this agent expects payment.”

The x402_a2a library gives you a helper, get_extension_declaration(), so you do not hand-write the JSON. Marking the extension required=true tells well-behaved clients they must activate x402 to transact. Below is a minimal seller agent card built on the A2A SDK.

Notice we never put a price in the card. The card only announces that the agent charges, not how much — pricing is dynamic and returned per request in the PaymentRequired task. That keeps the same agent able to charge $0.01 for one tool and $5.00 for another.

# seller_card.py
from a2a.types import AgentCard, AgentCapabilities, AgentSkill
from x402_a2a import get_extension_declaration, X402_EXTENSION_URI

# X402_EXTENSION_URI == "https://github.com/google-a2a/a2a-x402/v0.1"
x402_ext = get_extension_declaration(
    description="Supports payments using the x402 protocol for on-chain settlement.",
    required=True,
)

SELLER_CARD = AgentCard(
    name="premium-research-agent",
    description="Generates a paid research brief. Costs $0.10 USDC per call.",
    url="http://localhost:8001/",
    version="1.0.0",
    capabilities=AgentCapabilities(extensions=[x402_ext]),
    skills=[
        AgentSkill(
            id="research_brief",
            name="research_brief",
            description="Produce a sourced research brief on a topic.",
            tags=["research", "paid"],
        )
    ],
    default_input_modes=["text"],
    default_output_modes=["text"],
)

# Served automatically by the A2A server at:
#   http://localhost:8001/.well-known/agent-card.json

Step 2: Return a 402-style PaymentRequired task from the seller’s executor

When a buyer asks for a paid skill, the seller’s AgentExecutor raises an x402PaymentRequiredException, which the library turns into an A2A task in the input-required state carrying x402.payment.required metadata. This is the agent-to-agent equivalent of an HTTP 402: the work pauses, the buyer is told the price and where to pay, and the task waits for a signed payload.

The cleanest way to express “this costs money” is to throw the exception with a price and the seller’s receiving address. The x402PaymentRequiredException.for_service() constructor builds the PaymentRequirements for you — scheme exact, network base-sepolia, asset USDC, and the pay_to address. Under the hood the library calls create_payment_requirements() and writes an x402PaymentRequiredResponse with an accepts array into the task metadata.

Here is the seller executor. The first time a task arrives with no payment, it demands one. We will handle the second arrival — the one carrying the signed payload — in Step 4.

The key A2A mechanic to internalize: payment is a task state, not a separate endpoint. The same task ID flows through payment-required → payment-submitted → payment-completed. The library stores that state under the metadata key x402.payment.status, alongside x402.payment.required (the unsigned requirements), x402.payment.payload (the signed authorization), and x402.payment.receipts (the settlement receipts).

# seller_executor.py
from a2a.server.agent_execution import AgentExecutor, RequestContext
from a2a.server.events import EventQueue
from x402_a2a import x402PaymentRequiredException, x402Utils

PAY_TO = "0xYourSellerWallet"        # SELLER_PAY_TO
NETWORK = "base-sepolia"

class ResearchExecutor(AgentExecutor):
    def __init__(self):
        self.utils = x402Utils()

    async def execute(self, context: RequestContext, event_queue: EventQueue):
        task = context.current_task

        # Has the buyer already attached a signed payment? (Step 4 handles it.)
        status = self.utils.get_payment_status(task) if task else None
        if status != "payment-submitted":
            # First contact: demand payment. This raises and the server
            # converts it into an input-required task with x402 metadata.
            raise x402PaymentRequiredException.for_service(
                price="$0.10",                 # 0.10 USDC
                pay_to_address=PAY_TO,
                network=NETWORK,
                resource="research_brief",
                description="One sourced research brief.",
            )

        # ... payment present -> verify + settle (Step 4) ...

    async def cancel(self, context: RequestContext, event_queue: EventQueue):
        raise NotImplementedError

Step 3: The buyer agent signs an EIP-3009 USDC payment and resubmits

The buyer reads the PaymentRequired task, builds an EIP-3009 transferWithAuthorization message over USDC, signs it with its wallet, and resubmits the same task with an x402.payment.payload. This is the heart of agent-to-agent payments x402: a signature, not a transfer. The buyer authorizes a transfer; the facilitator (called by the seller) is what actually moves the USDC.

x402’s exact EVM scheme uses EIP-3009 because USDC implements it. The signed payload’s authorization object carries six fields — from, to, value (in the token’s base units; USDC has 6 decimals, so $0.10 = "100000"), validAfter, validBefore, and a random nonce — plus a 65-byte signature. The signature is an EIP-712 typed-data signature whose domain is { name: "USDC", version: "2", chainId, verifyingContract }, where verifyingContract is the USDC contract on your network.

The x402ClientExecutor automates all of this — given an eth-account object, it reads the requirements, signs, and resubmits. But to make the mechanism legible, here is the explicit version using process_payment_required() to produce the signed PaymentPayload, then create_payment_submission_message() to wrap it with the original task_id for correlation. That task_id is non-negotiable — it is how the seller matches your payment to the paused task.

When you resubmit, the library writes x402.payment.status = "payment-submitted" and x402.payment.payload = {...} into the message metadata. The seller’s executor (Step 2) sees that status and proceeds to settlement instead of demanding payment again.

# buyer.py
import os, httpx
from eth_account import Account
from a2a.client import A2AClient
from x402_a2a import (
    process_payment_required,            # build + sign the PaymentPayload
    create_payment_submission_message,   # wrap payload with task_id
    x402Utils,
)

account = Account.from_key(os.environ["BUYER_PRIVATE_KEY"])
utils = x402Utils()

async def buy(seller_url: str, prompt: str):
    async with httpx.AsyncClient() as http:
        client = await A2AClient.get_client_from_agent_card_url(
            http, seller_url  # reads /.well-known/agent-card.json (discovery)
        )

        # 1) Ask for the paid skill -> get a PaymentRequired task back.
        task = await client.send_message(prompt)
        requirements = utils.get_payment_requirements(task)   # x402.payment.required

        # 2) Sign an EIP-3009 transferWithAuthorization over USDC.
        #    Produces a PaymentPayload: {scheme:'exact', network, payload:{
        #      authorization:{from,to,value,validAfter,validBefore,nonce}, signature}}
        payload = process_payment_required(
            requirements,
            account=account,           # eth-account signer
        )

        # 3) Resubmit the SAME task with the signed payload (task_id correlates).
        message = create_payment_submission_message(
            task_id=task.id,
            payment_payload=payload,
        )
        completed = await client.send_message(message)
        return utils.get_result(completed)   # the delivered service

if __name__ == "__main__":
    import asyncio
    print(asyncio.run(buy("http://localhost:8001", "Brief me on x402 adoption")))

Step 4: The seller settles via a Coinbase CDP facilitator and delivers

On the resubmission, the seller verifies the signed payload and calls the facilitator’s settle endpoint, which broadcasts the EIP-3009 transfer on-chain and returns a transaction hash — only then does the seller release the service. This closes the loop and is exactly how agent pays another agent USDC end-to-end. The facilitator does the on-chain work so the seller never runs blockchain infrastructure.

The CDP facilitator exposes two operations: verify (is this signature valid and the authorization unspent?) and settle (submit transferWithAuthorization with the signature and authorization params). Settlement on Base with USDC completes in roughly 200 milliseconds for a fraction of a cent. The library’s verify_payment() and settle_payment() wrap these calls; you pass a facilitator config, and on success you get a SettleResponse with the transaction hash.

Below is the completed seller executor branch. After a successful settle, record_payment_success() writes the receipt into x402.payment.receipts and flips the task to payment-completed, and you finally run the actual paid work. Critically: do the work after settlement, never before. A signed payload is a promise; a receipt is money.

To move from testnet to production, change network to base and point facilitator_config at the CDP facilitator with your CDP_API_KEY_ID/CDP_API_KEY_SECRET. The signing and task code does not change — that network-string-only switch is the payoff of building on the standard.

# seller_executor.py (continued — the payment-submitted branch)
from x402_a2a import verify_payment, settle_payment, x402ErrorCode
from x402.facilitator import FacilitatorConfig   # CDP or testnet facilitator

# Testnet: public base-sepolia facilitator (no key). Mainnet: CDP + API key.
FACILITATOR = FacilitatorConfig(url="https://x402.org/facilitator")
# For Base mainnet via Coinbase CDP:
# FACILITATOR = FacilitatorConfig(
#     url="https://api.cdp.coinbase.com/platform/v2/x402",
#     api_key_id=os.environ["CDP_API_KEY_ID"],
#     api_key_secret=os.environ["CDP_API_KEY_SECRET"],
# )

    async def execute(self, context, event_queue):
        task = context.current_task
        if self.utils.get_payment_status(task) == "payment-submitted":
            payload = self.utils.get_payment_payload(task)        # signed authorization
            requirements = self.utils.get_payment_requirements(task)

            # 1) Verify the signature + authorization window are valid.
            verify = await verify_payment(payload, requirements, FACILITATOR)
            if not verify.is_valid:
                task = self.utils.record_payment_failure(
                    task, x402ErrorCode.INVALID_SIGNATURE, verify)
                return await event_queue.enqueue_event(task)

            # 2) Settle on-chain: facilitator submits transferWithAuthorization.
            settle = await settle_payment(payload, requirements, FACILITATOR)
            if not settle.success:
                task = self.utils.record_payment_failure(
                    task, x402ErrorCode.SETTLEMENT_FAILED, settle)
                return await event_queue.enqueue_event(task)

            # 3) Money received (settle.transaction is the tx hash). Now do the work.
            task = self.utils.record_payment_success(task, settle)  # -> payment-completed
            brief = run_research(context.get_user_input())          # your paid service
            task = self.utils.add_result(task, brief)
            return await event_queue.enqueue_event(task)

Run the full agent-to-agent payment demo and check the receipt

Start the seller A2A server, fund the buyer with testnet USDC, run the buyer script, and you will see the task move through payment-required, payment-submitted, and payment-completed with a real Base Sepolia transaction hash. This is the complete x402_a2a library python loop running locally.

Wire the executor into an A2A server with the card from Step 1 and launch it. Then run the buyer. The buyer discovers the seller, receives the 402-style task, signs the EIP-3009 payload, resubmits, and prints the delivered research brief — after settlement is confirmed.

Inspect the completed task’s x402.payment.receipts metadata to find the transaction hash, then look it up on Base Sepolia’s explorer to confirm the USDC actually moved. That receipt is your audit trail — and in production it is what you log against the AP2 mandate to prove the spend was both authorized (AP2) and settled (x402).

# server.py — host the seller agent
import uvicorn
from a2a.server.apps import A2AStarletteApplication
from a2a.server.request_handlers import DefaultRequestHandler
from a2a.server.tasks import InMemoryTaskStore
from seller_card import SELLER_CARD
from seller_executor import ResearchExecutor

handler = DefaultRequestHandler(
    agent_executor=ResearchExecutor(),
    task_store=InMemoryTaskStore(),
)
app = A2AStarletteApplication(agent_card=SELLER_CARD, http_handler=handler)

if __name__ == "__main__":
    uvicorn.run(app.build(), host="0.0.0.0", port=8001)

# Terminal 1:  python server.py
# Terminal 2:  python buyer.py
#
# Expected task lifecycle (status under x402.payment.status):
#   payment-required  -> payment-submitted -> payment-completed
# And in x402.payment.receipts:
#   [{"network": "base-sepolia", "transaction": "0xabc...", "success": true}]

“A signed payload is a promise. A settlement receipt is money. In agentic commerce, never deliver the service on the promise.”

Surya Koritala, founder of Cyntr and Loomfeed

Error: extension not activated / buyer never gets a PaymentRequired task

The seller card must declare the x402 extension and the buyer must activate it. Confirm the agent card at /.well-known/agent-card.json contains the extension URI https://github.com/google-a2a/a2a-x402/v0.1. If you wrote the card by hand, switch to get_extension_declaration(). On the client side, the x402ClientExecutor activates the extension automatically; if you call the client manually, add the activation header (add_extension_activation_header).

settle_payment returns INVALID_SIGNATURE

Almost always an EIP-712 domain mismatch. The domain must be {name:’USDC’, version:’2′, chainId, verifyingContract} where verifyingContract is the USDC contract for THAT network (Base Sepolia and Base mainnet have different addresses). The library derives this from the requirements, so make sure the buyer signed against the requirements it received, not a hard-coded copy. Also confirm ‘value’ is in base units (6 decimals): $0.10 USDC is ‘100000’, not ‘0.1’.

EXPIRED_PAYMENT or the nonce is rejected

EIP-3009 authorizations carry validAfter/validBefore and a one-time nonce. If your buyer and seller clocks drift, or the buyer sat on the task too long before resubmitting, validBefore can elapse. Keep the window tight but realistic (e.g. 60-120s) and sign right before resubmitting. A DUPLICATE_NONCE error means you reused an authorization — generate a fresh random nonce per payment.

Insufficient funds on settle (buyer has USDC but tx fails)

On base-sepolia, fund the buyer address from a Base Sepolia USDC faucet. The buyer needs USDC but NOT ETH for gas — EIP-3009 lets the facilitator submit and (on CDP) sponsor gas. If you switched to mainnet, confirm the buyer holds real USDC on Base and that your CDP facilitator key is set; the CDP free tier covers 1,000 transactions/month before $0.001/tx.

How do you monetize an A2A agent, and where does AP2 fit?

To monetize an A2A agent, declare the x402 extension on its card, return PaymentRequired for paid skills, and settle each call in USDC — then layer AP2 on top so every payment is provably authorized. The four steps above are the complete revenue path; AP2 is what makes it safe to let an agent spend without a human clicking buy each time.

AP2 supplies the missing authorization layer. Before the buyer signs the x402 payload, it constructs a Payment Mandate — a verifiable credential signed by the principal that says “I authorize spending up to this amount for this cart.” The seller (or an auditor) can later verify that the settled transaction maps to a valid mandate. In the three-layer model, x402’s receipt and AP2’s mandate together answer both questions a regulator will ask: did the money move, and was it allowed to?

This is why the design is converging across the industry rather than fragmenting. In May 2026, AWS shipped Amazon Bedrock AgentCore Payments — built with Coinbase and Stripe — letting agents discover, pay for, and settle services in USDC on Base and Solana over the same x402 protocol, with spending limits and compliance checks baked in. Coinbase reported x402 had processed more than 169 million payments across 590,000+ buyers and 100,000+ sellers in its first year. The pattern you just built locally is the pattern the hyperscalers are productizing.

So the monetization checklist is short: (1) add the extension to your agent card, (2) price each skill via PaymentRequired, (3) verify and settle through a facilitator before delivering, and (4) attach an AP2 mandate so the spend is authorized, not just possible. Build those four and your agent has a real, auditable revenue stream in the agent economy.

The whole loop in one breath: card declares x402 -> seller returns PaymentRequired -> buyer signs EIP-3009 USDC payload -> facilitator settles on Base -> seller delivers on the receipt. Wrap it in an

Builder’s take

I build payment-aware agents at Cyntr and Loomfeed, and the gap this tutorial fills is the one that cost me the most time: every public a2a x402 resource shows you the protocol shape but never the wiring between the three layers. Here is what I tell my own team.

• Keep the layers separate in your head and your code: A2A is just the envelope (discovery + task states), x402 is the money (signed EIP-3009 authorization + settlement), and AP2 is the permission slip (a signed mandate that says the human actually approved this spend). Conflating them is how you ship an agent that pays without authorization.
• Never let your seller agent settle against the buyer’s word. The PaymentPayload is a signature, not a transfer — until the facilitator’s settle call returns a transaction hash, you have been promised nothing. Gate service delivery on the receipt, not the submission.
• Start on base-sepolia with the CDP facilitator’s free tier (1,000 tx/month) before you touch mainnet. The exact same code runs on Base mainnet by flipping the network string, so there is zero reason to debug with real USDC.
• Treat the nonce and validBefore window as security primitives, not boilerplate. A replayed nonce or a too-long validity window is the agentic-commerce equivalent of leaving your card on the table.

Frequently asked questions

Primary sources

• a2a-x402 extension repository (Google Agentic Commerce) — GitHub
• x402_a2a Python library README — GitHub
• x402 exact EVM scheme specification — GitHub / Coinbase
• Coinbase Developer Platform x402 facilitator overview — Coinbase Developer Platform
• Google Agentic Payments Protocol + x402 launch — Coinbase
• Agents that transact: Amazon Bedrock AgentCore Payments — Amazon Web Services
• Agent Payments Protocol (AP2) repository — GitHub

Last updated: June 3, 2026. Related: Commerce.