x402z-client

Client-side helpers for the erc7984-mind-v1 x402 scheme.

Install

pnpm add x402z-client x402z-shared

Folder map

• src/http/: HTTP client helpers
• src/scheme/: scheme implementation + registration
• src/relayer/: relayer payment input helpers
• src/index.ts: public exports

Usage

import { createX402zClient } from "x402z-client";
import { createRelayer, SepoliaConfig } from "x402z-shared";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount("0x...");
const relayer = await createRelayer(SepoliaConfig);

const client = createX402zClient({
  preferredMethods: ["erc7984-mind-v1.CONFIDENTIAL_USDC.sepolia"] as const,
  signer: {
    address: account.address,
    signTypedData: account.signTypedData,
  },
  relayer,
});

const paid = await client.pay("https://example.com/demo");
console.log(paid.response.status);

createX402zClient builds the confidential payment input automatically using the confidential.batcherAddress provided by the server’s payment requirements.

Choosing Payment Methods (Client)

The client picks the first preferred method that matches the server’s accepts list by scheme + network + asset.

You can specify preferred methods in two ways:

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

preferredMethods: ["exact.USDC.base", "erc7984-mind-v1.CONFIDENTIAL_USDC.sepolia"] as const

2. Config entry (from SCHEME_CONFIG):

import { SCHEME_CONFIG } from "x402z-scheme-config";

preferredMethods: [
  SCHEME_CONFIG.exact.USDC.base,
  SCHEME_CONFIG["erc7984-mind-v1"].CONFIDENTIAL_USDC.sepolia,
]

If preferredMethods is omitted, the client defaults to SCHEME_CONFIG_NAMES (all known methods, in order).

API

• createX402zClient(config)
  • preferredMethods (optional): ordered list of preferred methods.
    • Name form: "exact.USDC.base" (matches scheme/token/network alias from x402z-scheme-config).
    • Config form: SCHEME_CONFIG.exact.USDC.base.
  • signer (required): signer used for both exact and confidential schemes
  • relayer (required when using erc7984-mind-v1): Zama relayer instance used to build encrypted inputs
  • fetch (optional): custom fetch implementation
• client.pay(url, options?): performs the 402 handshake and retries with payment headers
  • returns { response, paymentRequired?, confidentialRequirements? }

Examples

See examples/README.md for the full-process scripts (client-pay.ts, client-wrap.ts, client-unwrap.ts).

Exact scheme (ERC20) usage

import { createX402zClient } from "x402z-client";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount("0x...");
const client = createX402zClient({
  preferredMethods: ["exact.USDC.sepolia"] as const,
  signer: account,
});

const paid = await client.pay("http://localhost:8090/erc20-demo");
console.log(paid.response.status);

Notes

• Confidential scheme name: erc7984-mind-v1
• Exact scheme name: exact
• The client does not expose balance helpers; use x402z-shared for that.
• For browser usage, use x402z-client-web with x402z-shared-web.

API surface

Exports:

• X402zEvmClientScheme: client scheme implementation for erc7984-mind-v1.
• registerX402zEvmClientScheme: registers the scheme with x402 client.
• buildPaymentInput: builds encrypted payment input for a requirement.
• createX402zClient: convenience client wrapper for pay flows.
• x402Client: core x402 client constructor.
• x402HTTPClient: core HTTP client wrapper.

Types:

• X402zClientSchemeOptions: scheme config for client registration.
• X402zClientRegistrationOptions: registration options for the scheme.
• PreferredPaymentMethod: preferred payment method selector (object form or scheme-config name string).
• X402zClientOptions: options for createX402zClient.
• X402zConfidentialClientOptions: options for confidential payments.
• X402zExactClientOptions: options for exact payments.
• PayOptions: per-request payment options.
• AfterPaymentCreationHook: hook after a payment is built.
• BeforePaymentCreationHook: hook before a payment is built.
• OnPaymentCreationFailureHook: hook on payment build failures.
• PaymentCreatedContext: context for successful payment creation.
• PaymentCreationContext: context for payment creation.
• PaymentCreationFailureContext: context for payment errors.
• PaymentPolicy: policy for selecting payment requirements.
• SchemeRegistration: generic scheme registration type.
• SelectPaymentRequirements: selection callback for requirements.
• x402ClientConfig: x402 client configuration type.
• re-exported types from @x402/core/types: shared x402 types.