run402 1.2.0 → 1.4.0

package/cli.mjs

@@ -13,10 +13,18 @@ Usage:
   run402 <command> [subcommand] [options]
 
 Commands:
-  wallet    Manage your x402 wallet (create, fund, check status)
-  projects  Manage deployed projects (list, query, inspect, renew, delete)
-  deploy    Deploy a full-stack app or static site (Postgres + hosting)
-  image     Generate AI images via x402 micropayments
+  wallet      Manage your x402 wallet (create, fund, balance, status)
+  projects    Manage projects (provision, list, query, inspect, renew, delete)
+  deploy      Deploy a full-stack app or static site (Postgres + hosting)
+  functions   Manage serverless functions (deploy, invoke, logs, list, delete)
+  secrets     Manage project secrets (set, list, delete)
+  storage     Manage file storage (upload, download, list, delete)
+  sites       Deploy static sites
+  subdomains  Manage custom subdomains (claim, list, delete)
+  apps        Browse and manage the app marketplace
+  image       Generate AI images via x402 micropayments
+  message     Send messages to Run402 developers
+  agent       Manage agent identity (contact info)
 
 Run 'run402 <command> --help' for detailed usage of each command.
 
@@ -26,6 +34,8 @@ Examples:
   run402 deploy --tier prototype --manifest app.json
   run402 projects list
   run402 projects sql <project_id> "SELECT * FROM users LIMIT 5"
+  run402 functions deploy <project_id> my-fn --code handler.ts
+  run402 secrets set <project_id> API_KEY sk-1234
   run402 image generate "a startup mascot, pixel art" --output logo.png
 
 Getting started:
@@ -55,11 +65,51 @@ switch (cmd) {
     await run([sub, ...rest].filter(Boolean));
     break;
   }
