@stellar-agent/cli 0.4.3 → 0.5.0

package/dist/index.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
-import { EXIT_CODES, StellarAgentError, configSchema, createDefaultConfig, fail, formatStroops, ok, parseAmount, paymentRequestSchema, redactSensitive, resolvePath, serializeError } from "@stellar-agent/core";
+import { EXIT_CODES, MAINNET_AGENT_WALLET_AUTOSIGN_WARNING, MAINNET_AGENT_WALLET_WARNING, StellarAgentError, configSchema, assertMainnetAgentWalletBalanceWithinBudget as assertCoreMainnetAgentWalletBalanceWithinBudget, assertMainnetAgentWalletPaymentPreflight, createDefaultConfig, fail, formatStroops, mainnetAgentWalletConfigFingerprint as coreMainnetAgentWalletConfigFingerprint, mainnetAgentWalletIntegrityFailures as coreMainnetAgentWalletIntegrityFailures, mainnetAgentWalletRiskBudgetState as coreMainnetAgentWalletRiskBudgetState, ok, parseAmount, paymentRequestSchema, redactSensitive, resolvePath, serializeError } from "@stellar-agent/core";
 import { latestLedger, lookupTransaction, parseStellarCliTransactionHash, resolveNetworkProfile } from "@stellar-agent/stellar";
 import { appendEvent, latestReceipt, listReceipts, readReceipt, spendHistoryFromReceipts, verifyReceipt, writeReceipt } from "@stellar-agent/ledger-logger";
 import { DEFAULT_MAINNET_POLICY, DEFAULT_TESTNET_POLICY, defaultPolicyForNetwork, evaluateDefiAquariusRequest, evaluateDefiBlendRequest, evaluateMarketLiquidityRequest, evaluatePaymentRequest, parsePolicyYaml, policyToYaml } from "@stellar-agent/policy";
 import { createTestnetHarness, ensureWallet, importPublicWallet, initTestnetWorkspace, listWalletPublicViews, loadWallet, loadWalletPublic, walletBalances, walletTrustlines } from "@stellar-agent/testnet-suite";
 import { Command } from "commander";
