@h402/cli 0.1.0

package/dist/commands.js

@@ -0,0 +1,539 @@
+import { randomUUID } from "node:crypto";
+import { assertOk, backendErrorCode, IDEMPOTENCY_MONEY_GUIDANCE, requestJson } from "./api.js";
+import { BASE_USDC_BALANCE_ASSET, BASE_USDC_BALANCE_NETWORK, getBaseUsdcBalance } from "./base-usdc-balance.js";
+import { explicitShowSelection, fetchCatalogRoute, resolveProvider, selectCatalogCandidate, withProviderSelection, withProviderSelectionError } from "./catalog.js";
+import { backendUrl, loadConfig, updateConfig } from "./config.js";
+import { CliError } from "./errors.js";
+import { createOwsWallet, getOwsWallet, listOwsWallets, signOwsMessage } from "./ows.js";
+import { promptPassphrase } from "./prompt.js";
+import { assertConcreteProvider, buildProxyPath, encodeRouteId, flagBoolean, flagString, isRecord, mergeH402, parseJsonFlag, parseQueryFlag, printJson, requireValue, resolveMethod } from "./utils.js";
+import { createPaymentSignatureHeader, paymentRequiredFromResponse, selectBaseUsdcRequirement, X402_HEADERS } from "./x402.js";
+const DEFAULT_WALLET_NAME = "h402";
+function walletName(args) {
+    return flagString(args.flags, "name", DEFAULT_WALLET_NAME);
+}
+// Explicit passphrase from flags/env. Wallets are passphrase-less by default
+// (the onboarding default), so this is usually undefined and signing simply
+// runs without one. --no-passphrase force-skips even an exported passphrase.
+function explicitPassphrase(args) {
+    if (flagBoolean(args.flags, "no-passphrase")) {
+        return undefined;
+    }
+    return flagString(args.flags, "passphrase", process.env.H402_WALLET_PASSPHRASE);
+}
+// OWS reports any keystore/passphrase disagreement as an AEAD decryption
+// failure: a protected wallet signed without (or with the wrong) passphrase,
+// or a passphrase supplied for a wallet created without one.
+const PASSPHRASE_MISMATCH = /decryption failed/i;
+async function promptBarePassphrase(options = { confirm: false }) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error("Bare --passphrase prompts interactively; pass --passphrase <s> or set H402_WALLET_PASSPHRASE in non-interactive use.");
+    }
+    return promptPassphrase(options);
+}
+// Sign with the explicit passphrase (usually none). Only a passphrase-protected
+// keystore escalates: prompt once on an interactive terminal, otherwise fail
+// with the H402_WALLET_PASSPHRASE hint — that env var is only ever needed for
+// wallets that opted into a passphrase at create time.
+export async function signWithWalletPassphrase(args, walletName, sign) {
+    // Bare --passphrase = "prompt me" (kept out of shell history/env).
+    const explicit = flagBoolean(args.flags, "no-passphrase")
+        ? undefined
+        : args.flags.passphrase === true
+            ? await promptBarePassphrase()
+            : explicitPassphrase(args);
+    try {
+        return await sign(explicit);
+    }
+    catch (error) {
+        if (!(error instanceof Error) || !PASSPHRASE_MISMATCH.test(error.message)) {
+            throw error;
+        }
+        if (explicit !== undefined) {
+            throw new Error(`Wallet "${walletName}" rejected the passphrase from --passphrase / H402_WALLET_PASSPHRASE.`);
+        }
+        if (flagBoolean(args.flags, "no-passphrase")) {
+            throw new Error(`Wallet "${walletName}" is passphrase-protected, but --no-passphrase was passed.`);
+        }
+        if (!process.stdin.isTTY || !process.stdout.isTTY) {
+            throw new Error(`Wallet "${walletName}" is passphrase-protected. Set H402_WALLET_PASSPHRASE (or pass --passphrase <s>) for non-interactive use.`);
+        }
+        return sign(await promptPassphrase({ confirm: false }));
+    }
+}
+// Passphrase for `wallet create`: none by default (agents sign with zero flags);
+// opt in with `--passphrase <s>` / H402_WALLET_PASSPHRASE, or bare `--passphrase`
+// to be prompted with confirmation.
+export async function createPassphrase(args) {
+    if (flagBoolean(args.flags, "no-passphrase")) {
+        return undefined;
+    }
+    if (args.flags.passphrase === true) {
+        return promptBarePassphrase({ confirm: true });
+    }
+    return explicitPassphrase(args);
+}
+function withIdempotencyKey(error, idempotencyKey) {
+    const existingDetail = error instanceof CliError ? error.detail : undefined;
+    const detail = isRecord(existingDetail)
+        ? { ...existingDetail, idempotencyKey }
+        : { idempotencyKey, ...(existingDetail === undefined ? {} : { detail: existingDetail }) };
+    const message = `${error instanceof Error ? error.message : String(error)} (idempotency-key: ${idempotencyKey})`;
+    return new CliError(message, detail);
+}
+function adoptWallet(config, name, address) {
+    config.wallets[name] = { address };
+    return { name, address };
+}
+function rejectExtraPositionals(args, maxPositionals, commandForHelp, hint) {
+    const extra = args.positional.slice(maxPositionals);
+    if (extra.length === 0) {
+        return;
+    }
+    const label = extra.length === 1 ? "Unexpected positional argument" : "Unexpected positional arguments";
+    const rendered = extra.map((value) => JSON.stringify(value)).join(", ");
+    throw new Error(`${label}: ${rendered}. ${hint ?? `Run: h402 ${commandForHelp} --help`}`);
+}
+function isMissingOwsWalletError(error) {
+    return error instanceof Error && /(?:not found|does not exist|no wallet|unknown wallet|wallet .* missing)/i.test(error.message);
+}
+function isExistingOwsWalletError(error) {
+    return error instanceof Error && /already exists/i.test(error.message);
+}
+async function adoptOwsWalletByName(name, config) {
+    try {
+        const wallet = await getOwsWallet(name);
+        const resolved = adoptWallet(config, wallet.name || name, wallet.address.toLowerCase());
+        await updateConfig((current) => {
+            adoptWallet(current, resolved.name, resolved.address);
+        });
+        return resolved;
+    }
+    catch (error) {
+        if (isMissingOwsWalletError(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function adoptOwsWalletByAddress(address, config) {
+    const wallets = await listOwsWallets();
+    const match = wallets.find((wallet) => wallet.address.toLowerCase() === address);
+    if (!match)
+        return undefined;
+    const resolved = adoptWallet(config, match.name, match.address.toLowerCase());
+    await updateConfig((current) => {
+        adoptWallet(current, resolved.name, resolved.address);
+    });
+    return resolved;
+}
+function normalizeOwsWallets(wallets) {
+    return wallets.map((wallet) => ({ name: wallet.name, address: wallet.address.toLowerCase() }));
+}
+async function restoreOwsWallets(config) {
+    const wallets = await listOwsWallets();
+    let changed = false;
+    const restored = normalizeOwsWallets(wallets);
+    for (const wallet of restored) {
+        if (config.wallets[wallet.name]?.address?.toLowerCase() !== wallet.address) {
+            adoptWallet(config, wallet.name, wallet.address);
+            changed = true;
+        }
+    }
+    if (changed) {
+        await updateConfig((current) => {
+            for (const wallet of restored) {
+                adoptWallet(current, wallet.name, wallet.address);
+            }
+        });
+    }
+    return restored;
+}
+// Resolve the wallet that will BOTH sign and own the request address, so the two
+// can never silently diverge. The OWS signer is keyed by wallet *name*, so the
+// address presented upstream must be that wallet's address — not an unrelated
+// `--wallet` string. `--name` selects by name; `--wallet` selects the local
+// wallet that owns that address; if both are given they must agree.
+export async function resolveSigningWallet(args, config) {
+    config ??= await loadConfig();
+    const explicitAddress = flagString(args.flags, "wallet")?.toLowerCase();
+    const explicitName = flagString(args.flags, "name");
+    if (explicitName) {
+        const address = config.wallets[explicitName]?.address?.toLowerCase();
+        if (!address) {
+            const adopted = await adoptOwsWalletByName(explicitName, config);
+            if (adopted) {
+                if (explicitAddress && explicitAddress !== adopted.address) {
+                    throw new Error(`--wallet ${explicitAddress} does not match wallet "${explicitName}" (${adopted.address}). Omit --wallet or pass the wallet that owns this address.`);
+                }
+                return adopted;
+            }
+            throw new Error(`No address known for wallet "${explicitName}". Run: h402 wallet create --name ${explicitName}, or h402 wallet restore to re-adopt existing OWS wallets.`);
+        }
+        if (explicitAddress && explicitAddress !== address) {
+            throw new Error(`--wallet ${explicitAddress} does not match wallet "${explicitName}" (${address}). Omit --wallet or pass the wallet that owns this address.`);
+        }
+        return { name: explicitName, address };
+    }
+    if (explicitAddress) {
+        const owner = Object.entries(config.wallets).find(([, wallet]) => wallet.address?.toLowerCase() === explicitAddress);
+        if (!owner) {
+            const adopted = await adoptOwsWalletByAddress(explicitAddress, config);
+            if (adopted)
+                return adopted;
+            throw new Error(`No local wallet owns address ${explicitAddress}. Create it (h402 wallet create), run h402 wallet restore to re-adopt existing OWS wallets, or select one with --name.`);
+        }
+        return { name: owner[0], address: explicitAddress };
+    }
+    const address = config.wallets[DEFAULT_WALLET_NAME]?.address?.toLowerCase();
+    if (!address) {
+        const adopted = await adoptOwsWalletByName(DEFAULT_WALLET_NAME, config);
+        if (adopted)
+            return adopted;
+        throw new Error(`No address known for wallet "${DEFAULT_WALLET_NAME}". Run: h402 wallet create --name ${DEFAULT_WALLET_NAME} (or pass --name/--wallet), or h402 wallet restore to re-adopt existing OWS wallets.`);
+    }
+    return { name: DEFAULT_WALLET_NAME, address };
+}
+export async function walletCommand(args) {
+    const subcommand = requireValue(args.positional[1], "wallet subcommand is required");
+    rejectExtraPositionals(args, 2, `wallet ${subcommand}`);
+    const name = walletName(args);
+    const config = await loadConfig();
+    if (subcommand === "create") {
+        let wallet;
+        try {
+            wallet = await createOwsWallet(name, await createPassphrase(args));
+        }
+        catch (error) {
+            if (isExistingOwsWalletError(error)) {
+                throw new Error(`Wallet "${name}" already exists in the OWS vault. Run: h402 wallet address --name ${name} to re-adopt and print it, or h402 wallet restore to re-adopt all OWS wallets.`);
+            }
+            throw error;
+        }
+        adoptWallet(config, name, wallet.address);
+        await updateConfig((current) => {
+            adoptWallet(current, name, wallet.address);
+        });
+        await printJson({ wallet: { name, address: wallet.address } });
+        return;
+    }
+    if (subcommand === "address") {
+        await printJson({ wallet: await resolveSigningWallet(args, config) });
+        return;
+    }
+    if (subcommand === "list") {
+        await printJson({ wallets: normalizeOwsWallets(await listOwsWallets()) });
+        return;
+    }
+    if (subcommand === "restore") {
+        await printJson({ wallets: await restoreOwsWallets(config) });
+        return;
+    }
+    if (subcommand === "balance") {
+        const { name: signingName, address } = await resolveSigningWallet(args, config);
+        await printJson({
+            wallet: { name: signingName, address },
+            network: BASE_USDC_BALANCE_NETWORK,
+            asset: BASE_USDC_BALANCE_ASSET,
+            balance: await getBaseUsdcBalance(address)
+        });
+        return;
+    }
+    if (subcommand === "fund") {
+        const { name: signingName, address } = await resolveSigningWallet(args, config);
+        await printJson({
+            wallet: { name: signingName, address },
+            network: "base",
+            token: "USDC",
+            instructions: `Send Base USDC to this address from an exchange, bridge, or another wallet, then run h402 wallet balance --name ${signingName}.`
+        });
+        return;
+    }
+    throw new Error(`Unknown wallet subcommand: ${subcommand}`);
+}
+export async function authCommand(args) {
+    rejectExtraPositionals(args, 1, "auth");
+    const config = await loadConfig();
+    const apiUrl = backendUrl(config, flagString(args.flags, "api-url"));
+    const { name, address } = await resolveSigningWallet(args, config);
+    const challenge = assertOk(await requestJson(apiUrl, "/api/auth/challenge", {
+        method: "POST",
+        body: JSON.stringify({ address })
+    })).challenge;
+    const signature = await signWithWalletPassphrase(args, name, (passphrase) => signOwsMessage(name, challenge.message, passphrase));
+    const session = assertOk(await requestJson(apiUrl, "/api/auth/verify", {
+        method: "POST",
+        body: JSON.stringify({ address, message: challenge.message, signature })
+    })).session;
+    await updateConfig((current) => {
+        current.backendUrl = apiUrl;
+        current.sessions[apiUrl] = session.token;
+    });
+    await printJson({ session: { address: session.address, expiresAt: session.expiresAt } });
+}
+function searchLimit(flags) {
+    const raw = flagString(flags, "limit", "20");
+    if (!/^\d+$/.test(raw) || Number(raw) < 1) {
+        throw new Error(`Flag --limit must be a positive integer (got "${raw}").`);
+    }
+    return raw;
+}
+function rejectQueryOnPost(method, query) {
+    if (method === "POST" && query && Object.keys(query).length > 0) {
+        throw new Error("Flag --query cannot be combined with POST requests; use --query for GET parameters or --json for a POST body, not both.");
+    }
+}
+function explicitProviderFlag(flags) {
+    const provider = flagString(flags, "provider");
+    if (provider === undefined) {
+        return undefined;
+    }
+    if (!provider) {
+        throw new Error("Flag --provider requires a non-empty provider slug.");
+    }
+    return assertConcreteProvider(provider);
+}
+async function parseProxyInvocation(args, command) {
+    rejectExtraPositionals(args, 2, command, `Did you forget --json for a request body or --query for URL parameters? Run: h402 ${command} --help`);
+    const routeId = requireValue(args.positional[1], "route id is required");
+    encodeRouteId(routeId);
+    const body = parseJsonFlag(args.flags);
+    const query = parseQueryFlag(args.flags);
+    const explicitProvider = explicitProviderFlag(args.flags);
+    const method = resolveMethod(args.flags, body !== undefined);
+    rejectQueryOnPost(method, query);
+    const config = await loadConfig();
+    const apiUrl = backendUrl(config, flagString(args.flags, "api-url"));
+    return { routeId, body, query, explicitProvider, method, config, apiUrl };
+}
+export async function searchCommand(args) {
+    // Validate the required query before any network work.
+    const query = requireValue(args.positional.slice(1).join(" ").trim() || undefined, 'search query is required (e.g. h402 search "web search")');
+    const config = await loadConfig();
+    const apiUrl = backendUrl(config, flagString(args.flags, "api-url"));
+    const params = new URLSearchParams({ q: query, limit: searchLimit(args.flags) });
+    const result = assertOk(await requestJson(apiUrl, `/api/catalog/search?${params.toString()}`));
+    await printJson(result);
+}
+export async function showCommand(args) {
+    rejectExtraPositionals(args, 2, "show");
+    const routeId = requireValue(args.positional[1], "route id is required");
+    encodeRouteId(routeId);
+    const provider = explicitProviderFlag(args.flags);
+    const config = await loadConfig();
+    const apiUrl = backendUrl(config, flagString(args.flags, "api-url"));
+    const { route } = await fetchCatalogRoute(apiUrl, routeId);
+    if (provider === undefined) {
+        await printJson({ route });
+        return;
+    }
+    const candidate = selectCatalogCandidate(route, provider);
+    const routeSummary = {
+        id: route.id,
+        routeKey: route.routeKey,
+        category: route.category,
+        action: route.action,
+        title: route.title,
+        summary: route.summary,
+        method: route.method,
+        tags: route.tags,
+        defaultProvider: route.defaultProvider,
+        defaultCandidateKey: route.defaultCandidateKey,
+        stats: route.stats,
+        flow: route.flow,
+        flowFollowUps: route.flowFollowUps
+    };
+    await printJson({
+        route: routeSummary,
+        candidate,
+        providerSelection: explicitShowSelection(apiUrl, routeId, provider, args.flags)
+    });
+}
+export async function creditsCommand(args) {
+    rejectExtraPositionals(args, 1, "credits");
+    const config = await loadConfig();
+    const apiUrl = backendUrl(config, flagString(args.flags, "api-url"));
+    const token = config.sessions[apiUrl];
+    if (!token) {
+        throw new Error("No session token. Run h402 auth first.");
+    }
+    await printJson(assertOk(await requestJson(apiUrl, "/api/me/credits", { token })));
+}
+export async function quoteCommand(args) {
+    const { routeId, body, query, explicitProvider, method, apiUrl } = await parseProxyInvocation(args, "quote");
+    const providerSelection = await resolveProvider(apiUrl, routeId, explicitProvider, "quote", args.flags);
+    try {
+        const result = await requestJson(apiUrl, buildProxyPath(routeId, providerSelection.provider, query), {
+            method,
+            body: body === undefined ? undefined : JSON.stringify(body)
+        });
+        const paymentRequired = result.status === 402 ? paymentRequiredFromResponse(result.headers, result.body) : null;
+        if (paymentRequired) {
+            await printJson(withProviderSelection({ paymentRequired }, providerSelection));
+            return;
+        }
+        // No challenge: a free route returns its result with a 2xx. Any non-2xx
+        // (404/410/500/...) is a real error and must exit non-zero, not print as a result.
+        await printJson(withProviderSelection(assertOk(result), providerSelection));
+    }
+    catch (error) {
+        throw withProviderSelectionError(error, providerSelection);
+    }
+}
+function parseUsdMicros(raw, source) {
+    if (!/^\d+(?:\.\d{1,6})?$/.test(raw)) {
+        throw new Error(`${source} must be a non-negative USD amount with at most 6 decimal places (got "${raw}").`);
+    }
+    const [whole, fractional = ""] = raw.split(".");
+    const micros = BigInt(whole) * 1000000n + BigInt(fractional.padEnd(6, "0"));
+    return micros;
+}
+function parseBaseUsdcMicros(raw, source) {
+    if (typeof raw !== "string" || !/^\d+$/.test(raw)) {
+        throw new Error(`${source} must be an unsigned integer amount in USDC micros (got ${JSON.stringify(raw)}).`);
+    }
+    return BigInt(raw);
+}
+function formatUsdMicros(micros) {
+    const whole = micros / 1000000n;
+    const fractional = (micros % 1000000n).toString().padStart(6, "0").replace(/0+$/, "");
+    return fractional ? `${whole}.${fractional}` : whole.toString();
+}
+function maxUsd(args, config) {
+    if (args.flags["max-usd"] === true) {
+        throw new Error("Flag --max-usd requires a USD amount, for example --max-usd 0.05.");
+    }
+    const raw = flagString(args.flags, "max-usd", config.maxUsd);
+    return raw === undefined ? undefined : { raw, micros: parseUsdMicros(raw, "--max-usd / config.maxUsd") };
+}
+function assertUnderMaxUsd(amount, cap) {
+    const amountMicros = parseBaseUsdcMicros(amount, "x402 payment amount");
+    if (cap && amountMicros > cap.micros) {
+        throw new Error(`Payment amount $${formatUsdMicros(amountMicros)} USDC exceeds --max-usd ${cap.raw}; refusing to sign.`);
+    }
+    return amountMicros;
+}
+function withSignedAmount(body, accepted, amountMicros) {
+    const signedAmount = { amount: accepted.amount, asset: "USDC", decimals: 6, usd: formatUsdMicros(amountMicros) };
+    return mergeH402(body, { signedAmount });
+}
+function authorizationClockFromResponseDate(headers) {
+    const date = headers.get("date");
+    if (!date)
+        return undefined;
+    const millis = Date.parse(date);
+    return Number.isFinite(millis) ? Math.floor(millis / 1000) : undefined;
+}
+const PAYMENT_SETTLEMENT_RETRY_DELAYS_MS = [250, 1_000, 2_000];
+const REPLACEMENT_IDEMPOTENCY_KEY_HEADER = "x-h402-replacement-idempotency-key";
+function isPaymentSettlementPending(response) {
+    return response.status === 409 && backendErrorCode(response.body) === "payment_settlement_pending";
+}
+function waitForPaymentSettlement(delayMs) {
+    return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+// Once a signed request is sent, a network drop or non-terminal response can
+// hide a completed settlement. Keep that uncertainty visible so callers do not
+// create a second authorization accidentally.
+function withSettlementRiskGuidance(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes(IDEMPOTENCY_MONEY_GUIDANCE)) {
+        return error;
+    }
+    return new CliError(`${message}. ${IDEMPOTENCY_MONEY_GUIDANCE}`, error instanceof CliError ? error.detail : undefined);
+}
+function isPaymentSettlementFailure(error) {
+    return error instanceof CliError && backendErrorCode(error.detail) === "payment_settlement_failed";
+}
+function isConclusiveSettlementFailure(error, idempotencyKey) {
+    if (!isPaymentSettlementFailure(error) || !isRecord(error.detail)) {
+        return false;
+    }
+    const backendError = error.detail.error;
+    return (isRecord(backendError) &&
+        backendError.idempotencyKey === idempotencyKey &&
+        backendError.paid === false &&
+        backendError.safeToStartNewCall === true);
+}
+function isReplacementPaymentResponse(response) {
+    return response.headers.has(REPLACEMENT_IDEMPOTENCY_KEY_HEADER);
+}
+function automaticReplacementRefused(response, idempotencyKey) {
+    return withSettlementRiskGuidance(new CliError("Automatic replacement payment refused. This invocation did not sign a replacement authorization. Start a separate explicit h402 call only if you intentionally accept a new payment; the original settlement remains unknown.", {
+        code: "automatic_replacement_refused",
+        idempotencyKey,
+        settlementStatus: "unknown",
+        replacementAuthorizationSigned: false,
+        separateCallRequired: true,
+        url: response.url
+    }));
+}
+export async function callCommand(args) {
+    const { routeId, body, query, explicitProvider, method, config, apiUrl } = await parseProxyInvocation(args, "call");
+    const idempotencyKey = flagString(args.flags, "idempotency-key", randomUUID());
+    const paymentCap = maxUsd(args, config);
+    const token = config.sessions[apiUrl];
+    const providerSelection = await resolveProvider(apiUrl, routeId, explicitProvider, "call", args.flags, paymentCap?.raw);
+    let signedRequestSent = false;
+    try {
+        const path = buildProxyPath(routeId, providerSelection.provider, query);
+        const requestBody = body === undefined ? undefined : JSON.stringify(body);
+        const headers = {
+            "idempotency-key": idempotencyKey
+        };
+        if (token && !flagBoolean(args.flags, "no-credit")) {
+            headers.authorization = `Bearer ${token}`;
+        }
+        const first = await requestJson(apiUrl, path, {
+            method,
+            headers,
+            body: requestBody
+        });
+        if (isReplacementPaymentResponse(first)) {
+            throw automaticReplacementRefused(first, idempotencyKey);
+        }
+        const paymentRequired = first.status === 402 ? paymentRequiredFromResponse(first.headers, first.body) : null;
+        if (!paymentRequired) {
+            // A 2xx means the route answered without payment (free, or covered by credit).
+            // A non-2xx first response (incl. an unparseable 402) is a real error: assertOk
+            // exits non-zero instead of printing the error body as a successful result.
+            await printJson(withProviderSelection(assertOk(first), providerSelection));
+            return;
+        }
+        const accepted = selectBaseUsdcRequirement(paymentRequired);
+        const amountMicros = assertUnderMaxUsd(accepted.amount, paymentCap);
+        const { name, address: walletAddress } = await resolveSigningWallet(args, config);
+        const paymentSignature = await signWithWalletPassphrase(args, name, (passphrase) => createPaymentSignatureHeader({
+            paymentRequired,
+            walletAddress,
+            walletName: name,
+            passphrase,
+            authorizationNow: authorizationClockFromResponseDate(first.headers)
+        }));
+        const paidHeaders = {
+            "idempotency-key": idempotencyKey,
+            [X402_HEADERS.paymentSignature]: paymentSignature
+        };
+        const sendSignedRequest = () => requestJson(apiUrl, path, { method, headers: paidHeaders, body: requestBody });
+        signedRequestSent = true;
+        let paid = await sendSignedRequest();
+        if (isReplacementPaymentResponse(paid)) {
+            throw automaticReplacementRefused(paid, idempotencyKey);
+        }
+        for (const delayMs of PAYMENT_SETTLEMENT_RETRY_DELAYS_MS) {
+            if (!isPaymentSettlementPending(paid))
+                break;
+            await waitForPaymentSettlement(delayMs);
+            paid = await sendSignedRequest();
+            if (isReplacementPaymentResponse(paid)) {
+                throw automaticReplacementRefused(paid, idempotencyKey);
+            }
+        }
+        await printJson(withProviderSelection(withSignedAmount(assertOk(paid), accepted, amountMicros), providerSelection));
+    }
+    catch (error) {
+        const settlementRiskIsUnresolved = (signedRequestSent || isPaymentSettlementFailure(error)) && !isConclusiveSettlementFailure(error, idempotencyKey);
+        const guardedError = settlementRiskIsUnresolved ? withSettlementRiskGuidance(error) : error;
+        throw withProviderSelectionError(withIdempotencyKey(guardedError, idempotencyKey), providerSelection);
+    }
+}