@faremeter/middleware

Server middleware for adding payment walls to API endpoints using the x402 protocol.

Installation

pnpm install @faremeter/middleware

Features

• Paywall any endpoint - Add middleware to any route
• Framework agnostic - Express, Hono, or custom
• Multi-chain support - Solana, EVM, extensible
• Fast validation - Payment requirements caching
• Facilitator integration - Handles settlement verification

API Reference

Functions

• createHTTPFacilitatorHandler
• findMatchingPaymentRequirements
• findMatchingPaymentRequirementsV2
• relaxedRequirementsToV2
• resolveSupportedVersions
• validateMiddlewareArgs
• deriveCapabilities
• deriveSchemes
• deriveResourceInfo
• acceptsToPricing
• createRemoteX402Handlers
• resolveConfig
• resolveCapturesAt
• handleMiddlewareRequest
• createMiddleware
• createMiddleware

createHTTPFacilitatorHandler

Creates a FacilitatorHandler that delegates to a remote facilitator via HTTP.

The glue layer constructs valid x402PaymentRequirements from ResourcePricing using the handler's declared schemes, then passes them to getRequirements. This handler POSTs those to the facilitator's /accepts endpoint for enrichment.

Cache key stability: caching assumes that identical accepts arrays produce identical facilitator responses. If the facilitator returns time-dependent values (e.g. recentBlockhash), use a short maxAge or disable caching.

findMatchingPaymentRequirements

Finds the payment requirement that matches the client's v1 payment payload.

Parameters:

• accepts: - Array of accepted payment requirements from the facilitator
• payload: - The client's payment payload

Returns:

The matching requirement, or undefined if no match found

findMatchingPaymentRequirementsV2

Finds the payment requirement that matches the client's v2 payment payload.

Parameters:

• accepts: - Array of accepted payment requirements from the facilitator
• payload: - The client's v2 payment payload

Returns:

The matching requirement, or undefined if no match found

relaxedRequirementsToV2

Converts v1 relaxed requirements to v2 format, preserving all fields including extra.

resolveSupportedVersions

Resolve and validate supported versions config. Returns resolved config with defaults applied. Throws if configuration is invalid.

validateMiddlewareArgs

Validates that CommonMiddlewareArgs has exactly one configuration mode.

deriveCapabilities

Derives HandlerCapabilities from relaxed v1 requirements. Used by framework adapters to construct capabilities for the HTTP wrapper from the legacy accepts configuration.

deriveSchemes

Derives the distinct set of x402 schemes from relaxed v1 requirements. Sibling of {@link deriveCapabilities}; kept separate because schemes are x402-specific and live on the handler rather than on {@link HandlerCapabilities }.

deriveResourceInfo

Extracts resource info from v1 accepts entries. Used by framework adapters to build the resource info for the 402 response.

acceptsToPricing

createRemoteX402Handlers

Creates x402 facilitator handlers backed by a remote HTTP facilitator.

This is the composable equivalent of the facilitatorURL + accepts shorthand on {@link CommonMiddlewareArgs}. Use it when you need to combine a remote x402 facilitator with in-process MPP handlers in the same middleware.

Returns:

An array of FacilitatorHandler suitable for createMiddleware({ x402Handlers: ... }).

resolveConfig

Resolves {@link CommonMiddlewareArgs} into the handlers + pricing tuple that {@link handleMiddlewareRequest} needs. For the facilitatorURL path, creates an HTTP handler wrapper and converts accepts to pricing.

resolveCapturesAt

Resolves whether the body callback should capture at /request (one-phase) or defer to /response (two-phase).

canAuthorize is "any handler that actually accepts THIS scheme / method declares verification". For x402 the candidate set is narrowHandlers(handlers, requirements) further filtered by h.schemes?.includes(requirements.scheme) — the scheme filter is load-bearing because narrowHandlers only checks network and asset, so without it a multi-scheme handler set with one verify- capable handler would leak canAuthorize = true to schemes served only by settle-only handlers. For MPP the candidate set is the handlers filtered by exact method match. The middleware computes the predicate per request before invoking body, so the body callback only has to read context.capturesAt.

pin is the operator-supplied override from PaymentPolicy.pin keyed by <protocol>:<scheme-or-method>. A pin to "response" against a handler that cannot authorize is rejected at construction by validateOperationPolicies in middleware-openapi. If one somehow reaches this resolver at runtime (e.g. a programmatic spec that bypasses validation) the body's authorize() call will throw "no handler accepted the verification", which propagates up as a 500 -- loud failure rather than a silent demotion to one-phase.

handleMiddlewareRequest

Core middleware request handler that processes x402 and MPP payment flows.

Delegates to protocol-specific glue layers for challenge generation, settlement, and verification. The middleware formats HTTP responses but never constructs protocol types directly.

createMiddleware

Creates Express middleware that gates routes behind x402 and MPP payment.

Parameters:

• args: - Configuration including handlers + pricing or facilitator URL

Returns:

An Express middleware function

createMiddleware

Creates Hono middleware that gates routes behind x402 and MPP payment.

The middleware intercepts requests, checks for payment headers, validates and settles payments via x402 or MPP protocol, and only allows the request to proceed if payment is successful.

Parameters:

• args: - Configuration including handlers + pricing or facilitator URL

Returns:

A Hono middleware handler

AgedLRUCache

An LRU cache with time-based expiration.

Entries are evicted when they exceed maxAge or when the cache reaches capacity (least recently used entries are removed first).

Methods

• get
• put

get

put

Types