+import { createHash } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { createRequire } from "node:module";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
@@ -15,6 +16,7 @@ const require = createRequire(import.meta.url);
 const { version: VERSION } = require("../package.json");
 export function buildProgram() {
     const program = new Command();
+    const parseState = { json: false };
     program
         .name("stellar-agent")
         .description("Stellar Agent Bridge\n\nSafe agentic payments on Stellar from your terminal.")
@@ -49,12 +51,19 @@ Common commands:
   stellar-agent market pools list --asset-a XLM --asset-b USDC:G... --json
   stellar-agent market lp preflight --pool 0123... --max-a 1 --max-b 1 --min-price 0.9 --max-price 1.1 --json
   stellar-agent policy explain --request ./payment-request.json`);
+    program.configureOutput({
+        writeErr: (str) => {
+            if (!parseState.json)
+                process.stderr.write(str);
+        }
+    });
     addProfileCommands(program);
     addTestnetCommands(program);
     addWalletCommands(program);
     addApprovalCommands(program);
     addTransactionCommands(program);
     addPayCommands(program);
+    addX402Commands(program);
     addClaimableCommands(program);
     addContractCommands(program);
     addMarketCommands(program);
@@ -65,21 +74,31 @@ Common commands:
     addReceiptCommands(program);
     addCacheCommands(program);
     addMainnetCommands(program);
-    installVersionPrecheck(program);
+    installVersionPrecheck(program, parseState);
     program.action(() => {
         program.outputHelp();
     });
     return program;
 }
-function installVersionPrecheck(program) {
+function installVersionPrecheck(program, parseState) {
     const originalParseAsync = program.parseAsync.bind(program);
     program.parseAsync = (async (argv, parseOptions) => {
+        parseState.json = jsonOptionRequested(argv, parseOptions);
         const versionOptions = rootVersionOptions(program, argv, parseOptions);
         if (versionOptions) {
             printVersion(versionOptions);
-            program._exit(EXIT_CODES.success, "commander.version", VERSION);
+            return program;
+        }
+        installExitOverride(program);
+        try {
+            return await originalParseAsync(argv, parseOptions);
+        }
+        catch (error) {
+            if (isCommanderHelpOrVersionExit(error))
+                return program;
+            printError({ json: parseState.json }, commanderErrorToStellarAgentError(error));
+            return program;
         }
-        return await originalParseAsync(argv, parseOptions);
     });
 }
 function rootVersionOptions(program, argv = process.argv, parseOptions) {
@@ -117,6 +136,14 @@ function userArgs(argv, parseOptions) {
         return args.slice(1);
     return args.slice(2);
 }
+function jsonOptionRequested(argv = process.argv, parseOptions) {
+    return userArgs(argv, parseOptions).includes("--json");
+}
+function installExitOverride(command) {
+    command.exitOverride();
+    for (const subcommand of command.commands)
+        installExitOverride(subcommand);
+}
 function addCacheCommands(program) {
     const cache = program.command("cache").description("Inspect and clear in-process session caches.");
     cache
@@ -623,6 +650,7 @@ function addApprovalCommands(program) {
         .description("Start the local approval bridge HTTP server.")
         .option("--host <host>", "Host", "127.0.0.1")
         .option("--port <port>", "Port", parsePortOption, 0)
+        .option("--allow-remote-access", "Allow binding the approval bridge to a non-loopback host")
         .action(async (options, command) => {
         const parent = command.optsWithGlobals();
         const config = await loadConfig(parent);
@@ -632,13 +660,15 @@ function addApprovalCommands(program) {
         const bridge = await startApprovalBridge({
             approvalsDir: context.config.storage.approvalsDir,
             host: options.host,
-            port: options.port
+            port: options.port,
+            allowRemoteAccess: Boolean(options.allowRemoteAccess)
         });
         if (parent.json) {
-            process.stdout.write(`${JSON.stringify(ok({ url: bridge.url, authToken: bridge.authToken, approvalsDir: context.config.storage.approvalsDir }))}\n`);
+            process.stdout.write(`${JSON.stringify(ok({ url: bridge.url, uiUrl: bridge.uiUrl, authToken: bridge.authToken, approvalsDir: context.config.storage.approvalsDir }))}\n`);
         }
         else {
             process.stdout.write(`Approval bridge listening at ${bridge.url}\n`);
+            process.stdout.write(`Open approval UI: ${bridge.uiUrl}\n`);
             process.stdout.write("Approval bridge API requires the printed session token for non-browser requests.\n");
             process.stdout.write(`Session token: ${bridge.authToken}\n`);
         }
@@ -684,6 +714,7 @@ function addTransactionCommands(program) {
         const policyDecision = evaluatePaymentRequest(policy, request, history);
         if (policyDecision.status === "denied")
             throw policyDeniedError();
+        const mainnetAgentWallet = await assertMainnetAgentWalletPaymentAllowed(context, request);
         if (profile.realFunds && policyDecision.status === "requires_approval") {
             throw new StellarAgentError({
                 code: "APPROVAL_REQUIRED",
@@ -710,7 +741,13 @@ function addTransactionCommands(program) {
             profile: profile.name,
             data: { source: sourcePublicKey, destination: options.to, asset: options.asset, amount: built.amount, policyDecision }
         });
-        return { ...built, policyDecision, spendHistory: history, realFunds: profile.realFunds };
+        return {
+            ...built,
+            policyDecision,
+            spendHistory: mainnetAgentWallet?.spendHistory ?? history,
+            realFunds: profile.realFunds,
+            ...(mainnetAgentWallet === undefined ? {} : { mainnetAgentWallet })
+        };
     }, "Unsigned payment transaction built."));
     tx
         .command("request-payment-signature")
@@ -747,6 +784,7 @@ function addTransactionCommands(program) {
         const policyDecision = evaluatePaymentRequest(policy, request, history);
         if (policyDecision.status === "denied")
             throw policyDeniedError();
+        const mainnetAgentWallet = await assertMainnetAgentWalletPaymentAllowed(context, request);
         const built = await buildPaymentTransactionXdr({
             sourcePublicKey,
             destination: options.to,
@@ -762,7 +800,8 @@ function addTransactionCommands(program) {
             approvalsDir: context.config.storage.approvalsDir,
             network: profile.name,
             transactionXdr: built.xdr,
-            summary: options.summary ?? `Sign ${built.amount} ${built.asset} payment to ${options.to} on ${profile.name}`
+            summary: options.summary ?? `Sign ${built.amount} ${built.asset} payment to ${options.to} on ${profile.name}`,
+            payment: request
         });
         await appendEvent(join(context.config.storage.logsDir, "events.jsonl"), {
             event: "approval_requested",
@@ -772,7 +811,14 @@ function addTransactionCommands(program) {
             requestId: approval.id,
             data: { approval, source: sourcePublicKey, destination: options.to, asset: options.asset, amount: built.amount, policyDecision }
         });
-        return { approval, built, policyDecision, spendHistory: history, realFunds: profile.realFunds };
+        return {
+            approval,
+            built,
+            policyDecision,
+            spendHistory: mainnetAgentWallet?.spendHistory ?? history,
+            realFunds: profile.realFunds,
+            ...(mainnetAgentWallet === undefined ? {} : { mainnetAgentWallet })
+        };
     }, "Payment signature approval request created."));
     tx
         .command("submit-xdr")
@@ -851,6 +897,10 @@ function addTransactionCommands(program) {
             acknowledgeRealFunds: Boolean(options.iUnderstandRealFunds),
             action: "signed approval submission"
         });
+        const approvalPayment = approval.payment;
+        const approvedPayment = approvalPayment === undefined
+            ? undefined
+            : await evaluateApprovedPaymentBeforeSubmission(context, approvalPayment);
         const { submitTransactionXdr } = await import("@stellar-agent/stellar");
         const transaction = await submitTransactionXdr({
             xdr: approval.decision.signedTransactionXdr,
@@ -869,19 +919,38 @@ function addTransactionCommands(program) {
                 transaction
             }
         });
-        const receiptPath = await writeSubmittedXdrReceipt(context, {
-            command: "tx submit-approval",
-            profile,
-            operation: {
-                type: "tx.submit_approval",
-                details: {
-                    approvalId: approval.id,
-                    signerPublicKey: approval.decision.signerPublicKey,
-                    realFundsAcknowledged: profile.realFunds
-                }
-            },
-            transaction
-        });
+        let receiptPath;
+        if (approvedPayment === undefined || approvalPayment === undefined) {
+            receiptPath = await writeSubmittedXdrReceipt(context, {
+                command: "tx submit-approval",
+                profile,
+                operation: {
+                    type: "tx.submit_approval",
+                    details: {
+                        approvalId: approval.id,
+                        signerPublicKey: approval.decision.signerPublicKey,
+                        realFundsAcknowledged: profile.realFunds
+                    }
+                },
+                transaction
+            });
+        }
+        else {
+            receiptPath = await writeSubmittedPaymentApprovalReceipt(context, {
+                command: "tx submit-approval",
+                profile,
+                approvalId: approval.id,
+                ...(approval.decision.signerPublicKey === undefined
+                    ? {}
+                    : { signerPublicKey: approval.decision.signerPublicKey }),
+                payment: approvalPayment,
+                policyDecision: approvedPayment.policyDecision,
+                transaction,
+                ...(approvedPayment.mainnetAgentWallet === undefined
+                    ? {}
+                    : { mainnetAgentWallet: approvedPayment.mainnetAgentWallet })
+            });
+        }
         return { approvalId: approval.id, signerPublicKey: approval.decision.signerPublicKey, transaction, receiptPath, realFunds: profile.realFunds };
     }, "Signed approval transaction submitted."));
 }
@@ -922,7 +991,7 @@ function addPayCommands(program) {
     }, "Payment quote complete."));
     pay
         .command("send")
-        .description("Send an XLM or issued-asset payment on Testnet when policy allows.")
+        .description("Send an XLM or issued-asset payment on Testnet, or an explicitly armed Mainnet agent-wallet payment.")
         .requiredOption("--to <address>", "Destination public key")
         .requiredOption("--amount <amount>", "Payment amount")
         .option("--asset <asset>", "Asset", "XLM")
@@ -930,14 +999,13 @@ function addPayCommands(program) {
         .option("--memo <memo>", "Memo")
         .option("--fee-strategy <strategy>", "Fee strategy: base, low, medium, high, p95", "medium")
         .option("--approval-id <id>", "Approved local approval request id")
+        .option("--allow-real-funds", "Permit the guarded Mainnet agent-wallet autosign path")
+        .option("--i-understand-real-funds", "Acknowledge this payment can spend real Mainnet funds")
+        .option("--i-understand-agent-wallet-autosign", "Acknowledge bounded Mainnet agent-wallet autosigning risk")
         .option("--dry-run", "Evaluate locally without submitting")
         .action(withContext(async (context, options) => {
         if (context.profileName === "mainnet") {
-            throw new StellarAgentError({
-                code: "MAINNET_NOT_ENABLED",
-                message: "Mainnet payment submission is blocked in v0.",
-                docs: "docs/mainnet-safety.md"
-            });
+            return sendMainnetAgentWalletPayment(context, options);
         }
         const policy = await loadPolicy(context);
         const source = await loadWallet(context.config, options.from);
@@ -1205,6 +1273,45 @@ function addPayCommands(program) {
         });
     }, "MPP session complete."));
 }
+function addX402Commands(program) {
+    const x402 = program.command("x402").description("Scaffold and inspect x402-style paid API workflows.");
+    x402
+        .command("init-server")
+        .description("Create a local Testnet x402-style paid API server scaffold.")
+        .option("--out <dir>", "Output directory", "./stellar-agent-x402-server")
+        .option("--force", "Overwrite scaffold files if they already exist")
+        .action(withContext(async (_context, options) => {
+        const outDir = resolvePath(options.out);
+        const files = x402ServerScaffoldFiles();
+        await mkdir(outDir, { recursive: true });
+        for (const [name, contents] of Object.entries(files)) {
+            const target = join(outDir, name);
+            if (!options.force) {
+                try {
+                    await readFile(target, "utf8");
+                    throw new StellarAgentError({
+                        code: "INVALID_INPUT",
+                        message: `Refusing to overwrite existing scaffold file '${target}'.`,
+                        hint: "Use --force to replace scaffold files intentionally."
+                    });
+                }
+                catch (error) {
+                    if (error instanceof StellarAgentError)
+                        throw error;
+                    if (error?.code !== "ENOENT")
+                        throw error;
+                }
+            }
+            await writeFile(target, contents, { mode: name.endsWith(".mjs") ? 0o755 : 0o600 });
+        }
+        return {
+            path: outDir,
+            files: Object.keys(files),
+            network: "testnet",
+            realFunds: false
+        };
+    }, "x402 server scaffold initialized."));
+}
 function addClaimableCommands(program) {
     const claimable = program.command("claimable").description("Create, list, and claim claimable balances.");
     claimable
@@ -2354,7 +2461,7 @@ function addDefiCommands(program) {
             ...(options.shares === undefined ? {} : { shareAmount: options.shares }),
             ...(options.minAmount.length === 0 ? {} : { minAmounts: options.minAmount })
         });
-        const policy = await loadPolicy(context);
+        const policy = await loadPolicyForRequestNetwork(context, network);
         const policyDecision = evaluateDefiAquariusRequest(policy, aquariusLpPolicyRequest(preflight));
         return { policyDecision, preflight };
     }, "Aquarius LP preflight complete."));
@@ -2388,15 +2495,16 @@ function addDefiCommands(program) {
         .option("--network <name>", "Network profile to inspect: testnet or mainnet")
         .action(withContext(async (context, options) => {
         const { preflightAquariusSwap } = await loadDefi();
+        const network = resolveAquariusNetworkOption(context, options.network);
         const preflight = await preflightAquariusSwap({
-            network: resolveAquariusNetworkOption(context, options.network),
+            network,
             inputAsset: options.from,
             outputAsset: options.to,
             amount: options.amount,
             mode: parseAquariusSwapMode(options.mode),
             slippageBps: options.slippageBps
         });
-        const policy = await loadPolicy(context);
+        const policy = await loadPolicyForRequestNetwork(context, network);
         const policyDecision = evaluateDefiAquariusRequest(policy, aquariusSwapPolicyRequest(preflight));
         return { policyDecision, preflight };
     }, "Aquarius swap preflight complete."));
@@ -2427,9 +2535,11 @@ function addPolicyCommands(program) {
         .action(withContext(async (context, options) => {
         const target = defaultPolicyForNetwork(options.network);
         const path = options.output ??
-            join(context.config.storage.policiesDir, options.network === "mainnet" ? "default-mainnet.yaml" : "default-testnet.yaml");
-        await writeFile(resolvePath(path), policyToYaml(target), { mode: 0o600 });
-        return { path: resolvePath(path), policy: target };
+            join(context.config.storage.policiesDir, defaultPolicyFilename(options.network));
+        const resolvedPath = resolvePath(path);
+        await mkdir(dirname(resolvedPath), { recursive: true });
+        await writeFile(resolvedPath, policyToYaml(target), { mode: 0o600 });
+        return { path: resolvedPath, policy: target };
     }, "Policy initialized."));
     policy
         .command("check")
@@ -2551,6 +2661,15 @@ function addReceiptCommands(program) {
             return { receipt: null };
         return latest;
     }, "Latest receipt loaded."));
+    receipts
+        .command("summary")
+        .description("Summarize local receipt spend, Mainnet exposure, and recent activity.")
+        .option("--profile <name>", "Filter by profile: testnet, mainnet, or local")
+        .option("--asset <asset>", "Filter by payment asset")
+        .action(withContext(async (context, options) => receiptSummary(context, {
+        ...(options.profile === undefined ? {} : { profile: options.profile }),
+        ...(options.asset === undefined ? {} : { asset: options.asset })
+    }), "Receipt summary loaded."));
     receipts
         .command("show")
         .description("Show a receipt file.")
@@ -2623,6 +2742,228 @@ function addMainnetCommands(program) {
             "Receipts must mark realFunds: true."
         ]
     }), "Mainnet readiness checked."));
+    const agentWallet = mainnet.command("agent-wallet").description("Manage a risk-budgeted Mainnet agent wallet for guarded external-signing workflows.");
+    agentWallet
+        .command("create")
+        .description("Create or replace the dedicated Mainnet agent-wallet profile without storing a Mainnet secret key.")
+        .requiredOption("--address <address>", "Dedicated Mainnet agent wallet public key")
+        .option("--name <name>", "Local watch-only wallet name", "mainnet-agent")
+        .option("--max-balance <amount>", "Maximum allowed wallet balance", "25")
+        .option("--per-tx-limit <amount>", "Maximum single payment amount", "1")
+        .option("--daily-limit <amount>", "Maximum daily payment amount", "5")
+        .option("--monthly-limit <amount>", "Optional monthly payment amount")
+        .option("--asset <asset>", "Allowed asset; repeat for more than one", collectArg, [])
+        .option("--allow-destination <address>", "Allowed destination; repeat for more than one", collectArg, [])
+        .action(withContext(async (context, options) => {
+        const now = new Date().toISOString();
+        const riskBudget = parseMainnetAgentWalletRiskBudget(options);
+        await importPublicWallet({
+            config: context.config,
+            name: options.name,
+            publicKey: options.address,
+            network: "mainnet"
+        });
+        context.config.mainnetAgentWallet = {
+            schemaVersion: "stellar-agent.mainnetAgentWallet.v1",
+            walletName: options.name,
+            publicKey: options.address,
+            status: "disarmed",
+            createdAt: context.config.mainnetAgentWallet?.createdAt ?? now,
+            updatedAt: now,
+            riskBudget
+        };
+        await writeConfig(context.config, context.options);
+        return mainnetAgentWalletView(context.config.mainnetAgentWallet);
+    }, "Mainnet agent wallet created."));
+    agentWallet
+        .command("enable")
+        .description("Configure the dedicated Mainnet agent wallet, optionally enable env-var autosigning, and optionally arm it.")
+        .requiredOption("--address <address>", "Dedicated Mainnet agent wallet public key")
+        .option("--name <name>", "Local watch-only wallet name", "mainnet-agent")
+        .option("--max-balance <amount>", "Maximum allowed wallet balance", "25")
+        .option("--per-tx-limit <amount>", "Maximum single payment amount", "1")
+        .option("--daily-limit <amount>", "Maximum daily payment amount", "5")
+        .option("--monthly-limit <amount>", "Optional monthly payment amount")
+        .option("--asset <asset>", "Allowed asset; repeat for more than one", collectArg, [])
+        .option("--allow-destination <address>", "Allowed destination; repeat for more than one", collectArg, [])
+        .option("--enable-autosign", "Enable env-var based autosigning for this agent wallet only")
+        .option("--secret-key-env <name>", "Environment variable containing the agent-wallet secret key", "STELLAR_AGENT_MAINNET_AGENT_SECRET_KEY")
+        .option("--i-understand-agent-wallet-autosign", "Acknowledge bounded Mainnet agent-wallet autosigning risk")
+        .option("--arm", "Arm the wallet after configuration")
+        .option("--i-understand-real-funds", "Acknowledge this wallet can spend real Mainnet funds")
+        .action(withContext(async (context, options) => {
+        const now = new Date().toISOString();
+        const riskBudget = parseMainnetAgentWalletRiskBudget(options);
+        await importPublicWallet({
+            config: context.config,
+            name: options.name,
+            publicKey: options.address,
+            network: "mainnet"
+        });
+        context.config.mainnetAgentWallet = {
+            schemaVersion: "stellar-agent.mainnetAgentWallet.v1",
+            walletName: options.name,
+            publicKey: options.address,
+            status: "disarmed",
+            createdAt: context.config.mainnetAgentWallet?.createdAt ?? now,
+            updatedAt: now,
+            riskBudget,
+            ...(options.enableAutosign
+                ? {
+                    autosign: mainnetAgentWalletAutosignConfig({
+                        secretKeyEnvVar: options.secretKeyEnv,
+                        acknowledged: Boolean(options.iUnderstandAgentWalletAutosign)
+                    })
+                }
+                : {})
+        };
+        if (options.arm) {
+            context.config.mainnetAgentWallet = await armMainnetAgentWallet(context, {
+                iUnderstandRealFunds: Boolean(options.iUnderstandRealFunds)
+            });
+        }
+        await writeConfig(context.config, context.options);
+        return mainnetAgentWalletView(context.config.mainnetAgentWallet);
+    }, "Mainnet agent wallet enabled."));
+    agentWallet
+        .command("status")
+        .description("Show Mainnet agent-wallet arming and risk-budget status.")
+        .action(withContext(async (context) => {
+        const wallet = context.config.mainnetAgentWallet;
+        if (!wallet)
+            return { configured: false, armed: false, realFunds: true };
+        return {
+            configured: true,
+            ...mainnetAgentWalletView(wallet),
+            ...(await mainnetAgentWalletIntegrity(context, wallet))
+        };
+    }, "Mainnet agent wallet status loaded."));
+    const autosign = agentWallet.command("autosign").description("Manage env-var based Mainnet agent-wallet autosigning.");
+    autosign
+        .command("enable")
+        .description("Enable autosigning for the armed agent-wallet path only; no secret key is stored.")
+        .option("--secret-key-env <name>", "Environment variable containing the agent-wallet secret key", "STELLAR_AGENT_MAINNET_AGENT_SECRET_KEY")
+        .option("--i-understand-agent-wallet-autosign", "Acknowledge bounded Mainnet agent-wallet autosigning risk")
+        .action(withContext(async (context, options) => {
+        const wallet = requireMainnetAgentWallet(context.config);
+        context.config.mainnetAgentWallet = {
+            ...wallet,
+            status: "disarmed",
+            updatedAt: new Date().toISOString(),
+            autosign: mainnetAgentWalletAutosignConfig({
+                secretKeyEnvVar: options.secretKeyEnv,
+                acknowledged: Boolean(options.iUnderstandAgentWalletAutosign)
+            }),
+            arming: undefined
+        };
+        await writeConfig(context.config, context.options);
+        return mainnetAgentWalletView(context.config.mainnetAgentWallet);
+    }, "Mainnet agent-wallet autosigning enabled and wallet disarmed for re-arming."));
+    autosign
+        .command("disable")
+        .description("Disable Mainnet agent-wallet autosigning and disarm the wallet.")
+        .action(withContext(async (context) => {
+        const wallet = requireMainnetAgentWallet(context.config);
+        context.config.mainnetAgentWallet = {
+            ...wallet,
+            status: "disarmed",
+            updatedAt: new Date().toISOString(),
+            autosign: { ...(wallet.autosign ?? mainnetAgentWalletAutosignConfig({ secretKeyEnvVar: "STELLAR_AGENT_MAINNET_AGENT_SECRET_KEY", acknowledged: true })), enabled: false },
+            arming: undefined
+        };
+        await writeConfig(context.config, context.options);
+        return mainnetAgentWalletView(context.config.mainnetAgentWallet);
+    }, "Mainnet agent-wallet autosigning disabled."));
+    autosign
+        .command("status")
+        .description("Show Mainnet agent-wallet autosigning status without reading the secret key.")
+        .action(withContext(async (context) => {
+        const wallet = requireMainnetAgentWallet(context.config);
+        return {
+            publicKey: wallet.publicKey,
+            autosign: mainnetAgentWalletAutosignView(wallet),
+            warning: mainnetAgentWalletAutosignWarning()
+        };
+    }, "Mainnet agent-wallet autosigning status loaded."));
+    agentWallet
+        .command("limits")
+        .description("Show or update Mainnet agent-wallet risk-budget limits. Updating limits disarms the wallet.")
+        .option("--max-balance <amount>", "Maximum allowed wallet balance")
+        .option("--per-tx-limit <amount>", "Maximum single payment amount")
+        .option("--daily-limit <amount>", "Maximum daily payment amount")
+        .option("--monthly-limit <amount>", "Optional monthly payment amount")
+        .option("--asset <asset>", "Allowed asset; repeat for more than one", collectArg, [])
+        .option("--allow-destination <address>", "Allowed destination; repeat for more than one", collectArg, [])
+        .action(withContext(async (context, options) => {
+        const wallet = requireMainnetAgentWallet(context.config);
+        const updates = parseMainnetAgentWalletRiskBudget({
+            maxBalance: options.maxBalance ?? wallet.riskBudget.maxBalance,
+            perTxLimit: options.perTxLimit ?? wallet.riskBudget.perTxLimit,
+            dailyLimit: options.dailyLimit ?? wallet.riskBudget.dailyLimit,
+            monthlyLimit: options.monthlyLimit ?? wallet.riskBudget.monthlyLimit,
+            asset: options.asset.length > 0 ? options.asset : wallet.riskBudget.allowedAssets,
+            allowDestination: options.allowDestination.length > 0 ? options.allowDestination : wallet.riskBudget.allowedDestinations
+        });
+        context.config.mainnetAgentWallet = {
+            ...wallet,
+            status: "disarmed",
+            updatedAt: new Date().toISOString(),
+            riskBudget: updates,
+            arming: undefined
+        };
+        await writeConfig(context.config, context.options);
+        return mainnetAgentWalletView(context.config.mainnetAgentWallet);
+    }, "Mainnet agent wallet limits updated."));
+    agentWallet
+        .command("arm")
+        .description("Arm the Mainnet agent wallet after explicit Mainnet enablement and risk-budget checks.")
+        .option("--i-understand-real-funds", "Acknowledge this wallet can spend real funds through guarded external-signing workflows")
+        .action(withContext(async (context, options) => {
+        context.config.mainnetAgentWallet = await armMainnetAgentWallet(context, {
+            iUnderstandRealFunds: Boolean(options.iUnderstandRealFunds)
+        });
+        await writeConfig(context.config, context.options);
+        return mainnetAgentWalletView(context.config.mainnetAgentWallet);
+    }, "Mainnet agent wallet armed."));
+    agentWallet
+        .command("disarm")
+        .description("Disarm the Mainnet agent wallet.")
+        .action(withContext(async (context) => {
+        const wallet = requireMainnetAgentWallet(context.config);
+        context.config.mainnetAgentWallet = {
+            ...wallet,
+            status: "disarmed",
+            updatedAt: new Date().toISOString(),
+            arming: undefined
+        };
+        await writeConfig(context.config, context.options);
+        return mainnetAgentWalletView(context.config.mainnetAgentWallet);
+    }, "Mainnet agent wallet disarmed."));
+    agentWallet
+        .command("rotate")
+        .description("Rotate the dedicated Mainnet agent-wallet public key. Rotation disarms the wallet.")
+        .requiredOption("--address <address>", "New dedicated Mainnet agent wallet public key")
+        .option("--name <name>", "Local watch-only wallet name")
+        .action(withContext(async (context, options) => {
+        const wallet = requireMainnetAgentWallet(context.config);
+        const walletName = options.name ?? wallet.walletName;
+        await importPublicWallet({
+            config: context.config,
+            name: walletName,
+            publicKey: options.address,
+            network: "mainnet"
+        });
+        context.config.mainnetAgentWallet = {
+            ...wallet,
+            walletName,
+            publicKey: options.address,
+            status: "disarmed",
+            updatedAt: new Date().toISOString(),
+            arming: undefined
+        };
+        await writeConfig(context.config, context.options);
+        return mainnetAgentWalletView(context.config.mainnetAgentWallet);
+    }, "Mainnet agent wallet rotated and disarmed."));
 }
 function withContext(handler, humanMessage) {
     return async (...args) => {
@@ -2686,20 +3027,40 @@ async function createTestnetWalletResult(context, name, fund) {
     });
     return { wallet, funding };
 }
-async function loadPolicy(context, explicitPath) {
+async function loadPolicy(context, explicitPath, network = context.profileName) {
     const policyPath = explicitPath ??
         context.options.policy ??
         process.env.STELLAR_AGENT_POLICY ??
-        join(context.config.storage.policiesDir, context.profileName === "mainnet" ? "default-mainnet.yaml" : "default-testnet.yaml");
+        join(context.config.storage.policiesDir, defaultPolicyFilename(network));
     try {
         return parsePolicyYaml(await readFile(resolvePath(policyPath), "utf8"));
     }
     catch (error) {
         if (error?.code === "ENOENT")
-            return defaultPolicyForNetwork(context.profileName);
+            return defaultPolicyForNetwork(network);
         throw error;
     }
 }
+async function loadPolicyForRequestNetwork(context, network) {
+    const explicitPath = context.options.policy ?? process.env.STELLAR_AGENT_POLICY;
+    const policy = await loadPolicy(context, undefined, network);
+    if (explicitPath && policy.network !== network) {
+        throw new StellarAgentError({
+            code: "INVALID_INPUT",
+            message: `Policy network '${policy.network}' does not match Aquarius preflight network '${network}'.`,
+            hint: `Use a ${network} policy file or omit --policy to use the default ${network} policy.`,
+            docs: network === "mainnet" ? "docs/mainnet-safety.md#mainnet-defi" : "docs/defi-aquarius.md"
+        });
+    }
+    return policy;
+}
+function defaultPolicyFilename(network) {
+    if (network === "mainnet")
+        return "default-mainnet.yaml";
+    if (network === "local")
+        return "default-local.yaml";
+    return "default-testnet.yaml";
+}
 function resolveBlendNetworkOption(context, network) {
     if (!network)
         return blendNetworkForProfile(resolveNetworkProfile(context.profileName, context.config.profiles));
@@ -3310,6 +3671,503 @@ async function loadSpendHistory(context, request) {
         asset: request.asset
     });
 }
+async function evaluateApprovedPaymentBeforeSubmission(context, payment) {
+    if (payment.network !== context.profileName) {
+        throw new StellarAgentError({
+            code: "INVALID_INPUT",
+            message: "Approval payment metadata must match the active submission profile.",
+            docs: "docs/mainnet-safety.md#signed-xdr-submission"
+        });
+    }
+    const policy = await loadPolicy(context, undefined, payment.network);
+    const history = await loadSpendHistory(context, payment);
+    const policyDecision = evaluatePaymentRequest(policy, payment, history);
+    if (policyDecision.status === "denied")
+        throw policyDeniedError();
+    const mainnetAgentWallet = await assertMainnetAgentWalletPaymentAllowed(context, payment);
+    return {
+        policyDecision,
+        ...(mainnetAgentWallet === undefined ? {} : { mainnetAgentWallet })
+    };
+}
+function parseMainnetAgentWalletRiskBudget(options) {
+    const allowedAssets = options.asset.length > 0 ? options.asset : ["XLM"];
+    for (const asset of allowedAssets)
+        parseAssetForPolicy(asset);
+    for (const destination of options.allowDestination)
+        paymentRequestSchema.shape.destination.parse(destination);
+    return {
+        maxBalance: parseAmount(options.maxBalance, "XLM").value,
+        perTxLimit: parseAmount(options.perTxLimit, "XLM").value,
+        dailyLimit: parseAmount(options.dailyLimit, "XLM").value,
+        ...(options.monthlyLimit === undefined ? {} : { monthlyLimit: parseAmount(options.monthlyLimit, "XLM").value }),
+        allowedAssets: allowedAssets.map((asset) => asset.toUpperCase()),
+        allowedDestinations: [...new Set(options.allowDestination)],
+        allowedOperations: ["payment"]
+    };
+}
+function mainnetAgentWalletAutosignConfig(options) {
+    if (!options.acknowledged) {
+        throw new StellarAgentError({
+            code: "MAINNET_NOT_ENABLED",
+            message: "Enabling Mainnet agent-wallet autosigning requires --i-understand-agent-wallet-autosign.",
+            hint: mainnetAgentWalletAutosignWarning(),
+            docs: "docs/mainnet-safety.md#agent-wallet-autosigning"
+        });
+    }
+    if (!/^[A-Z_][A-Z0-9_]*$/.test(options.secretKeyEnvVar)) {
+        throw new StellarAgentError({
+            code: "INVALID_INPUT",
+            message: "Agent-wallet autosign secret key env var must be an uppercase environment variable name.",
+            docs: "docs/mainnet-safety.md#agent-wallet-autosigning"
+        });
+    }
+    const now = new Date().toISOString();
+    return {
+        enabled: true,
+        secretKeyEnvVar: options.secretKeyEnvVar,
+        enabledAt: now,
+        warningAcknowledgedAt: now
+    };
+}
+async function armMainnetAgentWallet(context, options) {
+    if (!options.iUnderstandRealFunds) {
+        throw new StellarAgentError({
+            code: "MAINNET_NOT_ENABLED",
+            message: "Arming the Mainnet agent wallet requires --i-understand-real-funds.",
+            docs: "docs/mainnet-safety.md#risk-budgeted-mainnet-agent-wallet"
+        });
+    }
+    if (!context.config.profiles.mainnet?.enabled) {
+        throw new StellarAgentError({
+            code: "MAINNET_NOT_ENABLED",
+            message: "Arming the Mainnet agent wallet requires Mainnet enablement.",
+            hint: "Run stellar-agent mainnet enable --i-understand-real-funds first.",
+            docs: "docs/mainnet-safety.md#risk-budgeted-mainnet-agent-wallet"
+        });
+    }
+    const current = requireMainnetAgentWallet(context.config);
+    if (!current.publicKey) {
+        throw new StellarAgentError({
+            code: "WALLET_NOT_FOUND",
+            message: "Mainnet agent wallet does not have a public key.",
+            hint: "Run stellar-agent mainnet agent-wallet create --address G...",
+            docs: "docs/mainnet-safety.md#risk-budgeted-mainnet-agent-wallet"
+        });
+    }
+    if (current.riskBudget.allowedDestinations.length === 0) {
+        throw new StellarAgentError({
+            code: "POLICY_DENIED",
+            message: "Mainnet agent wallet requires an explicit destination allowlist before arming.",
+            docs: "docs/mainnet-safety.md#risk-budgeted-mainnet-agent-wallet"
+        });
+    }
+    await assertMainnetAgentWalletBalanceWithinBudget(context, current);
+    const now = new Date().toISOString();
+    const armedWallet = {
+        ...current,
+        status: "armed",
+        updatedAt: now,
+        spendCounters: await mainnetAgentWalletSpendCounters(context, current),
+        arming: undefined
+    };
+    const policyFingerprint = await mainnetAgentWalletPolicyFingerprint(context);
+    armedWallet.arming = {
+        armedAt: now,
+        configPath: configFingerprintPath(context),
+        configFingerprint: coreMainnetAgentWalletConfigFingerprint({ ...context.config, mainnetAgentWallet: armedWallet }),
+        policyPath: policyFingerprint.path,
+        policyFingerprint: policyFingerprint.fingerprint
+    };
+    return armedWallet;
+}
+function requireMainnetAgentWallet(config) {
+    const wallet = config.mainnetAgentWallet;
+    if (!wallet) {
+        throw new StellarAgentError({
+            code: "WALLET_NOT_FOUND",
+            message: "Mainnet agent wallet is not configured.",
+            hint: "Run stellar-agent mainnet agent-wallet create --address G...",
+            docs: "docs/mainnet-safety.md#risk-budgeted-mainnet-agent-wallet"
+        });
+    }
+    return wallet;
+}
+function mainnetAgentWalletView(wallet) {
+    return {
+        walletName: wallet.walletName,
+        publicKey: wallet.publicKey,
+        armed: wallet.status === "armed",
+        status: wallet.status,
+        realFunds: true,
+        riskBudget: wallet.riskBudget,
+        spendCounters: wallet.spendCounters,
+        autosign: mainnetAgentWalletAutosignView(wallet),
+        warning: mainnetAgentWalletWarning(),
+        arming: wallet.arming === undefined
+            ? undefined
+            : {
+                armedAt: wallet.arming.armedAt,
+                configPath: wallet.arming.configPath,
+                policyPath: wallet.arming.policyPath
+            }
+    };
+}
+function mainnetAgentWalletWarning() {
+    return MAINNET_AGENT_WALLET_WARNING;
+}
+function mainnetAgentWalletAutosignWarning() {
+    return MAINNET_AGENT_WALLET_AUTOSIGN_WARNING;
+}
+function mainnetAgentWalletAutosignView(wallet) {
+    return {
+        enabled: Boolean(wallet.autosign?.enabled),
+        secretKeyEnvVar: wallet.autosign?.secretKeyEnvVar,
+        enabledAt: wallet.autosign?.enabledAt,
+        warning: wallet.autosign?.enabled ? mainnetAgentWalletAutosignWarning() : undefined
+    };
+}
+async function mainnetAgentWalletIntegrity(context, wallet) {
+    if (wallet.status !== "armed")
+        return { integrity: { ok: true, checked: false, reason: "wallet_not_armed" } };
+    const failures = await mainnetAgentWalletIntegrityFailures(context, wallet);
+    return { integrity: { ok: failures.length === 0, checked: true, failures } };
+}
+async function mainnetAgentWalletIntegrityFailures(context, wallet) {
+    if (!wallet.arming) {
+        return ["arming_metadata_missing"];
+    }
+    const currentPolicy = await mainnetAgentWalletPolicyFingerprint(context);
+    return coreMainnetAgentWalletIntegrityFailures({
+        wallet,
+        config: context.config,
+        configPath: configFingerprintPath(context),
+        policyPath: currentPolicy.path,
+        policyFingerprint: currentPolicy.fingerprint
+    });
+}
+async function assertMainnetAgentWalletPaymentAllowed(context, request) {
+    const wallet = context.config.mainnetAgentWallet;
+    if (!wallet || wallet.publicKey !== request.source || request.network !== "mainnet")
+        return undefined;
+    const spendHistory = await loadSpendHistory(context, request);
+    const policyFingerprint = await mainnetAgentWalletPolicyFingerprint(context);
+    assertMainnetAgentWalletPaymentPreflight({
+        wallet,
+        request,
+        config: context.config,
+        configPath: configFingerprintPath(context),
+        policyPath: policyFingerprint.path,
+        policyFingerprint: policyFingerprint.fingerprint,
+        spendHistory
+    });
+    assertCoreMainnetAgentWalletBalanceWithinBudget(wallet, await readMainnetAgentWalletBalances(context, wallet));
+    return { warning: mainnetAgentWalletWarning(), spendHistory };
+}
+async function assertMainnetAgentWalletAutosignPayment(context, request, options) {
+    if (!options.allowRealFunds || !options.iUnderstandRealFunds || !options.iUnderstandAgentWalletAutosign) {
+        throw new StellarAgentError({
+            code: "MAINNET_NOT_ENABLED",
+            message: "Mainnet agent-wallet autosigning requires --allow-real-funds, --i-understand-real-funds, and --i-understand-agent-wallet-autosign.",
+            hint: mainnetAgentWalletAutosignWarning(),
+            docs: "docs/mainnet-safety.md#agent-wallet-autosigning"
+        });
+    }
+    const wallet = requireMainnetAgentWallet(context.config);
+    if (!wallet.autosign?.enabled) {
+        throw new StellarAgentError({
+            code: "MAINNET_NOT_ENABLED",
+            message: "Mainnet agent-wallet autosigning is not enabled.",
+            hint: "Run stellar-agent mainnet agent-wallet autosign enable --i-understand-agent-wallet-autosign, then arm the wallet.",
+            docs: "docs/mainnet-safety.md#agent-wallet-autosigning"
+        });
+    }
+    const allowed = await assertMainnetAgentWalletPaymentAllowed(context, request);
+    if (!allowed) {
+        throw new StellarAgentError({
+            code: "MAINNET_NOT_ENABLED",
+            message: "Mainnet auto-signing is blocked outside the dedicated agent-wallet path.",
+            docs: "docs/mainnet-safety.md#agent-wallet-autosigning"
+        });
+    }
+    const secretKey = process.env[wallet.autosign.secretKeyEnvVar];
+    if (!secretKey) {
+        throw new StellarAgentError({
+            code: "SECRET_KEY_BLOCKED",
+            message: `Mainnet agent-wallet secret key env var '${wallet.autosign.secretKeyEnvVar}' is not set.`,
+            hint: "Set the env var only in the process that should autosign; the secret is never stored in config or receipts.",
+            docs: "docs/mainnet-safety.md#agent-wallet-autosigning"
+        });
+    }
+    const { publicKeyFromSecret } = await import("@stellar-agent/stellar");
+    let publicKey;
+    try {
+        publicKey = publicKeyFromSecret(secretKey);
+    }
+    catch {
+        throw new StellarAgentError({
+            code: "WALLET_INVALID",
+            message: "Mainnet agent-wallet autosign secret key is invalid.",
+            docs: "docs/mainnet-safety.md#agent-wallet-autosigning"
+        });
+    }
+    if (publicKey !== wallet.publicKey) {
+        throw new StellarAgentError({
+            code: "WALLET_INVALID",
+            message: "Mainnet agent-wallet autosign secret key does not match the configured public key.",
+            docs: "docs/mainnet-safety.md#agent-wallet-autosigning"
+        });
+    }
+    return {
+        wallet,
+        source: { publicKey, secretKey },
+        warning: mainnetAgentWalletAutosignWarning(),
+        spendHistory: allowed.spendHistory
+    };
+}
+async function sendMainnetAgentWalletPayment(context, options) {
+    const configured = requireMainnetAgentWallet(context.config);
+    if (options.from !== configured.walletName && options.from !== configured.publicKey) {
+        throw new StellarAgentError({
+            code: "MAINNET_NOT_ENABLED",
+            message: "Mainnet auto-signing is blocked outside the configured agent-wallet account.",
+            hint: `Use --from ${configured.walletName} for the dedicated agent-wallet flow.`,
+            docs: "docs/mainnet-safety.md#agent-wallet-autosigning"
+        });
+    }
+    if (!configured.publicKey) {
+        throw new StellarAgentError({
+            code: "WALLET_NOT_FOUND",
+            message: "Mainnet agent wallet does not have a public key.",
+            docs: "docs/mainnet-safety.md#risk-budgeted-mainnet-agent-wallet"
+        });
+    }
+    const policy = await loadPolicy(context, undefined, "mainnet");
+    const request = paymentRequestSchema.parse({
+        source: configured.publicKey,
+        destination: options.to,
+        amount: options.amount,
+        asset: options.asset,
+        memo: options.memo,
+        network: "mainnet",
+        agentWalletAutosign: true
+    });
+    const history = await loadSpendHistory(context, request);
+    if (history.unreadable) {
+        throw new StellarAgentError({
+            code: "POLICY_DENIED",
+            message: "Mainnet agent-wallet spend history could not be read, so payment fails closed.",
+            docs: "docs/mainnet-safety.md#risk-budgeted-mainnet-agent-wallet"
+        });
+    }
+    const policyDecision = evaluatePaymentRequest(policy, request, history);
+    if (options.dryRun)
+        return { request, policyDecision, spendHistory: history, dryRun: true, autosign: mainnetAgentWalletAutosignView(configured) };
+    await assertMainnetAgentWalletPaymentAllowed(context, request);
+    if (policyDecision.status === "denied")
+        throw policyDeniedError();
+    if (policyDecision.status === "requires_approval") {
+        throw new StellarAgentError({
+            code: "APPROVAL_REQUIRED",
+            message: "Mainnet agent-wallet autosigning requires policy status 'allowed'.",
+            hint: "Use an external approval flow or add an explicit policy exception for risk-budgeted agent-wallet autosigning.",
+            docs: "docs/mainnet-safety.md#agent-wallet-autosigning",
+            details: { policyDecision }
+        });
+    }
+    const autosign = await assertMainnetAgentWalletAutosignPayment(context, request, options);
+    const { sendPayment } = await import("@stellar-agent/stellar");
+    const mainnetProfile = resolveNetworkProfile("mainnet", context.config.profiles);
+    const transaction = await sendPayment({
+        source: autosign.source,
+        destination: options.to,
+        amount: options.amount,
+        asset: options.asset,
+        ...(options.memo === undefined ? {} : { memo: options.memo }),
+        profile: mainnetProfile,
+        allowRealFunds: true,
+        feeStrategy: parseFeeStrategy(options.feeStrategy),
+        ...(context.options.noCache === undefined ? {} : { noCache: context.options.noCache })
+    });
+    const eventLog = join(context.config.storage.logsDir, "events.jsonl");
+    await appendEvent(eventLog, {
+        event: "transaction_confirmed",
+        status: "successful",
+        command: "pay send",
+        profile: "mainnet",
+        data: {
+            transaction,
+            source: configured.walletName,
+            sourcePublicKey: configured.publicKey,
+            destination: options.to,
+            asset: options.asset,
+            mainnetAgentWalletAutosign: true,
+            warning: autosign.warning
+        }
+    });
+    const { path: receiptPath } = await writeReceipt(context.config.storage.receiptsDir, {
+        command: "pay send",
+        profile: "mainnet",
+        networkPassphrase: mainnetProfile.networkPassphrase,
+        realFunds: true,
+        payment: {
+            source: configured.publicKey,
+            destination: options.to,
+            asset: options.asset,
+            amount: request.amount,
+            ...(options.memo === undefined ? {} : { memo: options.memo })
+        },
+        operation: {
+            type: "pay.send",
+            source: configured.publicKey,
+            destination: options.to,
+            asset: options.asset,
+            amount: request.amount,
+            details: {
+                mainnetAgentWallet: {
+                    autosign: true,
+                    walletName: configured.walletName,
+                    publicKey: configured.publicKey,
+                    secretKeyEnvVar: configured.autosign?.secretKeyEnvVar,
+                    riskBudgetState: coreMainnetAgentWalletRiskBudgetState(configured, autosign.spendHistory, request),
+                    warning: autosign.warning
+                },
+                realFundsAcknowledged: true
+            }
+        },
+        policyDecision: {
+            status: policyDecision.status,
+            matchedRules: [...policyDecision.matchedRules, "mainnet_agent_wallet_autosign_acknowledged"]
+        },
+        transaction,
+        ...(transaction.ledger === undefined ? {} : { ledger: { confirmedLedger: transaction.ledger } }),
+        eventLog
+    });
+    await appendEvent(eventLog, {
+        event: "receipt_written",
+        status: "success",
+        command: "pay send",
+        profile: "mainnet",
+        data: { receiptPath }
+    });
+    if (context.config.mainnetAgentWallet) {
+        context.config.mainnetAgentWallet = {
+            ...context.config.mainnetAgentWallet,
+            spendCounters: await mainnetAgentWalletSpendCounters(context, context.config.mainnetAgentWallet)
+        };
+        await writeConfig(context.config, context.options);
+    }
+    return {
+        request,
+        policyDecision,
+        autosign: {
+            enabled: true,
+            warning: autosign.warning
+        },
+        transaction,
+        receiptPath,
+        realFunds: true
+    };
+}
+async function assertMainnetAgentWalletBalanceWithinBudget(context, wallet) {
+    assertCoreMainnetAgentWalletBalanceWithinBudget(wallet, await readMainnetAgentWalletBalances(context, wallet));
+}
+async function readMainnetAgentWalletBalances(context, wallet) {
+    if (!wallet.publicKey) {
+        throw new StellarAgentError({ code: "WALLET_NOT_FOUND", message: "Mainnet agent wallet public key is missing." });
+    }
+    try {
+        const profile = resolveNetworkProfile("mainnet", context.config.profiles);
+        return await fetchMainnetAgentWalletBalances(wallet.publicKey, profile);
+    }
+    catch (error) {
+        throw new StellarAgentError({
+            code: "HORIZON_UNAVAILABLE",
+            message: "Mainnet agent-wallet balance could not be read, so arming and spend fail closed.",
+            docs: "docs/mainnet-safety.md#risk-budgeted-mainnet-agent-wallet",
+            details: error instanceof Error ? error.message : String(error)
+        });
+    }
+}
+async function fetchMainnetAgentWalletBalances(publicKey, profile) {
+    if (!profile.horizonUrl) {
+        throw new StellarAgentError({ code: "HORIZON_UNAVAILABLE", message: "Mainnet Horizon is not configured." });
+    }
+    const response = await fetch(`${profile.horizonUrl.replace(/\/$/, "")}/accounts/${publicKey}`, {
+        signal: AbortSignal.timeout(15_000)
+    });
+    const body = await response.text();
+    const parsed = safeJsonParse(body);
+    if (!response.ok) {
+        throw new StellarAgentError({
+            code: "HORIZON_UNAVAILABLE",
+            message: "Could not load Mainnet agent-wallet balances from Horizon.",
+            details: parsed ?? body
+        });
+    }
+    return (parsed?.balances ?? []).map((balance) => ({
+        asset: balance.asset_type === "native" ? "XLM" : `${balance.asset_code}:${balance.asset_issuer}`,
+        balance: String(balance.balance)
+    }));
+}
+async function mainnetAgentWalletPolicyFingerprint(context) {
+    const policyPath = context.options.policy ??
+        process.env.STELLAR_AGENT_POLICY ??
+        join(context.config.storage.policiesDir, defaultPolicyFilename("mainnet"));
+    const resolvedPath = resolvePath(policyPath);
+    let source;
+    try {
+        source = await readFile(resolvedPath, "utf8");
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+        source = policyToYaml(DEFAULT_MAINNET_POLICY);
+    }
+    return { path: resolvedPath, fingerprint: sha256(source) };
+}
+async function mainnetAgentWalletSpendCounters(context, wallet) {
+    const entries = await Promise.all(wallet.riskBudget.allowedAssets.map(async (asset) => [
+        asset,
+        await spendHistoryFromReceipts(context.config.storage.receiptsDir, {
+            profile: "mainnet",
+            asset
+        })
+    ]));
+    return {
+        updatedAt: new Date().toISOString(),
+        source: "receipts",
+        assets: Object.fromEntries(entries)
+    };
+}
+function configFingerprintPath(context) {
+    return resolvePath(context.options.config ?? process.env.STELLAR_AGENT_CONFIG ?? join(context.config.storage.rootDir, "config.yaml"));
+}
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function addAmountValues(left, right, asset) {
+    return formatStroops(parseNonnegativeStroops(left, asset) + parseNonnegativeStroops(right, asset));
+}
+function parseAssetForPolicy(asset) {
+    if (asset.toUpperCase() === "XLM")
+        return;
+    if (!/^[A-Z0-9]{1,12}(:G[A-Z2-7]{55})?$/.test(asset.toUpperCase())) {
+        throw new StellarAgentError({
+            code: "INVALID_ASSET",
+            message: "Allowed asset must be XLM, CODE, or CODE:G... issuer format.",
+            docs: "docs/mainnet-safety.md#risk-budgeted-mainnet-agent-wallet"
+        });
+    }
+}
+function safeJsonParse(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
 function parseFeeStrategy(value) {
     if (value === "base" || value === "low" || value === "medium" || value === "high" || value === "p95")
         return value;
@@ -3514,6 +4372,44 @@ function printError(options, error) {
     if (serialized.docs)
         process.stderr.write(`Docs: ${serialized.docs}\n`);
 }
+function commanderErrorToStellarAgentError(error) {
+    if (error instanceof StellarAgentError)
+        return error;
+    if (!isCommanderError(error))
+        return error;
+    const message = normalizeCommanderMessage(error.message);
+    return new StellarAgentError({
+        code: "INVALID_INPUT",
+        message,
+        hint: "Run the command with --help and correct the input.",
+        docs: docsForCommanderMessage(message),
+        exitCode: typeof error.exitCode === "number" ? error.exitCode : EXIT_CODES.usage
+    });
+}
+function isCommanderError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string" &&
+        error.code.startsWith("commander.") &&
+        "message" in error &&
+        typeof error.message === "string");
+}
+function isCommanderHelpOrVersionExit(error) {
+    return (isCommanderError(error) &&
+        (error.code === "commander.helpDisplayed" || error.code === "commander.version") &&
+        (error.exitCode === undefined || error.exitCode === EXIT_CODES.success));
+}
+function normalizeCommanderMessage(message) {
+    return message.replace(/^error:\s*/i, "");
+}
+function docsForCommanderMessage(message) {
+    if (message.includes("--slippage-bps"))
+        return "docs/defi-aquarius.md#swap-quoting-and-preflight";
+    if (message.includes("aquarius"))
+        return "docs/defi-aquarius.md";
+    return "docs/troubleshooting.md";
+}
 function fixtureRequest(amount) {
     return {
         destination: "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF",
@@ -3676,12 +4572,26 @@ async function writeBlendReceipt(context, args) {
 }
 async function writeSubmittedXdrReceipt(context, args) {
     const eventLog = join(context.config.storage.logsDir, "events.jsonl");
+    const operation = args.profile.realFunds && context.config.mainnetAgentWallet?.status === "armed"
+        ? {
+            ...args.operation,
+            details: {
+                ...(typeof args.operation.details === "object" && args.operation.details !== null ? args.operation.details : {}),
+                mainnetAgentWallet: {
+                    armed: true,
+                    walletName: context.config.mainnetAgentWallet.walletName,
+                    publicKey: context.config.mainnetAgentWallet.publicKey,
+                    warning: mainnetAgentWalletWarning()
+                }
+            }
+        }
+        : args.operation;
     const { path: receiptPath } = await writeReceipt(context.config.storage.receiptsDir, {
         command: args.command,
         profile: args.profile.name,
         networkPassphrase: args.profile.networkPassphrase,
         realFunds: args.profile.realFunds,
-        operation: args.operation,
+        operation,
         policyDecision: {
             status: args.profile.realFunds ? "requires_approval" : "allowed",
             matchedRules: args.profile.realFunds
@@ -3701,6 +4611,69 @@ async function writeSubmittedXdrReceipt(context, args) {
     });
     return receiptPath;
 }
+async function writeSubmittedPaymentApprovalReceipt(context, args) {
+    const eventLog = join(context.config.storage.logsDir, "events.jsonl");
+    const { path: receiptPath } = await writeReceipt(context.config.storage.receiptsDir, {
+        command: args.command,
+        profile: args.profile.name,
+        networkPassphrase: args.profile.networkPassphrase,
+        realFunds: args.profile.realFunds,
+        payment: {
+            source: args.payment.source ?? "",
+            destination: args.payment.destination,
+            asset: args.payment.asset,
+            amount: args.payment.amount,
+            ...(args.payment.memo === undefined ? {} : { memo: args.payment.memo }),
+            ...(args.payment.domain === undefined ? {} : { domain: args.payment.domain }),
+            ...(args.payment.url === undefined ? {} : { url: args.payment.url })
+        },
+        operation: {
+            type: "tx.submit_payment_approval",
+            ...(args.payment.source === undefined ? {} : { source: args.payment.source }),
+            destination: args.payment.destination,
+            asset: args.payment.asset,
+            amount: args.payment.amount,
+            details: {
+                approvalId: args.approvalId,
+                signerPublicKey: args.signerPublicKey,
+                realFundsAcknowledged: args.profile.realFunds,
+                ...(args.mainnetAgentWallet === undefined
+                    ? {}
+                    : {
+                        mainnetAgentWallet: {
+                            armed: true,
+                            walletName: context.config.mainnetAgentWallet?.walletName,
+                            publicKey: context.config.mainnetAgentWallet?.publicKey,
+                            riskBudgetState: coreMainnetAgentWalletRiskBudgetState(context.config.mainnetAgentWallet, args.mainnetAgentWallet.spendHistory, args.payment),
+                            warning: args.mainnetAgentWallet.warning
+                        }
+                    })
+            }
+        },
+        policyDecision: {
+            status: args.policyDecision.status,
+            matchedRules: args.policyDecision.matchedRules
+        },
+        transaction: args.transaction,
+        ...(args.transaction.ledger === undefined ? {} : { ledger: { confirmedLedger: args.transaction.ledger } }),
+        eventLog
+    });
+    await appendEvent(eventLog, {
+        event: "receipt_written",
+        status: "success",
+        command: args.command,
+        profile: args.profile.name,
+        data: { receiptPath }
+    });
+    if (context.config.mainnetAgentWallet && args.mainnetAgentWallet) {
+        context.config.mainnetAgentWallet = {
+            ...context.config.mainnetAgentWallet,
+            spendCounters: await mainnetAgentWalletSpendCounters(context, context.config.mainnetAgentWallet)
+        };
+        await writeConfig(context.config, context.options);
+    }
+    return receiptPath;
+}
 async function attachContractSubmissionReceipt(context, args) {
     if (args.network.toLowerCase() !== "testnet")
         return args.result;
@@ -3755,6 +4728,121 @@ async function buildLocalReport(context) {
         }
     };
 }
+async function receiptSummary(context, options = {}) {
+    const paths = await listReceipts(context.config.storage.receiptsDir);
+    const summary = {
+        receiptCount: 0,
+        unreadableCount: 0,
+        paymentCount: 0,
+        realFundsCount: 0,
+        totals: {},
+        profiles: {},
+        latest: null
+    };
+    for (const path of paths) {
+        try {
+            const receipt = await readReceipt(path);
+            if (options.profile && receipt.profile !== options.profile)
+                continue;
+            if (options.asset && receipt.payment?.asset.toUpperCase() !== options.asset.toUpperCase())
+                continue;
+            summary.receiptCount += 1;
+            const profile = (summary.profiles[receipt.profile] ??= { count: 0, realFundsCount: 0 });
+            profile.count += 1;
+            if (receipt.network.realFunds) {
+                summary.realFundsCount += 1;
+                profile.realFundsCount += 1;
+            }
+            if (!summary.latest) {
+                summary.latest = {
+                    path,
+                    id: receipt.id,
+                    command: receipt.command,
+                    createdAt: receipt.createdAt,
+                    profile: receipt.profile
+                };
+            }
+            if (!receipt.payment || receipt.transaction.successful !== true || receipt.policyDecision.status === "denied")
+                continue;
+            summary.paymentCount += 1;
+            const key = `${receipt.profile}:${receipt.payment.asset.toUpperCase()}`;
+            const current = summary.totals[key] ?? { amount: "0.0000000", count: 0 };
+            summary.totals[key] = {
+                amount: addAmountValues(current.amount, receipt.payment.amount, receipt.payment.asset),
+                count: current.count + 1
+            };
+        }
+        catch {
+            summary.unreadableCount += 1;
+        }
+    }
+    return summary;
+}
+function x402ServerScaffoldFiles() {
+    return {
+        "package.json": `${JSON.stringify({
+            type: "module",
+            scripts: {
+                start: "node server.mjs"
+            },
+            dependencies: {}
+        }, null, 2)}\n`,
+        "server.mjs": `import { createServer } from "node:http";
+
+const port = Number(process.env.PORT ?? 8787);
+const price = process.env.X402_PRICE ?? "0.0000001 XLM";
+const destination = process.env.X402_DESTINATION ?? "set-testnet-merchant-public-key";
+
+const server = createServer((request, response) => {
+  if (request.url === "/health") {
+    response.writeHead(200, { "content-type": "application/json" });
+    response.end(JSON.stringify({ ok: true }));
+    return;
+  }
+
+  const payment = request.headers["x-payment"];
+  if (!payment) {
+    response.writeHead(402, {
+      "content-type": "application/json",
+      "x-accepts-payment": JSON.stringify({
+        network: "testnet",
+        asset: "XLM",
+        amount: price,
+        destination
+      })
+    });
+    response.end(JSON.stringify({ error: "payment_required", network: "testnet", price, destination }));
+    return;
+  }
+
+  response.writeHead(200, { "content-type": "application/json" });
+  response.end(JSON.stringify({ ok: true, paid: true, message: "Replace this demo verifier before production." }));
+});
+
+server.listen(port, () => {
+  console.log(\`x402 demo server listening on http://127.0.0.1:\${port}\`);
+});
+`,
+        "README.md": `# Stellar Agent x402 Testnet Server
+
+This scaffold is a local Testnet demo target for \`stellar-agent pay x402\`.
+
+Run it:
+
+\`\`\`sh
+npm start
+\`\`\`
+
+Configure the destination with a Testnet merchant public key:
+
+\`\`\`sh
+X402_DESTINATION=G... npm start
+\`\`\`
+
+This scaffold does not verify payments. Replace the demo verifier before using it outside a local Testnet experiment.
+`
+    };
+}
 function enableX402ForUrl(policy, url) {
     const host = new URL(url).host;
     if (!/^localhost(?::\d+)?$/.test(host) && !/^127\.0\.0\.1(?::\d+)?$/.test(host)) {