x402 icon indicating copy to clipboard operation
x402 copied to clipboard
Published 1 month ago • verified publisher icon coinbase

v2 Development

Open CarsonRoscoe opened this issue 2 months ago • 3 comments

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.

CarsonRoscoe avatar Oct 23 '25 18:10 CarsonRoscoe

🟡 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

cb-heimdall avatar Oct 23 '25 18:10 cb-heimdall

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

Project Deployment Preview Comments Updated (UTC)
x402 Ready Ready Preview Comment Nov 17, 2025 8:52pm

vercel[bot] avatar Oct 23 '25 18:10 vercel[bot]

Hi @CarsonRoscoe @erikreppel-cb

I have created https://github.com/coinbase/x402/pull/643 to implement the Python X402Client for V2, hoping to get a couple of eyes on it.

If it's well received, I plan to help with the full implementation parity for Python (server, facilitator etc.).

marcosmmb avatar Nov 15 '25 07:11 marcosmmb