@mingderwang/x402 0.1.0 → 0.1.2

package/package.json

@@ -1,16 +1,23 @@
 {
   "name": "@mingderwang/x402",
-  "version": "0.1.0",
-  "description": "x402 (HTTP 402 Payment Required) client + server helpers: payment requirements, EIP-3009 signing, X-PAYMENT, verification and settlement.",
+  "version": "0.1.2",
+  "description": "x402 (HTTP 402 Payment Required) client + server helpers: EIP-3009 signing, X-PAYMENT, verification and settlement. Ships an `x402` CLI.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "x402": "./dist/cli.js"
+  },
   "exports": {
-    ".": "./dist/index.js"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
   },
   "files": [
     "dist",
+    "src",
     "README.md"
   ],
   "engines": {
@@ -20,7 +27,7 @@
     "build": "node ./scripts/build.mjs"
   },
   "dependencies": {
-    "@mingderwang/wallet": "^0.1.0",
+    "@mingderwang/wallet": "^0.1.1",
     "ethers": "^6.13.4"
   },
   "keywords": [

package/src/cli.ts

@@ -0,0 +1,342 @@
+#!/usr/bin/env node
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readKeystore, loadWallet, processEnvPassword } from '@mingderwang/wallet';
+import {
+  decodeJson,
+  detectPaymentRequired,
+  makePaymentPayload,
+  verifyPaymentPayload,
+  settlePayment,
+  xPaymentHeader,
+  PAYMENT_REQUIRED_HEADER,
+  type PaymentRequirements,
+  type PaymentRequirementsResponse,
+  type PaymentPayload,
+} from './index';
+
+const VERSION = '0.1.2';
+
+const C = {
+  bold: (s: string) => `\x1b[1m${s}\x1b[0m`,
+  green: (s: string) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s: string) => `\x1b[33m${s}\x1b[0m`,
+  red: (s: string) => `\x1b[31m${s}\x1b[0m`,
+  gray: (s: string) => `\x1b[90m${s}\x1b[0m`,
+};
+
+function defaultKeystore(): string {
+  return process.env.X402_WALLET_PATH ?? join(homedir(), '.wallet', 'wallet.json');
+}
+
+function promptHidden(question: string): Promise<string> {
+  const env = processEnvPassword();
+  if (env) {
+    process.stderr.write(`${question}[using WALLET_PASSWORD env]\n`);
+    return Promise.resolve(env);
+  }
+  process.stderr.write(question);
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    const wasRaw = !!stdin.isRaw;
+    stdin.setRawMode(true);
+    stdin.resume();
+    let input = '';
+    const onData = (buf: Buffer) => {
+      const code = buf[0];
+      if (code === 3) {
+        stdin.removeListener('data', onData);
+        stdin.setRawMode(false);
+        stdin.pause();
+        process.exit(130);
+      }
+      if (code === 13 || code === 10) {
+        stdin.removeListener('data', onData);
+        stdin.setRawMode(false);
+        stdin.pause();
+        process.stderr.write('\n');
+        resolve(input);
+        return;
+      }
+      if (code === 127 || code === 8) input = input.slice(0, -1);
+      else input += buf.toString('utf8');
+    };
+    stdin.on('data', onData);
+  });
+}
+
+function parseRequirement(spec: string): PaymentRequirements {
+  const raw = existsSync(spec) ? readFileSync(spec, 'utf8') : spec;
+  const parsed = JSON.parse(raw) as PaymentRequirementsResponse | PaymentRequirements;
+  if (Array.isArray((parsed as PaymentRequirementsResponse).accepts)) {
+    const first = (parsed as PaymentRequirementsResponse).accepts[0];
+    if (!first) throw new Error('PaymentRequirementsResponse has no accepts[] entries.');
+    return first;
+  }
+  return parsed as PaymentRequirements;
+}
+
+function parsePayload(spec: string): PaymentPayload {
+  if (/^[A-Za-z0-9+/=]+$/.test(spec) && spec.length > 64) return decodeJson<PaymentPayload>(spec);
+  const raw = existsSync(spec) ? readFileSync(spec, 'utf8') : spec;
+  return JSON.parse(raw) as PaymentPayload;
+}
+
+async function loadSigner(action: string, keystorePath: string): Promise<import('ethers').Wallet> {
+  if (!existsSync(keystorePath)) {
+    console.log(C.red(`No keystore at ${keystorePath}`) + ` — create one with the \`wallet\` CLI.`);
+    process.exit(2);
+  }
+  const keystore = readKeystore(keystorePath);
+  for (let attempt = 1; ; attempt++) {
+    const password = await promptHidden(`Keystore password (${action}): `);
+    try {
+      return loadWallet(keystore, password);
+    } catch {
+      if (attempt >= 3) {
+        console.log(C.red('Incorrect password. Exiting.'));
+        process.exit(1);
+      }
+      console.log(C.red('Incorrect password, try again.'));
+    }
+  }
+}
+
+function printHeaders(set: Headers): void {
+  const h = set.get(PAYMENT_REQUIRED_HEADER);
+  if (h) console.log(`  ${C.gray('payment-required')} ${h.slice(0, 60)}…`);
+  const retry = set.get('retry-after');
+  if (retry) console.log(`  ${C.gray('retry-after')}    ${retry}`);
+}
+
+async function requestWithBody(url: string, method: string, headers: Record<string, string>): Promise<Response> {
+  return fetch(url, { method, headers });
+}
+
+// ---------- commands ----------
+
+async function cmdRequirements(url: string, method: string, hdrs: Record<string, string>): Promise<void> {
+  const res = await requestWithBody(url, method, hdrs);
+  const text = await res.text();
+  if (res.status !== 402) {
+    console.log(C.yellow(`Response is ${res.status}, not 402 — no payment required.`));
+    console.log(text.slice(0, 400));
+    process.exit(0);
+  }
+  const reqs = detectPaymentRequired({ status: res.status, headers: res.headers, text });
+  if (res.headers && res.headers.size) printHeaders(res.headers);
+  console.log(JSON.stringify(reqs, null, 2));
+}
+
+async function cmdSign(requirementArg: string, keystorePath: string, json: boolean): Promise<void> {
+  const requirement = parseRequirement(requirementArg);
+  const wallet = await loadSigner('sign', keystorePath);
+  const payload = await makePaymentPayload({ wallet, requirement });
+  const header = xPaymentHeader(payload);
+  if (json) {
+    console.log(JSON.stringify({ payload, header }, null, 2));
+    return;
+  }
+  console.log(`  ${C.bold('Signer')}    ${wallet.address}`);
+  console.log(`  ${C.bold('Network')}   ${requirement.network}`);
+  console.log(`  ${C.bold('Amount')}    ${requirement.maxAmountRequired} (${requirement.asset})`);
+  console.log('');
+  console.log(`  ${C.green('X-PAYMENT header')}:`);
+  console.log('  ' + header);
+}
+
+async function cmdPay(url: string, method: string, hdrs: Record<string, string>, keystorePath: string, json: boolean): Promise<void> {
+  const first = await requestWithBody(url, method, hdrs);
+  const firstText = await first.text();
+
+  if (first.status !== 402) {
+    console.log(C.yellow(`No payment required (${first.status}) — nothing to do.`));
+    console.log(firstText.slice(0, 400));
+    return;
+  }
+  const reqs = detectPaymentRequired({ status: first.status, headers: first.headers, text: firstText });
+  if (!reqs) {
+    console.log(C.red('402 response had no parseable payment requirements.'));
+    process.exit(1);
+  }
+  const requirement = reqs.accepts[0];
+  if (!requirement) {
+    console.log(C.red('PaymentRequirementsResponse has no accepts[] entries.'));
+    process.exit(1);
+  }
+  const wallet = await loadSigner('pay', keystorePath);
+  console.log(`  ${C.bold('Paying')} ${requirement.maxAmountRequired} ${requirement.asset} on ${requirement.network}`);
+  console.log(`  ${C.gray('from')} ${wallet.address} ${C.gray('→')} ${requirement.payTo}\n`);
+  const payload = await makePaymentPayload({ wallet, requirement });
+  const retried = await requestWithBody(url, method, { ...hdrs, 'X-PAYMENT': xPaymentHeader(payload) });
+  const body = await retried.text();
+  if (retried.status === 402) {
+    console.log(C.red(`Still 402 after payment:`));
+    console.log(body.slice(0, 400));
+    process.exit(1);
+  }
+  if (json) {
+    let parsed = null;
+    try { parsed = JSON.parse(body); } catch { /* non-json */ }
+    console.log(JSON.stringify({ status: retried.status, headers: Object.fromEntries(retried.headers.entries()), body: parsed ?? body }, null, 2));
+    return;
+  }
+  console.log(C.green(`${retried.status} ${retried.statusText}`));
+  try {
+    console.log(JSON.stringify(JSON.parse(body), null, 2));
+  } catch {
+    console.log(body.slice(0, 800));
+  }
+}
+
+async function cmdDecode(spec: string): Promise<void> {
+  const payload = parsePayload(spec);
+  console.log(JSON.stringify(payload, null, 2));
+}
+
+async function cmdVerify(payloadArg: string, requirementArg: string): Promise<void> {
+  const payload = parsePayload(payloadArg);
+  const requirement = parseRequirement(requirementArg);
+  const result = verifyPaymentPayload(payload, requirement);
+  if (result.isValid) console.log(JSON.stringify({ isValid: true, payer: result.payer }, null, 2));
+  else console.log(JSON.stringify({ isValid: false, invalidReason: result.invalidReason }, null, 2));
+}
+
+async function cmdSettle(payloadArg: string, requirementArg: string, gasKey?: string, rpcUrl?: string): Promise<void> {
+  const payload = parsePayload(payloadArg);
+  const requirement = parseRequirement(requirementArg);
+  if (gasKey) process.env.X402_GAS_PRIVATE_KEY = gasKey;
+  if (rpcUrl) process.env.X402_RPC_URL = rpcUrl;
+  const result = await settlePayment(payload, requirement, {});
+  console.log(JSON.stringify(result, null, 2));
+}
+
+// ---------- help ----------
+
+const HELP = `x402 v${VERSION}
+
+x402 (HTTP 402 Payment Required) toolkit: sign, pay, verify and settle
+EIP-3009 USDC payments.
+
+Usage:
+  x402 requirements <url> [--method GET] [--header K:V]...
+      Print the PaymentRequirementsResponse if the URL responds 402.
+  x402 sign <requirements.json> [--wallet <keystore>]
+      Sign a payment for the first accepts[] entry; print the X-PAYMENT header base64.
+  x402 pay <url> [--method GET] [--header K:V]... [--wallet <keystore>]
+      Full round trip: hit the URL, pay the 402, retry with X-PAYMENT, print the result.
+  x402 decode <base64-or-file | payload.json>
+      Decode an X-PAYMENT header value into the PaymentPayload JSON.
+  x402 verify <payload> <requirements.json>
+      Offline signature/amount/time sanity check. payload = base64 header or JSON file.
+  x402 settle <payload> <requirements.json> [--gas-key <private>] [--rpc <url>]
+      Broadcast transferWithAuthorization (uses X402_GAS_PRIVATE_KEY / X402_RPC_URL env if set).
+
+Options:
+  --wallet <keystore>   Keystore file (default ~/.wallet/wallet.json)
+  --json                Machine-readable output
+  --header K:V          Extra HTTP header (repeatable)
+  --method <verB>       HTTP method (default GET)
+
+Password:
+  Prompts interactively, or set WALLET_PASSWORD / XSIFT_WALLET_PASSWORD in the environment.`;
+
+function printHelp(): void {
+  console.log(HELP);
+}
+
+// ---------- entry ----------
+
+interface Parsed {
+  cmd: string;
+  positional: string[];
+  opts: Record<string, string>;
+  headers: Record<string, string>;
+  json: boolean;
+}
+
+function parseArgs(args: string[]): Parsed {
+  const positional: string[] = [];
+  const opts: Record<string, string> = {};
+  const headers: Record<string, string> = {};
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--json') {
+      json = true;
+      continue;
+    }
+    if (a === '--header') {
+      const kv = args[++i];
+      const idx = kv ? kv.indexOf(':') : -1;
+      if (!kv || idx < 0) {
+        console.log(C.red('--header expects K:V'));
+        process.exit(1);
+      }
+      headers[kv.slice(0, idx).trim()] = kv.slice(idx + 1).trim();
+      continue;
+    }
+    if (a === '--wallet' || a === '--gas-key' || a === '--rpc' || a === '--method' || a === '--path') {
+      opts[a.slice(2)] = args[++i] ?? '';
+      continue;
+    }
+    if (!a.startsWith('--')) positional.push(a);
+  }
+  const cmd = positional[0] ?? 'help';
+  return { cmd, positional: positional.slice(1), opts, headers, json };
+}
+
+async function main(): Promise<void> {
+  const { cmd, positional, opts, headers, json } = parseArgs(process.argv.slice(2));
+  const keystore = opts.wallet ?? defaultKeystore();
+  const method = (opts.method ?? 'GET').toUpperCase();
+  switch (cmd) {
+    case 'requirements': {
+      const url = positional[0];
+      if (!url) throw new Error('usage: x402 requirements <url>');
+      return cmdRequirements(url, method, headers);
+    }
+    case 'sign': {
+      const spec = positional[0];
+      if (!spec) throw new Error('usage: x402 sign <requirements.json> [--wallet <keystore>]');
+      return cmdSign(spec, keystore, json);
+    }
+    case 'pay': {
+      const url = positional[0];
+      if (!url) throw new Error('usage: x402 pay <url> [--wallet <keystore>]');
+      return cmdPay(url, method, headers, keystore, json);
+    }
+    case 'decode': {
+      const spec = positional[0];
+      if (!spec) throw new Error('usage: x402 decode <base64-or-file>');
+      return cmdDecode(spec);
+    }
+    case 'verify': {
+      const [payloadArg, reqArg] = positional;
+      if (!payloadArg || !reqArg) throw new Error('usage: x402 verify <payload> <requirements.json>');
+      return cmdVerify(payloadArg, reqArg);
+    }
+    case 'settle': {
+      const [payloadArg, reqArg] = positional;
+      if (!payloadArg || !reqArg) throw new Error('usage: x402 settle <payload> <requirements.json>');
+      return cmdSettle(payloadArg, reqArg, opts['gas-key'], opts.rpc);
+    }
+    case 'help':
+    case '-h':
+    case '--help':
+      return printHelp();
+    case '-v':
+    case '--version':
+      return console.log(VERSION);
+    default:
+      console.log(C.red(`Unknown command: ${cmd}`) + '\n');
+      printHelp();
+      process.exit(1);
+  }
+}
+
+main().catch((e) => {
+  console.error(e instanceof Error ? e.message : e);
+  process.exit(1);
+});

