v2 Development

[CarsonRoscoe]

x402 v2 — Development Branch

This branch represents the in-progress implementation of the x402 v2 Specification.
Community contributions are welcome. Please PR directly into this branch as we swarm on reference implementations.

---

Overview

x402 v2 introduces a modular architecture separating the specification, facilitator, and SDK layers.
This branch is dedicated to building the reference SDKs as we build out v2.

All legacy Typescript x402 packages are being deprecated and replaced by these new, modularized packages.
The Python and Go packages will be completely rewritten to follow this new structure as well.
Java is being deprecated unless the community chooses to update it to v2.

---

Typescript Reference Package Map

The following packages should be used as references when implementing more mechanisms, middleware and client interceptors.

Package	Description	Reference Role	Next Targets
@x402/core	Core types, utilities, validation schemas, and shared logic across all packages.	Foundation for all SDKs.	Acts as the baseline reference for future Python and Go SDKs.
@x402/evm	EVM mechanism implementation for verification and settlement.	Reference implementation for how mechanisms should be implemented.	Solana is next mechanism target.
@x402/express	Express middleware for x402 payment signaling and consent.	Reference for how to integrate server frameworks.	Next up: Hono and Next.js middlewares.
@x402/fetch	Fetch wrapper/interceptor for x402-aware client requests.	Reference for client-side integrations.	Next up: Axios client package.
@x402/extensions	An extensions package providing extensions which add additional capabilities and schema declarations.	Reference for how extensions are structured and registered.	Next up: Sign-In-With-X extension.

---

Testing

Current Test Coverage

The v2 implementation will include unit, integration, and e2e tests. However, to validate the reference packages and demonstrate intended usage, we have implemented two integration tests and one e2e test so far.

Integration Tests

• @x402/core:
  • Transport-agnostic flow: x402Client, x402ResourceService and x402Facilitator
  • HTTP flow: x402HTTPClient, x402HTTPResourceService and x402Facilitator wrapped in FacilitatorClient

End-to-End Tests

• Current Coverage:
  • @x402/express (server) and @x402/fetch (client) are tested together
  • Both use the @x402/evm mechanism implementation
  • Tests verify the complete payment flow from client request through server verification

Testing Requirements

Every client and server package must have:

1. E2E Test Implementation: Each package needs an accompanying e2e client or server in the /e2e directory
2. Test Suite Integration: Must be discoverable and executable by the automated test suite
3. Full Pass Rate: All tests must pass across all supported environments

We ask that PR's adding new functionality to the repo do their best to adhere to the testing standards set-out for the respective language, as well as

---

Roadmap

Legend

• ✅ Complete
• 🟨 Draft
• 🟧 Work in progress
• 🔄 Scaffolded
• 🧭 Planned
• 💭 Proposed

TypeScript:

• 🟨 @x402/core
• 🟨 @x402/evm
• 🟨 @x402/express
• 🟨 @x402/fetch
• 🟨 @x402/extensions
• 🟨 @x402/svm
• 🔄 @x402/hono
• 🔄 @x402/next
• 🔄 @x402/axios
• 🔄 @x402/sign-in-with-x

Python:

• 🧭 x402.core
• 🧭 x402.client
• 🧭 x402.server
• 🧭 x402.facilitator
• 🧭 x402.mechanisms.evm
• 🧭 x402.mechanisms.svm
• 🧭 x402.http
• 🧭 x402.http.fastapi
• 🧭 x402.http.flask
• 🧭 x402.http.httpx
• 🧭 x402.http.requests
• 🧭 x402.extensions

Go:

• 🟨 x402/core
• 🟨 x402/client
• 🟨 x402/server
• 🟨 x402/facilitator
• 🟨 x402/mechanisms/evm
• 🟨 x402/mechanisms/svm
• 🟨 x402/http
• 🟨 x402/http/gin
• 💭 x402/http/fiber
• 💭 x402/http/resty
• 🟨 x402/http/http-client
• 🟧 x402/extensions

Package TODO Files

Every package contains a TODO.md file that documents:

• What work remains to be done
• Implementation guidance and tips
• Reference implementations to follow

You can contribute by:

1. Proposing TODO updates: Submit PRs to update TODO files with clarifications or additional requirements
2. Implementing solutions: Submit PRs with your implementation directly
3. Reviewing existing TODOs: Help identify missing requirements or suggest improvements

---

Notes

• The EVM mechanism (@x402/evm) serves as the canonical example for mechanism design.
• The Express middleware (@x402/express) demonstrates framework integration.
• The Fetch client (@x402/fetch) demonstrates client interception and wrapping.
• The extensions (@x402/extensions) demonstrates schema and extension patterns.
• @x402/core provides all shared primitives — use it as the baseline for other languages.

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
x402	Ready	Preview	Comment	Dec 1, 2025 1:26am

[phdargen]

V2 is live 🚀