pay402

A universal payment layer for machine-to-machine commerce.

HTTP 402 ("Payment Required") has been a reserved status code since 1997 — a placeholder for a future where software could pay for services the same way it follows redirects. That future is here. Multiple payment protocols now use 402, but they're incompatible with each other: Lightning uses macaroons and invoices, x402 uses EIP-712 signatures on Base, Solana has its own flow, and Arkade uses Bitcoin VTXOs. A client built for one can't talk to the others.

pay402 is the universal adapter. One SDK that speaks every 402 dialect, so your code — whether it's an AI agent, an MCP server, a backend service, or a script — can pay any 402-gated endpoint regardless of which payment rail it uses. Configure your wallets once, set spend limits, and client.fetch() handles everything: challenge parsing, rail selection, payment execution, proof caching, and automatic retry.

But pay402 goes further than just client-side payments:

• Bridge layer — Don't have the right wallet? pay402 routes payments across rails. An Arkade wallet can pay a Lightning invoice via Boltz atomic swap, or a USDC wallet can pay one via LendaSat. The server never knows the difference.
• Server middleware — Gate your own Express routes or MCP tools behind payment with a few lines of config. Multi-rail, multi-price, plug in your own verification.
• Agent skill — Register pay402 as MCP tools so AI agents can discover, estimate, and execute paid API calls autonomously — with spending controls that keep them on a leash.

The net effect: any software with a wallet can pay any service with a price. The payment rail becomes an implementation detail, not a compatibility barrier.

Supported Rails

Rail	Protocol	Currency	Network
L402	Lightning Labs	Bitcoin (sats)	Lightning Network
x402	Coinbase	USDC	Base, Solana

Arkade and EVM (USDC) wallets are also supported as funding sources via the bridge layer — they can pay L402 invoices through atomic swaps (Boltz for Arkade, LendaSat for USDC), but neither is a server-facing payment rail for L402.

Install

npm install pay402

Optional peer dependencies for bridge support:

npm install @arkade-os/sdk            # Arkade wallet
npm install @arkade-os/boltz-swap     # Arkade→Lightning bridge
npm install @lendasat/lendaswap-sdk-pure  # USDC→Lightning bridge

Quick Start

The fastest way to get running — configure wallets via environment variables:

# Set at least one wallet
export EVM_PRIVATE_KEY=0x...           # for x402 (Base/USDC)
# or
export LND_HOST=https://localhost:8080  # for L402 (Lightning)
export LND_MACAROON=hex-encoded-macaroon
# or
export ARKADE_MNEMONIC="your twelve word mnemonic phrase here"
export ARKADE_SERVER_URL=https://arkade.computer
export ARKADE_NETWORK=mainnet

# Set spend limits
export PAY402_MAX_DAILY=10.00
export PAY402_MAX_PER_REQUEST=1.00

import { fromEnv } from "pay402";

const client = fromEnv();

const res = await client.fetch("https://api.example.com/premium-data");
const data = await res.json();

That's it. The client auto-detects which wallets are configured, handles 402 responses, pays, retries, and caches tokens. See .env.example for all available options.

Try it locally

git clone https://github.com/RDMoutlaw/pay402.git && cd pay402
npm install
npx tsx examples/mock-server.ts   # Terminal 1: starts a 402-gated server
npx tsx examples/client-test.ts   # Terminal 2: pays and gets access

Manual Configuration

For full control, configure the client directly:

import { pay402Fetch } from "pay402";

const fetch402 = pay402Fetch({
  wallets: [
    {
      type: "lightning",
      lndHost: process.env.LND_HOST!,
      lndMacaroon: process.env.LND_MACAROON!,
    },
    {
      type: "evm",
      privateKey: process.env.EVM_PRIVATE_KEY! as `0x${string}`,
      chain: "base",
    },
    {
      type: "solana",
      secretKey: process.env.SOLANA_SECRET_KEY!,
      cluster: "mainnet-beta",
    },
    {
      type: "arkade",
      mnemonic: process.env.ARKADE_MNEMONIC!,
      arkServerUrl: process.env.ARKADE_SERVER_URL!,
      network: "mainnet",
    },
  ],
  autoFetchBtcPrice: true,
  logLevel: "info",
  spendControls: {
    global: { maxDaily: 10.0, maxPerRequest: 2.0 },
    denylist: ["https://*.untrusted.com/**"],
  },
});

const res = await fetch402("https://api.example.com/premium-data");
const data = await res.json();

Class API

