x402 Facilitator on Hono

A lightweight and efficient payment facilitator for the x402 standard, built with Hono. This server supports payment verification and settlement on multiple blockchains, such as Solana and Base.

⚠️ Disclaimer and Important Notes

This project is a re-implementation of the official x402 facilitator example from Coinbase, which was originally written in Express. You can find the original example here:

• coinbase/x402/examples/typescript/facilitator

This implementation is intended for educational and demonstrational purposes only. It serves as a learning resource for those who want to build their own x402 facilitator using Hono.

Please DO NOT use this code in a production environment as-is. Before considering deployment, you must thoroughly review and enhance the security, including the secure management of private keys, error handling, and overall robustness of the code to suit your specific needs.

This application is designed for deployment to Vercel. Please be aware that you are responsible for all configurations and verifications necessary for a production environment. Use at your own risk.

✨ Key Features

• Blazing Fast: Built on top of Hono, one of the fastest web frameworks for JavaScript.
• Multi-Chain Support: Supports payment handling on both the Solana (Mainnet, Devnet) and Base (Mainnet, Sepolia) blockchains.
• x402 Compliant: Implements verify and settle endpoints for the x402 payment standard.
• Static Frontend: A simple and informative landing page built with Hono's JSX and styled with Tailwind CSS.

🛠️ Tech Stack

• Framework: Hono
• Runtime: Node.js
• Language: TypeScript
• UI Styling: Tailwind CSS
• Testing: Vitest
• Package Manager: Yarn (with Corepack)

🚀 Getting Started

Follow these instructions to get a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

• Node.js (v20 LTS or later recommended)
• Yarn (enabled via Corepack)

Installation & Setup

1. Clone the repository:

   git clone https://github.com/snc2work/x402-facilitator-hono.git
   cd x402-facilitator-hono

2. Enable Corepack and set Yarn version: Corepack is the modern way to manage package managers.

   corepack enable
   corepack use yarn@1

3. Install dependencies:

   yarn install

4. Set up environment variables: Create a .env file in the root of the project by copying the example file. It's recommended to create a .env.example file in your repository for others.

   cp .env.example .env

   Now, open .env and fill in the required values.

Running the Development Server

To start the development server with hot-reloading:

yarn dev

The server will be running at http://localhost:3004 (or the port specified in your .env).

💡 Tips for Buyers (Client-Side)

This section provides a tip for developers building a Buyer application on Solana Mainnet using x402-fetch.

When using libraries like x402-fetch, you may encounter issues on Solana Mainnet. The default public RPC URL used internally by these libraries is often heavily rate-limited, which can cause payment verification or settlement to fail.

For more reliable operation, you can also use a dedicated RPC provider such as Helius or QuickNode. You can pass your custom RPC URL via the svmConfig option.

The following example applies to x402-fetch version ^0.7.0. The specifications may differ in future versions.

Here is a practical example of how to configure wrapFetchWithPayment with a custom Helius RPC URL:

import { wrapFetchWithPayment, createSigner } from "x402-fetch";

const solanaPrivateKey = process.env.SOLANA_PRIVATE_KEY;
const signer = await createSigner("solana", solanaPrivateKey);

const heliusApiKey = process.env.HELIUS_API_KEY;
const heliusRpcUrl = `https://mainnet.helius-rpc.com/?api-key=${heliusApiKey}`;

// Wrap the fetch function, providing the custom RPC URL via svmConfig.
const fetchWithPayment = wrapFetchWithPayment(
  fetch,
  signer,
  undefined,
  undefined,
  {
    svmConfig: {
      rpcUrl: heliusRpcUrl,
    },
  }
);

⚙️ Environment Variables

The following environment variables are required for the application to run. Create a .env file in the project root.

# Node environment (development, production, test)
NODE_ENV=development

# Server port (e.g., 3002)
PORT=3002

# Allowed origins for CORS (e.g., http://localhost:3000,https://example.com)
ALLOWED_ORIGINS=

# Comma-separated list of supported networks
SUPPORTED_NETWORKS=base,base-sepolia,solana,solana-devnet

# EVM private key for settling payments (e.g., 0x...)
EVM_PRIVATE_KEY=your-key

# SVM private key for settling payments (Base58 encoded)
SVM_PRIVATE_KEY=your-key

# -----------------------------------------------------------------
# Optional but Recommended: RPC URLs for Solana networks
# Public RPCs may be rate-limited. For reliable performance, especially on mainnet,
# it is highly recommended to use a dedicated RPC provider like Helius or QuickNode.
# -----------------------------------------------------------------
SOLANA_RPC_URL=
SOLANA_DEVNET_RPC_URL=

📜 Available Scripts

• yarn dev: Starts the development server with live reloading.
• yarn build: Compiles the TypeScript code and builds assets for production.
• yarn start: Starts the production server from the dist directory.
• yarn test: Runs the test suite using Vitest.

📡 API Endpoints

The server provides the following API endpoints. The root path (GET /) serves the HTML landing page.

Method	Path
GET	/health
GET	/supported
GET	/verify
POST	/verify
GET	/settle
POST	/settle

📄 License

This project is licensed under the Apache License 2.0. See the LICENSE and NOTICE files for details.