[Feat]: Support explicit 'Payment Required' state / HTTP 402 in A2A protocol
- Dominant language
- Shell
- Stars
- 25.7k
- Forks
- 2.6k
- Avg merge
- 3d 6h
- Merged PRs (30d)
- 16
Description
### Is your feature request related to a problem? Please describe.
At present, the A2A protocol and its specification do NOT define or reserve HTTP 402 Payment Required as a first-class signal for client-agents.
This creates ambiguity for implementers and consumers when an agent or skill intends to require payment or fee authorizations before task execution. By contrast, HTTP 401 Unauthorized and 403 Forbidden *are* explicitly defined and mapped to the authentication and authorization flows in both the `docs/specification.md` and `docs/topics/enterprise-ready.md` documentation.
Real-world agent deployments increasingly require monetization or paywall support (“payment required before continuing”), but there’s no interoperable way to communicate this as a protocol event or status.
Today, task flows that need payment often overload TASK_STATE_INPUT_REQUIRED, add custom error payloads, or invent ecosystem-specific behaviors. This leads to non-standard client UX patterns, confusion between clarification-required and payment-required, and inability for client frameworks and agents to properly surface payment steps as distinct from authentication or generic input gating.
### Describe the solution you'd like
A2A should reserve, define, and document an official way to signal “payment required” conditions. This could be:
- Explicit support for HTTP 402 in the protocol, similar to how HTTP 401 and 403 are handled for authentication/authorization
- An official task state (e.g., `TASK_STATE_PAYMENT_REQUIRED`) paralleling `TASK_STATE_INPUT_REQUIRED` and `TASK_STATE_AUTH_REQUIRED`
- Or, at a minimum, spec guidance and/or an ecosystem standard extension describing how agents should surface payment-required events, how clients should respond, and which metadata to provide (e.g., invoice, payment URL, amount, currency).
This would enable:
- Interoperable client/agent behavior for paywall flows
- Reliable error handling and UX separation of payment from input/auth flows
- Stronger support for agent monetization patterns without ecosystem fragmentation
- Consistency with other explicit protocol event states (input required, auth required, forbidden, etc.)
Reference: [google-agentic-commerce/a2a-x402](https://github.com/google-agentic-commerce/a2a-x402) explores one such extension; spec guidance could recommend an extension, native event, or best practice for common flows.
### Describe alternatives you've considered
- Continue overloading `TASK_STATE_INPUT_REQUIRED` for payment steps (semantically ambiguous)
- Use HTTP 401/403/other status codes incorrectly (potentially breaks clients)
- Invent agent-specific or platform-specific extensions (fragments the ecosystem and breaks semantic interop)
- Do nothing and let payment wall signaling remain ad-hoc
### Additional context
The addition of HTTP 402/payment-required support would bring consistency to how the protocol signals action gating, matching what’s already provided for authentication (`401`/`TASK_STATE_AUTH_REQUIRED`) and authorization (`403`). There is prior discussion on whether overloading `INPUT_REQUIRED` is semantically clear, given 401/403 have explicit status mapping.
See:
- [docs/topics/enterprise-ready.md](https://github.com/a2aproject/A2A/blob/main/docs/topics/enterprise-ready.md) §Authentication for 401/403 usage
- `TASK_STATE_INPUT_REQUIRED` sample in [specification.md](https://github.com/a2aproject/A2A/blob/main/docs/specification.md)
- Example extension: https://github.com/google-agentic-commerce/a2a-x402
Open for feedback on best-fit design (protocol, official extension, or both). Will cross-link to ongoing threads/proposals as needed.
### Code of Conduct
- [x] I agree to follow this project's Code of Conduct
Contributor guide
Research direction
Review the A2A protocol specification in docs/specification.md and the enterprise-ready.md documentation to understand how HTTP 401 and 403 are currently mapped to task states. Examine the existing task state definitions and the a2a-x402 extension proposal. Determine where to add the new state or status code mapping, and draft the spec changes. Testing would involve updating protocol implementations to handle the new state.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, backend-api-design
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 45/100