WrapFetchParams

Defined in: src/x402/fetch.ts:51

Parameters for wrapFetch.

Properties

fetch?

readonly optional fetch?: X402Fetch

Defined in: src/x402/fetch.ts:60

Optional underlying fetch implementation. Defaults to globalThis.fetch.

---

hooks?

readonly optional hooks?: ObservabilityHooks

Defined in: src/x402/fetch.ts:95

Optional observability callbacks. wrapFetch emits an onClientPayment event for every paywall round-trip — success when the retry returns 2xx with a PAYMENT-RESPONSE header, failure otherwise (including onPayment declining the retry).

---

idempotencyKeyFor?

readonly optional idempotencyKeyFor?: (input, requirements, paymentRequired) => string | undefined

Defined in: src/x402/fetch.ts:105

Optional mapper from a request to a reasoning-step idempotency key (M5-1). When it returns a key, the key is (a) sent as the Idempotency-Key request header so the server can deduplicate, and (b) forwarded into the signer so the EIP-3009 nonce is derived deterministically (on-chain backstop). Return undefined to fall back to today’s random-nonce behaviour. Build keys with createIdempotencyKeyBuilder from kawasekit/idempotency at the agent harness’s tool-execution boundary, where the reasoning-step intent is visible.

Parameters

input

string | URL | Request

requirements

X402PaymentRequirements

paymentRequired

X402PaymentRequiredResponse

Returns

string | undefined

---

onPayment

readonly onPayment: (requirements, paymentRequired) => boolean | Promise<boolean | undefined> | undefined

Defined in: src/x402/fetch.ts:85

Required gate invoked just before the retry request goes out. Receives the chosen requirements and the parsed 402 body so the caller can log spending, prompt the user, or enforce a budget.

Returning false aborts the retry — the original 402 is returned. Returning true (or undefined) proceeds with the signed retry.

This callback is required at the type level: a 402 retry transfers real funds, and kawasekit refuses to default to “always pay” silently. If your caller already enforces a budget elsewhere, return true explicitly — the empty function () => true is a deliberate opt-in.

See docs/THREAT_MODEL.md Threat 1.8 / §6.1.

Parameters

requirements

X402PaymentRequirements

paymentRequired

X402PaymentRequiredResponse

Returns

boolean | Promise<boolean | undefined> | undefined

---

selectRequirements?

readonly optional selectRequirements?: (accepts, response) => X402PaymentRequirements | null

Defined in: src/x402/fetch.ts:66

Optional policy for choosing one entry from the server’s accepts list. Defaults to the first entry. Return null to abort — the original 402 response is returned without retry.

Parameters

accepts

readonly X402PaymentRequirements[]

response

Response

Returns

X402PaymentRequirements | null

---

signer

readonly signer: X402PaymentSigner

Defined in: src/x402/fetch.ts:56

The signer used to produce X402PaymentPayloads when the server returns 402. Bound to one EOA.