@layr-labs/ecloud-cli 1.0.0-devep7 → 1.0.0

package/dist/commands/billing/__tests__/top-up.test.js

@@ -11,6 +11,7 @@ import {
   createComputeModule,
   createBillingModule,
   createBuildModule,
+  createAdminModule,
   getEnvironmentConfig as getEnvironmentConfig3,
   requirePrivateKey
 } from "@layr-labs/ecloud-sdk";
@@ -250,7 +251,7 @@ var commonFlags = {
     required: false,
     description: "Deployment environment to use",
     env: "ECLOUD_ENV",
-    default: async () => getDefaultEnvironment() || (getBuildType2() === "dev" ? "sepolia-dev" : "sepolia")
+    default: async () => getDefaultEnvironment() || (getBuildType2() === "dev" ? "sepolia-dev" : "mainnet-alpha")
   }),
   "private-key": Flags.string({
     required: false,
@@ -280,6 +281,12 @@ var commonFlags = {
   nonce: Flags.string({
     required: false,
     description: 'Override transaction nonce (integer or "latest" to replace a stuck transaction)'
+  }),
+  "non-interactive": Flags.boolean({
+    required: false,
+    description: "Assume non-interactive mode: default safe prompts and error all-at-once on missing required inputs",
+    env: "ECLOUD_NON_INTERACTIVE",
+    default: false
   })
 };
 async function validateCommonFlags(flags, options) {
@@ -312,7 +319,8 @@ async function createBillingClient(flags) {
     walletClient,
     publicClient,
     environment,
-    skipTelemetry: true
+    skipTelemetry: true,
+    privateKey
   });
 }
 
@@ -380,22 +388,299 @@ async function withTelemetry(command, action) {
   }
 }
 
