Extensions Overview

Extensions are the composable layer on top of x402’s core payment protocol. They let resource servers, facilitators, and clients add optional capabilities — discovery, authentication, receipts, gas sponsoring — without modifying the core payment flow.

How Extensions Work

x402 has two extension points that serve different roles in the payment flow:

Resource Server Extensions

These run on the resource server (the service accepting payments) and hook into the HTTP payment lifecycle. A ResourceServerExtension can intervene at four points:

Declaration (enrichDeclaration) — Called at route registration time. The extension can modify or narrow the route’s extension declaration based on transport context (e.g., Bazaar narrows the HTTP method).
402 Response (enrichPaymentRequiredResponse) — Called when the server returns 402 Payment Required. The extension can add data to the response (e.g., signed offers, discovery metadata).
Settlement Response (enrichSettlementResponse) — Called after successful payment. The extension can add data to the PAYMENT-RESPONSE header (e.g., signed receipts, payment identifiers).
Verify/settle lifecycle hooks (hooks) — Scoped verify and settle hooks that run only when the extension is declared on the route. These follow the same pattern as the server-level hooks (onBeforeVerify, onAfterVerify, onVerifyFailure, onBeforeSettle, onAfterSettle, onSettleFailure) but receive the extension’s declaration as a first argument.

All four points are optional. Most extensions use one or two — not all.

Facilitator Extensions

These run on the facilitator (the service that verifies and settles payments on behalf of the resource server). A FacilitatorExtension provides a key and is stored for use by mechanism implementations during verification and settlement. Gas sponsoring extensions are the primary example — they inject batch signing capabilities into the settlement flow so the facilitator can sponsor gas on behalf of the payer.

Registering an Extension (Server)

Extensions implement the ResourceServerExtension interface and are registered via registerExtension:

import { x402ResourceServer } from "@x402/express";

const resourceServer = new x402ResourceServer(facilitatorClient)
  .register("eip155:84532", new ExactEvmScheme())
  .registerExtension(myExtension)       // Add one extension
  .registerExtension(anotherExtension); // Stack another

Each extension has a unique key that identifies it in route declarations and response payloads.

The ResourceServerExtension Interface

interface ResourceServerExtension {
  /** Unique identifier for this extension */
  key: string;

  /**
   * Names of fields under the extension's `info` that are dynamic — regenerated
   * on every PaymentRequired response (e.g. nonces, timestamps) — rather than
   * static committed terms. Dynamic fields are excluded from client echo
   * validation. Defaults to none (all info fields treated as static / strict).
   */
  dynamicInfoFields?: string[];

  /** Enrich the extension declaration at route registration time */
  enrichDeclaration?: (declaration: unknown, transportContext: unknown) => unknown;

  /** Add data to the 402 PaymentRequired response */
  enrichPaymentRequiredResponse?: (
    declaration: unknown,
    context: PaymentRequiredContext,
  ) => Promise<unknown>;

  /** Add data to the settlement response after successful payment */
  enrichSettlementResponse?: (
    declaration: unknown,
    context: SettleResultContext,
  ) => Promise<unknown>;

  /**
   * Verify/settle lifecycle hooks scoped to this extension.
   * These run only when the extension is declared on the route (i.e. declaredExtensions[key] is set).
   * The extension's declaration is passed as the first argument to each hook.
   * Hook contexts are read-only for core protocol fields; use abort/recover return values instead of mutation.
   */
  hooks?: {
    onBeforeVerify?: (declaration: unknown, context: VerifyContext) => Promise<void | { abort: true; reason: string; message?: string }>;
    onAfterVerify?: (declaration: unknown, context: VerifyResultContext) => Promise<void>;
    onVerifyFailure?: (declaration: unknown, context: VerifyFailureContext) => Promise<void | { recovered: true; result: VerifyResponse }>;
    onBeforeSettle?: (declaration: unknown, context: SettleContext) => Promise<void | { abort: true; reason: string; message?: string }>;
    onAfterSettle?: (declaration: unknown, context: SettleResultContext) => Promise<void>;
    onSettleFailure?: (declaration: unknown, context: SettleFailureContext) => Promise<void | { recovered: true; result: SettleResponse }>;
  };
}

Declaring Extensions on Routes

Extensions are declared per-route in the payment middleware configuration. Each extension’s declaration goes under extensions keyed by the extension’s key:

app.use(
  paymentMiddleware(
    {
      "GET /api/data": {
        accepts: [{ scheme: "exact", price: "$0.01", network: "eip155:84532", payTo: address }],
        description: "Premium data",
        mimeType: "application/json",
        extensions: {
          // Each key matches a registered extension
          "offer-receipt": { includeTxHash: false },
          "bazaar": { /* bazaar config */ },
        },
      },
    },
    resourceServer,
  ),
);

If an extension is declared on a route but not registered on the server, it is silently ignored.

Which Hooks Do Extensions Use?

Not all extensions use the same hooks. Here’s how the built-in extensions map to the extension points:

