# @faremeter/middleware Server middleware for adding payment walls to API endpoints using the x402 protocol. ## Installation ```bash 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](#createhttpfacilitatorhandler) - [findMatchingPaymentRequirements](#findmatchingpaymentrequirements) - [findMatchingPaymentRequirementsV2](#findmatchingpaymentrequirementsv2) - [relaxedRequirementsToV2](#relaxedrequirementstov2) - [resolveSupportedVersions](#resolvesupportedversions) - [validateMiddlewareArgs](#validatemiddlewareargs) - [deriveCapabilities](#derivecapabilities) - [deriveSchemes](#deriveschemes) - [deriveResourceInfo](#deriveresourceinfo) - [acceptsToPricing](#acceptstopricing) - [createRemoteX402Handlers](#createremotex402handlers) - [resolveConfig](#resolveconfig) - [resolveCapturesAt](#resolvecapturesat) - [handleMiddlewareRequest](#handlemiddlewarerequest) - [createMiddleware](#createmiddleware) - [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. | Function | Type | | ------------------------------ | ---------------------------------------------------------------------------------------- | | `createHTTPFacilitatorHandler` | `(facilitatorURL: string, opts: CreateHTTPFacilitatorHandlerOpts) => FacilitatorHandler` | ### findMatchingPaymentRequirements Finds the payment requirement that matches the client's v1 payment payload. | Function | Type | | --------------------------------- | ------------------------------------------------------------------------------ | | `findMatchingPaymentRequirements` | `(accepts: x402PaymentRequirementsV1[], payload: x402PaymentPayloadV1) => any` | 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. | Function | Type | | ----------------------------------- | -------------------------------------------------------------------------- | | `findMatchingPaymentRequirementsV2` | `(accepts: x402PaymentRequirements[], payload: x402PaymentPayload) => any` | 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`. | Function | Type | | ------------------------- | ------------------------------------------------------------- | | `relaxedRequirementsToV2` | `(req: x402PaymentRequirementsV1) => x402PaymentRequirements` | ### resolveSupportedVersions Resolve and validate supported versions config. Returns resolved config with defaults applied. Throws if configuration is invalid. | Function | Type | | -------------------------- | -------------------------------------------------------------------------------------- | | `resolveSupportedVersions` | `(config?: SupportedVersionsConfig or undefined) => Required` | ### validateMiddlewareArgs Validates that CommonMiddlewareArgs has exactly one configuration mode. | Function | Type | | ------------------------ | -------------------------------------- | | `validateMiddlewareArgs` | `(args: CommonMiddlewareArgs) => void` | ### deriveCapabilities Derives `HandlerCapabilities` from relaxed v1 requirements. Used by framework adapters to construct capabilities for the HTTP wrapper from the legacy `accepts` configuration. | Function | Type | | -------------------- | --------------------------------------------------------------- | | `deriveCapabilities` | `(accepts: x402PaymentRequirementsV1[]) => HandlerCapabilities` | ### 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 }. | Function | Type | | --------------- | ---------------------------------------------------- | | `deriveSchemes` | `(accepts: x402PaymentRequirementsV1[]) => string[]` | ### deriveResourceInfo Extracts resource info from v1 accepts entries. Used by framework adapters to build the resource info for the 402 response. | Function | Type | | -------------------- | --------------------------------------------------------------------------------- | | `deriveResourceInfo` | `(accepts: x402PaymentRequirementsV1[], resourceURL: string) => x402ResourceInfo` | ### acceptsToPricing | Function | Type | | ------------------ | ------------------------------------------------------------- | | `acceptsToPricing` | `(accepts: x402PaymentRequirementsV1[]) => ResourcePricing[]` | ### 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. | Function | Type | | -------------------------- | -------------------------------------------------------------- | | `createRemoteX402Handlers` | `(args: CreateRemoteX402HandlersArgs) => FacilitatorHandler[]` | 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. | Function | Type | | --------------- | ------------------------------------------------ | | `resolveConfig` | `(args: CommonMiddlewareArgs) => ResolvedConfig` | ### resolveCapturesAt Resolves whether the body callback should capture at `/request` (one-phase) or defer to `/response` (two-phase). | `canAuthorize` | `hasAuthorize` | `pin` | `capturesAt` | | -------------- | -------------- | ------------ | ------------ | | false | any | none | `request` | | true | false | none | `request` | | true | true | none | `response` | | any | any | `"request"` | `request` | | true | any | `"response"` | `response` | `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 `:`. 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. | Function | Type | | ------------------- | --------------------------------------------------------------------------------------------- | | `resolveCapturesAt` | `(canAuthorize: boolean, hasAuthorize: boolean, pin?: CapturesAt or undefined) => CapturesAt` | ### 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. | Function | Type | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `handleMiddlewareRequest` | `(args: HandleMiddlewareRequestArgs) => Promise` | ### createMiddleware Creates Express middleware that gates routes behind x402 and MPP payment. | Function | Type | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `createMiddleware` | `(args: CommonMiddlewareArgs) => Promise<(req: Request>, res: Response<...>, next: NextFunction) => Promise<...>>` | 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. | Function | Type | | ------------------ | ------------------------------------------------------------ | | `createMiddleware` | `(args: CreateMiddlewareArgs) => Promise` | 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](#get) - [put](#put) #### get | Method | Type | | ------ | ---------------------------- | | `get` | `(key: K) => V or undefined` | #### put | Method | Type | | ------ | ---------------------------- | | `put` | `(key: K, value: V) => void` | ## Types - [AgedLRUCacheOpts](#agedlrucacheopts) - [RelaxedRequirements](#relaxedrequirements) - [RelaxedRequirementsV2](#relaxedrequirementsv2) - [SupportedVersionsConfig](#supportedversionsconfig) - [CommonMiddlewareArgs](#commonmiddlewareargs) - [CreateRemoteX402HandlersArgs](#createremotex402handlersargs) - [ResolvedConfig](#resolvedconfig) - [CaptureResultV1](#captureresultv1) - [CaptureResultV2](#captureresultv2) - [CaptureResult](#captureresult) - [AuthorizeResultV1](#authorizeresultv1) - [AuthorizeResultV2](#authorizeresultv2) - [AuthorizeResult](#authorizeresult) - [CapturesAt](#capturesat) - [PaymentPolicy](#paymentpolicy) - [MiddlewareBodyContextV1](#middlewarebodycontextv1) - [MiddlewareBodyContextV2](#middlewarebodycontextv2) - [CaptureResultMPP](#captureresultmpp) - [AuthorizeResultMPP](#authorizeresultmpp) - [MiddlewareBodyContextMPP](#middlewarebodycontextmpp) - [MiddlewareBodyContext](#middlewarebodycontext) - [HandleMiddlewareRequestArgs](#handlemiddlewarerequestargs) ### AgedLRUCacheOpts Configuration options for the AgedLRUCache. | Type | Type | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `AgedLRUCacheOpts` | `{ /** Maximum number of entries. Defaults to 256. */ capacity?: number; /** Maximum age in milliseconds before entries expire. Defaults to 30000. */ maxAge?: number; /** Custom time function for testing. Defaults to Date.now. */ now?: () => number; }` | ### RelaxedRequirements | Type | Type | | --------------------- | ------------------------------------ | | `RelaxedRequirements` | `Partial` | ### RelaxedRequirementsV2 | Type | Type | | ----------------------- | ---------------------------------- | | `RelaxedRequirementsV2` | `Partial` | ### SupportedVersionsConfig Configuration for which x402 protocol versions the middleware supports. At least one version must be enabled. | Type | Type | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `SupportedVersionsConfig` | `{ /** Support x402 v1 protocol (JSON body responses, X-PAYMENT header). Default: true */ x402v1?: boolean; /** Support x402 v2 protocol (PAYMENT-REQUIRED header, PAYMENT-SIGNATURE header). Default: false */ x402v2?: boolean; }` | ### CommonMiddlewareArgs Common configuration arguments shared by all middleware implementations. Supports two mutually exclusive modes: in-process handlers or remote facilitator. | Type | Type | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CommonMiddlewareArgs` | `{ /** x402 handlers for in-process settlement. */ x402Handlers?: FacilitatorHandler[]; /** MPP method handlers for in-process settlement. */ mppMethodHandlers?: MPPMethodHandler[]; /** Protocol-agnostic pricing for in-process handlers. */ pricing?: ResourcePricing[]; /** URL of a remote facilitator service (backward compat). */ facilitatorURL?: string; /** Payment requirements for the remote facilitator path. */ accepts?: (RelaxedRequirements or RelaxedRequirements[])[]; /** Cache configuration for remote facilitator responses. */ cacheConfig?: AgedLRUCacheOpts and { disable?: boolean }; /** Which x402 protocol versions to support. */ supportedVersions?: SupportedVersionsConfig; }` | ### CreateRemoteX402HandlersArgs | Type | Type | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `CreateRemoteX402HandlersArgs` | `{ facilitatorURL: string; accepts: (RelaxedRequirements or RelaxedRequirements[])[]; cacheConfig?: AgedLRUCacheOpts and { disable?: boolean }; }` | ### ResolvedConfig | Type | Type | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `ResolvedConfig` | `{ handlers: FacilitatorHandler[]; pricing: ResourcePricing[]; mppHandlers: MPPMethodHandler[]; resourceInfo?: x402ResourceInfo; }` | ### 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 or CaptureResultV2` | ### 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 or AuthorizeResultV2` | ### 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. | Type | Type | | ------------ | ----------------------- | | `CapturesAt` | `request" or "response` | ### 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 `":"`: - `"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. | Type | Type | | --------------- | -------------------------------------------------------------------------- | | `PaymentPolicy` | `{ allow?: string[]; pin?: Record; }` | ### 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`. | Type | Type | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `MiddlewareBodyContextV1` | `{ protocolVersion: 1; capturesAt: CapturesAt; paymentRequirements: x402PaymentRequirementsV1; paymentPayload: x402PaymentPayloadV1; capture: () => Promise>; authorize: () => Promise>; }` | ### 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`. | Type | Type | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `MiddlewareBodyContextV2` | `{ protocolVersion: 2; capturesAt: CapturesAt; paymentRequirements: x402PaymentRequirements; paymentPayload: x402PaymentPayload; capture: () => Promise>; authorize: () => Promise>; }` | ### 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). | Type | Type | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `MiddlewareBodyContextMPP` | `{ protocolVersion: "mpp"; capturesAt: CapturesAt; credential: mppCredential; capture: () => Promise>; authorize?: or (() => Promise>) or undefined; }` | ### MiddlewareBodyContext Context provided to the middleware body handler. Use protocolVersion to discriminate between v1, v2, and mpp request types. | Type | Type | | ----------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `MiddlewareBodyContext` | ` | MiddlewareBodyContextV1 or MiddlewareBodyContextV2 or MiddlewareBodyContextMPP` | ### HandleMiddlewareRequestArgs Arguments for the core middleware request handler. Framework-specific middleware implementations adapt their request/response objects to this interface. | Type | Type | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `HandleMiddlewareRequestArgs` | `{ /** x402 handlers for in-process settlement. */ x402Handlers?: FacilitatorHandler[]; /** MPP method handlers for in-process settlement. */ mppMethodHandlers?: MPPMethodHandler[]; /** Protocol-agnostic pricing entries for the current request. */ pricing: ResourcePricing[]; /** The resource URL being accessed. */ resource: string; /** Resolved supported versions configuration. */ supportedVersions: Required; /** Function to retrieve a request header value. */ getHeader: (key: string) => string or undefined; /** Function to send a JSON response with optional headers. */ sendJSONResponse: ( status: PossibleStatusCodes, body?: PossibleJSONResponse, headers?: Record, ) => MiddlewareResponse; /** Handler function called when a valid payment is received. */ body: ( context: MiddlewareBodyContext, ) => Promise; /** Optional function to set a response header. */ setResponseHeader?: (key: string, value: string) => void; /** Optional pre-built resource info for the 402 response. */ resourceInfo?: x402ResourceInfo; /** Optional accessor for the request body (for RFC 9530 digest). */ getBody?: () => Promise; /** * Whether the matched pricing rule has an explicit `authorize`* expression (i.e. is two-phase). Drives the per-handler`capturesAt`* decision resolved before each`body`invocation. Defaults to false; * non-OpenAPI callers that have no rule shape leave this unset and * the middleware treats every request as one-phase. */ hasAuthorize?: boolean; /** * Per-operation payment policy. Restricts which schemes / methods * are advertised in the 402 challenge, rejects payments for * disallowed schemes, and threads`pin`overrides into the *`capturesAt` resolution per matched handler. */ policy?: PaymentPolicy; }` | ## Examples See working examples in the [faremeter repository](https://github.com/faremeter/faremeter/tree/main/scripts): - [Express + Solana](https://github.com/faremeter/faremeter/blob/main/scripts/solana-example/server-express.ts) - [Express + EVM](https://github.com/faremeter/faremeter/blob/main/scripts/evm-example/server-express.ts) - [Hono + Solana](https://github.com/faremeter/faremeter/blob/main/scripts/solana-example/server-hono.ts) ## Related Packages - [@faremeter/fetch](https://www.npmjs.com/package/@faremeter/fetch) - Client-side fetch wrapper - [@faremeter/info](https://www.npmjs.com/package/@faremeter/info) - Network/asset configuration helpers - [@faremeter/facilitator](https://www.npmjs.com/package/@faremeter/facilitator) - Payment facilitator service ## License LGPL-3.0-only