common
Type Aliases
AuthorizeResult
AuthorizeResult<Defined in: packages/middleware/src/common.ts:500MiddlewareResponse> =AuthorizeResultV1<MiddlewareResponse> |AuthorizeResultV2<MiddlewareResponse>
Type Parameters
MiddlewareResponse
MiddlewareResponse
AuthorizeResultMPP
AuthorizeResultMPP<Defined in: packages/middleware/src/common.ts:634MiddlewareResponse> = {receipt:mppReceipt;success:true; } | {errorMessage?:string;errorResponse:MiddlewareResponse;success:false; }
Type Parameters
MiddlewareResponse
MiddlewareResponse
AuthorizeResultV1
AuthorizeResultV1<Defined in: packages/middleware/src/common.ts:484MiddlewareResponse> = {response:x402VerifyResponseV1;success:true; } | {errorMessage?:string;errorResponse:MiddlewareResponse;success:false; }
Type Parameters
MiddlewareResponse
MiddlewareResponse
AuthorizeResultV2
AuthorizeResultV2<Defined in: packages/middleware/src/common.ts:492MiddlewareResponse> = {response:x402VerifyResponse;success:true; } | {errorMessage?:string;errorResponse:MiddlewareResponse;success:false; }
Type Parameters
MiddlewareResponse
MiddlewareResponse
CaptureResult
CaptureResult<Defined in: packages/middleware/src/common.ts:480MiddlewareResponse> =CaptureResultV1<MiddlewareResponse> |CaptureResultV2<MiddlewareResponse>
Type Parameters
MiddlewareResponse
MiddlewareResponse
CaptureResultMPP
CaptureResultMPP<Defined in: packages/middleware/src/common.ts:626MiddlewareResponse> = {receipt:mppReceipt;success:true; } | {errorMessage?:string;errorResponse:MiddlewareResponse;success:false; }
Type Parameters
MiddlewareResponse
MiddlewareResponse
CaptureResultV1
CaptureResultV1<Defined in: packages/middleware/src/common.ts:464MiddlewareResponse> = {response:x402SettleResponseV1;success:true; } | {errorMessage?:string;errorResponse:MiddlewareResponse;success:false; }
Type Parameters
MiddlewareResponse
MiddlewareResponse
CaptureResultV2
CaptureResultV2<Defined in: packages/middleware/src/common.ts:472MiddlewareResponse> = {response:x402SettleResponse;success:true; } | {errorMessage?:string;errorResponse:MiddlewareResponse;success:false; }
Type Parameters
MiddlewareResponse
MiddlewareResponse
CapturesAt
CapturesAt =Defined in: packages/middleware/src/common.ts:519 When the body callback should drive capture."request"|"response"
"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 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.
CommonMiddlewareArgs
CommonMiddlewareArgs = object
Defined in: packages/middleware/src/common.ts:271
Common configuration arguments shared by all middleware implementations.
Supports two mutually exclusive modes: in-process handlers or remote facilitator.
Properties
accepts?
Defined in: packages/middleware/src/common.ts:282 Payment requirements for the remote facilitator path.optionalaccepts: (RelaxedRequirements|RelaxedRequirements[])[]
cacheConfig?
Defined in: packages/middleware/src/common.ts:284 Cache configuration for remote facilitator responses.optionalcacheConfig:AgedLRUCacheOpts&object
Type declaration
disable?
optionaldisable:boolean
facilitatorURL?
Defined in: packages/middleware/src/common.ts:280 URL of a remote facilitator service (backward compat).optionalfacilitatorURL:string
mppMethodHandlers?
Defined in: packages/middleware/src/common.ts:275 MPP method handlers for in-process settlement.optionalmppMethodHandlers:MPPMethodHandler[]
pricing?
Defined in: packages/middleware/src/common.ts:277 Protocol-agnostic pricing for in-process handlers.optionalpricing:ResourcePricing[]
supportedVersions?
Defined in: packages/middleware/src/common.ts:287 Which x402 protocol versions to support.optionalsupportedVersions:SupportedVersionsConfig
x402Handlers?
Defined in: packages/middleware/src/common.ts:273 x402 handlers for in-process settlement.optionalx402Handlers:FacilitatorHandler[]
CreateRemoteX402HandlersArgs
CreateRemoteX402HandlersArgs = object
Defined in: packages/middleware/src/common.ts:392
Properties
accepts
accepts: (Defined in: packages/middleware/src/common.ts:394RelaxedRequirements|RelaxedRequirements[])[]
cacheConfig?
Defined in: packages/middleware/src/common.ts:395optionalcacheConfig:AgedLRUCacheOpts&object
Type declaration
disable?
optionaldisable:boolean
facilitatorURL
facilitatorURL: string
Defined in: packages/middleware/src/common.ts:393
HandleMiddlewareRequestArgs
HandleMiddlewareRequestArgs<Defined in: packages/middleware/src/common.ts:674 Arguments for the core middleware request handler. Framework-specific middleware implementations adapt their request/response objects to this interface.MiddlewareResponse> =object
Type Parameters
MiddlewareResponse
MiddlewareResponse = unknown
Properties
body()
body: (Defined in: packages/middleware/src/common.ts:694 Handler function called when a valid payment is received.context) =>Promise<MiddlewareResponse|undefined>
Parameters
context
MiddlewareBodyContext<MiddlewareResponse>
Returns
Promise<MiddlewareResponse | undefined>
getBody()?
Defined in: packages/middleware/src/common.ts:702 Optional accessor for the request body (for RFC 9530 digest).optionalgetBody: () =>Promise<ArrayBuffer|null>
Returns
Promise<ArrayBuffer | null>
getHeader()
getHeader: (Defined in: packages/middleware/src/common.ts:686 Function to retrieve a request header value.key) =>string|undefined
Parameters
key
string
Returns
string | undefined
hasAuthorize?
Defined in: packages/middleware/src/common.ts:710 Whether the matched pricing rule has an explicitoptionalhasAuthorize:boolean
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.
mppMethodHandlers?
Defined in: packages/middleware/src/common.ts:678 MPP method handlers for in-process settlement.optionalmppMethodHandlers:MPPMethodHandler[]
policy?
Defined in: packages/middleware/src/common.ts:717 Per-operation payment policy. Restricts which schemes / methods are advertised in the 402 challenge, rejects payments for disallowed schemes, and threadsoptionalpolicy:PaymentPolicy
pin overrides into the
capturesAt resolution per matched handler.
pricing
pricing: ResourcePricing[]
Defined in: packages/middleware/src/common.ts:680
Protocol-agnostic pricing entries for the current request.
resource
resource: string
Defined in: packages/middleware/src/common.ts:682
The resource URL being accessed.
resourceInfo?
Defined in: packages/middleware/src/common.ts:700 Optional pre-built resource info for the 402 response.optionalresourceInfo:x402ResourceInfo
sendJSONResponse()
sendJSONResponse: (Defined in: packages/middleware/src/common.ts:688 Function to send a JSON response with optional headers.status,body?,headers?) =>MiddlewareResponse
Parameters
status
PossibleStatusCodes
body?
PossibleJSONResponse
headers?
Record<string, string>
Returns
MiddlewareResponse
setResponseHeader()?
Defined in: packages/middleware/src/common.ts:698 Optional function to set a response header.optionalsetResponseHeader: (key,value) =>void
Parameters
key
string
value
string
Returns
void
supportedVersions
supportedVersions:Defined in: packages/middleware/src/common.ts:684 Resolved supported versions configuration.Required<SupportedVersionsConfig>
x402Handlers?
Defined in: packages/middleware/src/common.ts:676 x402 handlers for in-process settlement.optionalx402Handlers:FacilitatorHandler[]
MiddlewareBodyContext
MiddlewareBodyContext<Defined in: packages/middleware/src/common.ts:664 Context provided to the middleware body handler. Use protocolVersion to discriminate between v1, v2, and mpp request types.MiddlewareResponse> =MiddlewareBodyContextV1<MiddlewareResponse> |MiddlewareBodyContextV2<MiddlewareResponse> |MiddlewareBodyContextMPP<MiddlewareResponse>
Type Parameters
MiddlewareResponse
MiddlewareResponse
MiddlewareBodyContextMPP
MiddlewareBodyContextMPP<Defined in: packages/middleware/src/common.ts:650 Context provided to the middleware body handler for MPP protocol requests.MiddlewareResponse> =object
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 Parameters
MiddlewareResponse
MiddlewareResponse
Properties
authorize()?
Defined in: packages/middleware/src/common.ts:655optionalauthorize: () =>Promise<AuthorizeResultMPP<MiddlewareResponse>>
Returns
Promise<AuthorizeResultMPP<MiddlewareResponse>>
capture()
capture: () =>Defined in: packages/middleware/src/common.ts:654Promise<CaptureResultMPP<MiddlewareResponse>>
Returns
Promise<CaptureResultMPP<MiddlewareResponse>>
capturesAt
capturesAt: CapturesAt
Defined in: packages/middleware/src/common.ts:652
credential
credential: mppCredential
Defined in: packages/middleware/src/common.ts:653
protocolVersion
protocolVersion: "mpp"
Defined in: packages/middleware/src/common.ts:651
MiddlewareBodyContextV1
MiddlewareBodyContextV1<Defined in: packages/middleware/src/common.ts:602 Context provided to the middleware body handler for v1 protocol requests. Contains payment information and the industry-standardMiddlewareResponse> =object
authorize /
capture operations. Under the hood these dispatch to the matched
x402 facilitator handler’s handleVerify / handleSettle.
Type Parameters
MiddlewareResponse
MiddlewareResponse
Properties
authorize()
authorize: () =>Defined in: packages/middleware/src/common.ts:608Promise<AuthorizeResultV1<MiddlewareResponse>>
Returns
Promise<AuthorizeResultV1<MiddlewareResponse>>
capture()
capture: () =>Defined in: packages/middleware/src/common.ts:607Promise<CaptureResultV1<MiddlewareResponse>>
Returns
Promise<CaptureResultV1<MiddlewareResponse>>
capturesAt
capturesAt: CapturesAt
Defined in: packages/middleware/src/common.ts:604
paymentPayload
paymentPayload: x402PaymentPayloadV1
Defined in: packages/middleware/src/common.ts:606
paymentRequirements
paymentRequirements: x402PaymentRequirementsV1
Defined in: packages/middleware/src/common.ts:605
protocolVersion
protocolVersion: 1
Defined in: packages/middleware/src/common.ts:603
MiddlewareBodyContextV2
MiddlewareBodyContextV2<Defined in: packages/middleware/src/common.ts:617 Context provided to the middleware body handler for v2 protocol requests. Contains payment information and the industry-standardMiddlewareResponse> =object
authorize /
capture operations. Under the hood these dispatch to the matched
x402 facilitator handler’s handleVerify / handleSettle.
Type Parameters
MiddlewareResponse
MiddlewareResponse
Properties
authorize()
authorize: () =>Defined in: packages/middleware/src/common.ts:623Promise<AuthorizeResultV2<MiddlewareResponse>>
Returns
Promise<AuthorizeResultV2<MiddlewareResponse>>
capture()
capture: () =>Defined in: packages/middleware/src/common.ts:622Promise<CaptureResultV2<MiddlewareResponse>>
Returns
Promise<CaptureResultV2<MiddlewareResponse>>
capturesAt
capturesAt: CapturesAt
Defined in: packages/middleware/src/common.ts:619
paymentPayload
paymentPayload: x402PaymentPayload
Defined in: packages/middleware/src/common.ts:621
paymentRequirements
paymentRequirements: x402PaymentRequirements
Defined in: packages/middleware/src/common.ts:620
protocolVersion
protocolVersion: 2
Defined in: packages/middleware/src/common.ts:618
PaymentPolicy
PaymentPolicy = object
Defined in: packages/middleware/src/common.ts:545
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
"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.
Properties
allow?
Defined in: packages/middleware/src/common.ts:546optionalallow:string[]
pin?
Defined in: packages/middleware/src/common.ts:547optionalpin:Record<string, {capturesAt?:CapturesAt; }>
RelaxedRequirements
RelaxedRequirements =Defined in: packages/middleware/src/common.ts:171Partial<x402PaymentRequirementsV1>
RelaxedRequirementsV2
RelaxedRequirementsV2 =Defined in: packages/middleware/src/common.ts:172Partial<x402PaymentRequirements>
ResolvedConfig
ResolvedConfig = object
Defined in: packages/middleware/src/common.ts:423
Properties
handlers
handlers: FacilitatorHandler[]
Defined in: packages/middleware/src/common.ts:424
mppHandlers
mppHandlers: MPPMethodHandler[]
Defined in: packages/middleware/src/common.ts:426
pricing
pricing: ResourcePricing[]
Defined in: packages/middleware/src/common.ts:425
resourceInfo?
Defined in: packages/middleware/src/common.ts:427optionalresourceInfo:x402ResourceInfo
SupportedVersionsConfig
SupportedVersionsConfig = object
Defined in: packages/middleware/src/common.ts:238
Configuration for which x402 protocol versions the middleware supports.
At least one version must be enabled.
Properties
x402v1?
Defined in: packages/middleware/src/common.ts:240 Support x402 v1 protocol (JSON body responses, X-PAYMENT header). Default: trueoptionalx402v1:boolean
x402v2?
Defined in: packages/middleware/src/common.ts:242 Support x402 v2 protocol (PAYMENT-REQUIRED header, PAYMENT-SIGNATURE header). Default: falseoptionalx402v2:boolean
Functions
acceptsToPricing()
acceptsToPricing(Defined in: packages/middleware/src/common.ts:377accepts):ResourcePricing[]
Parameters
accepts
Partial<{ asset: string; description: string; extra?: object; maxAmountRequired: string; maxTimeoutSeconds: number; mimeType?: string; network: string; outputSchema?: object; payTo: string; resource: string; scheme: string; }>[]
Returns
ResourcePricing[]
createRemoteX402Handlers()
createRemoteX402Handlers(Defined in: packages/middleware/src/common.ts:409 Creates x402 facilitator handlers backed by a remote HTTP facilitator. This is the composable equivalent of theargs):FacilitatorHandler[]
facilitatorURL + accepts
shorthand on CommonMiddlewareArgs. Use it when you need to
combine a remote x402 facilitator with in-process MPP handlers in the
same middleware.
Parameters
args
CreateRemoteX402HandlersArgs
Returns
FacilitatorHandler[]
An array of FacilitatorHandler suitable for
createMiddleware({ x402Handlers: ... }).
deriveCapabilities()
deriveCapabilities(Defined in: packages/middleware/src/common.ts:328 Derivesaccepts):HandlerCapabilities
HandlerCapabilities from relaxed v1 requirements.
Used by framework adapters to construct capabilities for the HTTP wrapper
from the legacy accepts configuration.
Parameters
accepts
Partial<{ asset: string; description: string; extra?: object; maxAmountRequired: string; maxTimeoutSeconds: number; mimeType?: string; network: string; outputSchema?: object; payTo: string; resource: string; scheme: string; }>[]
Returns
HandlerCapabilities
deriveResourceInfo()
deriveResourceInfo(Defined in: packages/middleware/src/common.ts:364 Extracts resource info from v1 accepts entries. Used by framework adapters to build the resource info for the 402 response.accepts,resourceURL):object
Parameters
accepts
Partial<{ asset: string; description: string; extra?: object; maxAmountRequired: string; maxTimeoutSeconds: number; mimeType?: string; network: string; outputSchema?: object; payTo: string; resource: string; scheme: string; }>[]
resourceURL
string
Returns
object
description?
optionaldescription:string
mimeType?
optionalmimeType:string
url
url: string
deriveSchemes()
deriveSchemes(Defined in: packages/middleware/src/common.ts:352 Derives the distinct set of x402 schemes from relaxed v1 requirements. Sibling of deriveCapabilities; kept separate because schemes are x402-specific and live on the handler rather than on HandlerCapabilities.accepts):string[]
Parameters
accepts
Partial<{ asset: string; description: string; extra?: object; maxAmountRequired: string; maxTimeoutSeconds: number; mimeType?: string; network: string; outputSchema?: object; payTo: string; resource: string; scheme: string; }>[]
Returns
string[]
findMatchingPaymentRequirements()
findMatchingPaymentRequirements(Defined in: packages/middleware/src/common.ts:150 Finds the payment requirement that matches the client’s v1 payment payload.accepts,payload):undefined| {asset:string;description:string;extra?:object;maxAmountRequired:string;maxTimeoutSeconds:number;mimeType?:string;network:string;outputSchema?:object;payTo:string;resource:string;scheme:string; }
Parameters
accepts
object[]
Array of accepted payment requirements from the facilitator
payload
The client’s payment payloadasset?
string
network
string
payload
object
scheme
string
x402Version
number
Returns
undefined | { asset: string; description: string; extra?: object; maxAmountRequired: string; maxTimeoutSeconds: number; mimeType?: string; network: string; outputSchema?: object; payTo: string; resource: string; scheme: string; }
The matching requirement, or undefined if no match found
findMatchingPaymentRequirementsV2()
findMatchingPaymentRequirementsV2(Defined in: packages/middleware/src/common.ts:164 Finds the payment requirement that matches the client’s v2 payment payload.accepts,payload):undefined| {amount:string;asset:string;extra?:object;maxTimeoutSeconds:number;network:string;payTo:string;scheme:string; }
Parameters
accepts
object[]
Array of accepted payment requirements from the facilitator
payload
The client’s v2 payment payloadaccepted
{amount: string; asset: string; extra?: object; maxTimeoutSeconds: number; network: string; payTo: string; scheme: string; }
accepted.amount
string
accepted.asset
string
accepted.extra?
object
accepted.maxTimeoutSeconds
number
accepted.network
string
accepted.payTo
string
accepted.scheme
string
extensions?
object
payload
object
resource?
{description?: string; mimeType?: string; url: string; }
resource.description?
string
resource.mimeType?
string
resource.url
string
x402Version
2
Returns
undefined | { amount: string; asset: string; extra?: object; maxTimeoutSeconds: number; network: string; payTo: string; scheme: string; }
The matching requirement, or undefined if no match found
handleMiddlewareRequest()
handleMiddlewareRequest<Defined in: packages/middleware/src/common.ts:771 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.MiddlewareResponse>(args):Promise<undefined|MiddlewareResponse>
Type Parameters
MiddlewareResponse
MiddlewareResponse
Parameters
args
HandleMiddlewareRequestArgs<MiddlewareResponse>
Returns
Promise<undefined | MiddlewareResponse>
relaxedRequirementsToV2()
relaxedRequirementsToV2(Defined in: packages/middleware/src/common.ts:178 Converts v1 relaxed requirements to v2 format, preserving all fields includingreq):Partial
extra.
Parameters
req
Partial
Returns
Partial
resolveCapturesAt()
resolveCapturesAt(Defined in: packages/middleware/src/common.ts:753 Resolves whether the body callback should capture atcanAuthorize,hasAuthorize,pin?):CapturesAt
/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.
Parameters
canAuthorize
boolean
hasAuthorize
boolean
pin?
CapturesAt
Returns
CapturesAt
resolveConfig()
resolveConfig(Defined in: packages/middleware/src/common.ts:435 Resolves CommonMiddlewareArgs into the handlers + pricing tuple that handleMiddlewareRequest needs. For theargs):ResolvedConfig
facilitatorURL path,
creates an HTTP handler wrapper and converts accepts to pricing.
Parameters
args
CommonMiddlewareArgs
Returns
ResolvedConfig
resolveSupportedVersions()
resolveSupportedVersions(Defined in: packages/middleware/src/common.ts:250 Resolve and validate supported versions config. Returns resolved config with defaults applied. Throws if configuration is invalid.config?):Required<SupportedVersionsConfig>
Parameters
config?
SupportedVersionsConfig
Returns
Required<SupportedVersionsConfig>
validateMiddlewareArgs()
validateMiddlewareArgs(Defined in: packages/middleware/src/common.ts:293 Validates that CommonMiddlewareArgs has exactly one configuration mode.args):void
Parameters
args
CommonMiddlewareArgs
Returns
void