Development v2

[CarsonRoscoe]

x402 v2 Development

This branch represents the in-progress implementation of the x402 v2 Specification, as well as a total rewrite of the Typescript and Go packages.
Community contributions are welcome. Please PR directly into this branch as we swarm on reference implementations.

(This PR is a continuation of #482 with a cleaned up commit history)

---

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 code has been moved down a folder into a /legacy subfolder. The legacy typescript packages can be found in /typescript/packages/legacy, the legacy go package in /go/legacy, examples in /examples/typescript/legacy, e2e tests in /e2e/legacy, etc.
• The top-level typescript, go, examples and e2e folders are current.
• Python remains unchanged, and will be updated in a fast-follow.
• Java is being deprecated until the community chooses to update it to v2.

---

TypeScript Packages

Package	Description
@x402/core	Core primitives — mechanism and transport agnostic
@x402/evm	Ethereum implementation of the exact scheme
@x402/svm	Solana implementation of the exact scheme
@x402/extensions	Optional extensions (bazaar discovery, sign-in-with-x) — tree-shakable
@x402/express	Express server middleware
@x402/hono	Hono server middleware
@x402/next	Next.js server middleware
@x402/fetch	Fetch API client interceptor
@x402/axios	Axios client interceptor
@x402/paywall	Paywall UI components (opt-in install)

Go Packages

Package	Description
x402	Core primitives — X402Client, X402ResourceServer, X402Facilitator
x402/http	HTTP transport layer (client wrapper, server integration)
x402/http/gin	Gin server middleware
x402/mechanisms/evm	Ethereum exact scheme (client, server, facilitator)
x402/mechanisms/svm	Solana exact scheme (client, server, facilitator)
x402/signers/evm	EVM signer helpers
x402/signers/svm	SVM signer helpers
x402/extensions	Protocol extensions (bazaar discovery)

Python Packages

Will be added shortly

---

Testing

The v2 implementation includes unit tests, integration tests, and e2e tests.

Running Tests

TypeScript:

cd typescript
pnpm test              # Unit tests
pnpm test:integration  # Integration tests

Go:

cd go
make test              # Unit tests
make test-integration  # Integration tests

E2E (all languages):

cd e2e
pnpm test              # Run e2e tests
pnpm test -v           # Verbose logging
pnpm test --min        # Minimize redundant tests, maximize coverage

---

Usage Patterns

TypeScript and Go follow nearly identical usage patterns. The examples below use TypeScript for demonstration purposes.

Client (TypeScript)

The x402Client uses a builder pattern to register payment schemes:

import { x402Client } from "@x402/fetch";  // or @x402/axios
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { ExactSvmScheme } from "@x402/svm/exact/client";

// Builder pattern with chaining
const client = new x402Client()
  .register("eip155:*", new ExactEvmScheme(evmSigner))      // All EVM chains
  .register("eip155:1", new ExactEvmScheme(ethereumSigner)) // Override for Ethereum
  .register("solana:*", new ExactSvmScheme(svmSigner))      // All Solana networks
  .registerPolicy((version, requirements) => requirements)  // Filter payment options
  .onBeforePaymentCreation(async (context) => {            // Validation hooks
    // Custom logic before payment creation
  })
  .onAfterPaymentCreation(async (context) => {             // Success hooks
    // Logging, metrics, analytics
  });

// Wrap native fetch with payment handling
const fetchWithPayment = wrapFetchWithPayment(fetch, client);

// Use like normal fetch - payments handled automatically
const response = await fetchWithPayment("https://api.example.com/data");
const data = await response.json();

Server (TypeScript)

The x402ResourceServer uses a builder pattern to register verification schemes:

import { x402ResourceServer, paymentMiddleware } from "@x402/express"; // or @x402/hono, @x402/next
import { HTTPFacilitatorClient } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { ExactSvmScheme } from "@x402/svm/exact/server";

// Builder pattern with chaining
const facilitatorClient = new HTTPFacilitatorClient({ url: facilitatorUrl }); // or array of facilitator clients
const server = new x402ResourceServer(facilitatorClient)
  .register("eip155:*", new ExactEvmScheme())      // All EVM chains
  .register("solana:*", new ExactSvmScheme())      // All Solana networks
  .onBeforeVerify(async (context) => {            // Verification hooks
    // Custom validation before verifying payment
  })
  .onAfterSettle(async (context) => {             // Settlement hooks
    // Logging, database updates after settlement
  });

// Use with Express middleware
app.use(paymentMiddleware({
  "GET /weather": {
    accepts: { scheme: "exact", price: "$0.001", network: "eip155:84532", payTo: evmAddress },
    description: "Weather data",
  },
}, server));

Facilitator (TypeScript)

The x402Facilitator verifies and settles payments on-chain:

import { x402Facilitator } from "@x402/core/facilitator";
import { ExactEvmScheme } from "@x402/evm/exact/facilitator";
import { ExactSvmScheme } from "@x402/svm/exact/facilitator";

// Builder pattern with chaining
const facilitator = new x402Facilitator()
  .register("eip155:84532", new ExactEvmScheme(evmSigner))
  .register("solana:*", new ExactSvmScheme(svmSigner));

// Add lifecycle hooks
facilitator
  .onBeforeVerify(async (context) => {
    // Pre-verification checks (rate limiting, fraud detection)
  })
  .onAfterSettle(async (context) => {
    // Post-settlement actions (cleanup, notifications)
  });

// Expose via HTTP endpoints
app.post("/verify", async (req, res) => {
  const result = await facilitator.verify(req.body.paymentPayload, req.body.paymentRequirements);
  res.json(result);
});

app.post("/settle", async (req, res) => {
  const result = await facilitator.settle(req.body.paymentPayload, req.body.paymentRequirements);
  res.json(result);
});

---

Backwards Compatibility

The EVM and SVM mechanism packages export v1 schemes from a /v1/ subpath for backwards compatibility with legacy x402 servers and clients. These must be registered using .registerV1().

Client:

import { ExactEvmSchemeV1 } from "@x402/evm/exact/v1/client";
import { ExactSvmSchemeV1 } from "@x402/svm/exact/v1/client";

const client = new x402Client()
  .registerV1("base-sepolia", new ExactEvmSchemeV1(evmSigner))
  .registerV1("solana-devnet", new ExactSvmSchemeV1(svmSigner));

Facilitator:

import { ExactEvmSchemeV1 } from "@x402/evm/exact/v1/facilitator";
import { ExactSvmSchemeV1 } from "@x402/svm/exact/v1/facilitator";

const facilitator = new x402Facilitator()
  .registerV1("base-sepolia", new ExactEvmSchemeV1(evmSigner))
  .registerV1("solana-devnet", new ExactSvmSchemeV1(svmSigner));