monetize-service

# Build an x402 Payment Server

Create an Express server that charges USDC for API access using the x402 payment protocol. Callers pay per-request in USDC on Base — no accounts, API keys, or subscriptions needed.

## How It Works

x402 is an HTTP-native payment protocol. When a client hits a protected endpoint without paying, the server returns HTTP 402 with payment requirements. The client signs a USDC payment and retries with a payment header. The facilitator verifies and settles the payment, and the server returns the response.

## Confirm wallet is initialized and authed

```bash
npx awal@latest status
```

If the wallet is not authenticated, refer to the `authenticate-wallet` skill.

## Step 1: Get the Payment Address

Run this to get the wallet address that will receive payments:

```bash
npx awal@latest address
```

Use this address as the `payTo` value.

## Step 2: Set Up the Project

```bash
mkdir x402-server && cd x402-server
npm init -y
npm install express x402-express
```

Create `index.js`:

```js
const express = require("express");
const { paymentMiddleware } = require("x402-express");

const app = express();
app.use(express.json());

const PAY_TO = "<address from step 1>";

// x402 payment middleware — protects routes below
const payment = paymentMiddleware(PAY_TO, {
  "GET /api/example": {
    price: "$0.01",
    network: "base",
    config: {
      description: "Description of what this endpoint returns",
    },
  },
});

// Protected endpoint
app.get("/api/example", payment, (req, res) => {
  res.json({ data: "This costs $0.01 per request" });
});

app.listen(3000, () => console.log("Server running on port 3000"));
```

## Step 3: Run It

```bash
node index.js
```

Test with curl — you should get a 402 response with payment requirements:

```bash
curl -i http://localhost:3000/api/example
```

## API Reference

### paymentMiddleware(payTo, routes, facilitator?)

Creates Express middleware that enforces x402 payments.

| Parameter     | Type     | Description                                           |
| ------------- | -------- | ----------------------------------------------------- |
| `payTo`       | string   | Ethereum address (0x...) to receive USDC payments     |
| `routes`      | object   | Route config mapping route patterns to payment config |
| `facilitator` | object?  | Optional custom facilitator (defaults to x402.org)    |

### Route Config

Each key in the routes object is `"METHOD /path"`. The value is either a price string or a config object:

```js
// Simple — just a price
{ "GET /api/data": "$0.05" }

// Full config
{
  "POST /api/query": {
    price: "$0.25",
    network: "base",
    config: {
      description: "Human-readable description of the endpoint",
      inputSchema: {
        bodyType: "json",
        bodyFields: {
          query: { type: "string", description: "The query to run" },
        },
      },
      outputSchema: {
        type: "object",
        properties: {
          result: { type: "string" },
        },
      },
    },
  },
}
```

### Route Config Fields

| Field                     | Type    | Description                                        |
| ------------------------- | ------- | -------------------------------------------------- |
| `price`                   | string  | USDC price (e.g. "$0.01", "$1.00")                 |
| `network`                 | string  | Blockchain network: "base" or "base-sepolia"       |
| `config.description`      | string? | What this endpoint does (shown to clients)         |
| `config.inputSchema`      | object? | Expected request body/query schema                 |
| `config.outputSchema`     | object? | Response body schema                               |
| `config.maxTimeoutSeconds` | number? | Max time for payment settlement                   |

### Supported Networks

| Network        | Description                    |
| -------------- | ------------------------------ |
| `base`         | Base mainnet (real USDC)       |
| `base-sepolia` | Base Sepolia testnet (test USDC) |

## Patterns

### Multiple endpoints with different prices

```js
const payment = paymentMiddleware(PAY_TO, {
  "GET /api/cheap": { price: "$0.001", network: "base" },
  "GET /api/expensive": { price: "$1.00", network: "base" },
  "POST /api/query": { price: "$0.25", network: "base" },
});

app.get("/api/cheap", payment, (req, res) => { /* ... */ });
app.get("/api/expensive", payment, (req, res) => { /* ... */ });
app.post("/api/query", payment, (req, res) => { /* ... */ });
```

### Wildcard routes

```js
const payment = paymentMiddleware(PAY_TO, {
  "GET /api/*": { price: "$0.05", network: "base" },
});

app.use(payment);
app.get("/api/users", (req, res) => { /* ... */ });
app.get("/api/posts", (req, res) => { /* ... */ });
```

### Health check (no payment)

Register free endpoints before the payment middleware:

```js
app.get("/health", (req, res) => res.json({ status: "ok" }));

// Payment middleware only applies to routes registered after it
app.get("/api/data", payment, (req, res) => { /* ... */ });
```

### POST with body schema

```js
const payment = paymentMiddleware(PAY_TO, {
  "POST /api/analyze": {
    price: "$0.10",
    network: "base",
    config: {
      description: "Analyze text sentiment",
      inputSchema: {
        bodyType: "json",
        bodyFields: {
          text: { type: "string", description: "Text to analyze" },
        },
      },
      outputSchema: {
        type: "object",
        properties: {
          sentiment: { type: "string" },
          score: { type: "number" },
        },
      },
    },
  },
});

app.post("/api/analyze", payment, (req, res) => {
  const { text } = req.body;
  // ... your logic
  res.json({ sentiment: "positive", score: 0.95 });
});
```

### Using the CDP facilitator (authenticated)

For production use with the Coinbase facilitator (supports mainnet):

```bash
npm install @coinbase/x402
```

```js
const { facilitator } = require("@coinbase/x402");

const payment = paymentMiddleware(PAY_TO, routes, facilitator);
```

This requires `CDP_API_KEY_ID` and `CDP_API_KEY_SECRET` environment variables. Get these from https://portal.cdp.coinbase.com.

## Testing with the pay-for-service Skill

Once the server is running, use the `pay-for-service` skill to test payments:

```bash
# Check the endpoint's payment requirements
npx awal@latest x402 details http://localhost:3000/api/example

# Make a paid request
npx awal@latest x402 pay http://localhost:3000/api/example
```

## Pricing Guidelines

| Use Case               | Suggested Price |
| ---------------------- | --------------- |
| Simple data lookup     | $0.001 - $0.01 |
| API proxy / enrichment | $0.01 - $0.10  |
| Compute-heavy query    | $0.10 - $0.50  |
| AI inference           | $0.05 - $1.00  |

## Checklist

- [ ] Get wallet address with `npx awal@latest address`
- [ ] Install `express` and `x402-express`
- [ ] Define routes with prices and descriptions
- [ ] Register payment middleware before protected routes
- [ ] Keep health/status endpoints before payment middleware
- [ ] Test with `curl` (should get 402) and `npx awal@latest x402 pay` (should get 200)
- [ ] Announce your service so other agents can find and use it