x402

x402

Deprecated (v1)
This npm package implements x402 v1. It is deprecated and will only receive security patches. Please migrate to v2 (@x402/core and related packages). See the Migration guide: v1 to v2. Legacy examples are available at git tag archive/legacy-v1-examples.

Core TypeScript implementation of the x402 Payment Protocol. This package provides the foundational types, schemas, and utilities that power all x402 integrations.

Installation

npm install x402

Overview

The x402 package provides the core building blocks for implementing the x402 Payment Protocol in TypeScript. It's designed to be used by:

• Middleware implementations (Express, Hono, Next.js)
• Client-side payment handlers (fetch wrapper)
• Facilitator services
• Custom integrations

Integration Packages

This core package is used by the following integration packages:

• x402-express: Express.js middleware
• x402-hono: Hono middleware
• x402-next: Next.js middleware
• x402-fetch: Fetch API wrapper
• x402-axios: Axios interceptor

Manual Server Integration

If you're not using one of our server middleware packages, you can implement the x402 protocol manually. Here's what you'll need to handle:

• Return 402 error responses with the appropriate response body
• Use the facilitator to validate payments
• Use the facilitator to settle payments
• Return the appropriate response header to the caller

For a complete example implementation, see our advanced server example which demonstrates both synchronous and asynchronous payment processing patterns.

Manual Client Integration

If you're not using our x402-fetch or x402-axios packages, you can manually integrate the x402 protocol in your client application. Here's how:

• Make a request to a x402-protected endpoint. The server will respond with a 402 status code and a JSON object containing:

  • x402Version: The version of the x402 protocol being used
  • accepts: An array of payment requirements you can fulfill

• Select the payment requirement you wish to fulfill from the accepts array

• Create the payment header using the selected payment requirement

• Retry your network call with:

  • The payment header assigned to the X-PAYMENT field
  • The Access-Control-Expose-Headers field set to "X-PAYMENT-RESPONSE" to receive the server's transaction response

For implementation examples, we recommend reviewing our official client packages:

• x402-fetch implementation
• x402-axios implementation