+// src/commands/billing/top-up.ts
+import {
+  getBillingEnvironmentConfig,
+  getBuildType as getBuildType4,
+  requirePrivateKey as requirePrivateKey2,
+  addHexPrefix as addHexPrefix2
+} from "@layr-labs/ecloud-sdk";
+import { privateKeyToAccount as privateKeyToAccount4 } from "viem/accounts";
+
+// src/x402/client.ts
+import { randomBytes as randomBytes2 } from "crypto";
+
+// src/x402/types.ts
+var USDC_DOMAINS = {
+  "eip155:84532": { name: "USDC", version: "2" },
+  // Base Sepolia
+  "eip155:8453": { name: "USD Coin", version: "2" }
+  // Base mainnet
+};
+function usdcDomainForNetwork(network, extra) {
+  const extraName = typeof extra?.name === "string" ? extra.name : void 0;
+  const extraVersion = typeof extra?.version === "string" ? extra.version : void 0;
+  if (extraName && extraVersion) {
+    return { name: extraName, version: extraVersion };
+  }
+  const fromTable = USDC_DOMAINS[network];
+  if (fromTable) {
+    return { name: extraName ?? fromTable.name, version: extraVersion ?? fromTable.version };
+  }
+  throw new Error(
+    `Cannot determine USDC EIP-712 domain for unknown x402 network "${network}"; the challenge must supply extra.name and extra.version.`
+  );
+}
+
+// src/x402/client.ts
+var DEFAULT_TIMEOUT_MS = 6e4;
+var X402Error = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "X402Error";
+    this.status = status;
+  }
+};
+function chainIdFromNetwork(network) {
+  const m = /^eip155:(\d+)$/.exec(network);
+  if (!m) {
+    throw new X402Error(`Unsupported x402 network "${network}" (expected eip155:<chainId>)`);
+  }
+  return Number(m[1]);
+}
+function parseChallenge(body) {
+  const reqs = body?.accepts?.[0];
+  if (!reqs) {
+    throw new X402Error("x402 challenge had no payment requirements (accepts was empty)");
+  }
+  if (reqs.scheme !== "exact") {
+    throw new X402Error(`Unsupported x402 scheme "${reqs.scheme}" (expected "exact")`);
+  }
+  chainIdFromNetwork(reqs.network);
+  const paymentId = reqs.extra?.paymentId;
+  if (typeof paymentId !== "string" || paymentId.length === 0) {
+    throw new X402Error("x402 challenge requirements missing extra.paymentId");
+  }
+  return reqs;
+}
+var TRANSFER_WITH_AUTHORIZATION_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" }
+  ]
+};
+async function buildSignedPayload(reqs, account, nowSeconds, randomNonce) {
+  const chainId = chainIdFromNetwork(reqs.network);
+  const domainInfo = usdcDomainForNetwork(reqs.network, reqs.extra);
+  const validAfter = nowSeconds - 600;
+  const validBefore = nowSeconds + 3600;
+  const nonce = randomNonce();
+  const authorization = {
+    from: account.address,
+    to: reqs.payTo,
+    value: reqs.amount,
+    // signed verbatim — never recomputed
+    validAfter: String(validAfter),
+    validBefore: String(validBefore),
+    nonce
+  };
+  const signature = await account.signTypedData({
+    domain: {
+      name: domainInfo.name,
+      version: domainInfo.version,
+      chainId,
+      verifyingContract: reqs.asset
+    },
+    types: TRANSFER_WITH_AUTHORIZATION_TYPES,
+    primaryType: "TransferWithAuthorization",
+    message: {
+      from: account.address,
+      to: reqs.payTo,
+      value: BigInt(reqs.amount),
+      validAfter: BigInt(validAfter),
+      validBefore: BigInt(validBefore),
+      nonce
+    }
+  });
+  return {
+    x402Version: 2,
+    payload: { signature, authorization },
+    accepted: reqs
+    // echoed verbatim; carries extra.paymentId
+  };
+}
+function encodePaymentHeader(payload) {
+  return Buffer.from(JSON.stringify(payload), "utf8").toString("base64");
+}
+function createNonce() {
+  return "0x" + randomBytes2(32).toString("hex");
+}
+function decodeReceipt(headerValue) {
+  if (!headerValue) return void 0;
+  try {
+    return JSON.parse(Buffer.from(headerValue, "base64").toString("utf8"));
+  } catch {
+    return void 0;
+  }
+}
+async function readBody(resp) {
+  const text = await resp.text();
+  try {
+    return text ? JSON.parse(text) : {};
+  } catch {
+    return { error: text };
+  }
+}
+function describeFetchError(err, url, timeoutMs) {
+  if (err instanceof X402Error) return err;
+  const name = err?.name;
+  if (name === "AbortError" || name === "TimeoutError") {
+    return new X402Error(`x402 request to ${url} timed out after ${timeoutMs}ms`);
+  }
+  const cause = err?.cause;
+  const code = cause?.code ?? err?.code;
+  const detail = [code, cause?.message ?? err?.message].filter(Boolean).join(": ") || String(err);
+  let hint = "";
+  switch (code) {
+    case "ENOTFOUND":
+    case "EAI_AGAIN":
+      hint = " \u2014 the platform host could not be resolved; check --api-url / ECLOUD_API_URL";
+      break;
+    case "ECONNREFUSED":
+      hint = " \u2014 the platform host refused the connection; is the API URL correct and reachable?";
+      break;
+    case "ETIMEDOUT":
+    case "ECONNRESET":
+      hint = " \u2014 the connection dropped; the host may be unreachable from this network";
+      break;
+  }
+  return new X402Error(`x402 request to ${url} failed: ${detail}${hint}`);
+}
+async function purchaseCreditsX402(opts) {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const body = JSON.stringify({ amountCents: opts.amountCents });
+  const log = (msg) => {
+    if (opts.verbose) console.error(`[x402] ${msg}`);
+  };
+  const request = async (label, headers) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const startedAt = Date.now();
+    log(`${label}: POST ${opts.url}`);
+    try {
+      const resp = await doFetch(opts.url, { method: "POST", headers, body, signal: controller.signal });
+      log(`${label}: \u2190 HTTP ${resp.status} (${Date.now() - startedAt}ms)`);
+      return resp;
+    } catch (err) {
+      log(
+        `${label}: transport error: ${err?.name ?? "Error"}: ${err?.message ?? err}` + (err?.cause ? ` (cause: ${err.cause.code ?? ""} ${err.cause.message ?? ""})` : "")
+      );
+      throw describeFetchError(err, opts.url, timeoutMs);
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+  log(`endpoint ${opts.url} \u2014 requesting ${opts.amountCents} cents of credits`);
+  const challengeResp = await request("challenge", { "Content-Type": "application/json" });
+  if (challengeResp.status !== 402) {
+    const errBody = await readBody(challengeResp);
+    log(
+      `challenge: expected 402, got ${challengeResp.status}; body: ${JSON.stringify(errBody)}`
+    );
+    throw new X402Error(
+      errBody?.error ?? `x402 challenge failed (HTTP ${challengeResp.status})`,
+      challengeResp.status
+    );
+  }
+  const reqs = parseChallenge(await readBody(challengeResp));
+  log(
+    `challenge: scheme=${reqs.scheme} network=${reqs.network} asset=${reqs.asset} amount=${reqs.amount} payTo=${reqs.payTo} paymentId=${reqs.extra?.paymentId}`
+  );
+  const payload = await buildSignedPayload(
+    reqs,
+    opts.account,
+    Math.floor(Date.now() / 1e3),
+    createNonce
+  );
+  const header = encodePaymentHeader(payload);
+  log(
+    `settle: signed authorization from=${payload.payload.authorization.from} validBefore=${payload.payload.authorization.validBefore}; sending X-PAYMENT (${header.length} chars)`
+  );
+  const settleResp = await request("settle", {
+    "Content-Type": "application/json",
+    "X-PAYMENT": header
+  });
+  if (settleResp.status !== 201) {
+    const errBody = await readBody(settleResp);
+    log(`settle: expected 201, got ${settleResp.status}; body: ${JSON.stringify(errBody)}`);
+    const serverMsg = typeof errBody?.error === "string" ? `: ${errBody.error}` : "";
+    switch (settleResp.status) {
+      case 402:
+        throw new X402Error(`x402 payment verification failed or the pending purchase expired${serverMsg}`, 402);
+      case 404:
+        throw new X402Error(`x402 target not found, or the pending purchase expired${serverMsg}`, 404);
+      case 409:
+        throw new X402Error(`x402 amount or target mismatch with the pending purchase${serverMsg}`, 409);
+      case 502:
+        throw new X402Error(`x402 settlement failed at the payment facilitator${serverMsg}`, 502);
+      default:
+        throw new X402Error(`x402 settlement failed (HTTP ${settleResp.status})${serverMsg}`, settleResp.status);
+    }
+  }
+  const ok = await readBody(settleResp);
+  const receipt = decodeReceipt(settleResp.headers.get("x-payment-response"));
+  const txHash = ok.txHash ?? receipt?.transaction ?? "";
+  const targetAddress = typeof ok.appId === "string" ? ok.appId : typeof ok.creatorAddr === "string" ? ok.creatorAddr : void 0;
+  const targetType = typeof ok.appId === "string" ? "app" : typeof ok.creatorAddr === "string" ? "creator" : void 0;
+  log(
+    `settle: 201 \u2014 txHash=${txHash} creditedCents=${ok.creditedCents} target=${targetType ?? "?"}:${targetAddress ?? "?"}`
+  );
+  return {
+    txHash,
+    paymentId: ok.paymentId ?? reqs.extra?.paymentId ?? "",
+    creditedCents: typeof ok.creditedCents === "number" ? ok.creditedCents : opts.amountCents,
+    targetType,
+    targetAddress
+  };
+}
+
 // src/commands/billing/top-up.ts
 var POLL_INTERVAL_MS = 5e3;
 var POLL_TIMEOUT_MS = 3 * 60 * 1e3;
+function resolveX402Target(flags, walletAddress) {
+  if (flags.app && flags.creator) {
+    throw new Error("--app and --creator are mutually exclusive");
+  }
+  if (flags.app) return { type: "app", address: flags.app };
+  if (flags.creator) return { type: "creator", address: flags.creator };
+  return { type: "creator", address: walletAddress };
+}
+function buildX402Url(baseUrl, target) {
+  const base = baseUrl.replace(/\/+$/, "");
+  const segment = target.type === "app" ? "apps" : "creators";
+  return `${base}/${segment}/${target.address}/x402-credits`;
+}
+function resolveX402BaseUrl(flags) {
+  const fromFlag = flags["api-url"];
+  if (fromFlag) return fromFlag.replace(/\/+$/, "");
+  const { billingApiServerURL } = getBillingEnvironmentConfig(getBuildType4());
+  if (billingApiServerURL) return billingApiServerURL.replace(/\/+$/, "");
+  throw new Error(
+    "No billing API URL configured; pass --api-url or set ECLOUD_API_URL / ECLOUD_BILLING_API_URL."
+  );
+}
 var BillingTopUp = class _BillingTopUp extends Command {
-  static description = "Purchase EigenCompute credits with USDC or credit card";
+  static description = "Purchase EigenCompute credits with USDC, credit card, or x402";
   static examples = [
     "<%= config.bin %> billing top-up",
     "<%= config.bin %> billing top-up --method usdc --amount 50",
-    "<%= config.bin %> billing top-up --method card --amount 25"
+    "<%= config.bin %> billing top-up --method card --amount 25",
+    "<%= config.bin %> billing top-up --method x402 --amount 50",
+    "<%= config.bin %> billing top-up --method x402 --amount 50 --app 0xApp...",
+    "<%= config.bin %> billing top-up --method x402 --amount 50 --creator 0xCreator..."
   ];
   static flags = {
     ...commonFlags,
     method: Flags2.string({
       required: false,
-      description: "Payment method: usdc (on-chain) or card (credit card)",
-      options: ["usdc", "card"]
+      description: "Payment method: usdc (on-chain), card (credit card), or x402 (USDC over x402)",
+      options: ["usdc", "card", "x402"]
     }),
     amount: Flags2.string({
       required: false,
@@ -411,6 +696,24 @@ var BillingTopUp = class _BillingTopUp extends Command {
       default: "compute",
       options: ["compute"],
       env: "ECLOUD_PRODUCT_ID"
+    }),
+    chain: Flags2.string({
+      required: false,
+      description: "Blockchain network for USDC payment: ethereum or base",
+      options: ["ethereum", "base"]
+    }),
+    creator: Flags2.string({
+      required: false,
+      description: "x402: creator address to credit (defaults to your wallet). Mutually exclusive with --app."
+    }),
+    app: Flags2.string({
+      required: false,
+      description: "x402: app address to credit. Mutually exclusive with --creator."
+    }),
+    "api-url": Flags2.string({
+      required: false,
+      description: "x402: override the billing API base URL (defaults to the environment's billing API)",
+      env: "ECLOUD_API_URL"
     })
   };
   async run() {
@@ -443,25 +746,39 @@ ${chalk2.bold("Purchase EigenCompute credits")}`);
         message: "How would you like to pay?",
         choices: [
           { value: "card", name: "Credit card" },
-          { value: "usdc", name: "USDC (on-chain)" }
+          { value: "usdc", name: "USDC (on-chain)" },
+          { value: "x402", name: "USDC (x402)" }
         ]
       });
       if (method === "usdc") {
         await this.handleUsdc(billing, flags, walletAddress, targetAccount, baselineTotal);
+      } else if (method === "x402") {
+        await this.handleX402(billing, flags, walletAddress, baselineTotal);
       } else {
         await this.handleCard(billing, flags, baselineTotal);
       }
     });
   }
   async handleUsdc(billing, flags, walletAddress, targetAccount, baselineTotal) {
-    const onChainState = await billing.getTopUpInfo();
+    let selectedChain = "ethereum";
+    if (billing.hasBaseSupport()) {
+      selectedChain = flags.chain ?? await select2({
+        message: "Which network?",
+        choices: [
+          { value: "ethereum", name: "Ethereum" },
+          { value: "base", name: "Base" }
+        ]
+      });
+    }
+    const onChainState = await billing.getTopUpInfo({ chain: selectedChain });
     const { usdcBalance, minimumPurchase } = onChainState;
     const balanceFormatted = formatUnits(usdcBalance, 6);
     this.log(`  ${chalk2.bold("USDC:")}    ${balanceFormatted} USDC`);
     if (usdcBalance === BigInt(0)) {
+      const networkName = selectedChain === "base" ? "Base Sepolia" : "Sepolia";
       this.log(`
 ${chalk2.yellow("  No USDC in wallet.")}`);
-      this.log(`  Send USDC on Sepolia to: ${chalk2.cyan(walletAddress)}`);
+      this.log(`  Send USDC on ${networkName} to: ${chalk2.cyan(walletAddress)}`);
       this.log(`  Then re-run: ${chalk2.cyan("ecloud billing top-up")}
 `);
       return;
@@ -494,7 +811,8 @@ ${chalk2.yellow("  No USDC in wallet.")}`);
   Purchasing ${chalk2.bold(`$${amountFloat.toFixed(2)}`)} in credits...`);
     const { txHash } = await billing.topUp({
       amount: amountRaw,
-      account: targetAccount
+      account: targetAccount,
+      chain: selectedChain
     });
     this.log(`  ${chalk2.green("\u2713")} Transaction confirmed: ${txHash}`);
     await this.pollForCredits(billing, flags, baselineTotal, amountFloat);
@@ -549,6 +867,66 @@ ${chalk2.yellow("  No USDC in wallet.")}`);
     }
     await this.pollForCredits(billing, flags, baselineTotal, dollars);
   }
