Faremeter API

---

Faremeter API / middleware/src / common

​

common

​

Type Aliases

​

CommonMiddlewareArgs

CommonMiddlewareArgs = object

Defined in: packages/middleware/src/common.ts:340 Common configuration arguments shared by all middleware implementations.

​

Properties

accepts

accepts: (RelaxedRequirements | RelaxedRequirements[])[]

Defined in: packages/middleware/src/common.ts:344 Payment requirements this endpoint accepts. Can be flat or nested arrays.

cacheConfig?

optional cacheConfig: createPaymentRequiredResponseCacheOpts

Defined in: packages/middleware/src/common.ts:346 Optional cache configuration for payment requirements responses.

facilitatorURL

facilitatorURL: string

Defined in: packages/middleware/src/common.ts:342 URL of the facilitator service.

supportedVersions?

optional supportedVersions: SupportedVersionsConfig

Defined in: packages/middleware/src/common.ts:348 Which x402 protocol versions to support.

---

​

createPaymentRequiredResponseCacheOpts

createPaymentRequiredResponseCacheOpts = AgedLRUCacheOpts & object

Defined in: packages/middleware/src/common.ts:787 Configuration options for the payment requirements response cache.

​

Type declaration

disable?

optional disable: boolean

If true, disables caching entirely.

---

​

HandleMiddlewareRequestArgs

HandleMiddlewareRequestArgs<MiddlewareResponse> = Omit<CommonMiddlewareArgs, "supportedVersions"> & object

Defined in: packages/middleware/src/common.ts:412 Arguments for the core middleware request handler. Framework-specific middleware implementations adapt their request/response objects to this interface.

​

Type declaration

body()

body: (context) => Promise<MiddlewareResponse | undefined>

Handler function called when a valid payment is received.

Parameters

context

MiddlewareBodyContext<MiddlewareResponse>

Returns

Promise<MiddlewareResponse | undefined>

fetch?

optional fetch: typeof fetch

Optional custom fetch function for facilitator requests.

getHeader()

getHeader: (key) => string | undefined

Function to retrieve a request header value.

Parameters

key

string

Returns

string | undefined

getPaymentRequiredResponse

getPaymentRequiredResponse: typeof getPaymentRequiredResponse

Function to fetch v1 payment requirements from the facilitator.

getPaymentRequiredResponseV2?

optional getPaymentRequiredResponseV2: typeof getPaymentRequiredResponseV2

Optional function to fetch v2 payment requirements from the facilitator.

resource

resource: string

The resource URL being accessed.

sendJSONResponse()

sendJSONResponse: (status, body?, headers?) => MiddlewareResponse

Function to send a JSON response with optional headers.

Parameters

status

PossibleStatusCodes

body?

PossibleJSONResponse

headers?

Record<string, string>

Returns

MiddlewareResponse

setResponseHeader()?

optional setResponseHeader: (key, value) => void

Optional function to set a response header.

Parameters

key

string

value

string

Returns

void

supportedVersions

supportedVersions: Required<SupportedVersionsConfig>

Resolved supported versions configuration.

​

Type Parameters

MiddlewareResponse

MiddlewareResponse = unknown

---

​

MiddlewareBodyContext

MiddlewareBodyContext<MiddlewareResponse> = MiddlewareBodyContextV1<MiddlewareResponse> | MiddlewareBodyContextV2<MiddlewareResponse>

Defined in: packages/middleware/src/common.ts:403 Context provided to the middleware body handler. Use protocolVersion to discriminate between v1 and v2 request types.

​

Type Parameters

MiddlewareResponse

MiddlewareResponse

---

​

MiddlewareBodyContextV1

MiddlewareBodyContextV1<MiddlewareResponse> = object

Defined in: packages/middleware/src/common.ts:379 Context provided to the middleware body handler for v1 protocol requests. Contains payment information and functions to verify or settle the payment.

​

Type Parameters

MiddlewareResponse

MiddlewareResponse

​

Properties

paymentPayload

paymentPayload: x402PaymentPayloadV1

Defined in: packages/middleware/src/common.ts:382

paymentRequirements

paymentRequirements: x402PaymentRequirementsV1

Defined in: packages/middleware/src/common.ts:381

protocolVersion

protocolVersion: 1

Defined in: packages/middleware/src/common.ts:380

settle()

settle: () => Promise<SettleResultV1<MiddlewareResponse>>

Defined in: packages/middleware/src/common.ts:383

Returns

Promise<SettleResultV1<MiddlewareResponse>>

verify()