Extension	`enrichDeclaration`	`enrichPaymentRequiredResponse`	`enrichSettlementResponse`	Facilitator
Bazaar	✅ (narrows HTTP method)	—	—	✅ (discovery cataloging)
Builder Code	—	✅ (declares app code + schema)	—	✅ (encodes ERC-8021 calldata suffix)
EIP-2612 Gas Sponsoring	—	—	—	✅ (batch signing)
ERC-20 Approval Gas Sponsoring	—	—	—	✅ (batch signing)
Payment Identifier	—	✅	✅	—
Sign-In-With-X	—	—	—	—
Signed Offers & Receipts	—	✅ (signs offers)	✅ (signs receipts)	—

Bazaar is unique in that it spans both sides: the resource server extension enriches declarations, while the facilitator component handles discovery cataloging and validation. Sign-In-With-X manages its own session lifecycle outside the standard hooks.

Available Extensions

Extension	Type	Description	SDK Support
Bazaar	Server + Facilitator	Discovery layer for x402 endpoints and MCP tools. Makes your services findable by AI agents and developers.	TypeScript, Go, Python
Builder Code	Server + Client + Facilitator	On-chain attribution tracking via ERC-8021 Schema 2. Appends CBOR-encoded builder codes to settlement transaction calldata.	TypeScript, Go, Python
EIP-2612 Gas Sponsoring	Facilitator	Sponsors gas for EIP-2612 permit-based token transfers.	TypeScript, Go, Python
ERC-20 Approval Gas Sponsoring	Facilitator	Sponsors gas for ERC-20 approval-based token transfers.	TypeScript, Go, Python
Payment Identifier	Server + Client	Attaches a unique identifier to each payment for tracking, reconciliation, and idempotency.	TypeScript, Go, Python
Sign-In-With-X	Server + Client	CAIP-122 wallet authentication. Lets clients prove wallet ownership to access previously purchased content without repaying.	TypeScript, Go, Python
Signed Offers & Receipts	Server + Client	Signs offers on 402 responses and receipts on 200 responses, producing cryptographic proof-of-interaction artifacts.	TypeScript

Building a Custom Extension

To create your own extension:

Define the extension object implementing ResourceServerExtension
Choose a unique key — this identifies your extension in route declarations and response payloads
Implement the hooks you need — enrichDeclaration, enrichPaymentRequiredResponse, enrichSettlementResponse, and/or hooks
Create a declare function — a helper that returns the route-level configuration for your extension
Register it on the x402ResourceServer via registerExtension
Submit a pull request to x402-foundation/x402 — extensions must be reviewed and approved by the x402 maintainers before they are included in the SDK

Here’s a minimal example:

import type { ResourceServerExtension } from "@x402/core";

const myExtension: ResourceServerExtension = {
  key: "my-extension",

  // Mark fields that are regenerated on every 402 response so they are
  // excluded from client echo validation (extension_echo_mismatch check).
  // Omit this property when all info fields are static committed terms.
  dynamicInfoFields: ["timestamp"],

  enrichPaymentRequiredResponse: async (declaration, context) => {
    // Add custom data to the 402 response
    return { info: { customField: "value", timestamp: Date.now() } };
  },

  enrichSettlementResponse: async (declaration, context) => {
    // Add custom data after successful payment
    return { settled: true, processedAt: Date.now() };
  },

  hooks: {
    // Runs only when this extension is declared on the route
    onAfterSettle: async (declaration, context) => {
      // declaration is the per-route config for this extension
      // context.result, context.requirements, etc. are read-only
      await auditLog.record({
        extensionConfig: declaration,
        payer: context.result.payer,
        transaction: context.result.transaction,
      });
    },
  },
};

// Declare helper for route config
function declareMyExtension(config: { customOption: boolean }) {
  return { "my-extension": config };
}

The data returned from enrichPaymentRequiredResponse and enrichSettlementResponse is included in the response under extensions["my-extension"]. The hooks callbacks run as part of the server’s verify/settle lifecycle but only when the extension is active on the route.

Welcome

Getting Started

Core Concepts

Payment Schemes

Extensions

Advanced Concepts

Guides

Developer Tools

SDK Features

Extensions Overview

How Extensions Work

Resource Server Extensions

Facilitator Extensions

Registering an Extension (Server)

The ResourceServerExtension Interface

Declaring Extensions on Routes

Which Hooks Do Extensions Use?

Available Extensions

Building a Custom Extension

Further Reading

​How Extensions Work

​Resource Server Extensions

​Facilitator Extensions

​Registering an Extension (Server)

​The ResourceServerExtension Interface

​Declaring Extensions on Routes

​Which Hooks Do Extensions Use?

​Available Extensions

​Building a Custom Extension

​Further Reading

How Extensions Work

Resource Server Extensions

Facilitator Extensions

Registering an Extension (Server)

The ResourceServerExtension Interface

Declaring Extensions on Routes

Which Hooks Do Extensions Use?

Available Extensions

Building a Custom Extension

Further Reading