run402 4.119.0 → 4.121.0

package/core-dist/wallet-auth.js

@@ -6,7 +6,7 @@ import { randomBytes } from "node:crypto";
 import { secp256k1 } from "@noble/curves/secp256k1.js";
 import { keccak_256 } from "@noble/hashes/sha3.js";
 import { bytesToHex } from "@noble/hashes/utils.js";
-import { readWallet } from "./wallet.js";
+import { isSignerWallet, readWallet } from "./wallet.js";
 import { getApiBase } from "./config.js";
 /**
  * EIP-55 mixed-case checksum encoding.
@@ -57,6 +57,33 @@ function personalSign(privateKeyHex, address, message) {
     const vHex = (recovery + 27).toString(16).padStart(2, "0");
     return "0x" + r + s + vHex;
 }
+export function prepareSIWx(opts) {
+    const message = formatSIWEMessage(opts, opts.address);
+    return {
+        message,
+        finish(signature) {
+            const payload = {
+                domain: opts.domain,
+                address: toChecksumAddress(opts.address),
+                statement: opts.statement,
+                uri: opts.uri,
+                version: opts.version ?? "1",
+                chainId: payloadChainId(opts.chainId),
+                type: opts.type ?? "eip191",
+                nonce: opts.nonce,
+                issuedAt: opts.issuedAt,
+                expirationTime: opts.expirationTime,
+                signature,
+            };
+            if (opts.resources !== undefined) {
+                payload.resources = opts.resources;
+            }
+            return {
+                "SIGN-IN-WITH-X": Buffer.from(JSON.stringify(payload)).toString("base64"),
+            };
+        },
+    };
+}
 /**
  * Format an EIP-4361 (SIWE) message. Must be byte-for-byte compatible
  * with the `siwe` library's message format used server-side for verification.
@@ -85,29 +112,54 @@ export function formatSIWEMessage(opts, address) {
     }
     return lines.join("\n");
 }
+/** SIWX headers signed with a local private key (synchronous). */
 export function buildSIWxAuthHeaders(opts) {
-    const message = formatSIWEMessage(opts, opts.wallet.address);
-    const signature = personalSign(opts.wallet.privateKey, opts.wallet.address, message);
-    const payload = {
-        domain: opts.domain,
-        address: toChecksumAddress(opts.wallet.address),
-        statement: opts.statement,
-        uri: opts.uri,
-        version: opts.version ?? "1",
-        chainId: payloadChainId(opts.chainId),
-        type: opts.type ?? "eip191",
-        nonce: opts.nonce,
-        issuedAt: opts.issuedAt,
-        expirationTime: opts.expirationTime,
-        signature,
-    };
-    if (opts.resources !== undefined) {
-        payload.resources = opts.resources;
+    if (!opts.wallet.privateKey) {
+        throw new SignerWalletError();
     }
+    const prepared = prepareSIWx({ ...opts, address: opts.wallet.address });
+    return prepared.finish(personalSign(opts.wallet.privateKey, opts.wallet.address, prepared.message));
+}
+/**
+ * Thrown where a synchronous signature is required but the wallet signs
+ * through a signer (`wallet.json` `signer`). Callers that can wait use
+ * `getWalletAuthHeadersAsync` with the SDK's signer instead.
+ */
+export class SignerWalletError extends Error {
+    code = "SIGNER_WALLET_ASYNC";
+    constructor() {
+        super("This wallet signs through a signer (wallet.json 'signer'), which this synchronous path cannot use.");
+        this.name = "SignerWalletError";
+    }
+}
+function walletSIWxOptions(path) {
+    const apiBase = getApiBase();
+    const url = new URL(apiBase);
+    const now = new Date();
     return {
-        "SIGN-IN-WITH-X": Buffer.from(JSON.stringify(payload)).toString("base64"),
+        domain: url.hostname,
+        uri: `${apiBase}${path}`,
+        statement: "Sign in to Run402",
+        chainId: "eip155:84532",
+        nonce: randomBytes(16).toString("hex"),
+        issuedAt: now.toISOString(),
+        expirationTime: new Date(now.getTime() + 5 * 60 * 1000).toISOString(),
     };
 }
+/**
+ * SIWX headers for any wallet: a key-backed wallet signs locally; a
+ * signer-backed one through `signerFor(wallet)`. Null when no wallet exists.
+ */
+export async function getWalletAuthHeadersAsync(path, walletPath, signerFor) {
+    const localWallet = readWallet(walletPath);
+    if (!localWallet || !localWallet.address)
+        return null;
+    if (!isSignerWallet(localWallet))
+        return getWalletAuthHeaders(path, walletPath);
+    const prepared = prepareSIWx({ ...walletSIWxOptions(path), address: localWallet.address });
+    const sign = await signerFor(localWallet);
+    return prepared.finish(await sign(prepared.message));
+}
 /**
  * Get SIWX auth headers for the Run402 API.
  * Returns null if no local wallet is configured.
@@ -121,26 +173,13 @@ export function getWalletAuthHeaders(path, walletPath) {
     // this helper returns SIWxAuthHeaders | null. Re-throw so callers above
     // the CLI's wrapper (e.g. SDK paid-fetch) can decide whether to swallow it.
     const localWallet = readWallet(walletPath);
-    if (!localWallet || !localWallet.address || !localWallet.privateKey)
+    if (!localWallet || !localWallet.address)
         return null;
-    const apiBase = getApiBase();
-    const url = new URL(apiBase);
-    const domain = url.hostname;
-    const uri = `${apiBase}${path}`;
-    const nonce = randomBytes(16).toString("hex");
-    const now = new Date();
-    const issuedAt = now.toISOString();
-    const expirationTime = new Date(now.getTime() + 5 * 60 * 1000).toISOString();
-    return buildSIWxAuthHeaders({
-        wallet: localWallet,
-        domain,
-        uri,
-        statement: "Sign in to Run402",
-        chainId: "eip155:84532",
-        nonce,
-        issuedAt,
-        expirationTime,
-    });
+    if (isSignerWallet(localWallet))
+        throw new SignerWalletError();
+    if (!localWallet.privateKey)
+        return null;
+    return buildSIWxAuthHeaders({ wallet: localWallet, ...walletSIWxOptions(path) });
 }
 function messageChainId(chainId) {
     if (typeof chainId === "number")

package/core-dist/wallet.js

@@ -6,6 +6,12 @@ import { getWalletPath } from "./config.js";
 const ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
 // 0x-prefixed 64-hex secp256k1 private key (32 bytes).
 const PRIVATE_KEY_RE = /^0x[a-fA-F0-9]{64}$/;
+// arn:aws:kms:<region>:<account>:key/<id>
+export const KMS_KEY_ARN_RE = /^arn:aws[a-z-]*:kms:([a-z0-9-]+):\d{12}:key\/[A-Za-z0-9-]+$/;
+/** True when the wallet signs through a signer instead of a local key. */
+export function isSignerWallet(wallet) {
+    return wallet.signer !== undefined;
+}
 /**
  * Load the agent wallet from disk.
  *
@@ -78,6 +84,21 @@ export function readWallet(path) {
         throw new Error("wallet.json missing valid 'address' (expected 0x-prefixed 40-hex string). " +
             "Back up the file and run 'run402 init' to recreate it.");
     }
+    if (data.privateKey !== undefined && data.signer !== undefined) {
+        throw new Error(`${p} has both 'privateKey' and 'signer'; a wallet is backed by exactly one. ` +
+            "Remove the one that does not belong to this wallet.");
+    }
+    if (data.signer !== undefined) {
+        const signer = data.signer;
+        if (!signer || typeof signer !== "object" || signer.kind !== "aws_kms" ||
+            typeof signer.key_arn !== "string" || !KMS_KEY_ARN_RE.test(signer.key_arn) ||
+            typeof signer.region !== "string" || signer.region.length === 0 ||
+            (signer.aws_profile !== undefined && (typeof signer.aws_profile !== "string" || signer.aws_profile.length === 0))) {
+            throw new Error(`${p} has a malformed 'signer' (expected { kind: "aws_kms", key_arn, region, aws_profile? }). ` +
+                "Re-import the wallet with 'run402 wallets import <name> --kms <key-arn>'.");
+        }
+        return data;
+    }
     if (typeof data.privateKey !== "string" || !PRIVATE_KEY_RE.test(data.privateKey)) {
         throw new Error("wallet.json missing valid 'privateKey' (expected 0x-prefixed 64-hex string). " +
             "Back up the file and run 'run402 init' to recreate it.");

package/lib/ci.mjs

@@ -325,7 +325,7 @@ async function linkGithub(args) {
 
   let signedDelegation;
   try {
-    signedDelegation = signCiDelegation(values, { apiBase: API });
+    signedDelegation = await signCiDelegation(values, { apiBase: API });
   } catch (err) {
     fail({
       code: "NO_WALLET",

package/lib/command-manifest.mjs

@@ -466,6 +466,9 @@ export const COMMAND_MANIFEST = [
   { path: ["contracts", "set-alert"], positionals: [p("signer_id")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["cwlt_gate1", "--threshold-wei", "1"] },
   { path: ["contracts", "call"], positionals: [p("signer_id")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["cwlt_gate1", "--to", "0x4444444444444444444444444444444444444444", "--abi", "[]", "--fn", "noop", "--args", "[]"] },
   { path: ["contracts", "deploy"], positionals: [p("signer_id")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["cwlt_gate1", "--bytecode", "0x00"] },
+  { path: ["contracts", "transfers", "create"], positionals: [p("signer_id")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["cwlt_gate1", "--to", "0x4444444444444444444444444444444444444444", "--amount", "1"] },
+  { path: ["contracts", "transfers", "get"], positionals: [p("signer_id")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["cwlt_gate1", "--transfer", "txf_gate1"] },
+  { path: ["contracts", "transfers", "list"], positionals: [p("signer_id")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["cwlt_gate1"] },
   { path: ["contracts", "read"], positionals: [], projectScoped: false, legacyPositionalProject: false, minimalArgs: ["--chain", "base-sepolia", "--to", "0x4444444444444444444444444444444444444444", "--abi", "[]", "--fn", "noop", "--args", "[]"] },
   { path: ["contracts", "status"], positionals: [p("call_id")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["ccall_gate1"] },
   { path: ["contracts", "drain"], positionals: [p("signer_id")], projectScoped: true, legacyPositionalProject: true, minimalArgs: ["cwlt_gate1", "--to", "0x4444444444444444444444444444444444444444", "--confirm"] },

package/lib/config.mjs

@@ -81,7 +81,15 @@ export function saveWallet(data) {
   coreSaveWallet(data);
 }
 
+/**
+ * The wallet's SIWX headers for `path`, or the NO_WALLET failure. Most
+ * callers use this only as a "a wallet is configured" check before handing
+ * the request to the SDK. A signer-backed wallet (KMS) signs asynchronously
+ * inside the SDK, so here it only proves the wallet exists and returns no
+ * headers; callers that need its signature use the SDK.
+ */
 export function walletAuthHeaders(path) {
+  if (readWallet()?.signer) return {};
   const headers = coreGetWalletAuthHeaders(path);
   if (!headers) {
     fail({

package/lib/contacts.mjs

@@ -104,7 +104,7 @@ async function preferences(args) {
     }
   }
   try {
-    const data = await getSdk().admin.setNotificationPreferences(patch, sessionProofs("/agent/v1/notifications/preferences"));
+    const data = await getSdk().admin.setNotificationPreferences(patch, await sessionProofs("/agent/v1/notifications/preferences"));
     console.log(JSON.stringify(data, null, 2));
   } catch (err) {
     reportSdkError(err);
@@ -185,7 +185,7 @@ async function channelsConnect(args) {
     fail({ code: "BAD_USAGE", message: `Unexpected argument for notifications channels connect: ${positionals[1]}` });
   }
 
-  const proofs = sessionProofs("/agent/v1/notifications/channels/telegram");
+  const proofs = await sessionProofs("/agent/v1/notifications/channels/telegram");
   let pending;
   try {
     pending = await getSdk().admin.channels.connectTelegram(label ? { label } : {}, proofs);
@@ -234,7 +234,7 @@ async function channelsRevoke(args) {
   });
   walletAuthHeaders("/agent/v1/notifications/channels/telegram");
   try {
-    console.log(JSON.stringify(await getSdk().admin.channels.revokeTelegram(bindingId, sessionProofs("/agent/v1/notifications/channels/telegram")), null, 2));
+    console.log(JSON.stringify(await getSdk().admin.channels.revokeTelegram(bindingId, await sessionProofs("/agent/v1/notifications/channels/telegram")), null, 2));
   } catch (err) {
     reportSdkError(err);
   }

package/lib/contracts.mjs

@@ -11,7 +11,7 @@ import {
   failUnknownSubcommand,
 } from "./argparse.mjs";
 
-const HELP = `run402 contracts — KMS-backed Ethereum signers for smart-contract calls
+const HELP = `run402 contracts — signers, your app's wallet, for smart-contract calls
 
   Pricing: $0.04/day per signer ($1.20/month) plus $0.000005 per contract call.
   Signer creation requires $1.20 of allowance (30 days of rent).
@@ -22,19 +22,25 @@ Usage:
 
 Subcommands:
   provision-signer <project_id> --chain <base-mainnet|base-sepolia> [--recovery 0x...]
-    Provision a KMS signer ($0.04/day, requires $1.20 prepay).
+    Provision a signer ($0.04/day wallet rent, requires $1.20 prepay).
   get-signer <project_id> <signer_id>
     Get signer metadata + live native balance.
   list-signers <project_id>
-    List all KMS signers for the project (includes deleted).
+    List all signers for the project (includes deleted).
+  transfers create <signer_id> --to 0x... --amount <base units> [--asset usdc] [--chain <base-mainnet|base-sepolia>] [--idempotency-key <k>]
+    Send a token from the signer with no gas on it: the platform's facilitator settles the signed EIP-3009 authorization and pays the gas. One signing fee.
+  transfers get <signer_id> --transfer <transfer_id>
+    Read one transfer (status, tx hash, nonce, failure phase).
+  transfers list <signer_id>
+    The signer's transfers, newest first.
   set-recovery <project_id> <signer_id> [--address 0x... | --clear]
     Set/clear the optional recovery address.
   set-alert <project_id> <signer_id> --threshold-wei <n>
     Set the low-balance alert threshold (in wei).
   call <project_id> <signer_id> --to 0x... --abi <json> --fn <name> --args <json> [--value-wei <n>] [--idempotency-key <k>]
-    Submit a contract write call (chain gas + $0.000005 KMS sign fee).
+    Submit a contract write call (gas from the signer's balance, topped up at cost when short, + $0.000005 signing fee).
   deploy <project_id> <signer_id> --bytecode 0x... [--chain <base-mainnet|base-sepolia>] [--value-wei <n>] [--idempotency-key <k>]
-    Deploy a contract (chain gas + $0.000005 KMS sign fee). Returns deterministic CREATE address synchronously.
+    Deploy a contract (gas from the signer's balance + $0.000005 signing fee). Returns deterministic CREATE address synchronously.
   read --chain <chain> --to 0x... --abi <json> --fn <name> --args <json>
     Read-only contract call (free).
   status <project_id> <call_id>
@@ -42,7 +48,7 @@ Subcommands:
   drain <project_id> <signer_id> --to 0x... --confirm
     Drain native balance to a destination address. Works on suspended signers.
   delete <project_id> <signer_id> --confirm
-    Schedule the KMS key for deletion (refused if balance >= dust).
+    Schedule the signing key for deletion (refused if balance >= dust).
 
 Examples:
   run402 contracts provision-signer proj_abc --chain base-mainnet
@@ -50,7 +56,22 @@ Examples:
 `;
 
 const SUB_HELP = {
-  "provision-signer": `run402 contracts provision-signer — Provision a KMS-backed signer
+  transfers: `run402 contracts transfers — Send a token from a signer with no gas on it
+
+Usage:
+  run402 contracts transfers create <signer_id> --to 0x... --amount <base units> [--asset usdc] [--chain <base-mainnet|base-sepolia>] [--idempotency-key <k>] [--project <project_id>]
+  run402 contracts transfers get <signer_id> --transfer <transfer_id> [--project <project_id>]
+  run402 contracts transfers list <signer_id> [--project <project_id>]
+
+The signer is the payer of an x402 payment: Run402 signs the token's EIP-3009
+authorization with the signer's key and its facilitator settles it and pays the
+gas. One $0.000005 signing fee, no gas, no ETH on the signer. --amount is in the
+asset's base units (USDC: 6 decimals; 100000 is $0.10). An idempotency key
+makes a repeat return the transfer already made; a transfer that failed before
+settlement re-executes under its key, one that died in settlement never does.
+A "unknown" status means the settle outcome never came back: poll it with get.
+`,
+  "provision-signer": `run402 contracts provision-signer — Provision a signer
 
 Usage:
   run402 contracts provision-signer --chain <chain> [--project <project_id>] [options]
@@ -91,11 +112,11 @@ Legacy (still supported):
   run402 contracts call <project_id> <signer_id> --to 0x... --abi <json>
     --fn <name> --args <json> [options]
 `,
-  deploy: `run402 contracts deploy — Deploy a smart contract from a KMS signer
+  deploy: `run402 contracts deploy — Deploy a smart contract from a signer
 
-KMS-signs a contract-creation transaction (to: null + data: bytecode) and broadcasts.
+the platform's key custody-signs a contract-creation transaction (to: null + data: bytecode) and broadcasts.
 Returns the deterministic CREATE address synchronously — known from (signer, nonce)
-before the tx confirms. Cost: chain gas at-cost + $0.000005 KMS sign fee.
+before the tx confirms. Cost: chain gas at-cost + $0.000005 signing fee.
 
 Usage:
   run402 contracts deploy <signer_id> --bytecode 0x... [--project <project_id>] [options]
@@ -130,7 +151,7 @@ Usage:
 Legacy (still supported):
   run402 contracts drain <project_id> <signer_id> --to 0x... --confirm
 `,
-  delete: `run402 contracts delete — Schedule the KMS key for deletion
+  delete: `run402 contracts delete — Schedule the signing key for deletion
 
 Usage:
   run402 contracts delete <signer_id> --confirm [--project <project_id>]
@@ -153,7 +174,7 @@ Arguments:
 Examples:
   run402 contracts get-signer prj_abc123 cwlt_abc123
 `,
-  "list-signers": `run402 contracts list-signers — List all KMS signers for a project
+  "list-signers": `run402 contracts list-signers — List all signers for a project
 
 Usage:
   run402 contracts list-signers [--project <project_id>]
@@ -344,7 +365,7 @@ async function call(projectId, signerId, args) {
     fail({
       code: "BAD_USAGE",
       message: "Required flags: --to, --abi, --fn, --args.",
-      hint: "Cost: chain gas + $0.000005 KMS sign fee.",
+      hint: "Cost: chain gas + $0.000005 signing fee.",
     });
   }
   assertAllowedValue(chain, ["base-mainnet", "base-sepolia"], "--chain");
@@ -369,6 +390,89 @@ async function call(projectId, signerId, args) {
   }
 }
 
+/**
+ * `run402 contracts transfers create|get|list` — a signer sends a token with
+ * no gas on it: the gateway signs the EIP-3009 authorization with the
+ * signer's key and the platform's facilitator settles it and pays the gas.
+ */
+async function transfers(projectId, args) {
+  const [transferAction, ...rest] = Array.isArray(args) ? args : [];
+  if (transferAction === "create") return transfersCreate(projectId, rest[0], rest.slice(1));
+  if (transferAction === "get") return transfersGet(projectId, rest[0], rest.slice(1));
+  if (transferAction === "list") return transfersList(projectId, rest[0], rest.slice(1));
+  return fail({
+    code: "BAD_USAGE",
+    message: `Unknown contracts transfers verb: ${transferAction ?? "(none)"}`,
+    hint: "Verbs: create <signer_id> --to 0x… --amount <base units> [--asset usdc] [--chain …] [--idempotency-key <k>]; get <signer_id> --transfer <transfer_id>; list <signer_id>.",
+  });
+}
+
+async function transfersCreate(projectId, signerId, args) {
+  const parsedArgs = normalizeArgv(args);
+  const valueFlags = ["--to", "--amount", "--asset", "--chain", "--idempotency-key"];
+  assertKnownFlags(parsedArgs, [...valueFlags, "--help", "-h"], valueFlags);
+  const extra = positionalArgs(parsedArgs, valueFlags);
+  if (!signerId || !/^[a-z]+_[A-Za-z0-9]{8,}$/.test(signerId)) {
+    fail({ code: "BAD_USAGE", message: "Missing <signer_id>.", hint: "run402 contracts transfers create <signer_id> --to 0x… --amount <base units>" });
+  }
+  if (extra.length > 0) {
+    fail({ code: "BAD_USAGE", message: `Unexpected argument for contracts transfers create: ${extra[0]}` });
+  }
+  const to = flagValue(parsedArgs, "--to");
+  const amount = flagValue(parsedArgs, "--amount");
+  const asset = flagValue(parsedArgs, "--asset") || "usdc";
+  const chain = flagValue(parsedArgs, "--chain") || "base-mainnet";
+  const idempotency = flagValue(parsedArgs, "--idempotency-key");
+  if (!to || !amount) {
+    fail({
+      code: "BAD_USAGE",
+      message: "Required flags: --to, --amount.",
+      hint: "--amount is in the asset's base units as a decimal string (USDC: 6 decimals, so 100000 is $0.10). Cost: one $0.000005 signing fee, no gas.",
+    });
+  }
+  assertAllowedValue(chain, ["base-mainnet", "base-sepolia"], "--chain");
+  validateEvmAddress(to, "--to");
+  if (!/^[1-9][0-9]*$/.test(amount)) {
+    fail({ code: "BAD_USAGE", message: "--amount must be a positive integer in the asset's base units." });
+  }
+  try {
+    const data = await getSdk().contracts.transfer(projectId, {
+      signerId, chain, asset, to, amount, idempotencyKey: idempotency ?? undefined,
+    });
+    console.log(JSON.stringify(data, null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function transfersGet(projectId, signerId, args) {
+  const parsedArgs = normalizeArgv(args);
+  assertKnownFlags(parsedArgs, ["--transfer", "--help", "-h"], ["--transfer"]);
+  const extra = positionalArgs(parsedArgs, ["--transfer"]);
+  const transferId = flagValue(parsedArgs, "--transfer");
+  if (!signerId || !transferId || extra.length > 0) {
+    fail({ code: "BAD_USAGE", message: "Usage: run402 contracts transfers get <signer_id> --transfer <transfer_id>" });
+  }
+  try {
+    console.log(JSON.stringify(await getSdk().contracts.transferStatus(projectId, signerId, transferId), null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
+async function transfersList(projectId, signerId, args) {
+  const parsedArgs = normalizeArgv(args);
+  assertKnownFlags(parsedArgs, ["--help", "-h"], []);
+  if (!signerId) {
+    fail({ code: "BAD_USAGE", message: "Usage: run402 contracts transfers list <signer_id>" });
+  }
+  try {
+    console.log(JSON.stringify(await getSdk().contracts.listTransfers(projectId, signerId), null, 2));
+  } catch (err) {
+    reportSdkError(err);
+  }
+}
+
 async function deploy(projectId, signerId, args) {
   const parsedArgs = normalizeArgv(args);
   const valueFlags = ["--bytecode", "--value-wei", "--chain", "--idempotency-key"];
@@ -385,7 +489,7 @@ async function deploy(projectId, signerId, args) {
     fail({
       code: "BAD_USAGE",
       message: "Required flag: --bytecode (0x-prefixed hex; full creation calldata = creation bytecode + ABI-encoded constructor args, concatenated client-side).",
-      hint: "Cost: chain gas + $0.000005 KMS sign fee. Returns deterministic CREATE address synchronously.",
+      hint: "Cost: chain gas + $0.000005 signing fee. Returns deterministic CREATE address synchronously.",
     });
   }
   assertAllowedValue(chain, ["base-mainnet", "base-sepolia"], "--chain");
@@ -469,7 +573,7 @@ async function drain(projectId, signerId, args) {
     fail({
       code: "BAD_USAGE",
       message: "Required: --to 0x... and --confirm.",
-      hint: "Cost: chain gas + $0.000005 KMS sign fee.",
+      hint: "Cost: chain gas + $0.000005 signing fee.",
     });
   }
   validateEvmAddress(to, "--to");
@@ -508,6 +612,13 @@ export async function run(sub, args) {
   // unknown subcommands (and the anonymous `read`) never trip project
   // resolution.
   const select = () => resolveProjectSelector(normalizeArgv(Array.isArray(args) ? args : []));
+  // The transfers group dispatches with `if` (not `case`) so the sync test
+  // inventories its leaf actions through parseContractsTransferActions.
+  if (sub === "transfers") {
+    const { projectId, rest } = select();
+    await transfers(projectId, rest);
+    return;
+  }
   switch (sub) {
     case "provision-signer": { const { projectId, rest } = select(); await provisionSigner(projectId, rest); break; }
     case "get-signer":       { const { projectId, rest } = select(); await getSigner(projectId, rest[0], rest.slice(1)); break; }

package/lib/orgs.mjs

@@ -21,7 +21,7 @@ Usage:
   run402 orgs list
   run402 orgs get    [<org_id>]
   run402 orgs rename [<org_id>] --name <display_name>   (or: --clear to remove the label)
-  run402 orgs payout-wallet [<org_id>] <wallet_address>  (or: --clear to remove the explicit default)
+  run402 orgs payout-wallet [<org_id>] <wallet_address>  (or: --signer <signer_id>; --clear removes the explicit default)
   run402 orgs lightning-receiver set    [<org_id>] <nwc-uri | ->   (receive-only NWC pairing; - reads it from stdin)
   run402 orgs lightning-receiver status [<org_id>]
   run402 orgs lightning-receiver delete [<org_id>]
@@ -161,6 +161,7 @@ call after a dropped response can never double-bill.
 
 Usage:
   run402 orgs payout-wallet [<org_id>] <wallet_address>
+  run402 orgs payout-wallet [<org_id>] --signer <signer_id>
   run402 orgs payout-wallet [<org_id>] --clear
 
 Legacy (still supported):
@@ -170,6 +171,11 @@ Admin/owner-only + step-up gated. The wallet must already be active and linked
 to the same org. This wallet receives x402 settlement for function web routes
 that declare pricing.pay_to = "org_default_payout". Pass --clear to remove the
 explicit default; a single active org wallet may still resolve automatically.
+Pass --signer <signer_id> to make one of the org's own signers (your app's
+wallet, run402 contracts provision-signer) the payout address instead, so what
+your priced routes earn is what your app pays out from. The signer must be
+active and owned by a project of this org; while it is selected, that project
+cannot be transferred out.
 
 The JSON response includes recovery.status, active_wallet_count, and
 next_actions for PAYOUT_WALLET_REQUIRED / PAYOUT_WALLET_AMBIGUOUS setup.
@@ -478,20 +484,24 @@ async function rename(args) {
 
 async function payoutWallet(args) {
   const a = normalizeArgv(args);
-  assertKnownFlags(a, ["--org", "--address", "--clear", "--help", "-h"], ["--org", "--address"]);
+  assertKnownFlags(a, ["--org", "--address", "--signer", "--clear", "--help", "-h"], ["--org", "--address", "--signer"]);
   const clear = a.includes("--clear");
   const walletFlag = flagValue(a, "--address");
-  const single = clear || walletFlag !== null;
-  const { orgId: org, rest: pos } = await takeOrgPositional(a, ["--org", "--address"], { cmd: "orgs" });
+  const signerFlag = flagValue(a, "--signer");
+  if (signerFlag !== null && (clear || walletFlag !== null)) {
+    fail({ code: "BAD_USAGE", message: "--signer cannot be combined with --address or --clear." });
+  }
+  const single = clear || walletFlag !== null || signerFlag !== null;
+  const { orgId: org, rest: pos } = await takeOrgPositional(a, ["--org", "--address", "--signer"], { cmd: "orgs" });
   requireRest(pos, {
     min: single ? 0 : 1,
     max: single ? 0 : 1,
-    command: "run402 orgs payout-wallet [<org_id>] --address <wallet_address>",
-    missing: "Missing <wallet_address> (use --address, or pass --clear).",
+    command: "run402 orgs payout-wallet [<org_id>] --address <wallet_address> | --signer <signer_id> | --clear",
+    missing: "Missing <wallet_address> (use --address, --signer <signer_id>, or --clear).",
   });
-  const walletAddress = clear ? null : (walletFlag ?? pos[0]);
+  const input = signerFlag !== null ? { signerId: signerFlag } : { walletAddress: clear ? null : (walletFlag ?? pos[0]) };
   try {
-    console.log(JSON.stringify(await getSdk().org(org).setPayoutWallet({ walletAddress }), null, 2));
+    console.log(JSON.stringify(await getSdk().org(org).setPayoutWallet(input), null, 2));
   } catch (err) {
     reportSdkError(err);
   }

package/lib/session-proofs.mjs

@@ -9,13 +9,17 @@
  * signed in once is never asked to enroll a second passkey. With no live cached
  * session this returns `undefined` and the verb uses wallet auth alone.
  */
-import { walletAuthHeaders } from "./config.mjs";
+import { walletAuthHeaders, walletFile } from "./config.mjs";
 import { loadLiveControlPlaneSession } from "../core-dist/control-plane-session.js";
+import { getWalletAuthHeadersAsync } from "../core-dist/wallet-auth.js";
+import { personalMessageSignerFor } from "#sdk/node";
 
 /** `{ siwx, token }` for `path`, or `undefined` when no live sign-in session is cached. */
-export function sessionProofs(path) {
-  const siwx = walletAuthHeaders(path)["SIGN-IN-WITH-X"];
+export async function sessionProofs(path) {
+  walletAuthHeaders(path); // NO_WALLET when none is configured
   const live = loadLiveControlPlaneSession();
   if (!live || !live.control_plane_session_token) return undefined;
-  return { siwx, token: live.control_plane_session_token };
+  // A key-backed wallet signs locally; a signer-backed one (KMS) through its signer.
+  const headers = await getWalletAuthHeadersAsync(path, walletFile(), (w) => personalMessageSignerFor(w));
+  return { siwx: headers["SIGN-IN-WITH-X"], token: live.control_plane_session_token };
 }

package/lib/subscriptions.mjs

@@ -136,7 +136,7 @@ async function rulesAdd(args) {
 
   walletAuthHeaders("/agent/v1/notifications/rules");
   try {
-    console.log(JSON.stringify(await getSdk().admin.rules.create(input, sessionProofs("/agent/v1/notifications/rules")), null, 2));
+    console.log(JSON.stringify(await getSdk().admin.rules.create(input, await sessionProofs("/agent/v1/notifications/rules")), null, 2));
   } catch (err) {
     reportSdkError(err);
   }
@@ -162,7 +162,7 @@ async function rulesRm(args) {
   });
   walletAuthHeaders("/agent/v1/notifications/rules");
   try {
-    console.log(JSON.stringify(await getSdk().admin.rules.delete(ruleId, sessionProofs("/agent/v1/notifications/rules")), null, 2));
+    console.log(JSON.stringify(await getSdk().admin.rules.delete(ruleId, await sessionProofs("/agent/v1/notifications/rules")), null, 2));
   } catch (err) {
     reportSdkError(err);
   }