@a3stack/payments 0.1.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@a3stack/payments",
+  "version": "0.1.0",
+  "description": "x402 payment flows for AI agents — client (paying) and server (receiving)",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --outDir dist",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@x402/fetch": "^2.4.0",
+    "@x402/evm": "^2.4.0",
+    "viem": "^2.39.3",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,209 @@
+/**
+ * Payment Client — wraps x402/fetch for easy agent-to-agent payments
+ */
+
+import { createPublicClient, createWalletClient, http, formatUnits } from "viem";
+import type { Account } from "viem";
+import {
+  DEFAULT_MAX_AMOUNT,
+  NETWORK_USDC,
+  DEFAULT_NETWORK,
+  ERC20_ABI,
+  NETWORK_RPC,
+  BASE_RPC,
+} from "./constants.js";
+import type {
+  PaymentClientConfig,
+  PaymentBalance,
+  PaymentDetails,
+} from "./types.js";
+
+export class PaymentClient {
+  private config: PaymentClientConfig;
+  private _paidFetch?: typeof fetch;
+
+  constructor(config: PaymentClientConfig) {
+    this.config = {
+      ...config,
+      chains: config.chains ?? ["eip155:*"],
+      maxAmountPerRequest: config.maxAmountPerRequest ?? DEFAULT_MAX_AMOUNT,
+    };
+  }
+
+  /**
+   * Initialize the payment-wrapped fetch (lazy — only creates when first used)
+   */
+  private async getPaidFetch(): Promise<typeof fetch> {
+    if (this._paidFetch) return this._paidFetch;
+
+    // Dynamic import to avoid bundling issues
+    const [{ wrapFetchWithPaymentFromConfig }, { ExactEvmScheme, toClientEvmSigner }] = await Promise.all([
+      import("@x402/fetch"),
+      import("@x402/evm"),
+    ]);
+
+    const account = this.config.account as Account;
+    const chains = this.config.chains!;
+
+    // ExactEvmScheme requires a ClientEvmSigner with address + signTypedData + readContract
+    // We build a minimal signer from the viem account + a public client for readContract
+    const rpcUrl = BASE_RPC;
+    const publicClient = createPublicClient({ transport: http(rpcUrl) });
+
+    // Build a ClientEvmSigner manually
+    const signer = toClientEvmSigner({
+      address: account.address,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      signTypedData: (params: any) => account.signTypedData?.(params) ?? Promise.reject(new Error("signTypedData not available on this account")),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      readContract: (params: any) => publicClient.readContract(params),
+    } as Parameters<typeof toClientEvmSigner>[0]);
+
+    // Build scheme registrations
+    const schemes = chains.map((network) => ({
+      network: network as `${string}:${string}`,
+      client: new ExactEvmScheme(signer),
+    }));
+
+    this._paidFetch = wrapFetchWithPaymentFromConfig(fetch, { schemes });
+    return this._paidFetch;
+  }
+
+  /**
+   * A fetch function that automatically handles x402 payment challenges
+   */
+  get fetch(): (input: Parameters<typeof fetch>[0], init?: RequestInit) => Promise<Response> {
+    return async (input, init) => {
+      const paidFetch = await this.getPaidFetch();
+      return paidFetch(input, init);
+    };
+  }
+
+  /**
+   * Create a payment-capable fetch pre-configured for a specific agent.
+   * The wallet is resolved automatically from the 402 payment requirements.
+   */
+  fetchForWallet(
+    _paymentWallet: `0x${string}`
+  ): (input: Parameters<typeof fetch>[0], init?: RequestInit) => Promise<Response> {
+    // The x402 protocol handles payment wallet resolution automatically via 402 response
+    // This just returns the standard paid fetch — the wallet in payment requirements 
+    // is provided by the server's 402 response
+    return this.fetch;
+  }
+
+  /**
+   * Check your USDC balance on a network
+   */
+  async getBalance(
+    network = DEFAULT_NETWORK,
+    rpc?: string
+  ): Promise<PaymentBalance> {
+    const usdcAddress = NETWORK_USDC[network];
+    if (!usdcAddress) {
+      throw new Error(
+        `No USDC address configured for network "${network}". ` +
+          `Supported networks: ${Object.keys(NETWORK_USDC).join(", ")}`
+      );
+    }
+
+    const rpcUrl = rpc ?? NETWORK_RPC[network] ?? BASE_RPC;
+    const client = createPublicClient({ transport: http(rpcUrl) });
+
+    const [rawBalance, decimals, symbol] = await Promise.all([
+      client.readContract({
+        address: usdcAddress,
+        abi: ERC20_ABI,
+        functionName: "balanceOf",
+        args: [this.config.account.address],
+      }) as Promise<bigint>,
+      client.readContract({
+        address: usdcAddress,
+        abi: ERC20_ABI,
+        functionName: "decimals",
+      }) as Promise<number>,
+      client.readContract({
+        address: usdcAddress,
+        abi: ERC20_ABI,
+        functionName: "symbol",
+      }) as Promise<string>,
+    ]);
+
+    return {
+      amount: rawBalance,
+      formatted: formatUnits(rawBalance, decimals),
+      symbol,
+      decimals,
+    };
+  }
+
+  /**
+   * Decode payment receipt from a successful x402 response
+   * Returns null if no payment was made (wasn't a 402 endpoint)
+   */
+  decodeReceipt(response: Response): PaymentDetails | null {
+    const paymentResponseHeader = response.headers.get("x-payment-response") ??
+      response.headers.get("PAYMENT-RESPONSE");
+    if (!paymentResponseHeader) return null;
+
+    try {
+      // The x402 response header contains base64-encoded payment details
+      const decoded = JSON.parse(
+        Buffer.from(paymentResponseHeader, "base64").toString("utf8")
+      );
+      return {
+        from: decoded.sender ?? decoded.from,
+        to: decoded.recipient ?? decoded.to ?? decoded.payTo,
+        amount: decoded.amount ?? decoded.value,
+        asset: decoded.asset ?? decoded.token,
+        network: decoded.network ?? decoded.chain ?? DEFAULT_NETWORK,
+        txHash: decoded.txHash ?? decoded.hash,
+        timestamp: decoded.timestamp ?? Date.now(),
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Check if an endpoint requires payment (without making the actual request)
+   */
+  async checkPaymentRequirements(url: string): Promise<{
+    requiresPayment: boolean;
+    amount?: string;
+    asset?: string;
+    network?: string;
+    payTo?: string;
+  }> {
+    const response = await fetch(url, { method: "HEAD" });
+
+    if (response.status !== 402) {
+      return { requiresPayment: false };
+    }
+
+    const reqHeader = response.headers.get("x-payment-required") ??
+      response.headers.get("X-PAYMENT-REQUIRED");
+    if (!reqHeader) return { requiresPayment: true };
+
+    try {
+      const reqs = JSON.parse(Buffer.from(reqHeader, "base64").toString("utf8"));
+      const first = Array.isArray(reqs.accepts) ? reqs.accepts[0] : reqs;
+      return {
+        requiresPayment: true,
+        amount: first.maxAmountRequired,
+        asset: first.asset,
+        network: first.network,
+        payTo: first.payTo,
+      };
+    } catch {
+      return { requiresPayment: true };
+    }
+  }
+}
+
+/**
+ * Create a payment client
+ */
+export function createPaymentClient(config: PaymentClientConfig): PaymentClient {
+  return new PaymentClient(config);
+}

package/src/constants.ts

@@ -0,0 +1,73 @@
+/**
+ * Payment Constants
+ */
+
+/** USDC on Base mainnet */
+export const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" as const;
+
+/** USDC on Ethereum mainnet */
+export const USDC_ETH = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" as const;
+
+/** USDC on Polygon */
+export const USDC_POLYGON = "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359" as const;
+
+/** USDC on Arbitrum */
+export const USDC_ARBITRUM = "0xaf88d065e77c8cC2239327C5EDb3A432268e5831" as const;
+
+/** USDC on Optimism */
+export const USDC_OPTIMISM = "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85" as const;
+
+/** Default USDC token per network */
+export const NETWORK_USDC: Record<string, `0x${string}`> = {
+  "eip155:1": USDC_ETH,
+  "eip155:8453": USDC_BASE,
+  "eip155:137": USDC_POLYGON,
+  "eip155:42161": USDC_ARBITRUM,
+  "eip155:10": USDC_OPTIMISM,
+};
+
+/** Default network (Base mainnet) */
+export const DEFAULT_NETWORK = "eip155:8453";
+
+/** Default max auto-pay amount: 10 USDC (10,000,000 base units) */
+export const DEFAULT_MAX_AMOUNT = "10000000";
+
+/** Default payment timeout: 5 minutes */
+export const DEFAULT_TIMEOUT_SECONDS = 300;
+
+/** ERC-20 ABI for balance checks */
+export const ERC20_ABI = [
+  {
+    name: "balanceOf",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "account", type: "address" }],
+    outputs: [{ name: "", type: "uint256" }],
+  },
+  {
+    name: "decimals",
+    type: "function",
+    stateMutability: "view",
+    inputs: [],
+    outputs: [{ name: "", type: "uint8" }],
+  },
+  {
+    name: "symbol",
+    type: "function",
+    stateMutability: "view",
+    inputs: [],
+    outputs: [{ name: "", type: "string" }],
+  },
+] as const;
+
+/** Base mainnet RPC */
+export const BASE_RPC = "https://mainnet.base.org";
+
+/** Default RPC per CAIP-2 network */
+export const NETWORK_RPC: Record<string, string> = {
+  "eip155:1": "https://eth.llamarpc.com",
+  "eip155:8453": BASE_RPC,
+  "eip155:137": "https://polygon-rpc.com",
+  "eip155:42161": "https://arb1.arbitrum.io/rpc",
+  "eip155:10": "https://mainnet.optimism.io",
+};

package/src/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @a3stack/payments
+ * x402 payment flows for AI agents — client (paying) and server (receiving)
+ */
+
+export { PaymentClient, createPaymentClient } from "./client.js";
+export { PaymentServer, createPaymentServer } from "./server.js";
+export {
+  USDC_BASE,
+  USDC_ETH,
+  USDC_POLYGON,
+  USDC_ARBITRUM,
+  USDC_OPTIMISM,
+  NETWORK_USDC,
+  DEFAULT_NETWORK,
+  DEFAULT_MAX_AMOUNT,
+} from "./constants.js";
+export type {
+  PaymentClientConfig,
+  PaymentServerConfig,
+  PaymentDetails,
+  PaymentBalance,
+  PaymentVerifyResult,
+  PaymentRequirements,
+  PaymentContext,
+} from "./types.js";

package/src/server.ts

@@ -0,0 +1,225 @@
+/**
+ * Payment Server — receive x402 payments in your HTTP server
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import {
+  DEFAULT_NETWORK,
+  DEFAULT_TIMEOUT_SECONDS,
+  NETWORK_USDC,
+} from "./constants.js";
+import type {
+  PaymentServerConfig,
+  PaymentRequirements,
+  PaymentVerifyResult,
+  PaymentDetails,
+} from "./types.js";
+
+/**
+ * Payment server for accepting x402 payments
+ */
+export class PaymentServer {
+  private config: Required<PaymentServerConfig>;
+
+  constructor(config: PaymentServerConfig) {
+    const network = config.network ?? DEFAULT_NETWORK;
+    this.config = {
+      payTo: config.payTo,
+      amount: config.amount,
+      asset: config.asset ?? NETWORK_USDC[network] ?? NETWORK_USDC["eip155:8453"],
+      network,
+      description: config.description ?? "AI agent service payment",
+      maxTimeoutSeconds: config.maxTimeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS,
+    };
+  }
+
+  /**
+   * Build x402 PaymentRequirements for a resource URL
+   */
+  buildRequirements(
+    resource: string,
+    overrides?: Partial<PaymentServerConfig>
+  ): PaymentRequirements {
+    return {
+      scheme: "exact",
+      network: overrides?.network ?? this.config.network,
+      maxAmountRequired: overrides?.amount ?? this.config.amount,
+      resource,
+      description: overrides?.description ?? this.config.description,
+      payTo: overrides?.payTo ?? this.config.payTo,
+      maxTimeoutSeconds: this.config.maxTimeoutSeconds,
+      asset: overrides?.asset ?? this.config.asset,
+    };
+  }
+
+  /**
+   * Build the X-PAYMENT-REQUIRED header value (base64-encoded JSON)
+   */
+  buildRequirementsHeader(resource: string, overrides?: Partial<PaymentServerConfig>): string {
+    const requirements = this.buildRequirements(resource, overrides);
+    // x402 v2 format: { version: 2, accepts: [...] }
+    const payload = {
+      version: 2,
+      accepts: [requirements],
+    };
+    return Buffer.from(JSON.stringify(payload)).toString("base64");
+  }
+
+  /**
+   * Parse the X-PAYMENT header from an incoming request
+   */
+  parsePaymentHeader(header: string | null): {
+    payload: unknown;
+    network: string;
+  } | null {
+    if (!header) return null;
+    try {
+      const decoded = JSON.parse(Buffer.from(header, "base64").toString("utf8"));
+      return {
+        payload: decoded.payload ?? decoded,
+        network: decoded.network ?? decoded.x402Version?.network ?? this.config.network,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Verify a payment — this is a lightweight signature check.
+   * For production, use a proper facilitator (e.g. x402.org/faciliate).
+   *
+   * Note: Full on-chain verification requires a funded facilitator wallet
+   * to settle the payment. This SDK provides the verification primitive;
+   * settlement is handled by the facilitator service.
+   */
+  async verify(
+    request: Request | IncomingMessage
+  ): Promise<PaymentVerifyResult> {
+    // Get the X-PAYMENT header
+    let paymentHeader: string | null = null;
+
+    if (request instanceof Request) {
+      paymentHeader =
+        request.headers.get("x-payment") ??
+        request.headers.get("X-PAYMENT");
+    } else {
+      const raw = (request as IncomingMessage).headers["x-payment"];
+      paymentHeader = Array.isArray(raw) ? raw[0] : raw ?? null;
+    }
+
+    if (!paymentHeader) {
+      return {
+        valid: false,
+        error: "Missing X-PAYMENT header. This endpoint requires x402 payment.",
+      };
+    }
+
+    const parsed = this.parsePaymentHeader(paymentHeader);
+    if (!parsed) {
+      return { valid: false, error: "Invalid X-PAYMENT header format" };
+    }
+
+    // For full on-chain verification, we'd use ExactEvmFacilitator from @x402/evm
+    // Here we do a structural validation (signature format check)
+    try {
+      const payload = parsed.payload as Record<string, unknown>;
+
+      // Check if it's an EIP-3009 payload
+      if (payload.authorization && typeof payload.authorization === "object") {
+        const auth = payload.authorization as Record<string, unknown>;
+        if (!auth.from || !auth.to || !auth.value || !auth.nonce) {
+          return { valid: false, error: "Invalid EIP-3009 authorization structure" };
+        }
+
+        const payment: PaymentDetails = {
+          from: auth.from as `0x${string}`,
+          to: auth.to as `0x${string}`,
+          amount: auth.value as string,
+          asset: this.config.asset,
+          network: parsed.network,
+          timestamp: Date.now(),
+        };
+
+        return { valid: true, payment };
+      }
+
+      // Check if it's a Permit2 payload
+      if (payload.permit2Authorization) {
+        const p2 = payload.permit2Authorization as Record<string, unknown>;
+        const payment: PaymentDetails = {
+          from: p2.from as `0x${string}`,
+          to: (p2 as Record<string, Record<string, unknown>>).witness?.to as `0x${string}`,
+          amount: (p2.permitted as Record<string, string>)?.amount,
+          asset: (p2.permitted as Record<string, string>)?.token as `0x${string}`,
+          network: parsed.network,
+          timestamp: Date.now(),
+        };
+        return { valid: true, payment };
+      }
+
+      return { valid: false, error: "Unrecognized payment payload format" };
+    } catch (e) {
+      return { valid: false, error: `Payment verification error: ${(e as Error).message}` };
+    }
+  }
+
+  /**
+   * Express-compatible middleware for payment verification.
+   * Automatically sends 402 response if payment is missing/invalid.
+   *
+   * Usage:
+   *   app.use('/paid-tool', paymentServer.middleware(), handler)
+   */
+  middleware(overrides?: Partial<PaymentServerConfig>) {
+    return async (
+      req: IncomingMessage & { url?: string; payment?: PaymentDetails },
+      res: ServerResponse,
+      next: () => void
+    ) => {
+      const paymentHeader =
+        (req.headers["x-payment"] as string) ??
+        (req.headers["X-PAYMENT"] as string);
+
+      if (!paymentHeader) {
+        // Return 402 with payment requirements
+        const resource = `${req.headers["host"] ?? ""}${req.url ?? "/"}`;
+        const requirementsHeader = this.buildRequirementsHeader(
+          `https://${resource}`,
+          overrides
+        );
+
+        res.writeHead(402, {
+          "Content-Type": "application/json",
+          "X-PAYMENT-REQUIRED": requirementsHeader,
+        });
+        res.end(
+          JSON.stringify({
+            error: "Payment Required",
+            message: this.config.description,
+            amount: `${this.config.amount} USDC base units`,
+            network: this.config.network,
+          })
+        );
+        return;
+      }
+
+      const result = await this.verify(req);
+      if (!result.valid) {
+        res.writeHead(402, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Payment Invalid", message: result.error }));
+        return;
+      }
+
+      // Attach payment details to request for downstream handlers
+      (req as typeof req & { payment: PaymentDetails }).payment = result.payment!;
+      next();
+    };
+  }
+}
+
+/**
+ * Create a payment server for receiving x402 payments
+ */
+export function createPaymentServer(config: PaymentServerConfig): PaymentServer {
+  return new PaymentServer(config);
+}

package/src/types.ts

@@ -0,0 +1,94 @@
+/**
+ * @a3stack/payments — Type Definitions
+ */
+
+export interface PaymentClientConfig {
+  /**
+   * viem Account (e.g. from privateKeyToAccount())
+   * Must have signTypedData for payment signing.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  account: any;
+  /**
+   * Supported chains in CAIP-2 format.
+   * Defaults to ["eip155:*"] (all EVM chains)
+   */
+  chains?: string[];
+  /**
+   * Maximum USDC amount (in base units, 6 decimals) to auto-pay per request.
+   * e.g. "1000000" = 1.00 USDC
+   * Defaults to "10000000" (10 USDC)
+   */
+  maxAmountPerRequest?: string;
+}
+
+export interface PaymentServerConfig {
+  /** Address to receive payments */
+  payTo: `0x${string}`;
+  /**
+   * Required payment amount in USDC base units (6 decimals).
+   * e.g. "100000" = 0.10 USDC
+   */
+  amount: string;
+  /**
+   * Token asset address. Defaults to USDC on Base mainnet.
+   */
+  asset?: `0x${string}`;
+  /**
+   * Network in CAIP-2 format. Defaults to "eip155:8453" (Base mainnet)
+   */
+  network?: string;
+  /**
+   * Description shown in payment requirements
+   */
+  description?: string;
+  /**
+   * Max timeout for payment verification in seconds. Defaults to 300.
+   */
+  maxTimeoutSeconds?: number;
+}
+
+export interface PaymentDetails {
+  from: `0x${string}`;
+  to: `0x${string}`;
+  amount: string;
+  asset: `0x${string}`;
+  network: string;
+  txHash?: `0x${string}`;
+  timestamp: number;
+}
+
+export interface PaymentVerifyResult {
+  valid: boolean;
+  payment?: PaymentDetails;
+  error?: string;
+}
+
+export interface PaymentBalance {
+  amount: bigint;
+  formatted: string;
+  symbol: string;
+  decimals: number;
+}
+
+export interface PaymentRequirements {
+  scheme: string;
+  network: string;
+  maxAmountRequired: string;
+  resource: string;
+  description?: string;
+  mimeType?: string;
+  payTo: string;
+  maxTimeoutSeconds: number;
+  asset: string;
+  outputSchema?: unknown;
+  extra?: Record<string, unknown>;
+}
+
+/**
+ * Middleware context — added to express req/res
+ */
+export interface PaymentContext {
+  payment: PaymentDetails;
+  requirements: PaymentRequirements;
+}