@faremeter/fetch
HTTP fetch wrapper that automatically handles 402 Payment Required responses with the x402 protocol.
Installation
pnpm install @faremeter/fetch
Features
- Automatic 402 handling - Transparently pays and retries
- Pluggable payment handlers - Support any blockchain
- Multi-chain support - Use multiple handlers simultaneously
- Smart payer selection - Choose based on balance, cost, etc.
- Retry logic - Configurable exponential backoff
- Type-safe - Full TypeScript support
API Reference
Functions
- chooseFirstAvailable
- processPaymentRequiredResponse
- processPaymentRequiredResponseMPP
- wrap
- responseFeeder
chooseFirstAvailable
Default payer chooser that selects the first available payment execer.
| Function | Type |
|---|---|
chooseFirstAvailable | (possiblePayers: PaymentExecer[]) => PaymentExecer |
Parameters:
possiblePayers: - Array of payment execers that can handle the requirements
Returns:
The first execer in the array
processPaymentRequiredResponse
Process a 402 Payment Required response, auto-detecting v1 or v2 protocol.
| Function | Type |
|---|---|
processPaymentRequiredResponse | (ctx: RequestContext, response: Response, options: ProcessPaymentRequiredResponseOpts) => Promise<ProcessPaymentRequiredResponseResult> |
Parameters:
ctx: - Request contextresponse: - The 402 Response object (must not have been consumed)options: - Processing options including payment handlers
Returns:
Payment information including header and detected version
processPaymentRequiredResponseMPP
| Function | Type |
|---|---|
processPaymentRequiredResponseMPP | (response: Response, handlers: MPPPaymentHandler[], opts?: ProcessMPPOpts or undefined) => Promise<string or undefined> |
wrap
Wraps a fetch function with automatic x402 payment handling.
When a 402 Payment Required response is received, the wrapper automatically processes the payment requirements, executes payment via the configured handlers, and retries the request with the payment header attached.
| Function | Type |
|---|---|
wrap | (phase2Fetch: (input: RequestInfo or URL, init?: RequestInit or undefined) => Promise<Response>, options: WrapOpts) => (input: RequestInfo or URL, init?: RequestInit) => Promise<...> |
Parameters:
phase2Fetch: - The fetch function to use for the paid request (phase 2)options: - Configuration including payment handlers and retry settings
Returns:
A wrapped fetch function with the same signature as native fetch
responseFeeder
Creates a mock fetch that returns responses from a queue in order.
Each call to the returned fetch function shifts the next response from the array. Responses can be either Response objects or fetch functions for dynamic behavior.
| Function | Type |
|---|---|
responseFeeder | (responses: (Response or ((input: RequestInfo or URL, init?: RequestInit or undefined) => Promise<Response>))[]) => (input: RequestInfo or URL, init?: RequestInit or undefined) => Promise<...> |
Parameters:
responses: - Array of responses or fetch functions to return in order
Returns:
A fetch function that serves responses from the queue
WrappedFetchError
Error thrown when payment fails after exhausting all retry attempts. Contains the final 402 response for inspection.
Types
- DetectedVersion
- ProcessPaymentRequiredResponseOpts
- ProcessPaymentRequiredResponseResult
- ProcessMPPOpts
- WrapOpts
- MockFetchType
- MockResponse
DetectedVersion
| Type | Type |
|---|---|
DetectedVersion | 1 or 2 |
ProcessPaymentRequiredResponseOpts
Options for processing a 402 Payment Required response.
| Type | Type |
|---|---|
ProcessPaymentRequiredResponseOpts | { /** Payment handlers that produce execers for payment requirements. */ handlers: PaymentHandler[]; /** Optional function to select among multiple possible payers. Defaults to chooseFirstAvailable. */ payerChooser?: (execer: PaymentExecer[]) => Promise<PaymentExecer>; } |
ProcessPaymentRequiredResponseResult
Result of processing a 402 Payment Required response.
| Type | Type |
|---|---|
ProcessPaymentRequiredResponseResult | { /** The selected payment execer. */ payer: PaymentExecer; /** The result from executing the payment. */ payerResult: { payload: object }; /** The payment payload in the detected protocol version format. */ paymentPayload: x402PaymentPayload or x402PaymentPayloadV1; /** Base64-encoded payment header ready to attach to the retry request. */ paymentHeader: string; /** The detected protocol version (1 or 2). */ detectedVersion: DetectedVersion; } |
ProcessMPPOpts
Attempts to process a 402 response as an MPP challenge.
Checks for a WWW-Authenticate header with Payment challenges, then iterates handlers to find one that matches. Returns the Authorization header value on success, or undefined if no MPP challenges are present or no handler matches (allowing fallthrough to x402).
Does not consume the response body.
| Type | Type |
|---|---|
ProcessMPPOpts | { bodyDigest?: string; } |
WrapOpts
Configuration options for wrapping a fetch function with x402 payment handling.
| Type | Type |
|---|---|
WrapOpts | ProcessPaymentRequiredResponseOpts and { /** MPP payment handlers for Authorization: Payment flow. */ mppHandlers?: MPPPaymentHandler[]; /** Optional fetch function for the initial request (phase 1). Defaults to phase2Fetch. */ phase1Fetch?: typeof fetch; /** Number of retry attempts after initial failure. Defaults to 2. */ retryCount?: number; /** Initial delay between retries in milliseconds. Doubles after each attempt. Defaults to 100. */ initialRetryDelay?: number; /** If true, returns the 402 response instead of throwing on payment failure. */ returnPaymentFailure?: boolean; } |
MockFetchType
| Type | Type |
|---|---|
MockFetchType | typeof fetch |
MockResponse
| Type | Type |
|---|---|
MockResponse | Response |
Examples
See working examples in the faremeter repository:
Related Packages
- @faremeter/rides - High-level SDK
- @faremeter/payment-solana - Solana payment handler
- @faremeter/payment-evm - EVM payment handler
- @faremeter/middleware - Server-side middleware
License
LGPL-3.0-only