import { Pay402Client } from "pay402";

const client = new Pay402Client({
  wallets: [{ type: "lightning", lndHost: "...", lndMacaroon: "..." }],
  btcPriceUsd: 60000,
  maxSinglePaymentUsd: 5,
  onPayment: (record) => {
    console.log(`Paid $${record.amountUsd} via ${record.rail} to ${record.endpoint}`);
  },
});

const res = await client.fetch("https://api.example.com/data");

// Call destroy() when done to stop background tasks (BTC price refresh)
client.destroy();

Axios Interceptor

import axios from "axios";
import { Pay402Client } from "pay402";

const client = new Pay402Client({ wallets: [...] });

axios.interceptors.request.use((config) => client.intercept(config));

Cross-Rail Bridging

When a server requires a rail your wallet doesn't natively support, pay402 can bridge the payment. For example, an Arkade wallet can pay a Lightning (L402) invoice via a Boltz submarine swap, or a USDC (EVM) wallet can pay one via a LendaSat atomic swap.

Bridging is opt-in and disabled by default:

// Arkade → Lightning
const client = new Pay402Client({
  wallets: [
    {
      type: "arkade",
      mnemonic: process.env.ARKADE_MNEMONIC!,
      arkServerUrl: "https://arkade.computer",
      network: "mainnet",
    },
  ],
  bridging: {
    enabled: true,
    maxBridgeFeeUsd: 0.50,              // max bridge fee you're willing to pay
    allowedPaths: ["arkade->l402"],      // only allow specific bridge paths
  },
  autoFetchBtcPrice: true,
});

// This works even though the server only accepts L402 (Lightning):
const res = await client.fetch("https://lightning-only-api.com/data");

// USDC → Lightning
const client = new Pay402Client({
  wallets: [
    {
      type: "evm",
      privateKey: process.env.EVM_PRIVATE_KEY! as `0x${string}`,
      chain: "base",
    },
  ],
  bridging: {
    enabled: true,
    maxBridgeFeeUsd: 0.50,
    allowedPaths: ["x402-base->l402"],
    lendasat: {
      chainId: 137,                      // Polygon (default)
      tokenAddress: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", // Polygon USDC (default)
    },
  },
  autoFetchBtcPrice: true,
});

// EVM wallet pays a Lightning invoice via LendaSat gasless swap:
const res = await client.fetch("https://lightning-only-api.com/data");

The server sees a valid L402 preimage — it doesn't know or care how the payment was funded. Bridge fees are included in spend control checks.

Currently supported bridge paths:

Source	Target	Provider	Peer Dependency
arkade	l402	Boltz submarine swap	@arkade-os/boltz-swap
x402-base	l402	LendaSat gasless atomic swap	@lendasat/lendaswap-sdk-pure

Agent Skill (MCP Client Tools)

Register pay402 as a set of tools on an MCP server so AI agents can discover and use paid APIs:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { registerPay402Tools } from "pay402/mcp-tool";

const server = new McpServer({ name: "my-agent", version: "1.0" });
registerPay402Tools(server);

This registers four tools:

Tool	Description	Key Input
pay402_fetch	Fetch a URL with automatic 402 payment	url, method?, headers?, body?
pay402_estimate	Dry-run cost estimation	url, method?
pay402_spending	View spending summary by period	period? (hour, day, all)
pay402_balance	Check wallet balances	—

You can pass a pre-built client or let it auto-configure from environment variables:

// With a pre-built client
const client = new Pay402Client({ wallets: [...] });
registerPay402Tools(server, { client });

// Or auto-configure from env
registerPay402Tools(server);

The package includes a SKILL.md file for agent skill discovery.

Programmatic Spending & Balance API

The client also exposes these methods directly:

// Spending summary
const summary = client.getSpendingSummary("hour");
// { totalUsd: 3.50, count: 5, byRail: { l402: { totalUsd: 2.0, count: 3 }, ... } }

// Wallet balances (currently supported for Arkade wallets)
const balances = await client.getBalances();
// [{ type: "arkade", balanceSats: 50000 }, { type: "lightning", error: "balance check not supported" }]

Server Middleware — Express

import express from "express";
import { pay402Middleware } from "pay402";

const app = express();

app.use(
  pay402Middleware({
    pricing: {
      "/api/premium/*": { l402: 1000, x402: 500000 }, // 1000 sats or 0.50 USDC
      "/api/data": { x402: 100000 },                                 // 0.10 USDC only
    },
    acceptedRails: ["l402", "x402"],
    verifyL402: (macaroon, preimage) => { /* your verification logic */ },
    verifyX402: (payload) => { /* your verification logic */ },
    x402PayTo: "0xYourAddress",
    x402Asset: "0xUSDCContractAddress",
    x402Network: "base",
    onPaymentReceived: ({ rail, route, amount }) => {
      console.log(`Received payment on ${rail} for ${route}`);
    },
  })
);

app.get("/api/premium/report", (req, res) => {
  res.json({ data: "premium content" });
});

MCP Payment Wrapper

Gate MCP tools behind payment without modifying tool implementations.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { mcpPaymentWrapper } from "pay402";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

// Wrap BEFORE registering tools
mcpPaymentWrapper({
  server,
  pricing: {
    "premium-analysis": { l402: 500, x402: 250000 },
    "generate-report": { x402: 1000000 },
  },
  acceptedRails: ["l402", "x402"],
  verifyL402: (macaroon, preimage) => true,
  verifyX402: (payload) => true,
  x402PayTo: "0xYourAddress",
  x402Asset: "0xUSDC",
});

// Register tools as normal — payment is handled by the wrapper
server.registerTool("premium-analysis", { description: "..." }, async (args) => {
  return { content: [{ type: "text", text: "analysis result" }] };
});

When a tool is called without payment, the wrapper returns a structured error:

{
  "error": "payment_required",
  "version": "pay402/1.0",
  "challenges": [
    { "rail": "l402", "amountSats": 500 },
    { "rail": "x402", "network": "base", "amountSmallestUnit": 250000, "payTo": "0x...", "asset": "0x...", "maxTimeoutSeconds": 60 },
  ]
}

The calling client retries with proof in the _payment_proof parameter.

Configuration Reference

Wallet Types

Type	Required Fields	Optional
lightning	lndHost, lndMacaroon	tlsCert
evm	privateKey (0x-prefixed), chain	rpcUrl, facilitatorUrl
solana	secretKey, cluster	facilitatorUrl
arkade	mnemonic, arkServerUrl, network	—

Environment Variables

Variable	Wallet	Description
LND_HOST	Lightning	LND REST API host
LND_MACAROON	Lightning	Hex-encoded admin macaroon
LND_TLS_CERT	Lightning	Base64 TLS cert for self-signed nodes
EVM_PRIVATE_KEY	EVM	0x-prefixed hex private key
EVM_CHAIN	EVM	base or base-sepolia (default: base)
EVM_FACILITATOR_URL	EVM	x402 facilitator URL
SOLANA_SECRET_KEY	Solana	Base58-encoded keypair
SOLANA_CLUSTER	Solana	mainnet-beta or devnet (default: mainnet-beta)
SOLANA_FACILITATOR_URL	Solana	x402 facilitator URL
ARKADE_MNEMONIC	Arkade	BIP-39 mnemonic phrase
ARKADE_SERVER_URL	Arkade	Arkade server URL
ARKADE_NETWORK	Arkade	mainnet or testnet (default: mainnet)
PAY402_MAX_PER_REQUEST	—	Max USD per request
PAY402_MAX_HOURLY	—	Max USD per rolling hour
PAY402_MAX_DAILY	—	Max USD per rolling day
PAY402_BTC_PRICE_USD	—	Static BTC price in USD
PAY402_AUTO_BTC_PRICE	—	true to auto-fetch from CoinGecko
PAY402_LOG_LEVEL	—	Logging level

Spend Controls

{
  perEndpoint: {
    "https://api.example.com/*": { maxPerRequest: 0.50, maxDaily: 5.00 }
  },
  global: {
    maxPerRequest: 2.00,  // USD
    maxHourly: 10.00,     // rolling window
    maxDaily: 50.00,      // rolling window
  },
  railPreference: ["x402-base", "l402"],  // or "cheapest"
  allowlist: ["https://trusted.com/**"],
  denylist: ["https://*.evil.com/**"],
  dryRun: false,
}

For a complete guide on configuring spend policies for autonomous agents — budget tiers, approval workflows, multi-agent setups, and emergency controls — see Agent Spend Policy Guide.

Bridging Config

{
  bridging: {
    enabled: true,                       // default: false
    maxBridgeFeeUsd: 1.00,              // default: $1
    allowedPaths: ["arkade->l402", "x402-base->l402"], // restrict which bridge paths are allowed
    lendasat: {                          // optional LendaSat config
      chainId: 137,                      // default: 137 (Polygon)
      tokenAddress: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", // default: Polygon USDC
    },
  },
}

Dry Run Mode

const client = new Pay402Client({
  wallets: [...],
  spendControls: { dryRun: true },
});

const res = await client.fetch("https://api.example.com/data");
const estimate = await res.json();
// { rail: "x402-base", estimatedCostUsd: 1.0, wouldExceedLimits: false }

Error Handling

All errors extend Pay402Error:

Error	When
NoCompatibleRailError	No adapter matches any advertised rail, or no wallet configured
SpendLimitExceededError	Any spend control check fails
PaymentFailedError	Adapter pay() threw — no auto-retry (money at stake)
PaymentInFlightError	LND returned IN_FLIGHT — outcome unknown
PaymentVerificationError	Server still returned 402 after payment
InvoiceExpiredError	BOLT11 invoice expired before payment attempt
BridgePaymentFailedError	Bridge swap failed (includes bridgePath field)

import { SpendLimitExceededError, PaymentFailedError, BridgePaymentFailedError } from "pay402";

try {
  await client.fetch("https://api.example.com/data");
} catch (err) {
  if (err instanceof SpendLimitExceededError) {
    console.log(`Limit hit: ${err.limitType}, tried $${err.attemptedAmountUsd}`);
  }
  if (err instanceof PaymentFailedError) {
    console.log(`Payment failed on ${err.rail}: ${err.underlyingError.message}`);
  }
  if (err instanceof BridgePaymentFailedError) {
    console.log(`Bridge failed on ${err.bridgePath}: ${err.underlyingError.message}`);
  }
}

Logging

Structured JSON logging via pino. Set via config or env var:

const client = new Pay402Client({ wallets: [...], logLevel: "debug" });

Or: PAY402_LOG_LEVEL=debug (silent | fatal | error | warn | info | debug | trace)

Logs payment events, cache hits, rail selection, and challenge parsing at appropriate levels.

Live BTC Price

// Auto-fetch and refresh every 5 minutes (CoinGecko)
const client = new Pay402Client({
  wallets: [...],
  autoFetchBtcPrice: true,
  btcPriceUsd: 60000, // fallback until first fetch completes
});

// Or use the provider directly
import { createBtcPriceProvider } from "pay402";

const provider = createBtcPriceProvider({ initialPrice: 60000 });
console.log(provider.getPrice()); // latest price
provider.stop(); // cleanup

How It Works

1. Client makes a request to a 402-gated endpoint
2. Server returns 402 with WWW-Authenticate (L402) and/or X-Payment-Required (x402) headers
3. SDK parses challenges from all headers
4. Checks token cache — if valid cached proof exists, skips payment
5. Runs spend control checks — blocks if any limit would be exceeded
6. Selects optimal rail based on wallet availability and preference config
7. If no direct match and bridging is enabled, attempts cross-rail bridge (e.g. Arkade -> L402)
8. Executes payment via the matching rail adapter (or bridge provider)
9. Retries the original request with proof-of-payment headers
10. Caches the token for future requests
11. Returns the response — caller never sees the 402

Security

This SDK handles private keys and real money. Keep these in mind:

• Never hardcode private keys or mnemonics. Load them from environment variables or a secret manager.
• The x402 facilitator is a trusted third party. When using x402, your signed EIP-3009 authorization is submitted to a facilitator (default: x402.org). The facilitator executes the on-chain transfer. A malicious facilitator could withhold or front-run transactions. Use facilitatorUrl to point to a facilitator you trust.
• Bridge swaps involve a third party. The Arkade→L402 bridge uses Boltz for submarine swaps; the USDC→L402 bridge uses LendaSat for atomic swaps. Bridge fees are included in spend control checks, but the swaps themselves are trust relationships with the respective services.
• Spend controls are your safety net. Always configure maxSinglePaymentUsd and global.maxDaily for autonomous agents. The default hard ceiling is $10 per payment.
• No auto-retry after payment failure. If a payment fails, the SDK throws immediately. It does not try another rail — money may have already left your wallet.
• No auto-fallback between rails. Rail selection happens before payment. Once a rail is chosen and payment begins, there's no switching.

To report a security vulnerability, please open a private issue or email the maintainers directly.

Contributing

git clone https://github.com/RDMoutlaw/pay402.git
cd pay402
npm install
npm test          # run tests
npm run typecheck # type-check without emitting

PRs welcome. Please include tests for new functionality.

License

MIT