Express

Getting started with Express

Start accepting x402 payments in your Express server in 2 minutes. For a complete Solana Mainnet merchant and buyer, follow the x402 Express guide, with pinned @x402/svm APIs and payment checks.

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 express dotenv @payai/facilitator @x402/core @x402/evm @x402/express @x402/extensions @x402/svm
npm install -D typescript tsx @types/express

pnpm

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

bun

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

This is the same dependency set as the upstream Express 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 express from "express";
import { paymentMiddleware, x402ResourceServer } from "@x402/express";
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";

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 = express();

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", (req, res) => {
  res.send({
    report: {
      weather: "sunny",
      temperature: 70,
    },
  });
});

app.listen(4021, () => {
  console.log(`Server listening at http://localhost:${4021}`);
});

Step 4: Run the server

npx tsx index.ts

Your server is now accepting 402 payments!

Step 5: Test the server

You can test payments against your server locally by following the fetch example or the axios example.

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 Express

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 Express

​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 Express

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?