verify: () => Promise<VerifyResultV1<MiddlewareResponse>>

Defined in: packages/middleware/src/common.ts:384

Returns

Promise<VerifyResultV1<MiddlewareResponse>>

---

​

MiddlewareBodyContextV2

MiddlewareBodyContextV2<MiddlewareResponse> = object

Defined in: packages/middleware/src/common.ts:391 Context provided to the middleware body handler for v2 protocol requests. Contains payment information and functions to verify or settle the payment.

​

Type Parameters

MiddlewareResponse

MiddlewareResponse

​

Properties

paymentPayload

paymentPayload: x402PaymentPayload

Defined in: packages/middleware/src/common.ts:394

paymentRequirements

paymentRequirements: x402PaymentRequirements

Defined in: packages/middleware/src/common.ts:393

protocolVersion

protocolVersion: 2

Defined in: packages/middleware/src/common.ts:392

settle()

settle: () => Promise<SettleResultV2<MiddlewareResponse>>

Defined in: packages/middleware/src/common.ts:395

Returns

Promise<SettleResultV2<MiddlewareResponse>>

verify()

verify: () => Promise<VerifyResultV2<MiddlewareResponse>>

Defined in: packages/middleware/src/common.ts:396

Returns

Promise<VerifyResultV2<MiddlewareResponse>>

---

​

RelaxedRequirements

RelaxedRequirements = Partial<x402PaymentRequirementsV1>

Defined in: packages/middleware/src/common.ts:154

---

​

RelaxedRequirementsV2

RelaxedRequirementsV2 = Partial<x402PaymentRequirements>

Defined in: packages/middleware/src/common.ts:155

---

​

SettleResult

SettleResult<MiddlewareResponse> = SettleResultV1<MiddlewareResponse> | SettleResultV2<MiddlewareResponse>

Defined in: packages/middleware/src/common.ts:359

​

Type Parameters

MiddlewareResponse

MiddlewareResponse

---

​

SettleResultV1

SettleResultV1<MiddlewareResponse> = { facilitatorResponse: x402SettleResponseV1; success: true; } | { errorResponse: MiddlewareResponse; success: false; }

Defined in: packages/middleware/src/common.ts:351

​

Type Parameters

MiddlewareResponse

MiddlewareResponse

---

​

SettleResultV2

SettleResultV2<MiddlewareResponse> = { facilitatorResponse: x402SettleResponse; success: true; } | { errorResponse: MiddlewareResponse; success: false; }

Defined in: packages/middleware/src/common.ts:355

​

Type Parameters

MiddlewareResponse

MiddlewareResponse

---

​

SupportedVersionsConfig

SupportedVersionsConfig = object

Defined in: packages/middleware/src/common.ts:308 Configuration for which x402 protocol versions the middleware supports. At least one version must be enabled.

​

Properties

x402v1?

optional x402v1: boolean

Defined in: packages/middleware/src/common.ts:310 Support x402 v1 protocol (JSON body responses, X-PAYMENT header). Default: true

x402v2?

optional x402v2: boolean

Defined in: packages/middleware/src/common.ts:312 Support x402 v2 protocol (PAYMENT-REQUIRED header, PAYMENT-SIGNATURE header). Default: false

---

​

VerifyResult

VerifyResult<MiddlewareResponse> = VerifyResultV1<MiddlewareResponse> | VerifyResultV2<MiddlewareResponse>

Defined in: packages/middleware/src/common.ts:371

​

Type Parameters

MiddlewareResponse

MiddlewareResponse

---

​

VerifyResultV1

VerifyResultV1<MiddlewareResponse> = { facilitatorResponse: x402VerifyResponseV1; success: true; } | { errorResponse: MiddlewareResponse; success: false; }

Defined in: packages/middleware/src/common.ts:363

​

Type Parameters

MiddlewareResponse

MiddlewareResponse

---

​

VerifyResultV2

VerifyResultV2<MiddlewareResponse> = { facilitatorResponse: x402VerifyResponse; success: true; } | { errorResponse: MiddlewareResponse; success: false; }

Defined in: packages/middleware/src/common.ts:367

​

Type Parameters

MiddlewareResponse

MiddlewareResponse

​

Functions

​

createPaymentRequiredResponseCache()

createPaymentRequiredResponseCache(opts): object

Defined in: packages/middleware/src/common.ts:801 Creates a cached wrapper around payment requirements fetching functions. The cache reduces load on the facilitator by reusing recent responses for identical requirements.

​

Parameters

opts

