A2A x402, letting agents charge each other on chain

HTTP 402 as a model for agent payment

The A2A x402 Extension is described as bringing cryptocurrency payments to the Agent-to-Agent protocol so agents can monetize their services through on-chain payments, and the project's own framing is that it revives the spirit of HTTP 402 Payment Required for the decentralized agent ecosystem.

That framing is the interesting part, because HTTP 402 is a status code that never really caught on. A server can return 402 and say what it wants, but the client has no standard way to negotiate, sign and settle a payment, so in practice 402 was replaced by a redirect to a payment page. What the x402 approach adds is the missing client half, and an agent has exactly the capabilities needed to fill it: it can hold a key, sign a transaction and pay.

The stated goal is agent commerce, a standardized way for agents to charge for their services and receive payments on-chain, which the description says transforms any A2A agent into a commercial service that can charge for API calls, data processing, AI inference, or any other valuable capability.

This is an extension, not a fork. The A2A protocol itself lives in a separate repository, and the x402 payment protocol this builds on is a separate specification with its own documentation, linked from the README alongside the Agent Payments Protocol, AP2, which is the other Google project in this space. So the layering is A2A for how agents talk, x402 for how they pay, and this repository for how those two meet.

The primary language is Python, the licence is Apache-2.0, the only recorded release is v0.1.0 from 2025-09-16, and the last push to the repository was on 2026-08-04.

Three messages, and that is the entire flow

The x402 extension defines a payment flow between agents that is deliberately small, and the three steps are the whole protocol.

First, payment required. A merchant agent, when payment is required for a service, responds with a `payment-required` message. Second, payment submitted. The client agent signs the payment details and sends them back to the merchant in a `payment-submitted` message. Third, payment completed. The merchant verifies the payment, settles it on-chain, and responds with a `payment-completed` message, delivering the requested service.

Three design decisions sit inside those three steps.

The first is that the client signs, not the merchant. The merchant never touches the client's private key, it receives a signed payload and verifies it. That keeps the client in control of its funds and means a malicious merchant cannot trigger a charge, which is the property that would make agents willing to pay each other automatically.

The second is that settlement happens after verification, and the service is delivered in the final message rather than being sent optimistically at the start. The merchant verifies, then settles on chain, then responds with the payload. The ordering puts the merchant's cost, the gas and the settlement latency, after the verification step, so an unpaid request never causes work.

The third is language neutrality, which the README states as a design goal: the flow is designed to be implemented in any language, allowing developers to focus on their agent's core logic. That is a real constraint on the design rather than a slogan, because it means the protocol cannot carry implementation objects, only serialisable messages, and that is why the specification matters more here than in a typical SDK.

The repository is organised to match that ambition, with a versioned specification directory, a schemes directory and one directory per language implementation.

The repository layout in full, as the project documents it.

x402-a2a/
├── spec/
│   └── v0.1/
│       └── spec.md         # The official x402 extension specification
│
├── schemes/                # Directory contains experimental x402 payment schemes drafted by partners and other contributors
│
└── {language}/             # Language-specific implementations (e.g., python/, typescript/)
    ├── x402_a2a/           # The core library for the x402 extension
    │
    └── examples/
        └── {demo}/         # Demonstrations for each language implementation

The versioned spec directory is worth noticing. A protocol extension with numbered message types needs a versioned definition of those types, and having `spec/v0.1/` in the tree rather than a single `spec.md` says the authors expect the messages to change.

Functional core, imperative shell

The architecture section names one pattern, and it is the one that makes a protocol library usable in two different ways.

The `x402_a2a` libraries follow a functional core, imperative shell architecture, split into two parts. The core protocol is the fundamental data structures and functions for creating, signing and verifying payments. The executors are middleware that automates the payment flow, making it easy to add payment capabilities to any agent.

The stated benefit is that you can either build custom payment logic with the core protocol or use the executors for a more hands-off approach.

That is a sensible split for a library whose users split into two groups. The first group is an agent author who wants a payment to be part of their business logic, with their own retry policy, their own settlement timing and their own error handling, and who needs to call the primitives directly. The second group is an agent author who wants their service to start charging for calls without restructuring it, and who wants the flow wired in as middleware.

The executors are the more interesting half for most users, because a payment flow is exactly the kind of thing that is tedious to get right in every agent. Three messages, a signature, a verification, a settlement, a response, and a set of failure cases where the client paid but the response was lost, or the merchant settled but the service call failed afterwards. Encoding that as reusable middleware means the edge cases are solved once.

The repository has a `SECURITY.md` at the root, which is appropriate for a library that handles signing and settlement, and the contributing guide asks you to read the specification and the existing code before opening a pull request. For a protocol, reading the spec first is not a formality, because the message names and their fields are the contract.

Where the schemes are still drafts

The `schemes/` directory is the part of this repository most likely to surprise someone expecting a finished payment stack, and the reason is in the one-line description in the repository structure section: it contains experimental x402 payment schemes drafted by partners and other contributors.

