Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.skale.space/llms.txt

Use this file to discover all available pages before exploring further.

Protect your HTTP endpoints with x402 payments using middleware. The middleware enforces Coinbase’s x402 handshake, forwards payment requirements to a facilitator, inspects X-PAYMENT headers from clients, and retries settlement before allowing requests to proceed.

​
Prerequisites

  • Node.js and npm installed
  • A SKALE Chain endpoint
  • Understanding of x402 protocol
  • Express or Hono framework
  • A facilitator service (see Running a Facilitator)

​
Overview

To become an x402 merchant, you need to:
  1. Set up a facilitator service
  2. Install x402 middleware
  3. Protect your HTTP endpoints
  4. Define payment requirements

​
Quick Start (Express)

import express from "express";
import { createMiddleware } from "@faremeter/middleware/express";

const paywalled = await createMiddleware({
  facilitatorURL: "https://facilitator.dirtroad.dev",
  accepts: [
    {
      scheme: "exact",
      network: "skale-base-sepolia",
      maxAmountRequired: "1.5",
      description: "SKALE USDC payment",
    },
  ],
});

const app = express();
app.use("/premium", paywalled, premiumRouter);
When a client reaches /premium, the middleware:
  1. Calls the facilitator’s /accepts endpoint to produce canonical requirements
  2. Returns a 402 Payment Required response (with the facilitator payload) if the incoming request lacks a valid X-PAYMENT header
  3. When a header is present, forwards it to /settle. If settlement succeeds, the request pipeline continues; otherwise another 402 is returned

​
Quick Start (Hono)

import { Hono } from "hono";
import { createMiddleware } from "@faremeter/middleware/hono";

const paywalled = await createMiddleware({
  facilitatorURL: "https://facilitator.dirtroad.dev",
  accepts: [
    {
      scheme: "exact",
      network: "skale-base-sepolia",
      maxAmountRequired: "1.5",
      description: "SKALE USDC payment",
    },
  ],
});

const app = new Hono();
app.use("/premium/*", paywalled);

​
API Surface

​
Express Adapter

const middleware = await createMiddleware({
  facilitatorURL: "https://facilitator.dirtroad.dev",
  accepts: [
    {
      scheme: "exact",
      network: "skale-base-sepolia",
      maxAmountRequired: "1.5",
      description: "SKALE USDC payment",
    },
  ],
  cacheConfig: {
    capacity: 256,
    maxAge: 30000, // 30 seconds
  },
});

​
Hono Adapter

const middleware = await createMiddleware({
  facilitatorURL: "https://facilitator.dirtroad.dev",
  accepts: [
    {
      scheme: "exact",
      network: "skale-base-sepolia",
      maxAmountRequired: "1.5",
      description: "SKALE USDC payment",
    },
  ],
});

​
Multiple Payment Options

Provide an array of arrays in accepts to describe alternative requirement sets: 
const middleware = await createMiddleware({
  facilitatorURL: "https://facilitator.dirtroad.dev",
  accepts: [
    [
      {
        scheme: "exact",
        network: "skale-base-sepolia",
        maxAmountRequired: "1.5",
        description: "SKALE USDC payment",
      },
      {
        scheme: "exact",
        network: "ethereum-mainnet",
        maxAmountRequired: "1.5",
        description: "Ethereum USDC payment",
      },
    ],
  ],
});

​
Resource-Specific Requirements

Leave resource undefined in the accepts entries to let the middleware fill it with the current request URL: 
const middleware = await createMiddleware({
  facilitatorURL: "https://facilitator.dirtroad.dev",
  accepts: [
    {
      scheme: "exact",
      network: "skale-base-sepolia",
      maxAmountRequired: "1.5",
    },
  ],
});

​
Error Handling

Invalid facilitator responses throw an exception (HTTP 500). When settlement fails, the middleware replays the facilitator payload to the client.

​
Resources