package/src/index.ts

@@ -0,0 +1,307 @@
+import { randomBytesHex, NETWORKS } from '@mingderwang/wallet';
+import { verifyTypedData, Contract, JsonRpcProvider, Wallet } from 'ethers';
+
+// ---------- types ----------
+
+export interface PaymentRequirements {
+  scheme: string;
+  network: string;
+  maxAmountRequired: string;
+  asset: string;
+  payTo: string;
+  resource: string;
+  description: string;
+  mimeType?: string;
+  outputSchema?: unknown;
+  maxTimeoutSeconds: number;
+  extra?: Record<string, unknown>;
+}
+
+export interface PaymentRequirementsResponse {
+  x402Version: 1;
+  error: string;
+  accepts: PaymentRequirements[];
+}
+
+export interface Authorization {
+  from: string;
+  to: string;
+  value: string;
+  validAfter: string;
+  validBefore: string;
+  nonce: string;
+}
+
+export interface PaymentPayload {
+  x402Version: 1;
+  scheme: 'exact';
+  network: string;
+  payload: {
+    signature: string;
+    authorization: Authorization;
+  };
+}
+
+export interface SettlementResponse {
+  success: boolean;
+  errorReason?: string;
+  transaction: string;
+  network: string;
+  payer: string;
+}
+
+export const PAYMENT_REQUIRED_HEADER = 'payment-required';
+export const PAYMENT_SIGNATURE_HEADER = 'x-payment';
+export const PAYMENT_RESPONSE_HEADER = 'payment-response';
+
+export const ERROR = {
+  insufficientFunds: 'insufficient_funds',
+  invalidValidAfter: 'invalid_exact_evm_payload_authorization_valid_after',
+  invalidValidBefore: 'invalid_exact_evm_payload_authorization_valid_before',
+  invalidValue: 'invalid_exact_evm_payload_authorization_value',
+  invalidSignature: 'invalid_exact_evm_payload_signature',
+  recipientMismatch: 'invalid_exact_evm_payload_recipient_mismatch',
+  invalidNetwork: 'invalid_network',
+  invalidPayload: 'invalid_payload',
+  invalidPaymentRequirements: 'invalid_payment_requirements',
+  invalidScheme: 'invalid_scheme',
+  invalidVersion: 'invalid_x402_version',
+  invalidTxState: 'invalid_transaction_state',
+} as const;
+
+// ---------- encoding ----------
+
+export function encodeJson(obj: unknown): string {
+  return Buffer.from(JSON.stringify(obj)).toString('base64');
+}
+
+export function decodeJson<T>(b64: string): T {
+  return JSON.parse(Buffer.from(b64, 'base64').toString('utf8')) as T;
+}
+
+// ---------- server: payment requirements ----------
+
+export function makePaymentRequired(
+  opts: {
+    resource: string;
+    description: string;
+    network: string;
+    amount: string; // atomic units, e.g. "500000" for 0.5 USDC
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds?: number;
+    mimeType?: string;
+    extra?: Record<string, unknown>;
+  }
+): PaymentRequirementsResponse {
+  return {
+    x402Version: 1,
+    error: `${PAYMENT_SIGNATURE_HEADER.toUpperCase()} header is required`,
+    accepts: [
+      {
+        scheme: 'exact',
+        network: opts.network,
+        maxAmountRequired: opts.amount,
+        asset: opts.asset.toLowerCase(),
+        payTo: opts.payTo.toLowerCase(),
+        resource: opts.resource,
+        description: opts.description,
+        mimeType: opts.mimeType ?? 'application/json',
+        outputSchema: null,
+        maxTimeoutSeconds: opts.maxTimeoutSeconds ?? 300,
+        extra: opts.extra ?? { name: 'USDC', version: '2' },
+      },
+    ],
+  };
+}
+
+// ---------- client: 402 detection + payment construction ----------
+
+export function detectPaymentRequired(response: { status: number; headers?: Headers; text?: string }): PaymentRequirementsResponse | null {
+  if (response.status !== 402) return null;
+  const header = response.headers?.get?.(PAYMENT_REQUIRED_HEADER);
+  if (header) {
+    try {
+      return decodeJson<PaymentRequirementsResponse>(header);
+    } catch {
+      /* fall through to body */
+    }
+  }
+  if (response.text) {
+    try {
+      const parsed = JSON.parse(response.text);
+      if (parsed && Array.isArray(parsed.accepts)) return parsed as PaymentRequirementsResponse;
+    } catch {
+      /* not json */
+    }
+  }
+  return null;
+}
+
+export interface PaymentOptions {
+  wallet: Wallet;
+  requirement: PaymentRequirements;
+  nowSeconds?: number;
+}
+
+export async function makePaymentPayload({ wallet, requirement, nowSeconds }: PaymentOptions): Promise<PaymentPayload> {
+  const { NETWORKS: _net } = { NETWORKS };
+  const chainId = chainIdForNetwork(requirement.network);
+  const now = nowSeconds ?? Math.floor(Date.now() / 1000);
+  const value = BigInt(requirement.maxAmountRequired);
+
+  const domain = {
+    name: 'USD Coin',
+    version: '2',
+    chainId,
+    verifyingContract: requirement.asset,
+  };
+  const types = {
+    TransferWithAuthorization: [
+      { name: 'from', type: 'address' },
+      { name: 'to', type: 'address' },
+      { name: 'value', type: 'uint256' },
+      { name: 'validAfter', type: 'uint256' },
+      { name: 'validBefore', type: 'uint256' },
+      { name: 'nonce', type: 'bytes32' },
+    ],
+  };
+  const authorization: Authorization = {
+    from: wallet.address,
+    to: requirement.payTo,
+    value: value.toString(),
+    validAfter: (now - 60).toString(),
+    validBefore: (now + requirement.maxTimeoutSeconds).toString(),
+    nonce: randomBytesHex(32),
+  };
+  const signature = await wallet.signTypedData(
+    domain,
+    types,
+    { from: authorization.from, to: authorization.to, value: authorization.value, validAfter: authorization.validAfter, validBefore: authorization.validBefore, nonce: authorization.nonce }
+  );
+  return {
+    x402Version: 1,
+    scheme: 'exact',
+    network: requirement.network,
+    payload: { signature, authorization },
+  };
+}
+
+export function chainIdForNetwork(network: string): number {
+  for (const n of Object.values(NETWORKS)) {
+    if (n.networkId === network) return n.chainId;
+  }
+  const m = /-(\d+)$/.exec(network);
+  if (m) return Number(m[1]);
+  throw new Error(`Unknown network ${network}`);
+}
+
+export function xPaymentHeader(payload: PaymentPayload): string {
+  return encodeJson(payload);
+}
+
+// ---------- server: verification + settlement ----------
+
+const TRANSFER_WITH_AUTH_ABI = [
+  'function transferWithAuthorization(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce)',
+  'function balanceOf(address) view returns (uint256)',
+] as const;
+
+export function verifyPaymentPayload(
+  payload: unknown,
+  requirement: PaymentRequirements
+): { isValid: boolean; payer?: string; invalidReason?: string } {
+  if (!payload || typeof payload !== 'object') {
+    return { isValid: false, invalidReason: ERROR.invalidPayload };
+  }
+  const p = payload as PaymentPayload;
+  if (p.x402Version !== 1) return { isValid: false, invalidReason: ERROR.invalidVersion };
+  if (p.scheme !== 'exact') return { isValid: false, invalidReason: ERROR.invalidScheme };
+  if (p.network !== requirement.network) return { isValid: false, invalidReason: ERROR.invalidNetwork };
+  const a = p.payload?.authorization;
+  const sig = p.payload?.signature;
+  if (!a || !sig) return { isValid: false, invalidReason: ERROR.invalidPayload };
+
+  const now = Math.floor(Date.now() / 1000);
+  const validAfter = Number(a.validAfter);
+  const validBefore = Number(a.validBefore);
+  if (now < validAfter) return { isValid: false, invalidReason: ERROR.invalidValidAfter };
+  if (now > validBefore) return { isValid: false, invalidReason: ERROR.invalidValidBefore };
+  if (BigInt(a.value) < BigInt(requirement.maxAmountRequired)) {
+    return { isValid: false, invalidReason: ERROR.invalidValue };
+  }
+  if (a.to.toLowerCase() !== requirement.payTo.toLowerCase()) {
+    return { isValid: false, invalidReason: ERROR.recipientMismatch };
+  }
+  if (!/^0x[a-fA-F0-9]{40}$/.test(a.from) || !/^0x[a-fA-F0-9]{64}$/.test(a.nonce)) {
+    return { isValid: false, invalidReason: ERROR.invalidPayload };
+  }
+
+  const chainId = chainIdForNetwork(requirement.network);
+  const domain = { name: 'USD Coin', version: '2', chainId, verifyingContract: requirement.asset };
+  const types = {
+    TransferWithAuthorization: [
+      { name: 'from', type: 'address' },
+      { name: 'to', type: 'address' },
+      { name: 'value', type: 'uint256' },
+      { name: 'validAfter', type: 'uint256' },
+      { name: 'validBefore', type: 'uint256' },
+      { name: 'nonce', type: 'bytes32' },
+    ],
+  };
+  const message = { from: a.from, to: a.to, value: a.value, validAfter: a.validAfter, validBefore: a.validBefore, nonce: a.nonce };
+  try {
+    const signer = verifyTypedData(domain, types, message, sig);
+    if (signer.toLowerCase() !== a.from.toLowerCase()) {
+      return { isValid: false, invalidReason: ERROR.invalidSignature };
+    }
+  } catch {
+    return { isValid: false, invalidReason: ERROR.invalidSignature };
+  }
+  return { isValid: true, payer: a.from };
+}
+
+export async function settlePayment(
+  payload: PaymentPayload,
+  requirement: PaymentRequirements,
+  opts: { signer?: Wallet; rpcUrl?: string; confirmations?: number }
+): Promise<SettlementResponse> {
+  const a = payload.payload.authorization;
+  const network = requirement.network;
+  const rpc = opts.rpcUrl ?? process.env.X402_RPC_URL;
+  const provider = new JsonRpcProvider(rpc);
+  const signer =
+    opts.signer ??
+    (process.env.X402_GAS_PRIVATE_KEY
+      ? new Wallet(process.env.X402_GAS_PRIVATE_KEY, provider)
+      : undefined);
+  if (!signer) {
+    return { success: false, errorReason: 'server has no gas signer configured', transaction: '', network, payer: a.from };
+  }
+  const contract = new Contract(requirement.asset, TRANSFER_WITH_AUTH_ABI, signer);
+  const erc20 = contract as unknown as {
+    balanceOf: (address: string) => Promise<bigint>;
+    transferWithAuthorization: (
+      from: string, to: string, value: string, validAfter: string, validBefore: string, nonce: string
+    ) => Promise<{ hash: string; wait: (confirmations?: number) => Promise<unknown> }>;
+  };
+  try {
+    const balance = await erc20.balanceOf(a.from);
+    if (balance < BigInt(a.value)) {
+      return { success: false, errorReason: ERROR.insufficientFunds, transaction: '', network, payer: a.from };
+    }
+    const tx = await erc20.transferWithAuthorization(a.from, a.to, a.value, a.validAfter, a.validBefore, a.nonce);
+    await tx.wait(opts.confirmations ?? 1);
+    return { success: true, transaction: tx.hash, network, payer: a.from };
+  } catch (e) {
+    return {
+      success: false,
+      errorReason: ERROR.invalidTxState,
+      transaction: '',
+      network,
+      payer: a.from,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      ...((e as any)?.shortMessage ? { errorReason: (e as { shortMessage: string }).shortMessage } : {}),
+    };
+  }
+}