npm package: @okxweb3/x402-express
Description: x402 Payment Protocol
Author: okfe
Latest version: 0.1.0

# @okxweb3/x402-express

Express middleware for the x402 Payment Protocol. Adds x402 payment requirements to Express.js applications.

## Installation

```bash
npm install @okxweb3/x402-express
```

## Quick Start

```typescript
import express from "express";
import { paymentMiddleware, x402ResourceServer } from "@okxweb3/x402-express";
import { ExactEvmScheme } from "@okxweb3/x402-evm/exact/server";
import { OKXFacilitatorClient } from "@okxweb3/x402-core/server";

const app = express();

const facilitatorClient = new OKXFacilitatorClient();
const resourceServer = new x402ResourceServer(facilitatorClient)
  .register("eip155:196", new ExactEvmScheme());

app.use(
  paymentMiddleware(
    {
      "GET /protected-route": {
        accepts: {
          scheme: "exact",
          price: "$0.10",
          network: "eip155:196",
          payTo: "0xYourAddress",
        },
        description: "Access to premium content",
      },
    },
    resourceServer,
  ),
);

app.get("/protected-route", (req, res) => {
  res.json({ message: "Premium content" });
});

app.listen(3000);
```

## API Reference

### paymentMiddleware

```typescript
function paymentMiddleware(
  routes: RoutesConfig,
  server: x402ResourceServer,
  syncFacilitatorOnStart?: boolean,
): (req: Request, res: Response, next: NextFunction) => Promise<void>;
```

Creates Express middleware that:

1. Checks if the incoming request matches a protected route
2. Validates payment headers if required
3. Returns payment instructions (402 status) if payment is missing or invalid
4. Processes the request if payment is valid
5. Handles settlement after successful response

#### Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `routes` | Yes | Route configurations for protected endpoints |
| `server` | Yes | Pre-configured `x402ResourceServer` instance |
| `syncFacilitatorOnStart` | No | Whether to sync with facilitator on startup (default: `true`) |

### setSettlementOverrides

```typescript
function setSettlementOverrides(res: Response, overrides: SettlementOverrides): void;
```

Set settlement overrides on the response for partial settlement.

### Route Configuration

```typescript
const routes: RoutesConfig = {
  "GET /api/protected": {
    accepts: {
      scheme: "exact",
      price: "$0.10",
      network: "eip155:196",
      payTo: "0xYourAddress",
      maxTimeoutSeconds: 60,
    },
    description: "Premium API access",
  },
};

app.use(paymentMiddleware(routes, resourceServer));
```

### Multiple Protected Routes

```typescript
app.use(
  paymentMiddleware(
    {
      "GET /api/premium/*": {
        accepts: {
          scheme: "exact",
          price: "$1.00",
          network: "eip155:196",
          payTo: "0xYourAddress",
        },
        description: "Premium API access",
      },
      "GET /api/data": {
        accepts: {
          scheme: "exact",
          price: "$0.50",
          network: "eip155:196",
          payTo: "0xYourAddress",
          maxTimeoutSeconds: 120,
        },
        description: "Data endpoint access",
      },
    },
    resourceServer,
  ),
);
```