@moltbankhq/x402-mod 0.1.0

package/moltbank.mod.json

@@ -0,0 +1,90 @@
+{
+  "modProtocolVersion": "1.1",
+  "name": "x402",
+  "displayName": "x402",
+  "version": "0.1.0",
+  "description": "x402 Capability. Provides cap.moltbank.x402 — Moltbank-orchestrated x402 payment flows on Base. The buy command funds the agent's registered x402 signer wallet from the Safe via account_execute (session-key path). The record command persists a completed x402 payment attestation via account_record_receipt (evm-local-attested verify-only) and records the payment row via record_x402_payment_result. All EVM signing delegates to the host's cap.signer.evm — this mod never holds wallet keys (architecture spec §10.1: only the trusted core signs).",
+  "publisher": "moltbankhq",
+  "homepage": "https://moltbank.bot/mods/x402",
+  "repository": "https://github.com/moltbankhq/openclaw-plugin",
+  "license": "MIT",
+  "tier": "official",
+  "signature": {
+    "algorithm": "ed25519",
+    "publisherKeyId": "moltbank-2026-01",
+    "issuedAt": "2026-05-14T00:00:00Z",
+    "expiresAt": "2027-05-14T00:00:00Z",
+    "value": ""
+  },
+  "category": "capability",
+  "riskLevel": "trade",
+  "moltbank": {
+    "minCliVersion": "0.1.8",
+    "requires": ["cap.signer.evm", "cap.identity.whoami"],
+    "provides": ["cap.moltbank.x402"]
+  },
+  "permissions": {
+    "requested": ["network", "signer_evm", "moltbank_mcp"],
+    "network": {
+      "allowedDomains": [
+        "base-rpc.publicnode.com",
+        "base-sepolia-rpc.publicnode.com"
+      ]
+    }
+  },
+  "payments": {
+    "spends": true,
+    "currency": "USDC",
+    "estimateCommand": "estimate",
+    "ledgerPath": "state/x402-ledger.jsonl"
+  },
+  "config": {
+    "schemaPath": "schemas/config.schema.json",
+    "setupCommand": "setup"
+  },
+  "state": { "scope": "~/.moltbank/mods/x402/" },
+  "backendExtension": { "allowed": false },
+  "interfaces": [
+    {
+      "type": "cli",
+      "binary": "x402-mod",
+      "package": "@moltbankhq/x402-mod",
+      "commands": [
+        "setup",
+        "doctor",
+        "estimate",
+        "run",
+        "status",
+        "feedback",
+        "buy",
+        "record",
+        "balances",
+        "help"
+      ],
+      "commandMetadata": {
+        "setup":    { "readOnly": false, "destructive": false, "idempotent": false, "openWorld": false },
+        "doctor":   { "readOnly": true,  "destructive": false, "idempotent": true,  "openWorld": false },
+        "estimate": { "readOnly": true,  "destructive": false, "idempotent": true,  "openWorld": false },
+        "run":      { "readOnly": true,  "destructive": false, "idempotent": true,  "openWorld": false },
+        "status":   { "readOnly": true,  "destructive": false, "idempotent": true,  "openWorld": false },
+        "feedback": { "readOnly": false, "destructive": false, "idempotent": false, "openWorld": false },
+        "buy":      { "readOnly": false, "destructive": false, "idempotent": false, "openWorld": true  },
+        "record":   { "readOnly": false, "destructive": false, "idempotent": false, "openWorld": true  },
+        "balances": { "readOnly": true,  "destructive": false, "idempotent": true,  "openWorld": true  },
+        "help":     { "readOnly": true,  "destructive": false, "idempotent": true,  "openWorld": false }
+      }
+    }
+  ],
+  "skill": {
+    "path": "SKILL.md",
+    "runtimes": ["claude-code", "openclaw"]
+  },
+  "review": { "securityReviewUrl": "https://moltbank.bot/mods/x402/review" },
+  "keywords": ["x402", "base", "usdc", "payments", "moltbank", "cap.moltbank.x402"],
+  "mcpScopes": [
+    "mcp:tool:get_account_details",
+    "mcp:tool:get_agent_wallet_status",
+    "mcp:tool:account_execute",
+    "mcp:tool:account_record_receipt"
+  ]
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@moltbankhq/x402-mod",
+  "version": "0.1.0",
+  "description": "x402 Capability. Provides cap.moltbank.x402 — Moltbank-orchestrated x402 payment flows on Base. Funds the agent's registered x402 signer wallet from the Safe and records completed payment attestations. All EVM signing delegates to the host.",
+  "type": "module",
+  "bin": {
+    "x402-mod": "bin/x402-mod"
+  },
+  "main": "./src/index.ts",
+  "files": [
+    "bin/",
+    "src/",
+    "schemas/",
+    "SKILL.md",
+    "moltbank.mod.json",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --import tsx --test tests/**/*.test.ts"
+  },
+  "dependencies": {
+    "@moltbankhq/mod-sdk": "^0.1.1",
+    "tsx": "^4.20.6",
+    "viem": "^2.21.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/schemas/config.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "x402 Mod Config",
+  "type": "object",
+  "properties": {
+    "defaultChain": {
+      "type": "string",
+      "enum": ["base"],
+      "description": "Default chain for x402 payments (currently only Base is supported)."
+    }
+  },
+  "additionalProperties": false
+}

package/src/calldata.ts

@@ -0,0 +1,26 @@
+import { encodeFunctionData, parseAbi, type Address } from 'viem';
+import { USDC_DECIMALS } from './constants.ts';
+
+const ERC20_ABI = parseAbi(['function transfer(address to, uint256 amount) returns (bool)']);
+
+export function buildErc20TransferCalldata(to: string, amountRaw: bigint): string {
+  return encodeFunctionData({
+    abi: ERC20_ABI,
+    functionName: 'transfer',
+    args: [to as Address, amountRaw]
+  });
+}
+
+export function parseUsdcAmount(amount: string | number): bigint {
+  const str = String(amount).trim();
+  const [intPart, fracPart = ''] = str.split('.');
+  const padded = fracPart.padEnd(USDC_DECIMALS, '0').slice(0, USDC_DECIMALS);
+  return BigInt(intPart + padded);
+}
+
+export function formatUsdc(raw: bigint): string {
+  const str = raw.toString().padStart(USDC_DECIMALS + 1, '0');
+  const intPart = str.slice(0, str.length - USDC_DECIMALS) || '0';
+  const fracPart = str.slice(str.length - USDC_DECIMALS).replace(/0+$/, '');
+  return fracPart ? `${intPart}.${fracPart}` : intPart;
+}

package/src/config.ts

@@ -0,0 +1,31 @@
+import type { MoltbankCli } from '@moltbankhq/mod-sdk';
+
+export type X402Config = {
+  defaultChain?: 'base';
+};
+
+const CONFIG_KEY = 'x402-config';
+
+export const ConfigSchema = {
+  type: 'object',
+  properties: {
+    defaultChain: { type: 'string', enum: ['base'] }
+  },
+  additionalProperties: false
+} as const;
+
+export async function loadConfig(moltbank: MoltbankCli): Promise<X402Config | null> {
+  try {
+    const state = moltbank.state;
+    const raw = await state.get(CONFIG_KEY);
+    if (!raw) return null;
+    return JSON.parse(raw as string) as X402Config;
+  } catch {
+    return null;
+  }
+}
+
+export async function saveConfig(config: X402Config, moltbank: MoltbankCli): Promise<void> {
+  const state = moltbank.state;
+  await state.set(CONFIG_KEY, JSON.stringify(config));
+}

package/src/constants.ts

@@ -0,0 +1,16 @@
+// USDC contract addresses — env-resolved at runtime via NEXT_PUBLIC_ENVIRONMENT.
+// Fallbacks are mainnet; testnet overrides via env vars.
+export const USDC_ADDRESS_BASE: string =
+  process.env.USDC_ADDRESS_BASE ?? '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+
+export const USDC_ADDRESS_BASE_SEPOLIA: string =
+  process.env.USDC_ADDRESS_BASE_SEPOLIA ?? '0x036CbD53842c5426634e7929541eC2318f3dCF7e';
+
+export const USDC_DECIMALS = 6;
+
+export type X402ChainKey = 'base';
+
+export function getX402UsdcAddress(env?: string): string {
+  const isTestnet = env === 'testnet' || env === 'staging';
+  return isTestnet ? USDC_ADDRESS_BASE_SEPOLIA : USDC_ADDRESS_BASE;
+}

package/src/index.ts

@@ -0,0 +1,601 @@
+// x402 Mod — entry point.
+// Provides cap.moltbank.x402:
+//   buy     — fund the agent's registered x402 signer wallet on Base from the Safe
+//             via account_execute (safe-7579 session-key USDC transfer).
+//   record  — record a completed x402 payment: calls account_record_receipt
+//             (evm-local-attested verify-only) when signedTypedData is provided,
+//             then calls record_x402_payment_result to persist the x402 payment row.
+//   balances — read USDC balance of the registered x402 signer wallet from Base.
+//
+// All EVM signing delegates to the host. This mod never holds wallet keys.
+
+import { randomUUID } from 'node:crypto';
+import { createPublicClient, getAddress, http, parseAbi, type Address } from 'viem';
+import { base, baseSepolia } from 'viem/chains';
+import {
+  defineMod,
+  type DoctorCheck,
+  type ModSdkLifecycleResult,
+  type MoltbankCli,
+  useFeedback,
+  useMoltbank,
+  useState
+} from '@moltbankhq/mod-sdk';
+import { USDC_ADDRESS_BASE, USDC_ADDRESS_BASE_SEPOLIA, USDC_DECIMALS } from './constants.ts';
+import { buildErc20TransferCalldata, formatUsdc, parseUsdcAmount } from './calldata.ts';
+import { ConfigSchema, loadConfig, saveConfig, type X402Config } from './config.ts';
+import { getAccountSafeAddress, getRegisteredX402SignerAddress } from './mcp.ts';
+import { buildPolicySpec } from './policy-spec.ts';
+
+// ---------- Helpers ---------------------------------------------------------
+
+function envelopeOk(command: string, data: unknown): ModSdkLifecycleResult {
+  return { ok: true, command, data };
+}
+
+function envelopeErr(
+  command: string,
+  code: string,
+  message: string,
+  details?: unknown
+): ModSdkLifecycleResult {
+  return {
+    ok: false,
+    command,
+    error: { code, message, ...(details !== undefined ? { details } : {}) }
+  };
+}
+
+function kebabToCamel(s: string): string {
+  return s.replace(/-([a-z])/g, (_m, c: string) => c.toUpperCase());
+}
+
+function parseValue(raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+function parseModArgs(args: string[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (let i = 0; i < args.length; i += 1) {
+    const entry = args[i];
+    if (typeof entry !== 'string') continue;
+    if (entry.startsWith('--') && entry.length > 2) {
+      const eq = entry.indexOf('=');
+      if (eq >= 0) {
+        const key = kebabToCamel(entry.slice(2, eq));
+        out[key] = parseValue(entry.slice(eq + 1));
+        continue;
+      }
+      const key = kebabToCamel(entry.slice(2));
+      const next = args[i + 1];
+      if (typeof next !== 'string' || next.startsWith('--')) {
+        out[key] = true;
+        continue;
+      }
+      out[key] = parseValue(next);
+      i += 1;
+      continue;
+    }
+    const eq = entry.indexOf('=');
+    if (eq > 0) {
+      const key = kebabToCamel(entry.slice(0, eq));
+      out[key] = parseValue(entry.slice(eq + 1));
+    }
+  }
+  return out;
+}
+
+function getUsdcAddress(config: X402Config | null): string {
+  const env = process.env.NEXT_PUBLIC_ENVIRONMENT;
+  const isTestnet = env === 'testnet' || env === 'staging';
+  return isTestnet ? USDC_ADDRESS_BASE_SEPOLIA : USDC_ADDRESS_BASE;
+}
+
+function getBaseChain(config: X402Config | null) {
+  const env = process.env.NEXT_PUBLIC_ENVIRONMENT;
+  const isTestnet = env === 'testnet' || env === 'staging';
+  return isTestnet ? baseSepolia : base;
+}
+
+function getBaseRpcUrl(): string {
+  const env = process.env.NEXT_PUBLIC_ENVIRONMENT;
+  const isTestnet = env === 'testnet' || env === 'staging';
+  return isTestnet ? 'https://base-sepolia-rpc.publicnode.com' : 'https://base-rpc.publicnode.com';
+}
+
+// ---------- buy (fund x402 signer wallet) -----------------------------------
+
+async function handleBuy(
+  args: string[],
+  config: X402Config | null,
+  moltbank: MoltbankCli
+): Promise<ModSdkLifecycleResult> {
+  const parsed = parseModArgs(args);
+  const organizationName =
+    typeof parsed.organizationName === 'string'
+      ? parsed.organizationName.trim()
+      : typeof parsed.org === 'string'
+        ? parsed.org.trim()
+        : '';
+  const accountName =
+    typeof parsed.accountName === 'string'
+      ? parsed.accountName.trim()
+      : typeof parsed.account === 'string'
+        ? parsed.account.trim()
+        : '';
+
+  if (!organizationName) return envelopeErr('buy', 'INVALID_INPUT', '--org / --organization-name is required.');
+  if (!accountName) return envelopeErr('buy', 'INVALID_INPUT', '--account / --account-name is required.');
+  if (!parsed.amount) return envelopeErr('buy', 'INVALID_INPUT', '--amount is required (USDC to fund, e.g. 5 or 5.5).');
+
+  let amountRaw: bigint;
+  try {
+    amountRaw = parseUsdcAmount(parsed.amount as string | number);
+    if (amountRaw <= 0n) throw new Error('Amount must be greater than zero.');
+  } catch (error) {
+    return envelopeErr('buy', 'INVALID_INPUT', `--amount: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  const amountHuman = formatUsdc(amountRaw);
+
+  let safeAddress: string;
+  try {
+    safeAddress = getAddress(await getAccountSafeAddress(moltbank, organizationName, accountName));
+  } catch (error) {
+    return envelopeErr(
+      'buy',
+      'ACCOUNT_RESOLVE_FAILED',
+      `Could not resolve Safe address: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+
+  let signerAddress: string;
+  try {
+    const addr = await getRegisteredX402SignerAddress(moltbank);
+    if (!addr) {
+      return envelopeErr(
+        'buy',
+        'SIGNER_NOT_REGISTERED',
+        "No x402 signer wallet registered for this agent. Call 'register_x402_wallet' first."
+      );
+    }
+    signerAddress = getAddress(addr);
+  } catch (error) {
+    return envelopeErr(
+      'buy',
+      'SIGNER_RESOLVE_FAILED',
+      `Could not resolve x402 signer address: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+
+  const usdcAddress = getUsdcAddress(config);
+  const transferData = buildErc20TransferCalldata(signerAddress, amountRaw);
+  const idempotencyKey = randomUUID();
+
+  console.error(`[phase9 x402 buy] safeAddress=${safeAddress} signerAddress=${signerAddress}`);
+  console.error(`[phase9 x402 buy] amount=${amountHuman} usdc=${usdcAddress}`);
+
+  const request = {
+    modName: 'x402',
+    capability: 'cap.moltbank.x402',
+    operationId: 'x402.fund-wallet',
+    organizationName,
+    accountName,
+    chain: 'base' as const,
+    signerMode: 'safe-7579' as const,
+    execution: {
+      kind: 'evm.safe7579.call' as const,
+      calls: [{ to: usdcAddress, data: transferData }],
+      signerPolicy: 'allowance-session' as const,
+      confirmation: 'wait' as const
+    },
+    budget: {
+      asset: 'USDC',
+      amountRaw: amountRaw.toString(),
+      budgetKind: 'transfer' as const,
+      recipientAddress: signerAddress
+    },
+    audit: {
+      summary: `x402 fund signer wallet: ${amountHuman} USDC → ${signerAddress}`,
+      rail: 'evm',
+      correlators: { operationId: 'x402.fund-wallet', signerAddress }
+    },
+    idempotencyKey
+  };
+
+  try {
+    console.error(`[phase9 x402 buy] → account_execute`);
+    const result = await moltbank.host.executeOperation(request);
+    console.error(`[phase9 x402 buy] account_execute result:`, JSON.stringify(result));
+    return envelopeOk('buy', {
+      amountUsdc: amountHuman,
+      signerAddress,
+      safeAddress,
+      ...(result as object)
+    });
+  } catch (error) {
+    return envelopeErr(
+      'buy',
+      'EXECUTE_FAILED',
+      `account_execute failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+// ---------- record (persist completed x402 payment) -------------------------
+
+type SignedTypedData = {
+  domain: unknown;
+  types: unknown;
+  message: unknown;
+  signature: string;
+};
+
+function extractSignedTypedData(localPaymentResult: unknown): SignedTypedData | null {
+  if (!localPaymentResult || typeof localPaymentResult !== 'object') return null;
+  const lpr = localPaymentResult as Record<string, unknown>;
+  const sa = lpr.signedAuthorization as Record<string, unknown> | undefined;
+  if (!sa) return null;
+  const td = sa.typedData as Record<string, unknown> | undefined;
+  const sig = sa.signatureHex ?? sa.signature;
+  if (!td || typeof sig !== 'string' || !sig) return null;
+  return {
+    domain: td.domain ?? td,
+    types: td.types ?? {},
+    message: td.message ?? td,
+    signature: sig
+  };
+}
+
+async function handleRecord(
+  args: string[],
+  config: X402Config | null,
+  moltbank: MoltbankCli
+): Promise<ModSdkLifecycleResult> {
+  const parsed = parseModArgs(args);
+  const organizationName =
+    typeof parsed.organizationName === 'string'
+      ? parsed.organizationName.trim()
+      : typeof parsed.org === 'string'
+        ? parsed.org.trim()
+        : '';
+  const accountName =
+    typeof parsed.accountName === 'string'
+      ? parsed.accountName.trim()
+      : typeof parsed.account === 'string'
+        ? parsed.account.trim()
+        : '';
+  const x402Url =
+    typeof parsed.x402Url === 'string' ? parsed.x402Url.trim() : typeof parsed.url === 'string' ? parsed.url.trim() : '';
+  const paidAmount = parsed.paidAmount ?? parsed.amount;
+  const paymentTxHash = typeof parsed.paymentTxHash === 'string' ? parsed.paymentTxHash.trim() : undefined;
+  const paymentHttpStatus =
+    typeof parsed.paymentHttpStatus === 'number'
+      ? parsed.paymentHttpStatus
+      : typeof parsed.httpStatus === 'number'
+        ? parsed.httpStatus
+        : undefined;
+  const localPaymentResult =
+    typeof parsed.localPaymentResult === 'object' && parsed.localPaymentResult !== null
+      ? parsed.localPaymentResult
+      : typeof parsed.localPaymentResult === 'string'
+        ? parseValue(parsed.localPaymentResult)
+        : undefined;
+  const signedTypedDataRaw =
+    typeof parsed.signedTypedData === 'object' && parsed.signedTypedData !== null
+      ? parsed.signedTypedData
+      : typeof parsed.signedTypedData === 'string'
+        ? parseValue(parsed.signedTypedData)
+        : null;
+  const fundingProposalId = typeof parsed.fundingProposalId === 'string' ? parsed.fundingProposalId.trim() : undefined;
+  const fundingTxHash = typeof parsed.fundingTxHash === 'string' ? parsed.fundingTxHash.trim() : undefined;
+
+  if (!organizationName) return envelopeErr('record', 'INVALID_INPUT', '--org / --organization-name is required.');
+  if (!accountName) return envelopeErr('record', 'INVALID_INPUT', '--account / --account-name is required.');
+  if (!x402Url) return envelopeErr('record', 'INVALID_INPUT', '--x402-url is required.');
+  if (!paidAmount) return envelopeErr('record', 'INVALID_INPUT', '--paid-amount is required (USDC amount paid).');
+  if (!paymentHttpStatus) {
+    return envelopeErr('record', 'INVALID_INPUT', '--payment-http-status is required (HTTP status from the merchant response).');
+  }
+
+  let amountRaw: bigint;
+  try {
+    amountRaw = parseUsdcAmount(paidAmount as string | number);
+    if (amountRaw <= 0n) throw new Error('Paid amount must be greater than zero.');
+  } catch (error) {
+    return envelopeErr('record', 'INVALID_INPUT', `--paid-amount: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  const idempotencyKey = randomUUID();
+  const operationId = `x402.record-${paymentTxHash ?? idempotencyKey}`;
+
+  // Resolve signer address for attestation
+  let signerAddress: string | null = null;
+  try {
+    signerAddress = await getRegisteredX402SignerAddress(moltbank);
+  } catch {
+    // non-fatal — skip attestation if signer not resolvable
+  }
+
+  // account_record_receipt: verifies the EIP-712 attestation (evm-local-attested verify-only)
+  // and persists the full payment details as the canonical receipt in mod_execution_receipts.
+  // This is the single generic write primitive — no protocol-specific recording tool needed.
+  const signedTypedData: SignedTypedData | null =
+    (signedTypedDataRaw as SignedTypedData | null) ?? extractSignedTypedData(localPaymentResult);
+
+  const receiptRequest = {
+    modName: 'x402',
+    capability: 'cap.moltbank.x402',
+    operationId,
+    organizationName,
+    accountName,
+    chain: 'base' as const,
+    signerMode: 'evm-local-attested' as const,
+    execution: {
+      kind: 'evm.local-attested.attestation' as const,
+      signerRef: signerAddress ?? '',
+      mode: 'verify-only' as const,
+      ...(signedTypedData ? { signedTypedData } : {})
+    },
+    receipt: {
+      protocolReceiptKind: 'x402.payment',
+      payload: {
+        id: paymentTxHash ?? operationId,
+        x402Url,
+        amountRaw: amountRaw.toString(),
+        paymentTxHash: paymentTxHash ?? null,
+        paymentHttpStatus: paymentHttpStatus ?? null,
+        fundingProposalId: fundingProposalId ?? null,
+        fundingTxHash: fundingTxHash ?? null,
+        signerAddress: signerAddress ?? null,
+        ...(localPaymentResult !== undefined ? { localPaymentResult } : {})
+      }
+    },
+    audit: {
+      summary: `x402 payment recorded: ${x402Url} ${formatUsdc(amountRaw)} USDC`,
+      rail: 'evm',
+      correlators: { x402Url, operationId }
+    },
+    idempotencyKey
+  };
+
+  console.error(`[phase9 x402 record] x402Url=${x402Url} amount=${formatUsdc(amountRaw)}`);
+  console.error(`[phase9 x402 record] signerAddress=${signerAddress} hasTypedData=${signedTypedData !== null}`);
+  console.error(`[phase9 x402 record] → account_record_receipt evm-local-attested verify-only`);
+
+  let receiptResult: unknown;
+  try {
+    receiptResult = await moltbank.host.recordReceipt(receiptRequest);
+    console.error(`[phase9 x402 record] account_record_receipt result:`, JSON.stringify(receiptResult));
+  } catch (error) {
+    return envelopeErr(
+      'record',
+      'RECORD_FAILED',
+      `account_record_receipt failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+
+  const r = receiptResult as { executionId?: string | null; status?: string } | null;
+  return envelopeOk('record', {
+    x402Url,
+    amountUsdc: formatUsdc(amountRaw),
+    paymentTxHash: paymentTxHash ?? null,
+    executionId: r?.executionId ?? null,
+    status: r?.status ?? 'recorded',
+    attestationVerified: signedTypedData !== null
+  });
+}
+
+// ---------- balances ---------------------------------------------------------
+
+const ERC20_BALANCE_ABI = parseAbi(['function balanceOf(address) returns (uint256)']);
+
+async function handleBalances(
+  args: string[],
+  config: X402Config | null,
+  moltbank: MoltbankCli
+): Promise<ModSdkLifecycleResult> {
+  let signerAddress: string | null;
+  try {
+    signerAddress = await getRegisteredX402SignerAddress(moltbank);
+  } catch (error) {
+    return envelopeErr(
+      'balances',
+      'SIGNER_RESOLVE_FAILED',
+      `Could not resolve x402 signer address: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+
+  if (!signerAddress) {
+    return envelopeErr(
+      'balances',
+      'SIGNER_NOT_REGISTERED',
+      "No x402 signer wallet registered. Call 'register_x402_wallet' first."
+    );
+  }
+
+  const chain = getBaseChain(config);
+  const rpcUrl = getBaseRpcUrl();
+  const usdcAddress = getUsdcAddress(config);
+
+  console.error(`[phase9 x402 balances] signerAddress=${signerAddress} usdc=${usdcAddress} rpc=${rpcUrl}`);
+
+  const publicClient = createPublicClient({ chain, transport: http(rpcUrl) });
+
+  try {
+    const balanceRaw = (await publicClient.readContract({
+      address: usdcAddress as Address,
+      abi: ERC20_BALANCE_ABI,
+      functionName: 'balanceOf',
+      args: [getAddress(signerAddress)]
+    })) as bigint;
+
+    return envelopeOk('balances', {
+      signerAddress: getAddress(signerAddress),
+      chain: 'base',
+      usdc: {
+        balanceRaw: balanceRaw.toString(),
+        balanceUsdc: formatUsdc(balanceRaw),
+        decimals: USDC_DECIMALS,
+        token: usdcAddress
+      }
+    });
+  } catch (error) {
+    return envelopeErr(
+      'balances',
+      'CHAIN_READ_FAILED',
+      `Failed to read USDC balance from chain: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+// ---------- doctor checks ---------------------------------------------------
+
+function x402DoctorChecks(moltbank: MoltbankCli | undefined): DoctorCheck[] {
+  return [
+    {
+      key: 'moltbank-cli',
+      run: async () => {
+        if (!moltbank) {
+          return {
+            key: 'moltbank-cli',
+            ok: false,
+            message: 'Moltbank CLI handle not available. Run via `moltbank mod`.',
+            code: 'MOLTBANK_CLI_MISSING',
+            remediation: 'Ensure the Moltbank CLI is installed and run commands through `moltbank mod run x402`.'
+          };
+        }
+        return { key: 'moltbank-cli', ok: true, message: 'Moltbank CLI handle is available.' };
+      }
+    },
+    {
+      key: 'x402-signer-registered',
+      run: async () => {
+        if (!moltbank) {
+          return { key: 'x402-signer-registered', ok: false, message: 'CLI handle missing.', code: 'MOLTBANK_CLI_MISSING' };
+        }
+        try {
+          const addr = await getRegisteredX402SignerAddress(moltbank);
+          if (!addr) {
+            return {
+              key: 'x402-signer-registered',
+              ok: false,
+              message: 'No x402 signer wallet registered.',
+              code: 'SIGNER_NOT_REGISTERED',
+              remediation: "Call 'register_x402_wallet' with your Base EOA wallet address."
+            };
+          }
+          return { key: 'x402-signer-registered', ok: true, message: `x402 signer wallet registered: ${addr}` };
+        } catch (error) {
+          return {
+            key: 'x402-signer-registered',
+            ok: false,
+            message: `Failed to check signer: ${error instanceof Error ? error.message : String(error)}`,
+            code: 'CHECK_FAILED'
+          };
+        }
+      }
+    }
+  ];
+}
+
+// ---------- createMod / dispatch --------------------------------------------
+
+export type CreateModOptions = {
+  moltbank?: MoltbankCli;
+  requireMoltbankCli?: boolean;
+};
+
+export function createMod(opts: CreateModOptions = {}) {
+  const sdkMod = defineMod<X402Config>({
+    name: 'x402',
+    requireMoltbankCli: opts.requireMoltbankCli,
+    ...(opts.moltbank ? { moltbank: opts.moltbank } : {}),
+    config: {
+      schema: ConfigSchema,
+      setup: async (_ctx) => {
+        const next: X402Config = { defaultChain: 'base' };
+        if (opts.moltbank) await saveConfig(next, opts.moltbank);
+        return next;
+      }
+    },
+    doctor: ({ moltbank }) => x402DoctorChecks(moltbank),
+    estimate: () => ({
+      totalUsdc: 0,
+      band: { lowUsdc: 0, highUsdc: 0 },
+      steps: [
+        {
+          step: 'buy-gas',
+          usdc: 0,
+          description: 'ERC20 transfer gas on Base (~25k gas at current base fee). Covered by the session-key wallet.'
+        }
+      ],
+      notes: [
+        'buy transfers USDC from the Safe to the registered x402 signer wallet.',
+        'record does not spend additional USDC — it only persists the payment receipt.',
+        'Gas for the buy transfer is paid by the session-key wallet (not the Safe).'
+      ]
+    }),
+    run: async () => {
+      throw new Error('x402 run is not implemented. Use buy / record / balances directly.');
+    },
+    status: async () => ({
+      modName: 'x402',
+      configured: true,
+      provides: ['cap.moltbank.x402']
+    })
+  });
+
+  async function dispatch(
+    subcommand: string,
+    argv: { args?: string[]; text?: string; runId?: string }
+  ): Promise<ModSdkLifecycleResult> {
+    const cmd = (subcommand || 'help').trim().toLowerCase();
+
+    if (cmd === 'buy' || cmd === 'record' || cmd === 'balances') {
+      if (!opts.moltbank) {
+        return envelopeErr(cmd, 'INVALID_INPUT', 'x402: moltbank CLI handle required.');
+      }
+      const config = opts.moltbank ? await loadConfig(opts.moltbank) : null;
+      if (cmd === 'buy') return handleBuy(argv.args ?? [], config, opts.moltbank);
+      if (cmd === 'record') return handleRecord(argv.args ?? [], config, opts.moltbank);
+      return handleBalances(argv.args ?? [], config, opts.moltbank);
+    }
+
+    if (cmd === 'policy-spec') {
+      const env = process.env.NEXT_PUBLIC_ENVIRONMENT;
+      return envelopeOk('policy-spec', buildPolicySpec(env));
+    }
+
+    if (cmd === 'help') {
+      return {
+        ok: true,
+        command: 'help',
+        data: {
+          modName: 'x402',
+          subcommands: ['setup', 'doctor', 'estimate', 'status', 'feedback', 'buy', 'record', 'balances', 'help'],
+          usage: {
+            buy: 'x402-mod buy --org <org> --account <account> --amount <usdc>',
+            record:
+              'x402-mod record --org <org> --account <account> --x402-url <url> --paid-amount <usdc> --payment-http-status <code> [--payment-tx-hash <0x...>] [--local-payment-result <json>]',
+            balances: 'x402-mod balances'
+          }
+        }
+      };
+    }
+
+    return sdkMod.dispatch(cmd, argv);
+  }
+
+  return { dispatch };
+}
+
+const productionMod = createMod({ moltbank: useMoltbank(), requireMoltbankCli: true });
+export const dispatchX402 = productionMod.dispatch;
+export const dispatch = productionMod.dispatch;
+
+export { useFeedback, useMoltbank, useState };

package/src/mcp.ts

@@ -0,0 +1,62 @@
+import type { MoltbankCli } from '@moltbankhq/mod-sdk';
+
+export async function callMcpTool<T = unknown>(
+  moltbank: MoltbankCli,
+  toolName: string,
+  args: Record<string, unknown>
+): Promise<T> {
+  const cliArgs = ['mcp', 'call', '--tool', toolName, '--body', JSON.stringify(args), '--json'];
+  try {
+    return await moltbank.invoke<T>(cliArgs);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const upstream = error as { code?: unknown; cliCode?: unknown; details?: unknown } | undefined;
+    const enriched = new Error(`moltbank mcp call ${toolName}: ${message}`) as Error & {
+      upstreamCode?: string;
+      upstreamDetails?: unknown;
+    };
+    const code =
+      typeof upstream?.cliCode === 'string'
+        ? upstream.cliCode
+        : typeof upstream?.code === 'string'
+          ? upstream.code
+          : undefined;
+    if (code) enriched.upstreamCode = code;
+    if (typeof upstream?.details !== 'undefined') enriched.upstreamDetails = upstream.details;
+    throw enriched;
+  }
+}
+
+export type AccountDetailsPayload = {
+  address: string;
+  organizationName?: string;
+  accountName?: string;
+};
+
+export async function getAccountSafeAddress(
+  moltbank: MoltbankCli,
+  organizationName: string,
+  accountName: string
+): Promise<string> {
+  const payload = await callMcpTool<AccountDetailsPayload>(moltbank, 'get_account_details', {
+    organizationName,
+    accountName
+  });
+  if (!payload || typeof payload !== 'object' || typeof payload.address !== 'string') {
+    throw new Error(`get_account_details returned no address (got ${JSON.stringify(payload)}).`);
+  }
+  return payload.address;
+}
+
+export type AgentWalletStatusPayload = {
+  agentId?: string;
+  agentLabel?: string;
+  organizationId?: string;
+  x402WalletAddress?: string | null;
+  status?: string;
+};
+
+export async function getRegisteredX402SignerAddress(moltbank: MoltbankCli): Promise<string | null> {
+  const payload = await callMcpTool<AgentWalletStatusPayload>(moltbank, 'get_agent_wallet_status', {});
+  return payload?.x402WalletAddress ?? null;
+}

package/src/policy-spec.ts

@@ -0,0 +1,37 @@
+import type { ModPolicySpec } from '@moltbankhq/mod-sdk';
+import { USDC_ADDRESS_BASE, USDC_DECIMALS } from './constants.ts';
+
+const SELECTOR_ERC20_TRANSFER = 'a9059cbb';
+
+export function buildPolicySpec(env?: string): ModPolicySpec {
+  const isTestnet = env === 'testnet' || env === 'staging';
+  const usdcAddress = isTestnet
+    ? (process.env.USDC_ADDRESS_BASE_SEPOLIA ?? '0x036CbD53842c5426634e7929541eC2318f3dCF7e')
+    : USDC_ADDRESS_BASE;
+
+  return {
+    modName: 'x402',
+    chain: 'base',
+    signerModes: ['safe-7579', 'evm-local-attested'],
+    receipts: ['x402.payment'],
+    facets: [
+      {
+        id: 'x402.fund-signer',
+        chain: 'base',
+        target: usdcAddress,
+        selector: SELECTOR_ERC20_TRANSFER,
+        asset: usdcAddress,
+        assetDecimals: USDC_DECIMALS,
+        label: 'x402 Fund Signer Wallet',
+        budgetCurrency: 'USDC',
+        defaultPeriod: 'Month',
+        deductsFromAllowance: true
+      }
+    ],
+    setupActions: [],
+    labels: {
+      buy: { description: 'x402 USDC Fund', direction: 'out' },
+      record: { description: 'x402 Payment Record', direction: 'out' }
+    }
+  };
+}