createPaymentRequiredResponseCacheOpts = {} Cache configuration options

​

Returns

Object containing cached getPaymentRequiredResponse functions

getPaymentRequiredResponse()

getPaymentRequiredResponse: (args) => Promise<{ accepts: object[]; error: string; x402Version: number; }>

Fetches v1 payment requirements from the facilitator’s /accepts endpoint.

Parameters

args

getPaymentRequiredResponseArgs Arguments including facilitator URL and accepted payment types

Returns

Promise<{ accepts: object[]; error: string; x402Version: number; }> The validated payment required response from the facilitator

getPaymentRequiredResponseV2()

getPaymentRequiredResponseV2: (args) => Promise<{ accepts: object[]; error?: string; extensions?: object; resource: { description?: string; mimeType?: string; url: string; }; x402Version: 2; }>

Fetches v2 payment requirements from the facilitator’s /accepts endpoint.

Parameters

args

getPaymentRequiredResponseV2Args Arguments including facilitator URL, resource info, and accepted payment types

Returns

Promise<{ accepts: object[]; error?: string; extensions?: object; resource: { description?: string; mimeType?: string; url: string; }; x402Version: 2; }> The validated v2 payment required response from the facilitator

---

​

findMatchingPaymentRequirements()

findMatchingPaymentRequirements(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; }

Defined in: packages/middleware/src/common.ts:117 Finds the payment requirement that matches the client’s v1 payment payload.

​

Parameters

accepts

object[] Array of accepted payment requirements from the facilitator

payload

The client’s payment payload

asset?

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(accepts, payload): undefined | { amount: string; asset: string; extra?: object; maxTimeoutSeconds: number; network: string; payTo: string; scheme: string; }

Defined in: packages/middleware/src/common.ts:131 Finds the payment requirement that matches the client’s v2 payment payload.

​

Parameters

accepts

object[] Array of accepted payment requirements from the facilitator

payload

The client’s v2 payment payload

accepted

{ 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

---

​

gateGetPaymentRequiredResponse()

gateGetPaymentRequiredResponse(res): void

Defined in: packages/middleware/src/common.ts:143 Validates that a facilitator response is successful, throwing if not.

​

Parameters

res

Response The Response from the facilitator

​

Returns

void

---

​

getPaymentRequiredResponse()

getPaymentRequiredResponse(args): Promise<{ accepts: object[]; error: string; x402Version: number; }>

Defined in: packages/middleware/src/common.ts:222 Fetches v1 payment requirements from the facilitator’s /accepts endpoint.

​

Parameters

args

getPaymentRequiredResponseArgs Arguments including facilitator URL and accepted payment types

​

Returns

Promise<{ accepts: object[]; error: string; x402Version: number; }> The validated payment required response from the facilitator

---

​

getPaymentRequiredResponseV2()

getPaymentRequiredResponseV2(args): Promise<{ accepts: object[]; error?: string; extensions?: object; resource: { description?: string; mimeType?: string; url: string; }; x402Version: 2; }>

Defined in: packages/middleware/src/common.ts:270 Fetches v2 payment requirements from the facilitator’s /accepts endpoint.

​

Parameters

args

getPaymentRequiredResponseV2Args Arguments including facilitator URL, resource info, and accepted payment types

​

Returns

Promise<{ accepts: object[]; error?: string; extensions?: object; resource: { description?: string; mimeType?: string; url: string; }; x402Version: 2; }> The validated v2 payment required response from the facilitator

---

​

handleMiddlewareRequest()

handleMiddlewareRequest<MiddlewareResponse>(args): Promise<undefined | MiddlewareResponse>

Defined in: packages/middleware/src/common.ts:452 Core middleware request handler that processes x402 payment flows. This function handles both v1 and v2 protocol versions, validates payment headers, communicates with the facilitator, and delegates to the body handler when payment is valid.

​

Type Parameters

MiddlewareResponse

MiddlewareResponse

​

Parameters

args

HandleMiddlewareRequestArgs<MiddlewareResponse> Handler arguments including framework-specific adapters

​

Returns

Promise<undefined | MiddlewareResponse> The middleware response, or undefined if the body handler should continue

---

​

resolveSupportedVersions()

resolveSupportedVersions(config?): Required<SupportedVersionsConfig>

Defined in: packages/middleware/src/common.ts:320 Resolve and validate supported versions config. Returns resolved config with defaults applied. Throws if configuration is invalid.

​

Parameters

config?

SupportedVersionsConfig

​

Returns

Required<SupportedVersionsConfig>