+  case "functions": {
+    const { run } = await import("./lib/functions.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "secrets": {
+    const { run } = await import("./lib/secrets.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "storage": {
+    const { run } = await import("./lib/storage.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "sites": {
+    const { run } = await import("./lib/sites.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "subdomains": {
+    const { run } = await import("./lib/subdomains.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "apps": {
+    const { run } = await import("./lib/apps.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "image": {
     const { run } = await import("./lib/image.mjs");
     await run(sub, rest);
     break;
   }
+  case "message": {
+    const { run } = await import("./lib/message.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "agent": {
+    const { run } = await import("./lib/agent.mjs");
+    await run(sub, rest);
+    break;
+  }
   default:
     console.error(`Unknown command: ${cmd}\n`);
     console.log(HELP);

package/lib/agent.mjs

@@ -0,0 +1,68 @@
+import { readWallet, API, WALLET_FILE } from "./config.mjs";
+import { existsSync } from "fs";
+
+const HELP = `run402 agent — Manage agent identity
+
+Usage:
+  run402 agent contact --name <name> [--email <email>] [--webhook <url>]
+
+Notes:
+  - Costs $0.001 USDC via x402
+  - Registers contact info so Run402 can reach your agent
+  - Only name is required; email and webhook are optional
+
+Examples:
+  run402 agent contact --name my-agent
+  run402 agent contact --name my-agent --email ops@example.com --webhook https://example.com/hook
+`;
+
+async function contact(args) {
+  let name = null, email = null, webhook = null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--name" && args[i + 1]) name = args[++i];
+    if (args[i] === "--email" && args[i + 1]) email = args[++i];
+    if (args[i] === "--webhook" && args[i + 1]) webhook = args[++i];
+  }
+  if (!name) { console.error(JSON.stringify({ status: "error", message: "Missing --name <name>" })); process.exit(1); }
+  if (!existsSync(WALLET_FILE)) {
+    console.error(JSON.stringify({ status: "error", message: "No wallet found. Run: run402 wallet create && run402 wallet fund" }));
+    process.exit(1);
+  }
+
+  const wallet = readWallet();
+  const { privateKeyToAccount } = await import("viem/accounts");
+  const { createPublicClient, http } = await import("viem");
+  const { baseSepolia } = await import("viem/chains");
+  const { x402Client, wrapFetchWithPayment } = await import("@x402/fetch");
+  const { ExactEvmScheme } = await import("@x402/evm/exact/client");
+  const { toClientEvmSigner } = await import("@x402/evm");
+  const account = privateKeyToAccount(wallet.privateKey);
+  const publicClient = createPublicClient({ chain: baseSepolia, transport: http() });
+  const signer = toClientEvmSigner(account, publicClient);
+  const client = new x402Client();
+  client.register("eip155:84532", new ExactEvmScheme(signer));
+  const fetchPaid = wrapFetchWithPayment(fetch, client);
+
+  const body = { name };
+  if (email) body.email = email;
+  if (webhook) body.webhook = webhook;
+
+  const res = await fetchPaid(`${API}/v1/agent/contact`, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  if (sub !== "contact") {
+    console.error(`Unknown subcommand: ${sub}\n`);
+    console.log(HELP);
+    process.exit(1);
+  }
+  await contact(args);
+}

package/lib/apps.mjs

@@ -0,0 +1,190 @@
+import { existsSync } from "fs";
+import { findProject, readWallet, loadProjects, saveProjects, API, WALLET_FILE, PROJECTS_FILE } from "./config.mjs";
+import { mkdirSync, writeFileSync } from "fs";
+
+const HELP = `run402 apps — Browse and manage the app marketplace
+
+Usage:
+  run402 apps <subcommand> [args...]
+
+Subcommands:
+  browse  [--tag <tag>]                   Browse public apps
+  fork    <version_id> <name> [--tier <tier>] [--subdomain <name>]
+                                           Fork a published app into your own project
+  publish <id> [--description <desc>] [--tags <t1,t2>] [--visibility <v>] [--fork-allowed]
+                                           Publish a project as an app
+  versions <id>                            List published versions of a project
+  inspect <version_id>                     Inspect a published app version
+  update  <project_id> <version_id> [--description <desc>] [--tags <t1,t2>] [--visibility <v>] [--fork-allowed] [--no-fork]
+                                           Update a published version
+  delete  <project_id> <version_id>        Delete a published version
+
+Examples:
+  run402 apps browse
+  run402 apps browse --tag auth
+  run402 apps fork ver_abc123 my-todo --tier prototype
+  run402 apps publish proj123 --description "Todo app" --tags todo,auth --visibility public --fork-allowed
+  run402 apps versions proj123
+  run402 apps inspect ver_abc123
+  run402 apps update proj123 ver_abc123 --description "Updated" --tags todo
+  run402 apps delete proj123 ver_abc123
+`;
+
+async function browse(args) {
+  let url = `${API}/v1/apps`;
+  const tags = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--tag" && args[i + 1]) tags.push(args[++i]);
+  }
+  if (tags.length > 0) url += "?" + tags.map(t => `tag=${encodeURIComponent(t)}`).join("&");
+  const res = await fetch(url);
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function fork(versionId, name, args) {
+  const opts = { tier: "prototype", subdomain: undefined };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--tier" && args[i + 1]) opts.tier = args[++i];
+    if (args[i] === "--subdomain" && args[i + 1]) opts.subdomain = args[++i];
+  }
+  if (!existsSync(WALLET_FILE)) {
+    console.error(JSON.stringify({ status: "error", message: "No wallet found. Run: run402 wallet create && run402 wallet fund" }));
+    process.exit(1);
+  }
+
+  const wallet = readWallet();
+  const { privateKeyToAccount } = await import("viem/accounts");
+  const { createPublicClient, http } = await import("viem");
+  const { baseSepolia } = await import("viem/chains");
+  const { x402Client, wrapFetchWithPayment } = await import("@x402/fetch");
+  const { ExactEvmScheme } = await import("@x402/evm/exact/client");
+  const { toClientEvmSigner } = await import("@x402/evm");
+  const account = privateKeyToAccount(wallet.privateKey);
+  const publicClient = createPublicClient({ chain: baseSepolia, transport: http() });
+  const signer = toClientEvmSigner(account, publicClient);
+  const client = new x402Client();
+  client.register("eip155:84532", new ExactEvmScheme(signer));
+  const fetchPaid = wrapFetchWithPayment(fetch, client);
+
+  const body = { version_id: versionId, name };
+  if (opts.subdomain) body.subdomain = opts.subdomain;
+
+  const res = await fetchPaid(`${API}/v1/fork/${opts.tier}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+
+  // Save project credentials locally
+  if (data.project_id) {
+    const projects = loadProjects();
+    projects.push({
+      project_id: data.project_id, anon_key: data.anon_key, service_key: data.service_key,
+      tier: data.tier, lease_expires_at: data.lease_expires_at,
+      site_url: data.site_url || data.subdomain_url, deployed_at: new Date().toISOString(),
+    });
+    const dir = PROJECTS_FILE.replace(/\/[^/]+$/, "");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(PROJECTS_FILE, JSON.stringify(projects, null, 2), { mode: 0o600 });
+  }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function publish(projectId, args) {
+  const p = findProject(projectId);
+  const opts = { description: undefined, tags: undefined, visibility: undefined, forkAllowed: undefined };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--description" && args[i + 1]) opts.description = args[++i];
+    if (args[i] === "--tags" && args[i + 1]) opts.tags = args[++i].split(",");
+    if (args[i] === "--visibility" && args[i + 1]) opts.visibility = args[++i];
+    if (args[i] === "--fork-allowed") opts.forkAllowed = true;
+  }
+  const body = {};
+  if (opts.description) body.description = opts.description;
+  if (opts.tags) body.tags = opts.tags;
+  if (opts.visibility) body.visibility = opts.visibility;
+  if (opts.forkAllowed !== undefined) body.fork_allowed = opts.forkAllowed;
+
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/publish`, {
+    method: "POST",
+    headers: { "Authorization": `Bearer ${p.service_key}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function versions(projectId) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/versions`, {
+    headers: { "Authorization": `Bearer ${p.service_key}` },
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function inspect(versionId) {
+  if (!versionId) { console.error(JSON.stringify({ status: "error", message: "Missing version ID" })); process.exit(1); }
+  const res = await fetch(`${API}/v1/apps/${versionId}`);
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function update(projectId, versionId, args) {
+  const p = findProject(projectId);
+  const body = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--description" && args[i + 1]) body.description = args[++i];
+    if (args[i] === "--tags" && args[i + 1]) body.tags = args[++i].split(",");
+    if (args[i] === "--visibility" && args[i + 1]) body.visibility = args[++i];
+    if (args[i] === "--fork-allowed") body.fork_allowed = true;
+    if (args[i] === "--no-fork") body.fork_allowed = false;
+  }
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/versions/${versionId}`, {
+    method: "PATCH",
+    headers: { "Authorization": `Bearer ${p.service_key}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function deleteVersion(projectId, versionId) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/versions/${versionId}`, {
+    method: "DELETE",
+    headers: { "Authorization": `Bearer ${p.service_key}` },
+  });
+  if (res.status === 204 || res.ok) {
+    console.log(JSON.stringify({ status: "ok", message: `Version ${versionId} deleted.` }));
+  } else {
+    const data = await res.json();
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data }));
+    process.exit(1);
+  }
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  switch (sub) {
+    case "browse":   await browse(args); break;
+    case "fork":     await fork(args[0], args[1], args.slice(2)); break;
+    case "publish":  await publish(args[0], args.slice(1)); break;
+    case "versions": await versions(args[0]); break;
+    case "inspect":  await inspect(args[0]); break;
+    case "update":   await update(args[0], args[1], args.slice(2)); break;
+    case "delete":   await deleteVersion(args[0], args[1]); break;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

package/lib/config.mjs

@@ -3,9 +3,10 @@
  * Kept in a separate module so credential reads stay isolated.
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from "fs";
-import { join } from "path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync, renameSync } from "fs";
+import { join, dirname } from "path";
 import { homedir } from "os";
+import { randomBytes } from "crypto";
 
 export const CONFIG_DIR = join(homedir(), ".config", "run402");
 export const WALLET_FILE = join(CONFIG_DIR, "wallet.json");
@@ -19,8 +20,10 @@ export function readWallet() {
 
 export function saveWallet(data) {
   mkdirSync(CONFIG_DIR, { recursive: true });
-  writeFileSync(WALLET_FILE, JSON.stringify(data, null, 2), { mode: 0o600 });
-  try { chmodSync(WALLET_FILE, 0o600); } catch {}
+  const tmp = join(CONFIG_DIR, `.wallet.${randomBytes(4).toString("hex")}.tmp`);
+  writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
+  renameSync(tmp, WALLET_FILE);
+  chmodSync(WALLET_FILE, 0o600);
 }
 
 export function loadProjects() {

package/lib/functions.mjs

@@ -0,0 +1,150 @@
+import { readFileSync, existsSync } from "fs";
+import { findProject, readWallet, API, WALLET_FILE } from "./config.mjs";
+
+const HELP = `run402 functions — Manage serverless functions
+
+Usage:
+  run402 functions <subcommand> [args...]
+
+Subcommands:
+  deploy <id> <name> --code <file> [--timeout <s>] [--memory <mb>] [--deps <pkg,...>]
+                                       Deploy a function to a project
+  invoke <id> <name> [--method <M>] [--body <json>]
+                                       Invoke a deployed function
+  logs   <id> <name> [--tail <n>]      Get function logs
+  list   <id>                          List all functions for a project
+  delete <id> <name>                   Delete a function
+
+Examples:
+  run402 functions deploy abc123 stripe-webhook --code handler.ts
+  run402 functions invoke abc123 stripe-webhook --body '{"event":"test"}'
+  run402 functions logs abc123 stripe-webhook --tail 100
+  run402 functions list abc123
+  run402 functions delete abc123 stripe-webhook
+
+Notes:
+  - Code must export a default async function: export default async (req: Request) => Response
+  - Deploy may require payment if the project lease has expired
+`;
+
+async function setupPaidFetch() {
+  if (!existsSync(WALLET_FILE)) {
+    console.error(JSON.stringify({ status: "error", message: "No wallet found. Run: run402 wallet create && run402 wallet fund" }));
+    process.exit(1);
+  }
+  const wallet = readWallet();
+  const { privateKeyToAccount } = await import("viem/accounts");
+  const { createPublicClient, http } = await import("viem");
+  const { baseSepolia } = await import("viem/chains");
+  const { x402Client, wrapFetchWithPayment } = await import("@x402/fetch");
+  const { ExactEvmScheme } = await import("@x402/evm/exact/client");
+  const { toClientEvmSigner } = await import("@x402/evm");
+  const account = privateKeyToAccount(wallet.privateKey);
+  const publicClient = createPublicClient({ chain: baseSepolia, transport: http() });
+  const signer = toClientEvmSigner(account, publicClient);
+  const client = new x402Client();
+  client.register("eip155:84532", new ExactEvmScheme(signer));
+  return wrapFetchWithPayment(fetch, client);
+}
+
+async function deploy(projectId, name, args) {
+  const p = findProject(projectId);
+  const opts = { code: null, timeout: undefined, memory: undefined, deps: undefined };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--code" && args[i + 1]) opts.code = args[++i];
+    if (args[i] === "--timeout" && args[i + 1]) opts.timeout = parseInt(args[++i]);
+    if (args[i] === "--memory" && args[i + 1]) opts.memory = parseInt(args[++i]);
+    if (args[i] === "--deps" && args[i + 1]) opts.deps = args[++i].split(",");
+  }
+  if (!opts.code) { console.error(JSON.stringify({ status: "error", message: "Missing --code <file>" })); process.exit(1); }
+  const code = readFileSync(opts.code, "utf-8");
+  const body = { name, code };
+  if (opts.timeout || opts.memory) body.config = {};
+  if (opts.timeout) body.config.timeout = opts.timeout;
+  if (opts.memory) body.config.memory = opts.memory;
+  if (opts.deps) body.deps = opts.deps;
+
+  const fetchPaid = await setupPaidFetch();
+  const res = await fetchPaid(`${API}/admin/v1/projects/${projectId}/functions`, {
+    method: "POST",
+    headers: { "Authorization": `Bearer ${p.service_key}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function invoke(projectId, name, args) {
+  const p = findProject(projectId);
+  const opts = { method: "POST", body: undefined };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--method" && args[i + 1]) opts.method = args[++i];
+    if (args[i] === "--body" && args[i + 1]) opts.body = args[++i];
+  }
+  const fetchOpts = {
+    method: opts.method,
+    headers: { "apikey": p.service_key },
+  };
+  if (opts.body && opts.method !== "GET" && opts.method !== "HEAD") {
+    fetchOpts.headers["Content-Type"] = "application/json";
+    fetchOpts.body = opts.body;
+  }
+  const res = await fetch(`${API}/functions/v1/${name}`, fetchOpts);
+  const text = await res.text();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, body: text })); process.exit(1); }
+  try { console.log(JSON.stringify(JSON.parse(text), null, 2)); } catch { process.stdout.write(text + "\n"); }
+}
+
+async function logs(projectId, name, args) {
+  const p = findProject(projectId);
+  let tail = 50;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--tail" && args[i + 1]) tail = parseInt(args[++i]);
+  }
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/functions/${encodeURIComponent(name)}/logs?tail=${tail}`, {
+    headers: { "Authorization": `Bearer ${p.service_key}` },
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function list(projectId) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/functions`, {
+    headers: { "Authorization": `Bearer ${p.service_key}` },
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function deleteFunction(projectId, name) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/functions/${encodeURIComponent(name)}`, {
+    method: "DELETE",
+    headers: { "Authorization": `Bearer ${p.service_key}` },
+  });
+  if (res.status === 204 || res.ok) {
+    console.log(JSON.stringify({ status: "ok", message: `Function '${name}' deleted.` }));
+  } else {
+    const data = await res.json().catch(() => ({}));
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1);
+  }
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  switch (sub) {
+    case "deploy": await deploy(args[0], args[1], args.slice(2)); break;
+    case "invoke": await invoke(args[0], args[1], args.slice(2)); break;
+    case "logs":   await logs(args[0], args[1], args.slice(2)); break;
+    case "list":   await list(args[0]); break;
+    case "delete": await deleteFunction(args[0], args[1]); break;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

package/lib/message.mjs

@@ -0,0 +1,56 @@
+import { readWallet, API, WALLET_FILE } from "./config.mjs";
+import { existsSync } from "fs";
+
+const HELP = `run402 message — Send messages to Run402 developers
+
+Usage:
+  run402 message send <text>
+
+Notes:
+  - Costs $0.01 USDC via x402
+  - Requires a funded wallet
+
+Examples:
+  run402 message send "Hello from my agent!"
+`;
+
+async function send(text) {
+  if (!text) { console.error(JSON.stringify({ status: "error", message: "Missing message text" })); process.exit(1); }
+  if (!existsSync(WALLET_FILE)) {
+    console.error(JSON.stringify({ status: "error", message: "No wallet found. Run: run402 wallet create && run402 wallet fund" }));
+    process.exit(1);
+  }
+
+  const wallet = readWallet();
+  const { privateKeyToAccount } = await import("viem/accounts");
+  const { createPublicClient, http } = await import("viem");
+  const { baseSepolia } = await import("viem/chains");
+  const { x402Client, wrapFetchWithPayment } = await import("@x402/fetch");
+  const { ExactEvmScheme } = await import("@x402/evm/exact/client");
+  const { toClientEvmSigner } = await import("@x402/evm");
+  const account = privateKeyToAccount(wallet.privateKey);
+  const publicClient = createPublicClient({ chain: baseSepolia, transport: http() });
+  const signer = toClientEvmSigner(account, publicClient);
+  const client = new x402Client();
+  client.register("eip155:84532", new ExactEvmScheme(signer));
+  const fetchPaid = wrapFetchWithPayment(fetch, client);
+
+  const res = await fetchPaid(`${API}/v1/message`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ message: text }),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  if (sub !== "send") {
+    console.error(`Unknown subcommand: ${sub}\n`);
+    console.log(HELP);
+    process.exit(1);
+  }
+  await send(args.join(" "));
+}

package/lib/projects.mjs

@@ -1,5 +1,5 @@
-import { findProject, loadProjects, saveProjects, readWallet, API, WALLET_FILE } from "./config.mjs";
-import { existsSync } from "fs";
+import { findProject, loadProjects, saveProjects, readWallet, API, WALLET_FILE, PROJECTS_FILE } from "./config.mjs";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
 
 const HELP = `run402 projects — Manage your deployed Run402 projects
 
@@ -7,27 +7,35 @@ Usage:
   run402 projects <subcommand> [args...]
 
 Subcommands:
-  list                           List all your projects (IDs, tiers, URLs, expiry)
-  sql   <id> "<query>"           Run a SQL query against a project's Postgres DB
-  rest  <id> <table> [params]    Query a table via the REST API (PostgREST)
-  usage <id>                     Show compute/storage usage for a project
-  schema <id>                    Inspect the database schema
-  renew <id>                     Extend the project lease (pays via x402)
-  delete <id>                    Delete a project and remove it from local state
+  quote                                   Show pricing tiers
+  provision [--tier <tier>] [--name <n>]  Provision a new Postgres project (pays via x402)
+  list                                    List all your projects (IDs, tiers, URLs, expiry)
+  sql   <id> "<query>"                    Run a SQL query against a project's Postgres DB
+  rest  <id> <table> [params]             Query a table via the REST API (PostgREST)
+  usage <id>                              Show compute/storage usage for a project
+  schema <id>                             Inspect the database schema
+  rls   <id> <template> <tables_json>     Apply Row-Level Security policies
+  renew <id>                              Extend the project lease (pays via x402)
+  delete <id>                             Delete a project and remove it from local state
 
 Examples:
+  run402 projects quote
+  run402 projects provision --tier prototype
+  run402 projects provision --tier hobby --name my-app
   run402 projects list
   run402 projects sql abc123 "SELECT * FROM users LIMIT 5"
   run402 projects rest abc123 users "limit=10&select=id,name"
   run402 projects usage abc123
   run402 projects schema abc123
+  run402 projects rls abc123 public_read '[{"table":"posts"}]'
   run402 projects renew abc123
   run402 projects delete abc123
 
 Notes:
   - <id> is the project_id shown in 'run402 projects list'
   - 'rest' uses PostgREST query syntax (table name + optional query string)
-  - 'renew' requires a funded wallet — payment is automatic via x402
+  - 'renew' and 'provision' require a funded wallet — payment is automatic via x402
+  - RLS templates: user_owns_rows, public_read, public_read_write
 `;
 
 async function setupPaidFetch() {
@@ -50,6 +58,56 @@ async function setupPaidFetch() {
   return wrapFetchWithPayment(fetch, client);
 }
 
+async function quote() {
+  const res = await fetch(`${API}/v1/projects`);
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function provision(args) {
+  const opts = { tier: "prototype", name: undefined };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--tier" && args[i + 1]) opts.tier = args[++i];
+    if (args[i] === "--name" && args[i + 1]) opts.name = args[++i];
+  }
+  const fetchPaid = await setupPaidFetch();
+  const body = { tier: opts.tier };
+  if (opts.name) body.name = opts.name;
+  const res = await fetchPaid(`${API}/v1/projects`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  // Save project credentials locally
+  if (data.project_id) {
+    const projects = loadProjects();
+    projects.push({
+      project_id: data.project_id, anon_key: data.anon_key, service_key: data.service_key,
+      tier: data.tier, lease_expires_at: data.lease_expires_at, deployed_at: new Date().toISOString(),
+    });
+    const dir = PROJECTS_FILE.replace(/\/[^/]+$/, "");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(PROJECTS_FILE, JSON.stringify(projects, null, 2), { mode: 0o600 });
+  }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function rls(projectId, template, tablesJson) {
+  const p = findProject(projectId);
+  const tables = JSON.parse(tablesJson);
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/rls`, {
+    method: "POST",
+    headers: { "Authorization": `Bearer ${p.service_key}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ template, tables }),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
 async function list() {
   const projects = loadProjects();
   if (projects.length === 0) { console.log(JSON.stringify({ status: "ok", projects: [], message: "No projects yet." })); return; }
@@ -113,13 +171,16 @@ export async function run(sub, args) {
     process.exit(0);
   }
   switch (sub) {
-    case "list":   await list(); break;
-    case "sql":    await sqlCmd(args[0], args[1]); break;
-    case "rest":   await rest(args[0], args[1], args[2]); break;
-    case "usage":  await usage(args[0]); break;
-    case "schema": await schema(args[0]); break;
-    case "renew":  await renew(args[0]); break;
-    case "delete": await deleteProject(args[0]); break;
+    case "quote":     await quote(); break;
+    case "provision": await provision(args); break;
+    case "list":      await list(); break;
+    case "sql":       await sqlCmd(args[0], args[1]); break;
+    case "rest":      await rest(args[0], args[1], args[2]); break;
+    case "usage":     await usage(args[0]); break;
+    case "schema":    await schema(args[0]); break;
+    case "rls":       await rls(args[0], args[1], args[2]); break;
+    case "renew":     await renew(args[0]); break;
+    case "delete":    await deleteProject(args[0]); break;
     default:
       console.error(`Unknown subcommand: ${sub}\n`);
       console.log(HELP);

package/lib/secrets.mjs

@@ -0,0 +1,70 @@
+import { findProject, API } from "./config.mjs";
+
+const HELP = `run402 secrets — Manage project secrets
+
+Usage:
+  run402 secrets <subcommand> [args...]
+
+Subcommands:
+  set    <id> <key> <value>    Set a secret on a project
+  list   <id>                  List all secrets for a project
+  delete <id> <key>            Delete a secret from a project
+
+Examples:
+  run402 secrets set abc123 STRIPE_KEY sk-1234
+  run402 secrets list abc123
+  run402 secrets delete abc123 STRIPE_KEY
+
+Notes:
+  - Secrets are injected as process.env in serverless functions
+  - Values are never shown after being set
+`;
+
+async function set(projectId, key, value) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/secrets`, {
+    method: "POST",
+    headers: { "Authorization": `Bearer ${p.service_key}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ key, value }),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify({ status: "ok", message: `Secret '${key}' set for project ${projectId}.` }));
+}
+
+async function list(projectId) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/secrets`, {
+    headers: { "Authorization": `Bearer ${p.service_key}` },
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function deleteSecret(projectId, key) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/secrets/${encodeURIComponent(key)}`, {
+    method: "DELETE",
+    headers: { "Authorization": `Bearer ${p.service_key}` },
+  });
+  if (res.status === 204 || res.ok) {
+    console.log(JSON.stringify({ status: "ok", message: `Secret '${key}' deleted.` }));
+  } else {
+    const data = await res.json().catch(() => ({}));
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1);
+  }
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  switch (sub) {
+    case "set":    await set(args[0], args[1], args[2]); break;
+    case "list":   await list(args[0]); break;
+    case "delete": await deleteSecret(args[0], args[1]); break;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

package/lib/sites.mjs

@@ -0,0 +1,112 @@
+import { readFileSync, existsSync } from "fs";
+import { readWallet, API, WALLET_FILE } from "./config.mjs";
+
+const HELP = `run402 sites — Deploy and manage static sites
+
+Usage:
+  run402 sites deploy --name <name> --manifest <file> [--project <id>] [--target <target>]
+  run402 sites status <deployment_id>
+  cat manifest.json | run402 sites deploy --name <name>
+
+Subcommands:
+  deploy  Deploy a static site
+  status  Check the status of a deployment
+
+Options (deploy):
+  --name <name>         Site name (e.g. 'portfolio', 'family-todo')
+  --manifest <file>     Path to manifest JSON file (or read from stdin)
+  --project <id>        Optional project ID to link this deployment to
+  --target <target>     Deployment target (e.g. 'production')
+  --help, -h            Show this help message
+
+Manifest format (JSON):
+  {
+    "files": [
+      { "file": "index.html", "data": "<html>...</html>" },
+      { "file": "style.css", "data": "body { margin: 0; }" }
+    ]
+  }
+
+Examples:
+  run402 sites deploy --name my-site --manifest site.json
+  run402 sites status dep_abc123
+  cat site.json | run402 sites deploy --name my-site
+
+Notes:
+  - Must include at least index.html in the files array
+  - Requires a funded wallet — payment ($0.05 USDC) is automatic via x402
+`;
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+async function deploy(args) {
+  const opts = { name: null, manifest: null, project: undefined, target: undefined };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--help" || args[i] === "-h") { console.log(HELP); process.exit(0); }
+    if (args[i] === "--name" && args[i + 1]) opts.name = args[++i];
+    if (args[i] === "--manifest" && args[i + 1]) opts.manifest = args[++i];
+    if (args[i] === "--project" && args[i + 1]) opts.project = args[++i];
+    if (args[i] === "--target" && args[i + 1]) opts.target = args[++i];
+  }
+  if (!opts.name) { console.error(JSON.stringify({ status: "error", message: "Missing --name <name>" })); process.exit(1); }
+  if (!existsSync(WALLET_FILE)) {
+    console.error(JSON.stringify({ status: "error", message: "No wallet found. Run: run402 wallet create && run402 wallet fund" }));
+    process.exit(1);
+  }
+
+  const manifest = opts.manifest ? JSON.parse(readFileSync(opts.manifest, "utf-8")) : JSON.parse(await readStdin());
+  const body = { name: opts.name, files: manifest.files };
+  if (opts.project) body.project = opts.project;
+  if (opts.target) body.target = opts.target;
+
+  const wallet = readWallet();
+  const { privateKeyToAccount } = await import("viem/accounts");
+  const { createPublicClient, http } = await import("viem");
+  const { baseSepolia } = await import("viem/chains");
+  const { x402Client, wrapFetchWithPayment } = await import("@x402/fetch");
+  const { ExactEvmScheme } = await import("@x402/evm/exact/client");
+  const { toClientEvmSigner } = await import("@x402/evm");
+  const account = privateKeyToAccount(wallet.privateKey);
+  const publicClient = createPublicClient({ chain: baseSepolia, transport: http() });
+  const signer = toClientEvmSigner(account, publicClient);
+  const client = new x402Client();
+  client.register("eip155:84532", new ExactEvmScheme(signer));
+  const fetchPaid = wrapFetchWithPayment(fetch, client);
+
+  const res = await fetchPaid(`${API}/v1/deployments`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function status(args) {
+  let deploymentId = null;
+  for (let i = 0; i < args.length; i++) {
+    if (!args[i].startsWith("-")) { deploymentId = args[i]; break; }
+  }
+  if (!deploymentId) { console.error(JSON.stringify({ status: "error", message: "Missing deployment ID" })); process.exit(1); }
+  const res = await fetch(`${API}/v1/deployments/${deploymentId}`);
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  switch (sub) {
+    case "deploy":  await deploy(args); break;
+    case "status":  await status(args); break;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

package/lib/storage.mjs

@@ -0,0 +1,101 @@
+import { readFileSync } from "fs";
+import { findProject, API } from "./config.mjs";
+
+const HELP = `run402 storage — Manage project file storage
+
+Usage:
+  run402 storage <subcommand> [args...]
+
+Subcommands:
+  upload   <id> <bucket> <path> [--file <local>] [--content-type <mime>]
+                                       Upload a file to storage
+  download <id> <bucket> <path>        Download a file from storage
+  delete   <id> <bucket> <path>        Delete a file from storage
+  list     <id> <bucket>               List files in a bucket
+
+Examples:
+  run402 storage upload abc123 assets logo.png --file ./logo.png --content-type image/png
+  echo "hello" | run402 storage upload abc123 data notes.txt
+  run402 storage download abc123 assets logo.png
+  run402 storage list abc123 assets
+  run402 storage delete abc123 assets logo.png
+
+Notes:
+  - <id> is the project_id from 'run402 projects list'
+  - Upload reads from --file or stdin if no --file is given
+`;
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+async function upload(projectId, bucket, path, args) {
+  const p = findProject(projectId);
+  const opts = { file: null, contentType: "text/plain" };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--file" && args[i + 1]) opts.file = args[++i];
+    if (args[i] === "--content-type" && args[i + 1]) opts.contentType = args[++i];
+  }
+  const content = opts.file ? readFileSync(opts.file, "utf-8") : await readStdin();
+  const res = await fetch(`${API}/storage/v1/object/${bucket}/${path}`, {
+    method: "POST",
+    headers: { "Content-Type": opts.contentType, "apikey": p.anon_key, "Authorization": `Bearer ${p.anon_key}` },
+    body: content,
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function download(projectId, bucket, path) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/storage/v1/object/${bucket}/${path}`, {
+    headers: { "apikey": p.anon_key, "Authorization": `Bearer ${p.anon_key}` },
+  });
+  if (!res.ok) {
+    const data = await res.json().catch(() => ({}));
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1);
+  }
+  const text = await res.text();
+  process.stdout.write(text);
+}
+
+async function deleteFile(projectId, bucket, path) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/storage/v1/object/${bucket}/${path}`, {
+    method: "DELETE",
+    headers: { "apikey": p.anon_key, "Authorization": `Bearer ${p.anon_key}` },
+  });
+  if (res.status === 204 || res.ok) {
+    console.log(JSON.stringify({ status: "ok", message: `File '${bucket}/${path}' deleted.` }));
+  } else {
+    const data = await res.json().catch(() => ({}));
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1);
+  }
+}
+
+async function list(projectId, bucket) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/storage/v1/object/list/${bucket}`, {
+    headers: { "apikey": p.anon_key, "Authorization": `Bearer ${p.anon_key}` },
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  switch (sub) {
+    case "upload":   await upload(args[0], args[1], args[2], args.slice(3)); break;
+    case "download": await download(args[0], args[1], args[2]); break;
+    case "delete":   await deleteFile(args[0], args[1], args[2]); break;
+    case "list":     await list(args[0], args[1]); break;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

package/lib/subdomains.mjs

@@ -0,0 +1,87 @@
+import { findProject, API } from "./config.mjs";
+
+const HELP = `run402 subdomains — Manage custom subdomains
+
+Usage:
+  run402 subdomains <subcommand> [args...]
+
+Subcommands:
+  claim  <deployment_id> <name> [--project <id>]   Claim a subdomain for a deployment
+  delete <name> [--project <id>]                    Release a subdomain
+  list   <id>                                       List subdomains for a project
+
+Examples:
+  run402 subdomains claim dpl_abc123 myapp
+  run402 subdomains claim dpl_abc123 myapp --project proj123
+  run402 subdomains delete myapp
+  run402 subdomains list proj123
+
+Notes:
+  - Subdomain names: 3-63 chars, lowercase alphanumeric + hyphens
+  - Creates <name>.run402.com pointing to the deployment
+`;
+
+async function claim(deploymentId, name, args) {
+  const opts = { project: null };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--project" && args[i + 1]) opts.project = args[++i];
+  }
+  const headers = { "Content-Type": "application/json" };
+  if (opts.project) {
+    const p = findProject(opts.project);
+    headers["Authorization"] = `Bearer ${p.service_key}`;
+  }
+  const res = await fetch(`${API}/v1/subdomains`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ name, deployment_id: deploymentId }),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function deleteSubdomain(name, args) {
+  const opts = { project: null };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--project" && args[i + 1]) opts.project = args[++i];
+  }
+  const headers = {};
+  if (opts.project) {
+    const p = findProject(opts.project);
+    headers["Authorization"] = `Bearer ${p.service_key}`;
+  }
+  const res = await fetch(`${API}/v1/subdomains/${encodeURIComponent(name)}`, {
+    method: "DELETE",
+    headers,
+  });
+  if (res.status === 204 || res.ok) {
+    console.log(JSON.stringify({ status: "ok", message: `Subdomain '${name}' released.` }));
+  } else {
+    const data = await res.json().catch(() => ({}));
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1);
+  }
+}
+
+async function list(projectId) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/v1/subdomains`, {
+    headers: { "Authorization": `Bearer ${p.service_key}` },
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === '--help' || sub === '-h') { console.log(HELP); process.exit(0); }
+  switch (sub) {
+    case "claim":  await claim(args[0], args[1], args.slice(2)); break;
+    case "delete": await deleteSubdomain(args[0], args.slice(1)); break;
+    case "list":   await list(args[0]); break;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

package/lib/wallet.mjs

@@ -1,4 +1,4 @@
-import { readWallet, saveWallet, API } from "./config.mjs";
+import { readWallet, saveWallet, WALLET_FILE, API } from "./config.mjs";
 
 const HELP = `run402 wallet — Manage your x402 wallet
 
@@ -9,25 +9,34 @@ Subcommands:
   status    Show wallet address, network, and funding status
   create    Generate a new wallet and save it locally
   fund      Request test USDC from the Run402 faucet (Base Sepolia)
+  balance   Show on-chain USDC (mainnet + testnet) and Run402 billing balance
   export    Print the wallet address (useful for scripting)
+  checkout  Create a billing checkout session (--amount <usd_micros>)
+  history   View billing transaction history (--limit <n>)
 
 Notes:
   - Wallet is stored locally at ~/.run402/wallet.json
-  - Network: Base Sepolia (testnet) — uses USDC for x402 payments
-  - You need to create and fund a wallet before deploying or generating images
+  - The wallet works on any EVM chain (currently Run402 uses Base Mainnet and Sepolia for testnet)
+  - You need to create and fund a wallet before any x402 transaction with Run402
 
 Examples:
   run402 wallet create
   run402 wallet status
   run402 wallet fund
   run402 wallet export
+  run402 wallet checkout --amount 5000000
+  run402 wallet history --limit 10
 `;
 
+const USDC_ABI = [{ name: "balanceOf", type: "function", stateMutability: "view", inputs: [{ name: "account", type: "address" }], outputs: [{ name: "", type: "uint256" }] }];
+const USDC_MAINNET = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+const USDC_SEPOLIA = "0x036CbD53842c5426634e7929541eC2318f3dCF7e";
+
 async function loadDeps() {
   const { generatePrivateKey, privateKeyToAccount } = await import("viem/accounts");
   const { createPublicClient, http } = await import("viem");
-  const { baseSepolia } = await import("viem/chains");
-  return { generatePrivateKey, privateKeyToAccount, createPublicClient, http, baseSepolia };
+  const { base, baseSepolia } = await import("viem/chains");
+  return { generatePrivateKey, privateKeyToAccount, createPublicClient, http, base, baseSepolia };
 }
 
 async function status() {
@@ -36,7 +45,7 @@ async function status() {
     console.log(JSON.stringify({ status: "no_wallet", message: "No wallet found. Run: run402 wallet create" }));
     return;
   }
-  console.log(JSON.stringify({ status: "ok", address: w.address, network: w.network || "base-sepolia", created: w.created, funded: w.funded || false }));
+  console.log(JSON.stringify({ status: "ok", address: w.address, created: w.created, funded: w.funded || false, path: WALLET_FILE }));
 }
 
 async function create() {
@@ -47,22 +56,74 @@ async function create() {
   const { generatePrivateKey, privateKeyToAccount } = await loadDeps();
   const privateKey = generatePrivateKey();
   const account = privateKeyToAccount(privateKey);
-  saveWallet({ address: account.address, privateKey, network: "base-sepolia", created: new Date().toISOString(), funded: false });
-  console.log(JSON.stringify({ status: "ok", address: account.address, message: "Wallet created and saved." }));
+  saveWallet({ address: account.address, privateKey, created: new Date().toISOString(), funded: false });
+  console.log(JSON.stringify({ status: "ok", address: account.address, message: `Wallet created. Stored locally at ${WALLET_FILE}` }));
 }
 
 async function fund() {
   const w = readWallet();
   if (!w) { console.log(JSON.stringify({ status: "error", message: "No wallet. Run: run402 wallet create" })); process.exit(1); }
+
+  const { createPublicClient, http, baseSepolia } = await loadDeps();
+  const client = createPublicClient({ chain: baseSepolia, transport: http() });
+  const before = await readUsdcBalance(client, USDC_SEPOLIA, w.address).catch(() => 0);
+
   const res = await fetch(`${API}/v1/faucet`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ address: w.address }) });
   const data = await res.json();
-  if (res.ok) {
-    saveWallet({ ...w, funded: true, lastFaucet: new Date().toISOString() });
-    console.log(JSON.stringify({ status: "ok", ...data }));
-  } else {
+  if (!res.ok) {
     console.log(JSON.stringify({ status: "error", ...data }));
     process.exit(1);
   }
+
+  const MAX_WAIT = 30;
+  for (let i = 0; i < MAX_WAIT; i++) {
+    await new Promise(r => setTimeout(r, 1000));
+    const now = await readUsdcBalance(client, USDC_SEPOLIA, w.address).catch(() => before);
+    if (now > before) {
+      saveWallet({ ...w, funded: true, lastFaucet: new Date().toISOString() });
+      console.log(JSON.stringify({
+        address: w.address,
+        onchain: {
+          "base-sepolia_usd_micros": now,
+        },
+      }, null, 2));
+      return;
+    }
+  }
+
+  saveWallet({ ...w, funded: true, lastFaucet: new Date().toISOString() });
+  console.log(JSON.stringify({ status: "ok", message: "Faucet request sent but balance not yet confirmed", ...data }));
+}
+
+async function readUsdcBalance(client, usdc, address) {
+  const raw = await client.readContract({ address: usdc, abi: USDC_ABI, functionName: "balanceOf", args: [address] });
+  return Number(raw);
+}
+
+async function balance() {
+  const w = readWallet();
+  if (!w) { console.log(JSON.stringify({ status: "error", message: "No wallet. Run: run402 wallet create" })); process.exit(1); }
+
+  const { createPublicClient, http, base, baseSepolia } = await loadDeps();
+  const mainnetClient = createPublicClient({ chain: base, transport: http() });
+  const sepoliaClient = createPublicClient({ chain: baseSepolia, transport: http() });
+
+  const [mainnetUsdc, sepoliaUsdc, billingRes] = await Promise.all([
+    readUsdcBalance(mainnetClient, USDC_MAINNET, w.address).catch(() => null),
+    readUsdcBalance(sepoliaClient, USDC_SEPOLIA, w.address).catch(() => null),
+    fetch(`${API}/v1/billing/accounts/${w.address.toLowerCase()}`),
+  ]);
+
+  const billing = billingRes.ok ? await billingRes.json() : null;
+
+  console.log(JSON.stringify({
+    address: w.address,
+    onchain: {
+      "base-mainnet_usd_micros": mainnetUsdc,
+      "base-sepolia_usd_micros": sepoliaUsdc,
+    },
+    run402: billing ? { balance_usd_micros: billing.available_usd_micros } : "no billing account",
+  }, null, 2));
 }
 
 async function exportAddr() {
@@ -71,16 +132,50 @@ async function exportAddr() {
   console.log(w.address);
 }
 
+async function checkout(args) {
+  const w = readWallet();
+  if (!w) { console.log(JSON.stringify({ status: "error", message: "No wallet. Run: run402 wallet create" })); process.exit(1); }
+  let amount = null;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--amount" && args[i + 1]) amount = parseInt(args[++i], 10);
+  }
+  if (!amount) { console.error(JSON.stringify({ status: "error", message: "Missing --amount <usd_micros> (e.g. --amount 5000000 for $5)" })); process.exit(1); }
+  const res = await fetch(`${API}/v1/billing/checkouts`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ wallet: w.address.toLowerCase(), amount_usd_micros: amount }),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function history(args) {
+  const w = readWallet();
+  if (!w) { console.log(JSON.stringify({ status: "error", message: "No wallet. Run: run402 wallet create" })); process.exit(1); }
+  let limit = 20;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--limit" && args[i + 1]) limit = parseInt(args[++i], 10);
+  }
+  const res = await fetch(`${API}/v1/billing/accounts/${w.address.toLowerCase()}/history?limit=${limit}`);
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
 export async function run(sub, args) {
   if (!sub || sub === '--help' || sub === '-h') {
     console.log(HELP);
     process.exit(0);
   }
   switch (sub) {
-    case "status": await status(); break;
-    case "create": await create(); break;
-    case "fund":   await fund(); break;
-    case "export": await exportAddr(); break;
+    case "status":  await status(); break;
+    case "create":  await create(); break;
+    case "fund":    await fund(); break;
+    case "balance": await balance(); break;
+    case "export":   await exportAddr(); break;
+    case "checkout": await checkout(args); break;
+    case "history":  await history(args); break;
     default:
       console.error(`Unknown subcommand: ${sub}\n`);
       console.log(HELP);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 micropayments.",
   "type": "module",
   "bin": {