Hono

Getting started with Hono

Start accepting x402 payments in your Hono server in 2 minutes.

You can find the full code for this example here.

Step 1: Create a project and install dependencies

Use your favorite package manager:

npm

mkdir my-server && cd my-server
npm init -y && npm pkg set type=module
npm install hono @hono/node-server dotenv @payai/facilitator @x402/core @x402/evm @x402/extensions @x402/hono @x402/svm
npm install -D typescript tsx

pnpm

mkdir my-server && cd my-server
pnpm init && pnpm pkg set type=module
pnpm add hono @hono/node-server dotenv @payai/facilitator @x402/core @x402/evm @x402/extensions @x402/hono @x402/svm
pnpm add -D typescript tsx

bun

mkdir my-server && cd my-server
bun init -y
bun add hono @hono/node-server dotenv @payai/facilitator @x402/core @x402/evm @x402/extensions @x402/hono @x402/svm
bun add -d typescript

This is the same dependency set as the upstream Hono example.

Step 2: Set your environment variables

Create a .env file in the project root and set:

EVM_ADDRESS=0x...   # EVM wallet address to receive payments
SVM_ADDRESS=...    # Solana wallet address to receive payments

@payai/facilitator automatically connects to the PayAI facilitator — no URL configuration needed.

Step 3: Preview the server code

Create index.ts: It loads your env, applies the x402 payment middleware, defines example routes, and logs the server URL.

import { config } from "dotenv";
import { paymentMiddleware, x402ResourceServer } from "@x402/hono";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { ExactSvmScheme } from "@x402/svm/exact/server";
import { HTTPFacilitatorClient } from "@x402/core/server";
import { declareDiscoveryExtension } from "@x402/extensions/bazaar";
import { facilitator } from "@payai/facilitator";
import { Hono } from "hono";
import { serve } from "@hono/node-server";

config();

const evmAddress = process.env.EVM_ADDRESS as `0x${string}`;
const svmAddress = process.env.SVM_ADDRESS;
if (!evmAddress || !svmAddress) {
  console.error("Missing required environment variables");
  process.exit(1);
}

const facilitatorClient = new HTTPFacilitatorClient(facilitator);

const app = new Hono();

app.use(
  paymentMiddleware(
    {
      "GET /weather": {
        accepts: [
          {
            scheme: "exact",
            price: "$0.001",
            network: "eip155:84532",
            payTo: evmAddress,
          },
          {
            scheme: "exact",
            price: "$0.001",
            network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
            payTo: svmAddress,
          },
        ],
        description: "Weather data",
        mimeType: "application/json",
        serviceName: "Weather API",
        tags: ["weather", "api"],
        extensions: {
          ...declareDiscoveryExtension({
            output: {
              example: {
                report: {
                  weather: "sunny",
                  temperature: 70,
                },
              },
            },
          }),
        },
      },
    },
    new x402ResourceServer(facilitatorClient)
      .register("eip155:84532", new ExactEvmScheme())
      .register("solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", new ExactSvmScheme()),
  ),
);

app.get("/weather", c => {
  return c.json({
    report: {
      weather: "sunny",
      temperature: 70,
    },
  });
});

serve({
  fetch: app.fetch,
  port: 4021,
});

console.log(`Server listening at http://localhost:4021`);

Step 4: Run the server

npx tsx index.ts

Your server is now accepting x402 payments!

Step 5: Test the server

You can test payments against your server locally by:

Following the fetch example or the axios example
Creating a paywall using @x402/paywall for EVM chains or x402-solana-react for Solana

Going to production

The examples above use testnets. For Mainnet, update the route’s network and any explicit scheme registrations together, use the matching asset and funded buyer, and verify the paid path. The Solana Mainnet example provides a complete tested configuration; adding credentials alone does not switch networks. This setup can serve ordinary exact mainnet payments in production within the free allowance — no API key or portal signup is required. Production readiness still includes normal controls such as secret management, monitoring, and failure handling. When you need paid capacity beyond the allowance, an autonomous agent can buy credits and receive an API key over x402; PayAI creates a wallet-owned agent account programmatically. You can also use the optional merchant dashboard. Add the resulting credentials to your .env:

PAYAI_API_KEY_ID=your-key-id
PAYAI_API_KEY_SECRET=your-key-secret

The @payai/facilitator package automatically detects these environment variables and authenticates your requests to the facilitator. See Facilitator Pricing for tier details and Facilitator Authentication for the full protocol reference.

x402 reference

For a deeper dive into message shapes, headers, verification and settlement responses, see the x402 Reference.

Need help?

Join our Community

Have questions or want to connect with other developers? Join our Discord server.

PayAI

x402

x402 Merchants

x402 Clients

x402 Facilitator

x402 Reference

Guides

X402 Echo Merchant

Project Info

Getting started with Hono

Step 1: Create a project and install dependencies

npm

pnpm

bun

Step 2: Set your environment variables

Step 3: Preview the server code

Step 4: Run the server

Step 5: Test the server

Going to production

x402 reference

Need help?

Join our Community

​Getting started with Hono

​Step 1: Create a project and install dependencies

npm

pnpm

bun

​Step 2: Set your environment variables

​Step 3: Preview the server code

​Step 4: Run the server

​Step 5: Test the server

​Going to production

​x402 reference

​Need help?

Join our Community

Getting started with Hono

Step 1: Create a project and install dependencies

Step 2: Set your environment variables

Step 3: Preview the server code

Step 4: Run the server

Step 5: Test the server

Going to production

x402 reference

Need help?