Quickstart

1. Install the publisher middleware

npm install @agents402/server-next @getalby/sdk zod

The reference Next.js middleware exposes the manifest, signs receipts with an ed25519 service key, and ships an L402 challenge wrapper for any route handler.

2. Add the manifest

Drop a route at app/.well-known/agents402.json/route.ts:

import { NextResponse } from "next/server";
import { listActions, getServiceKeys } from "@agents402/server-next";

export const dynamic = "force-dynamic";

export function GET() {
  return NextResponse.json({
    version: "0.1",
    service: {
      name:     "Example Pub",
      homepage: process.env.PUBLIC_URL,
    },
    actions:  listActions(),
    receipts: {
      pubkey_hex: getServiceKeys().publicKey,
      algorithm:  "ed25519",
    },
  });
}

3. Wrap an action

import { withL402 } from "@agents402/server-next";

export const POST = withL402(
  {
    id:          "extract.structured",
    type:        "structured_data",
    price_msats: 1000,
    risk:        "low",
    input: {
      doc_id: { type: "string", maxLength: 256 },
    },
  },
  async ({ input }) => {
    const doc = await loadDoc(input.doc_id);
    return { title: doc.title, summary: doc.summary };
  },
);

The wrapper handles 402 challenge issuance, token signing, idempotency, and receipt creation. Your handler runs only after payment is confirmed.

4. Wire up a Lightning wallet

The publisher needs a Lightning wallet that can issue invoices and confirm settlement. Use any NIP-47 NWC-compatible wallet (Coinos, Alby Hub, LNbits, Primal, …):

PUBLISHER_NWC_URL=nostr+walletconnect://…
L402_SECRET=any-random-string

5. Talk to the agent side

The reference agent integration is a Model Context Protocol (MCP) server that gives Claude (or any MCP-aware client) three tools:

• ·discover — fetches a manifest, surfaces actions and prices
• ·pay_and_invoke — pays the L402 challenge under deterministic policy and runs the action
• ·spend_summary— reports today's spend and remaining budget

Add the published reference server to any MCP-aware client:

{
  "mcpServers": {
    "faregate": {
      "command": "npx",
      "args": [
        "-y",
        "@agents402/mcp"
      ]
    }
  }
}

That's it — no wallet pre-configuration. The first time the agent hits a paywall, the MCP returns a structured needs_setup response and walks the user through pairing a wallet (paste an existing NWC URI, or open a browser to create a self-custodial Spark wallet).

Verify with a real payment

npx agents402 test https://your-publisher.example

The conformance harness fetches the manifest, triggers a 402, pays from the configured agent wallet, retries with proof, and validates the signed receipt. Exit code 0 = end-to-end mainnet flow verified.