• AgedLRUCacheOpts
• RelaxedRequirements
• RelaxedRequirementsV2
• SupportedVersionsConfig
• CommonMiddlewareArgs
• CreateRemoteX402HandlersArgs
• ResolvedConfig
• CaptureResultV1
• CaptureResultV2
• CaptureResult
• AuthorizeResultV1
• AuthorizeResultV2
• AuthorizeResult
• CapturesAt
• PaymentPolicy
• MiddlewareBodyContextV1
• MiddlewareBodyContextV2
• CaptureResultMPP
• AuthorizeResultMPP
• MiddlewareBodyContextMPP
• MiddlewareBodyContext
• HandleMiddlewareRequestArgs

AgedLRUCacheOpts

Configuration options for the AgedLRUCache.

RelaxedRequirements

RelaxedRequirementsV2

SupportedVersionsConfig

Configuration for which x402 protocol versions the middleware supports. At least one version must be enabled.

CommonMiddlewareArgs

Common configuration arguments shared by all middleware implementations. Supports two mutually exclusive modes: in-process handlers or remote facilitator.

CreateRemoteX402HandlersArgs

ResolvedConfig

CaptureResultV1

| Type | Type | | ----------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------- | | CaptureResultV1 | | { success: true; response: x402SettleResponseV1 } or { success: false; errorResponse: MiddlewareResponse; errorMessage?: string; } |

CaptureResultV2

| Type | Type | | ----------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------- | | CaptureResultV2 | | { success: true; response: x402SettleResponse } or { success: false; errorResponse: MiddlewareResponse; errorMessage?: string; } |

CaptureResult

| Type | Type | | --------------- | ---- | --------------------------------------------------------------------------- | | CaptureResult | | CaptureResultV1<MiddlewareResponse> or CaptureResultV2<MiddlewareResponse> |

AuthorizeResultV1

| Type | Type | | ------------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------- | | AuthorizeResultV1 | | { success: true; response: x402VerifyResponseV1 } or { success: false; errorResponse: MiddlewareResponse; errorMessage?: string; } |

AuthorizeResultV2

| Type | Type | | ------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------- | | AuthorizeResultV2 | | { success: true; response: x402VerifyResponse } or { success: false; errorResponse: MiddlewareResponse; errorMessage?: string; } |

AuthorizeResult

| Type | Type | | ----------------- | ---- | ------------------------------------------------------------------------------- | | AuthorizeResult | | AuthorizeResultV1<MiddlewareResponse> or AuthorizeResultV2<MiddlewareResponse> |

CapturesAt

When the body callback should drive capture.

"request" — one-phase: body calls capture() immediately and the payment clears before the resource is produced.

"response" — two-phase: body calls authorize() now and defers capture to a later phase (the OpenAPI gateway captures at /response once the final amount is known).

The middleware resolves this per-request via {@link resolveCapturesAt} from the matched handler's authorize capability and the rule's hasAuthorize flag, so the body callback never has to inspect the context shape to decide which path to take.

PaymentPolicy

Per-operation payment policy. Restricts which protocol schemes / methods are accepted for a given route and optionally pins specific ones to one-phase or two-phase capture regardless of the handler's declared capability.

Keys in allow and pin are of the form "<protocol>:<id>":

• "x402:exact", "x402:permit2" — x402 schemes
• "mpp:solana" — MPP methods

The protocol prefix is case-sensitive and uses the lowercase wire form ("mpp:", not "MPP:"), matching how schemes and methods are identified on the protocol surface itself.

allow: undefined permits every registered scheme and method. allow: [] denies all of them (the deny-all sentinel).

pin["x402:exact"].capturesAt: "request" forces one-phase capture for that scheme regardless of whether the handler supports handleVerify and regardless of whether the rule has authorize. A pin to "response" against a handler that cannot authorize is a configuration error caught at construction.

MiddlewareBodyContextV1

Context provided to the middleware body handler for v1 protocol requests. Contains payment information and the industry-standard authorize / capture operations. Under the hood these dispatch to the matched x402 facilitator handler's handleVerify / handleSettle.

MiddlewareBodyContextV2

Context provided to the middleware body handler for v2 protocol requests. Contains payment information and the industry-standard authorize / capture operations. Under the hood these dispatch to the matched x402 facilitator handler's handleVerify / handleSettle.

CaptureResultMPP

| Type | Type | | ------------------ | ---- | ------------------------------------------------------------------------------------------------------------------------ | | CaptureResultMPP | | { success: true; receipt: mppReceipt } or { success: false; errorResponse: MiddlewareResponse; errorMessage?: string; } |

AuthorizeResultMPP

| Type | Type | | -------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------ | | AuthorizeResultMPP | | { success: true; receipt: mppReceipt } or { success: false; errorResponse: MiddlewareResponse; errorMessage?: string; } |

MiddlewareBodyContextMPP

Context provided to the middleware body handler for MPP protocol requests.

authorize is optional because not every MPP method handler implements handleVerify. When capturesAt === "response" the middleware guarantees authorize is defined (the resolver only picks "response" when at least one matching handler can verify).

MiddlewareBodyContext

Context provided to the middleware body handler. Use protocolVersion to discriminate between v1, v2, and mpp request types.

| Type | Type | | ----------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------- | | MiddlewareBodyContext | | MiddlewareBodyContextV1<MiddlewareResponse> or MiddlewareBodyContextV2<MiddlewareResponse> or MiddlewareBodyContextMPP<MiddlewareResponse> |

HandleMiddlewareRequestArgs

Arguments for the core middleware request handler. Framework-specific middleware implementations adapt their request/response objects to this interface.

Examples

See working examples in the faremeter repository:

• Express + Solana
• Express + EVM
• Hono + Solana

Related Packages

• @faremeter/fetch - Client-side fetch wrapper
• @faremeter/info - Network/asset configuration helpers
• @faremeter/facilitator - Payment facilitator service

License

LGPL-3.0-only