The word experimental is doing real work there. A payment scheme is the part of the system that says which network, which asset, which facilitator and which settlement mechanism is in use. The extension defines the message flow, and the scheme defines the money. That means the extension can be stable while the schemes underneath it churn, and it also means the practical question for an implementer is not what the flow is but which scheme you are using.

The x402 protocol itself is documented separately, at x402.gitbook.io/x402, and the extension README links it as the underlying payment protocol. So a scheme is a way of using that protocol, contributed by partners, and the directory is where they land.

That arrangement has an upside. Payment schemes vary by region, by asset and by how the counterparty is verified, and centralising them in one place with per-scheme ownership is a workable model for something that is still forming. It also has an obvious downside, which is that the directory's contents are not covered by the extension's own version, so the version of the specification says nothing about the maturity of what you are building on.

For the same reason, the extension's own version number tells you less than it looks like it does. v0.1.0 of the extension, released in September 2025, with the last commit in August 2026, describes a protocol extension at version 0.1 whose schemes are experimental drafts. That is a coherent position for a specification project, and it is a different position from a library you would build a payment product on today.

The Apache-2.0 licence is the permissive one, with the LICENSE file at the root, and the repository uses release-please with a release-please configuration and manifest, which is the tooling that cuts a release when a conventional commit lands.

Getting started means reading three READMEs

There is no install command at the root of this repository, and the reason is that the root is not where the code is.

The getting started section says each language-specific implementation, for example `python/x402_a2a`, contains its own README with detailed instructions on how to install dependencies, run tests and use the library. The `examples/` directory contains various demonstrations of the extension, and each example also has its own README with instructions on how to run it.

So the actual setup path is: read the specification at `spec/v0.1/spec.md`, read `python/x402_a2a/README.md` for the library, and read the README of whichever example you intend to run. The root README is a map, and it says so.

That is a reasonable structure for a multi-language protocol project, and it has a cost. A developer who wants to know how to install the Python package has to go two directories down to find out, and the root of the repository gives no version number to pin and no command to copy.

The rest of the repository is documentation-first as well. The learn more section links the specification, the Python library documentation, the Python examples directory, the core A2A protocol in the a2a-python repository, the x402 protocol documentation, and the AP2 Agent Payments Protocol repository.

Two things are worth noticing in that list. The A2A protocol is linked to its Python implementation specifically, which tells you the extension is being developed against the Python flavour of A2A first. And AP2 is listed alongside x402 as a sibling, which is useful context: Google's Agent Payments Protocol is an alternative approach to the same problem of agents paying for things, and the extension README presents x402 as the underlying protocol for this flow rather than as the only option in the ecosystem.

The examples directory is where the protocol becomes concrete. Each demonstration has its own README, so the intended way to learn the flow is to run an example, see the three messages in action, and then read the code that produced them.

Where this sits against the alternatives

The comparison that matters for anyone reading this is against AP2, because the README links both and they come from the same organisation.

AP2, the Agent Payments Protocol, takes a different approach to agent payment. Rather than defining a new message flow for a payment negotiation inside the agent protocol, it defines a credential and mandate model, where an agent is authorised to pay under a mandate that a user or merchant sets up in advance, and the payment carries that authorisation rather than a per-call signature negotiation. The difference in approach is direct negotiation on every call versus pre-authorised spending authority.

x402 is the opposite in spirit to both of the vendor checkout flows, because it has no account on a merchant side and no card form. The merchant agent verifies a signature and settles directly on chain. That removes the card network from the path and puts a blockchain confirmation instead, which changes the latency and the failure modes rather than the cost structure.

So the three approaches are: a mandate-based authorisation model, a per-call signature negotiation in an extended agent protocol, and a conventional checkout that both of those are trying to avoid.

For a developer choosing between them, the practical question is where the trust boundary sits. AP2 puts it in a mandate and a credential issuer. x402 puts it in the client signing each payment and the merchant verifying it on chain, which means the merchant has to do the verification and the settlement, and therefore has to be willing to accept that cost for every call.

The other limit to keep in view is that this is a protocol extension with one release, an experimental schemes directory and per-language READMEs instead of a documented install path. The specification is the durable artefact here, and the code is a reference implementation of it. Anyone planning to build on this should treat the specification at `spec/v0.1/spec.md` as the thing to read and the message names as things to expect to change.

Editorial conclusion

A2A x402 suits a developer prototyping agent-to-agent commerce who wants the message flow and the signing and verification primitives without designing them, and it suits anyone who wants to read a short specification of how an agent asks to be paid. It does not suit a team shipping a live payment product, because there is one tagged release at v0.1.0, the payment schemes directory is explicitly experimental, and the root of the repository documents no installation path. Verify first that the specific payment scheme you need exists in the schemes directory, since those are experimental drafts contributed by partners, and read the version 0.1 specification before building against the message names, because a version 0.1 specification is a version 0.1 specification.

Frequently asked questions

Official sources

1. google-agentic-commerce/a2a-x402 on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases