Skip to main content
Accept crypto payments in your Bun HTTP server with a single function call.

Installation

Quick Start


How It Works

The middleware intercepts incoming requests and:
  1. Checks for payment headers (X-Payment or X402-PAYMENT)
  2. Verifies the payment signature and amount
  3. Returns null if valid (allowing your handler to proceed)
  4. Returns a Response with 402 status if payment is missing or invalid

Configuration

Required Options

Settlement Modes

Control how payments are settled after verification:

Verification Backend

Use your deployed verification backend in production.

Response Format

On successful payment verification, the middleware returns a Response with: Headers:
  • X-Payment-Verified: true
  • X-Payer-Address: 0x...
Body:

Error Responses

402 Payment Required

No payment header was provided.

402 Verification Failed

Payment signature or amount was invalid.

400 Settlement Failed

Settlement mode was settle but on-chain transaction failed.

Tips

For development and testing, use settlementMode: 'verify' to skip on-chain settlement while still verifying payment signatures.
The amount can be specified as a human-readable string like "1.0" for 1 token, or as a bigint for precise control over decimals.
Always validate the payTo address matches your wallet. The middleware does not check if the address is valid or belongs to you.

Advanced Mix-and-Match Config (Current API)

Use paymentMiddleware for per-token/per-network facilitator routing and extension-aware challenge headers:
For fully custom amount-per-combination behavior, pass explicit requirements:
Unsupported extension keys are auto-ignored (fail-open) per facilitator /supported capability response.