x402z-server

Server-side helpers for erc7984-mind-v1 and exact x402 schemes.

Install

pnpm add x402z-server

Folder map

• src/http/: server HTTP helpers
• src/scheme/: scheme implementation + registration
• src/index.ts: public exports

Usage

import {
  buildAcceptsFromConfigs,
  buildConfidentialServerConfigFromSchemeConfig,
  createX402zServer,
} from "x402z-server";
import { SCHEME_CONFIG } from "x402z-scheme-config";
import { createRelayer, SepoliaConfig } from "x402z-shared";

const relayer = await createRelayer({
  ...SepoliaConfig,
  network: "https://sepolia.infura.io/v3/...",
});

const allowedPayments = [
  {
    method: "exact.USDC.base",
    payTo: "0xPayTo",
    price: "$0.01",
  },
  {
    method: SCHEME_CONFIG["erc7984-mind-v1"].CONFIDENTIAL_USDC.sepolia,
    payTo: "0xPayTo",
    price: "1.0",
    maxTimeoutSeconds: 300,
  },
] as const;

const confidentialEntry = SCHEME_CONFIG["erc7984-mind-v1"].CONFIDENTIAL_USDC.sepolia;

const server = await createX402zServer({
  facilitatorUrl: "http://localhost:8040",
  confidential: buildConfidentialServerConfigFromSchemeConfig({
    config: confidentialEntry,
    signer: { address, signTypedData },
    relayer,
  }),
  routes: {
    "GET /demo": {
      accepts: buildAcceptsFromConfigs(allowedPayments),
      description: "Demo content",
      mimeType: "text/plain",
      onPaid: async () => ({
        body: "demo content from server",
      }),
    },
  },
});

server.listen(8080);

API

• createX402zServer(config)
  • facilitatorUrl (required): HTTP facilitator endpoint
• confidential (optional): confidential scheme config (required if any route uses erc7984-mind-v1)
• confidential.signer: signer used to decrypt transfer amounts
• confidential.relayer: FHEVM relayer instance used for decryption
• routes: map of METHOD /path to payment requirements
• routes["METHOD /path"].onRequest: optional pre-payment hook; return a response to short-circuit
• routes["METHOD /path"].onPaid: handler for successful payment (returns response body + optional headers)
  • onPaid receives { paymentRequirements, settleHeaders, request }
  • request includes method, path, url, and normalized headers

Examples

See examples/README.md for the full-process server + facilitator setup.

Exact scheme (ERC20) usage

import { createX402zServer } from "x402z-server";

const server = await createX402zServer({
  facilitatorUrl: "http://localhost:8040",
  routes: {
    "GET /erc20-demo": {
      accepts: [
        {
          scheme: "exact",
          payTo: "0xYourAddress",
          price: "$0.01",
          network: "eip155:84532",
        },
      ],
      description: "Exact USDC payment demo",
      mimeType: "text/plain",
      onPaid: async () => ({ body: "paid content" }),
    },
  },
});

server.listen(8090);

Choosing Payment Methods (Server)

Server routes accept an ordered list of payment methods, each paired with its own payTo and price.

You can specify methods in two ways:

1. Name string (scheme + token + network alias):

const method = "exact.USDC.base";

2. Config entry (from SCHEME_CONFIG):

const method = SCHEME_CONFIG.exact.USDC.base;

Build your accepts array from these entries:

const accepts = buildAcceptsFromConfigs([
  { method: "exact.USDC.base", payTo, price: "$0.01" },
  { method: SCHEME_CONFIG["erc7984-mind-v1"].CONFIDENTIAL_USDC.sepolia, payTo, price: "1.0" },
]);

Notes

• Confidential scheme name: erc7984-mind-v1
• Exact scheme name: exact
• confidential.batcherAddress is required in requirements; clients bind encrypted inputs to it.
• Scheme defaults are exported as SCHEME_CONFIG from x402z-scheme-config (and re-exported by x402z-server). Keys are scheme -> token -> networkAlias (e.g., SCHEME_CONFIG.exact.USDC.base).
• You can also refer to a method by its string name (e.g., exact.USDC.base). A full list is available as SCHEME_CONFIG_NAMES.

Choosing Schemes/Networks

Select supported methods using SCHEME_CONFIG entries in your server code. Pair each entry with its own payTo and price.

Scheme Naming Guidance

• Use a single scheme name when the payment flow is identical and only the asset changes (for example, multiple ERC-20 tokens using the exact same exact-scheme logic).
• Introduce a new scheme name only when the payment flow differs (for example, different contract method, different typed data, or different authorization logic).

API surface

Exports:

• X402zEvmServerScheme: server scheme implementation for erc7984-mind-v1.
• registerX402zEvmServerScheme: registers the scheme with x402 server.
• createX402zServer: helper to configure the paywalled server.
• buildExactAccept, buildConfidentialAccept, buildConfidentialServerConfig: helpers to construct accept items and confidential config.
• buildAcceptsFromConfigs: build accepts from SCHEME_CONFIG entries paired with payTo/price.
• SCHEME_CONFIG: full scheme/token/network config (addresses, network, decimals, EIP-712, batcher). Source of truth lives in x402z-scheme-config.
• buildConfidentialServerConfigFromSchemeConfig: build confidential server config from a SCHEME_CONFIG entry.
• SCHEME_CONFIG_NAMES: all supported method names as strings (e.g., exact.USDC.base).
• getSchemeConfigByName: resolve a method name string to its config entry.
• x402ResourceServer: core x402 resource server.
• HTTPFacilitatorClient: HTTP facilitator client wrapper.
• x402HTTPResourceServer: HTTP resource server helpers.

Types:

• X402zServerSchemeOptions: scheme config for server registration.
• X402zServerNetworkOptions: network config for the scheme.
• X402zServerRegistrationOptions: registration options for the scheme.
• X402zRouteOptions: route config for paywalled endpoints.
• X402zRouteAccept: accept config item for confidential or exact schemes.
• X402zRouteHandler: handler signature for paid requests.
• X402zServerOptions: options for createX402zServer.
• X402zConfidentialServerConfig: options for confidential server config.
• CompiledRoute: compiled route metadata.
• DynamicPayTo: callback for dynamic payee address.
• DynamicPrice: callback for dynamic pricing.
• FacilitatorClient: facilitator interface for settle requests.
• FacilitatorConfig: facilitator config shape.
• HTTPAdapter: adapter for HTTP runtime integration.
• HTTPProcessResult: result type for processing requests.
• HTTPRequestContext: request context for handlers.
• HTTPResponseInstructions: response instructions for handlers.
• PaywallConfig: paywall configuration for routes.
• PaywallProvider: interface for paywall config providers.
• PaymentOption: acceptable payment option shape.
• ProcessSettleFailureResponse: settle failure response shape.
• ProcessSettleResultResponse: settle result response shape.
• ProcessSettleSuccessResponse: settle success response shape.
• RouteConfigurationError: route config validation error.
• RouteValidationError: route validation error type.
• RoutesConfig: routes config map.
• UnpaidResponseBody: unpaid response shape.
• UnpaidResponseResult: unpaid response result.
• re-exported types from @x402/core/types: shared x402 types.
• ExactTokenConfig, ConfidentialTokenConfig: resolved token config for exact/confidential schemes.
• ExactTokenSymbol, ConfidentialTokenSymbol: allowed token symbols per scheme.
• PaymentMethodPricing: { method, payTo, price, maxTimeoutSeconds? } for buildAcceptsFromConfigs.
• BuildConfidentialServerConfigFromConfigInput: input shape for buildConfidentialServerConfigFromSchemeConfig.