+  async handleX402(billing, flags, walletAddress, baselineTotal) {
+    const MINIMUM_DOLLARS = 5;
+    const target = resolveX402Target(
+      { creator: flags.creator, app: flags.app },
+      walletAddress
+    );
+    const targetIsSelf = target.address.toLowerCase() === walletAddress.toLowerCase();
+    const baseUrl = resolveX402BaseUrl({ "api-url": flags["api-url"] });
+    const url = buildX402Url(baseUrl, target);
+    if (flags.verbose) {
+      console.error(`[x402] billing API base URL: ${baseUrl}`);
+      console.error(`[x402] endpoint: ${url}`);
+      console.error(`[x402] target: ${target.type} ${target.address} (self=${targetIsSelf})`);
+    }
+    const amountStr = flags.amount ?? await input2({
+      message: `How many dollars of credits to purchase? (minimum: $${MINIMUM_DOLLARS})`,
+      validate: (val) => {
+        const n = parseInt(val, 10);
+        if (isNaN(n) || n <= 0) return "Enter a positive whole number";
+        if (n.toString() !== val.trim()) return "Enter a whole dollar amount (no cents)";
+        if (n < MINIMUM_DOLLARS) return `Minimum purchase is $${MINIMUM_DOLLARS}`;
+        return true;
+      }
+    });
+    const dollars = parseInt(amountStr, 10);
+    if (isNaN(dollars) || dollars < MINIMUM_DOLLARS) {
+      this.error(`Minimum purchase is $${MINIMUM_DOLLARS}`);
+    }
+    const amountCents = dollars * 100;
+    if (target.type === "app") {
+      this.log(`  ${chalk2.bold("Crediting app:")} ${target.address}`);
+    } else if (!targetIsSelf) {
+      this.log(`  ${chalk2.bold("Crediting creator:")} ${target.address}`);
+    }
+    const { key } = await requirePrivateKey2({ privateKey: flags["private-key"] });
+    const account = privateKeyToAccount4(addHexPrefix2(key));
+    this.log(`
+  Purchasing ${chalk2.bold(`$${dollars}`)} in credits over x402...`);
+    const result = await purchaseCreditsX402({
+      url,
+      amountCents,
+      account,
+      verbose: flags.verbose
+    });
+    this.log(`  ${chalk2.green("\u2713")} x402 payment settled`);
+    this.log(`  ${chalk2.bold("Transaction:")} ${result.txHash}`);
+    this.log(`  ${chalk2.bold("Payment ID:")}  ${result.paymentId}`);
+    this.log(
+      `  ${chalk2.bold("Credits added:")} ${chalk2.cyan(`$${(result.creditedCents / 100).toFixed(2)}`)}`
+    );
+    if (targetIsSelf) {
+      await this.pollForCredits(billing, flags, baselineTotal, dollars);
+    } else {
+      this.log(
+        `
+  Credits applied to ${target.type} ${target.address}. Check that account's balance with: ecloud billing status
+`
+      );
+    }
+  }
   async pollForCredits(billing, flags, baselineTotal, amountPurchased) {
     this.log(chalk2.gray("\n  Waiting for credits to appear..."));
     const startTime = Date.now();
@@ -604,6 +982,22 @@ vi.mock("@inquirer/prompts", () => ({
 vi.mock("open", () => ({
   default: vi.fn()
 }));
+vi.mock("../../../x402/client", () => ({
+  purchaseCreditsX402: vi.fn()
+}));
+vi.mock("@layr-labs/ecloud-sdk", async (importOriginal) => {
+  const actual = await importOriginal();
+  return {
+    ...actual,
+    requirePrivateKey: vi.fn().mockResolvedValue({
+      key: "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80",
+      source: "test"
+    }),
+    getBillingEnvironmentConfig: vi.fn().mockReturnValue({
+      billingApiServerURL: "https://platform-dev.example"
+    })
+  };
+});
 var WALLET_ADDRESS = "0x1234567890abcdef1234567890abcdef12345678";
 var TX_HASH = "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890";
 describe("ecloud billing top-up", () => {
@@ -619,8 +1013,10 @@ describe("ecloud billing top-up", () => {
       getTopUpInfo: vi.fn(),
       topUp: vi.fn(),
       getPaymentMethods: vi.fn(),
-      purchaseCredits: vi.fn()
+      purchaseCredits: vi.fn(),
+      hasBaseSupport: vi.fn()
     };
+    mockBilling.hasBaseSupport.mockReturnValue(false);
     createBillingClient.mockResolvedValue(mockBilling);
     input3.mockResolvedValue("50");
   });
@@ -680,7 +1076,8 @@ describe("ecloud billing top-up", () => {
     expect(fullOutput).toContain("$60.00");
     expect(mockBilling.topUp).toHaveBeenCalledWith({
       amount: BigInt(5e7),
-      account: WALLET_ADDRESS
+      account: WALLET_ADDRESS,
+      chain: "ethereum"
     });
   });
   it("zero USDC balance: exits with fund wallet message", async () => {
@@ -715,7 +1112,8 @@ describe("ecloud billing top-up", () => {
     expect(fullOutput).toContain(targetAccount);
     expect(mockBilling.topUp).toHaveBeenCalledWith({
       amount: BigInt(5e7),
-      account: targetAccount
+      account: targetAccount,
+      chain: "ethereum"
     });
   });
   it("billing API poll timeout: shows timeout message", async () => {
@@ -758,6 +1156,68 @@ describe("ecloud billing top-up", () => {
     expect(fullOutput).toContain("Transaction confirmed");
     expect(fullOutput).toContain("Credits haven't appeared yet");
   });
+  it("usdc: prompts for chain selection when Base is available", async () => {
+    mockBilling.hasBaseSupport.mockReturnValue(true);
+    setupOnChainState();
+    mockBilling.topUp.mockResolvedValue({ txHash: TX_HASH, walletAddress: WALLET_ADDRESS });
+    mockBilling.getStatus.mockResolvedValueOnce({ subscriptionStatus: "active", remainingCredits: 10 }).mockResolvedValueOnce({ subscriptionStatus: "active", remainingCredits: 60 });
+    select3.mockResolvedValue("base");
+    const cmd = createCommand({ amount: "50", method: "usdc" });
+    const promise = cmd.run();
+    for (let i = 0; i < 10; i++) {
+      await vi.advanceTimersByTimeAsync(5e3);
+    }
+    await promise;
+    expect(select3).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: "Which network?",
+        choices: expect.arrayContaining([
+          expect.objectContaining({ value: "base" }),
+          expect.objectContaining({ value: "ethereum" })
+        ])
+      })
+    );
+    expect(mockBilling.getTopUpInfo).toHaveBeenCalledWith({ chain: "base" });
+    expect(mockBilling.topUp).toHaveBeenCalledWith({
+      amount: BigInt(5e7),
+      account: WALLET_ADDRESS,
+      chain: "base"
+    });
+  });
+  it("usdc: skips chain prompt when Base is not configured", async () => {
+    mockBilling.hasBaseSupport.mockReturnValue(false);
+    setupOnChainState();
+    mockBilling.topUp.mockResolvedValue({ txHash: TX_HASH, walletAddress: WALLET_ADDRESS });
+    mockBilling.getStatus.mockResolvedValueOnce({ subscriptionStatus: "active", remainingCredits: 10 }).mockResolvedValueOnce({ subscriptionStatus: "active", remainingCredits: 60 });
+    const cmd = createCommand({ amount: "50", method: "usdc" });
+    const promise = cmd.run();
+    for (let i = 0; i < 10; i++) {
+      await vi.advanceTimersByTimeAsync(5e3);
+    }
+    await promise;
+    expect(mockBilling.topUp).toHaveBeenCalledWith({
+      amount: BigInt(5e7),
+      account: WALLET_ADDRESS,
+      chain: "ethereum"
+    });
+  });
+  it("usdc: --chain flag skips network prompt", async () => {
+    mockBilling.hasBaseSupport.mockReturnValue(true);
+    setupOnChainState();
+    mockBilling.topUp.mockResolvedValue({ txHash: TX_HASH, walletAddress: WALLET_ADDRESS });
+    mockBilling.getStatus.mockResolvedValueOnce({ subscriptionStatus: "active", remainingCredits: 10 }).mockResolvedValueOnce({ subscriptionStatus: "active", remainingCredits: 60 });
+    const cmd = createCommand({ amount: "50", method: "usdc", chain: "base" });
+    const promise = cmd.run();
+    for (let i = 0; i < 10; i++) {
+      await vi.advanceTimersByTimeAsync(5e3);
+    }
+    await promise;
+    expect(mockBilling.topUp).toHaveBeenCalledWith({
+      amount: BigInt(5e7),
+      account: WALLET_ADDRESS,
+      chain: "base"
+    });
+  });
   it("credit card: charges selected card on file", async () => {
     mockBilling.getStatus.mockResolvedValueOnce({ subscriptionStatus: "active", remainingCredits: 10 }).mockResolvedValueOnce({ subscriptionStatus: "active", remainingCredits: 35 });
     mockBilling.getPaymentMethods.mockResolvedValue({
@@ -864,5 +1324,97 @@ describe("ecloud billing top-up", () => {
     expect(select3).not.toHaveBeenCalled();
     expect(input3).not.toHaveBeenCalled();
   });
+  describe("x402 helpers", () => {
+    const WALLET = "0x1234567890abcdef1234567890abcdef12345678";
+    describe("resolveX402Target", () => {
+      it("defaults to the caller's own creator address", () => {
+        expect(resolveX402Target({}, WALLET)).toEqual({ type: "creator", address: WALLET });
+      });
+      it("honors --creator", () => {
+        expect(resolveX402Target({ creator: "0xC" }, WALLET)).toEqual({ type: "creator", address: "0xC" });
+      });
+      it("honors --app", () => {
+        expect(resolveX402Target({ app: "0xA" }, WALLET)).toEqual({ type: "app", address: "0xA" });
+      });
+      it("throws when both --app and --creator are given", () => {
+        expect(() => resolveX402Target({ app: "0xA", creator: "0xC" }, WALLET)).toThrow(/mutually exclusive/i);
+      });
+    });
+    describe("buildX402Url", () => {
+      it("builds a creator URL and trims a trailing slash", () => {
+        expect(buildX402Url("https://h/", { type: "creator", address: "0xC" })).toBe(
+          "https://h/creators/0xC/x402-credits"
+        );
+      });
+      it("builds an app URL", () => {
+        expect(buildX402Url("https://h", { type: "app", address: "0xA" })).toBe(
+          "https://h/apps/0xA/x402-credits"
+        );
+      });
+    });
+    describe("resolveX402BaseUrl", () => {
+      it("prefers --api-url over the billing API config", () => {
+        expect(resolveX402BaseUrl({ "api-url": "https://flag" })).toBe("https://flag");
+      });
+      it("trims a trailing slash from --api-url", () => {
+        expect(resolveX402BaseUrl({ "api-url": "https://flag/" })).toBe("https://flag");
+      });
+      it("falls back to the billing API server URL", () => {
+        expect(resolveX402BaseUrl({})).toBe("https://platform-dev.example");
+      });
+    });
+  });
+  describe("x402 method", () => {
+    it("happy path: default creator target, 201 settle, prints tx + credits", async () => {
+      mockBilling.getStatus.mockResolvedValueOnce({ subscriptionStatus: "active", remainingCredits: 10 }).mockResolvedValueOnce({ subscriptionStatus: "active", remainingCredits: 60 });
+      purchaseCreditsX402.mockResolvedValue({
+        txHash: TX_HASH,
+        paymentId: "pay_abc",
+        creditedCents: 5e3,
+        targetType: "creator",
+        targetAddress: WALLET_ADDRESS
+      });
+      const cmd = createCommand({ amount: "50", method: "x402" });
+      const promise = cmd.run();
+      for (let i = 0; i < 10; i++) await vi.advanceTimersByTimeAsync(5e3);
+      await promise;
+      const out = logOutput.join("\n");
+      expect(purchaseCreditsX402).toHaveBeenCalledWith(
+        expect.objectContaining({
+          url: `https://platform-dev.example/creators/${WALLET_ADDRESS}/x402-credits`,
+          amountCents: 5e3
+        })
+      );
+      expect(out).toContain("x402 payment settled");
+      expect(out).toContain(TX_HASH);
+      expect(out).toContain("$50.00");
+    });
+    it("--app targets the apps route", async () => {
+      mockBilling.getStatus.mockResolvedValue({ subscriptionStatus: "active", remainingCredits: 10 });
+      purchaseCreditsX402.mockResolvedValue({
+        txHash: TX_HASH,
+        paymentId: "pay_abc",
+        creditedCents: 5e3,
+        targetType: "app",
+        targetAddress: "0xApp"
+      });
+      const cmd = createCommand({ amount: "50", method: "x402", app: "0xApp" });
+      await cmd.run();
+      expect(purchaseCreditsX402).toHaveBeenCalledWith(
+        expect.objectContaining({ url: "https://platform-dev.example/apps/0xApp/x402-credits" })
+      );
+    });
+    it("rejects --app together with --creator", async () => {
+      const cmd = createCommand({ amount: "50", method: "x402", app: "0xApp", creator: "0xC" });
+      await expect(cmd.run()).rejects.toThrow(/mutually exclusive/i);
+      expect(purchaseCreditsX402).not.toHaveBeenCalled();
+    });
+    it("rejects amount below $5", async () => {
+      mockBilling.getStatus.mockResolvedValue({ subscriptionStatus: "active", remainingCredits: 10 });
+      const cmd = createCommand({ amount: "3", method: "x402" });
+      await expect(cmd.run()).rejects.toThrow(/Minimum purchase is \$5/);
+      expect(purchaseCreditsX402).not.toHaveBeenCalled();
+    });
+  });
 });
 //# sourceMappingURL=top-up.test.js.map