@getalby/cli 0.7.0 → 0.9.0

package/build/commands/pay.js

@@ -4,6 +4,7 @@ import { payKeysend } from "../tools/nwc/pay_keysend.js";
 import { requestInvoiceFromLightningAddress } from "../tools/lightning/request_invoice_from_lightning_address.js";
 import { isPlausibleEvmAddress, payCrypto, findSupportedPair, } from "../lendaswap/swap.js";
 import { getClient, handleError, output } from "../utils.js";
+import { parseAmountNumber, classifyRail, resolveLightningSats, } from "../amount.js";
 function detectDestinationType(destination) {
     if (/^0x[0-9a-fA-F]{40}$/.test(destination))
         return "crypto";
@@ -16,48 +17,60 @@ function detectDestinationType(destination) {
         return "keysend";
     return null;
 }
+// Which flags each destination accepts. The amount axes (amount/currency/
+// unit/network) are shared by every lightning destination; the crypto rail
+// has no sub-unit, so `unit` is excluded there.
 const ALLOWED_OPTS = {
-    invoice: ["amount"],
-    "lightning-address": ["amount", "comment"],
-    keysend: ["amount", "preimage", "tlvRecords"],
+    invoice: ["amount", "currency", "unit", "network"],
+    "lightning-address": ["amount", "currency", "unit", "network", "comment"],
+    keysend: ["amount", "currency", "unit", "network", "preimage", "tlvRecords"],
     crypto: ["amount", "currency", "network"],
 };
 const OPT_FLAG = {
     amount: "--amount",
+    currency: "--currency",
+    unit: "--unit",
+    network: "--network",
     comment: "--comment",
     preimage: "--preimage",
     tlvRecords: "--tlv-records",
-    currency: "--currency",
-    network: "--network",
 };
 function rejectUnusedOpts(type, options, providedKeys) {
     const allowed = new Set(ALLOWED_OPTS[type]);
     const used = Object.keys(options).filter((k) => providedKeys.has(k));
     const stray = used.filter((k) => !allowed.has(k));
-    if (stray.length > 0) {
-        throw new Error(`Option${stray.length > 1 ? "s" : ""} ${stray.map((k) => OPT_FLAG[k] ?? `--${k}`).join(", ")} not applicable to ${type} payment`);
+    if (stray.length === 0) {
+        return;
+    }
+    // --unit is the most likely cross-rail mistake: it's only valid for BTC
+    // (a lightning destination), never for a crypto-token payment.
+    if (stray.includes("unit") && type === "crypto") {
+        throw new Error("Option --unit is not valid for crypto payments — only BTC has sub-units (sats/BTC)");
     }
+    throw new Error(`Option${stray.length > 1 ? "s" : ""} ${stray.map((k) => OPT_FLAG[k] ?? `--${k}`).join(", ")} not applicable to ${type} payment`);
 }
 export function registerPayCommand(program) {
     program
         .command("pay")
         .description("Pay any supported destination — auto-detects type from the destination string.\n\n" +
         "Supported destinations:\n" +
-        "  - BOLT-11 invoice (lnbc... / lntb... / lnbcrt... / lntbs...): no extra args (use --amount only for zero-amount invoices)\n" +
-        "  - Lightning address (user@domain): requires --amount (sats); optional --comment\n" +
-        "  - Node pubkey (66-char hex, compressed secp256k1): keysend, requires --amount (sats)\n" +
-        "  - EVM address (0x...): pay crypto/stablecoin, requires --amount, --currency, and --network")
+        "  - BOLT-11 invoice (lnbc... / lntb... / lnbcrt... / lntbs...): no amount flags (the invoice encodes the amount; pass --amount/--currency/--network only for a zero-amount invoice)\n" +
+        "  - Lightning address (user@domain): requires --amount, --currency, --network lightning (and --unit for BTC); optional --comment\n" +
+        "  - Node pubkey (66-char hex, compressed secp256k1): keysend, requires --amount, --currency, --network lightning (and --unit for BTC)\n" +
+        "  - EVM address (0x...): pay crypto/stablecoin, requires --amount, --currency (token), and --network <chain>")
         .argument("<destination>", "Invoice, lightning address, node pubkey, or EVM address")
-        .option("-a, --amount <number>", "Amount — sats for lightning destinations, target-currency units for crypto (e.g. 10 = 10 USDC)", Number)
+        .option("--amount <number>", "Amount", parseAmountNumber)
+        .option("--currency <code>", "Denomination: BTC, a fiat code (USD, EUR, …), or a crypto token (USDC, …)")
+        .option("--network <name>", 'Destination network: "lightning" to pay a lightning invoice/address (amount in --currency BTC or a fiat code), or a chain name (e.g. arbitrum) to pay a crypto/stablecoin address (funded from your lightning wallet)')
+        .option("--unit <sats|BTC>", "Sub-unit (required when --currency is BTC)")
         .option("--comment <text>", "Comment for lightning address payments")
         .option("--preimage <hex>", "Preimage for keysend (optional, generated if omitted)")
         .option("--tlv-records <json>", "TLV records for keysend, as JSON array [{type, value}]")
-        .option("--currency <name>", "Target currency for crypto payments (required for EVM destinations)")
-        .option("--network <name>", "Target network for crypto payments — chain name or id (required for EVM destinations)")
         .addHelpText("after", "\nExamples:\n" +
         "  $ npx @getalby/cli pay lnbc1...\n" +
-        "  $ npx @getalby/cli pay alice@getalby.com --amount 100 --comment hi\n" +
-        "  $ npx @getalby/cli pay 02aabb... --amount 100\n" +
+        "  $ npx @getalby/cli pay alice@getalby.com --amount 100 --currency BTC --unit sats --network lightning --comment hi\n" +
+        "  $ npx @getalby/cli pay alice@getalby.com --amount 5 --currency USD --network lightning\n" +
+        "  $ npx @getalby/cli pay 02aabb... --amount 100 --currency BTC --unit sats --network lightning\n" +
         "  $ npx @getalby/cli pay 0xabc... --amount 10 --currency USDC --network arbitrum\n")
         .action(async (destination, options, cmd) => {
         await handleError(async () => {
@@ -83,29 +96,47 @@ export function registerPayCommand(program) {
             rejectUnusedOpts(type, options, providedKeys);
             switch (type) {
                 case "invoice": {
-                    if (options.amount !== undefined &&
-                        !Number.isInteger(options.amount)) {
-                        throw new Error(`Invalid --amount: must be an integer number of sats`);
+                    // A BOLT-11 invoice encodes its own amount. Amount flags are only
+                    // for zero-amount invoices, and must come as a complete set.
+                    let amountInSats;
+                    let fiat;
+                    if (options.amount === undefined) {
+                        if (options.currency || options.unit || options.network) {
+                            throw new Error("--currency/--unit/--network only apply to a zero-amount invoice — also pass --amount, or omit them for a fixed-amount invoice");
+                        }
+                    }
+                    else {
+                        const resolved = await resolveLightningSats({
+                            amount: options.amount,
+                            currency: options.currency,
+                            unit: options.unit,
+                            network: options.network,
+                        });
+                        amountInSats = resolved.sats;
+                        fiat = resolved.fiat;
                     }
                     const client = await getClient(program);
                     const result = await payInvoice(client, {
                         invoice: destination,
-                        amount_in_sats: options.amount,
+                        amount_in_sats: amountInSats,
                         metadata: {},
                     });
-                    output(result);
+                    output({ ...result, ...(fiat && { fiat }) });
                     return;
                 }
                 case "lightning-address": {
                     if (options.amount === undefined) {
-                        throw new Error("Lightning address payments require --amount <sats>");
-                    }
-                    if (!Number.isInteger(options.amount) || options.amount <= 0) {
-                        throw new Error(`Invalid --amount: must be a positive integer number of sats`);
+                        throw new Error("Lightning address payments require --amount <n> --currency <code> --network lightning (and --unit for BTC)");
                     }
+                    const resolved = await resolveLightningSats({
+                        amount: options.amount,
+                        currency: options.currency,
+                        unit: options.unit,
+                        network: options.network,
+                    });
                     const invoice = await requestInvoiceFromLightningAddress({
                         lightning_address: destination,
-                        amount_in_sats: options.amount,
+                        amount_in_sats: resolved.sats,
                         comment: options.comment,
                     });
                     const client = await getClient(program);
@@ -120,16 +151,23 @@ export function registerPayCommand(program) {
                         invoice: invoice.paymentRequest,
                         metadata,
                     });
-                    output(result);
+                    output({
+                        ...result,
+                        amount_in_sats: resolved.sats,
+                        ...(resolved.fiat && { fiat: resolved.fiat }),
+                    });
                     return;
                 }
                 case "keysend": {
                     if (options.amount === undefined) {
-                        throw new Error("Keysend payments require --amount <sats>");
-                    }
-                    if (!Number.isInteger(options.amount) || options.amount <= 0) {
-                        throw new Error(`Invalid --amount: must be a positive integer number of sats`);
+                        throw new Error("Keysend payments require --amount <n> --currency <code> --network lightning (and --unit for BTC)");
                     }
+                    const resolved = await resolveLightningSats({
+                        amount: options.amount,
+                        currency: options.currency,
+                        unit: options.unit,
+                        network: options.network,
+                    });
                     let tlvRecords;
                     if (options.tlvRecords) {
                         tlvRecords = JSON.parse(options.tlvRecords);
@@ -137,30 +175,41 @@ export function registerPayCommand(program) {
                     const client = await getClient(program);
                     const result = await payKeysend(client, {
                         pubkey: destination,
-                        amount_in_sats: options.amount,
+                        amount_in_sats: resolved.sats,
                         preimage: options.preimage,
                         tlv_records: tlvRecords,
                     });
-                    output(result);
+                    output({
+                        ...result,
+                        amount_in_sats: resolved.sats,
+                        ...(resolved.fiat && { fiat: resolved.fiat }),
+                    });
                     return;
                 }
                 case "crypto": {
                     if (options.amount === undefined) {
-                        throw new Error("Crypto payments require --amount <number>");
+                        throw new Error("EVM address payments require --amount <n> --currency <token> --network <chain>");
                     }
-                    if (!Number.isFinite(options.amount) || options.amount <= 0) {
-                        throw new Error(`Invalid --amount: ${options.amount}`);
+                    // An EVM address is settled by a crypto-token swap on a chain
+                    // network — the lightning rail (BTC/fiat) is never valid here.
+                    if (options.network?.toLowerCase() === "lightning") {
+                        throw new Error("An EVM address is paid with a crypto token over a chain network " +
+                            "(e.g. --currency USDC --network arbitrum). --network lightning " +
+                            "(BTC/fiat) is not valid for an EVM address.");
                     }
-                    if (!options.currency) {
-                        throw new Error("Crypto payments require --currency <name>");
-                    }
-                    if (!options.network) {
-                        throw new Error("Crypto payments require --network <chain-name-or-id>");
+                    const rail = classifyRail({
+                        currency: options.currency,
+                        unit: options.unit,
+                        network: options.network,
+                    });
+                    if (rail.kind !== "crypto") {
+                        throw new Error("An EVM address is paid with a crypto token over a chain network " +
+                            "(e.g. --currency USDC --network arbitrum).");
                     }
                     if (!isPlausibleEvmAddress(destination)) {
                         throw new Error(`Recipient address does not look valid (expected 0x + 40 hex chars): ${destination}`);
                     }
-                    const pair = await findSupportedPair(options.currency, options.network);
+                    const pair = await findSupportedPair(rail.currency, rail.network);
                     const nwc = await getClient(program);
                     const { swapId } = await payCrypto({
                         pair,

package/build/commands/receive.js

@@ -1,40 +1,56 @@
 import { makeInvoice } from "../tools/nwc/make_invoice.js";
 import { getClient, handleError, output } from "../utils.js";
+import { parseAmountNumber, resolveLightningSats } from "../amount.js";
 export function registerReceiveCommand(program) {
     program
         .command("receive")
         .description("Get paid — returns either the wallet's lightning address or a BOLT-11 invoice.\n\n" +
-        "  - receive                    → returns the wallet's lightning address (if available)\n" +
-        "  - receive --amount <sats>    → returns a BOLT-11 invoice for the given amount")
-        .option("-a, --amount <sats>", "Invoice amount in sats", parseInt)
+        "  - receive                                                            → returns the wallet's lightning address (if available)\n" +
+        "  - receive --amount <n> --currency <code> --network lightning [--unit] → returns a BOLT-11 invoice for the given amount")
+        .option("--amount <number>", "Invoice amount", parseAmountNumber)
+        .option("--currency <code>", "Denomination: BTC, or a fiat code (USD, EUR, …) converted to sats at the current rate — required with --amount")
+        .option("--network <name>", 'Payment network — must be "lightning" (required with --amount)')
+        .option("--unit <sats|BTC>", "Sub-unit (required when --currency is BTC)")
         .option("-d, --description <text>", "Invoice description (requires --amount)")
         .addHelpText("after", "\nExamples:\n" +
         "  $ npx @getalby/cli receive\n" +
-        '  $ npx @getalby/cli receive --amount 2100 --description "coffee"\n')
+        '  $ npx @getalby/cli receive --amount 2100 --currency BTC --unit sats --network lightning --description "coffee"\n' +
+        "  $ npx @getalby/cli receive --amount 5 --currency USD --network lightning\n")
         .action(async (options) => {
         await handleError(async () => {
             if (options.amount === undefined) {
-                if (options.description !== undefined) {
-                    throw new Error("--description requires --amount");
+                // Amount-less call: no rail flags apply.
+                for (const [flag, value] of [
+                    ["--description", options.description],
+                    ["--currency", options.currency],
+                    ["--unit", options.unit],
+                    ["--network", options.network],
+                ]) {
+                    if (value !== undefined) {
+                        throw new Error(`${flag} requires --amount`);
+                    }
                 }
                 const client = await getClient(program);
                 if (!client.lud16) {
                     throw new Error("This wallet does not expose a lightning address. " +
-                        "Either pass --amount <sats> to generate a BOLT-11 invoice, " +
+                        "Either pass --amount <n> --currency <code> --network lightning to generate a BOLT-11 invoice, " +
                         "or connect a wallet that has a lightning address.");
                 }
                 output({ lightning_address: client.lud16 });
                 return;
             }
-            if (!Number.isInteger(options.amount) || options.amount <= 0) {
-                throw new Error("Invalid --amount: must be a positive integer number of sats");
-            }
+            const resolved = await resolveLightningSats({
+                amount: options.amount,
+                currency: options.currency,
+                unit: options.unit,
+                network: options.network,
+            });
             const client = await getClient(program);
             const result = await makeInvoice(client, {
-                amount_in_sats: options.amount,
+                amount_in_sats: resolved.sats,
                 description: options.description,
             });
-            output(result);
+            output({ ...result, ...(resolved.fiat && { fiat: resolved.fiat }) });
         });
     });
 }

package/build/commands/request-invoice-from-lightning-address.js

@@ -1,20 +1,32 @@
 import { requestInvoiceFromLightningAddress } from "../tools/lightning/request_invoice_from_lightning_address.js";
 import { handleError, output } from "../utils.js";
+import { parseAmountNumber, resolveLightningSats } from "../amount.js";
 export function registerRequestInvoiceFromLightningAddressCommand(program) {
     program
         .command("request-invoice-from-lightning-address")
         .description("Request an invoice from a lightning address")
         .requiredOption("-a, --address <ln-address>", "Lightning address")
-        .requiredOption("-s, --amount <sats>", "Amount in sats", parseInt)
+        .requiredOption("--amount <number>", "Amount", parseAmountNumber)
+        .requiredOption("--currency <code>", "Denomination: BTC, or a fiat code (USD, EUR, …) converted to sats at the current rate")
+        .requiredOption("--network <name>", 'Payment network — must be "lightning"')
+        .option("--unit <sats|BTC>", "Sub-unit (required when --currency is BTC)")
         .option("--comment <text>", "Optional comment")
+        .addHelpText("after", "\nExample:\n" +
+        "  $ npx @getalby/cli request-invoice-from-lightning-address -a hello@getalby.com --amount 1000 --currency BTC --unit sats --network lightning\n")
         .action(async (options) => {
         await handleError(async () => {
+            const resolved = await resolveLightningSats({
+                amount: options.amount,
+                currency: options.currency,
+                unit: options.unit,
+                network: options.network,
+            });
             const result = await requestInvoiceFromLightningAddress({
                 lightning_address: options.address,
-                amount_in_sats: options.amount,
+                amount_in_sats: resolved.sats,
                 comment: options.comment,
             });
-            output(result);
+            output({ ...result, ...(resolved.fiat && { fiat: resolved.fiat }) });
         });
     });
 }

package/build/commands/sats-to-fiat.js

@@ -1,15 +1,34 @@
 import { satsToFiat } from "../tools/lightning/sats_to_fiat.js";
 import { handleError, output } from "../utils.js";
+import { parseAmountNumber, resolveToSats } from "../amount.js";
 export function registerSatsToFiatCommand(program) {
     program
         .command("sats-to-fiat")
-        .description("Convert sats to fiat")
-        .requiredOption("-a, --amount <sats>", "Amount in sats", parseInt)
-        .requiredOption("--currency <code>", "Currency code (e.g., USD, EUR)")
+        .description("Convert a bitcoin amount to fiat")
+        .requiredOption("--amount <number>", "Amount on the bitcoin side (paired with --unit)", parseAmountNumber)
+        .requiredOption("--unit <sats|BTC>", "Sub-unit of --amount (sats or BTC)")
+        .requiredOption("--currency <code>", "Target fiat currency (e.g., USD, EUR)")
+        .addHelpText("after", "\nExample:\n" +
+        "  $ npx @getalby/cli sats-to-fiat --amount 1000 --unit sats --currency USD\n")
         .action(async (options) => {
         await handleError(async () => {
+            const normalizedUnit = options.unit.toLowerCase();
+            let unit;
+            if (normalizedUnit === "sats")
+                unit = "sats";
+            else if (normalizedUnit === "btc")
+                unit = "BTC";
+            else
+                throw new Error(`--unit must be "sats" or "BTC" (got "${options.unit}")`);
+            // The amount is denominated in BTC's sub-units, so resolve it to whole
+            // sats first (reusing the shared sats/BTC math), then convert.
+            const { sats } = await resolveToSats({
+                amount: options.amount,
+                currency: "BTC",
+                unit,
+            });
             const result = await satsToFiat({
-                amount_in_sats: options.amount,
+                amount_in_sats: sats,
                 currency: options.currency,
             });
             output(result);

package/build/index.js

@@ -37,9 +37,10 @@ program
     '    $ npx @getalby/cli connect "nostr+walletconnect://..."\n' +
     "    $ npx @getalby/cli get-balance\n" +
     "    $ npx @getalby/cli pay lnbc...\n" +
-    "    $ npx @getalby/cli pay alice@getalby.com --amount 100\n" +
-    '    $ npx @getalby/cli receive --amount 2100 --description "Coffee"')
-    .version("0.7.0")
+    "    $ npx @getalby/cli pay alice@getalby.com --amount 100 --currency BTC --unit sats --network lightning\n" +
+    "    $ npx @getalby/cli pay alice@getalby.com --amount 5 --currency USD --network lightning\n" +
+    '    $ npx @getalby/cli receive --amount 2100 --currency BTC --unit sats --network lightning --description "Coffee"')
+    .version("0.9.0")
     .configureHelp({ showGlobalOptions: true })
     .option("-w, --wallet-name <name>", "Use a named wallet's connection secret (~/.alby-cli/connection-secret-<name>.key)")
     .option("-c, --connection-secret <string>", "NWC connection secret (nostr+walletconnect://...) or path to file containing it (preferred)")
@@ -87,7 +88,7 @@ registerRequestInvoiceFromLightningAddressCommand(program);
 // Register fetch command for payment-protected resources
 program.commandsGroup("HTTP 402 Payments (requires wallet connection):");
 registerFetch402Command(program);
-// Register cross-currency payments (Lightning → EVM via atomic swap)
+// Register cross-currency payments (lightning → EVM via atomic swap)
 program.commandsGroup("Cross-Currency Payments (requires wallet connection):");
 registerPayCryptoCommand(program);
 // Register service discovery

package/build/lendaswap/swap.js

@@ -30,7 +30,7 @@ function getClient() {
 let supportedPairsPromise = null;
 /**
  * Fetch all (currency, network) pairs that can be the target of a
- * Lightning → EVM swap. The list comes straight from the Lendaswap API:
+ * lightning → EVM swap. The list comes straight from the Lendaswap API:
  * `getTokens()` for the token universe, intersected with `getSwapPairs()`
  * filtered to source = Lightning.
  */
@@ -79,7 +79,7 @@ export async function findSupportedPair(currency, network) {
     return pair;
 }
 /**
- * EVM address shape check: every chain reachable from Lightning is EVM, so
+ * EVM address shape check: every chain reachable from lightning is EVM, so
  * the universal `0x` + 40-hex format applies. Lendaswap does the
  * authoritative validation when it builds the swap; this is just a sanity
  * pre-check so an obvious typo fails fast before we lock funds.
@@ -106,7 +106,7 @@ async function createPaymentSwap(params) {
         referralCode: "lnds_2c07e38f10a28d47",
     });
     // Source is BTC_LIGHTNING and target is an EVM token, so the SDK routes
-    // through its Lightning→EVM path.
+    // through its lightning→EVM path.
     return result.response;
 }
 async function subscribeToSwap(swapId, onUpdate) {
@@ -118,7 +118,7 @@ async function claimSwap(swapId) {
     return client.claim(swapId);
 }
 /**
- * Run a Lightning → on-chain crypto payment swap and block until it reaches a
+ * Run a lightning → on-chain crypto payment swap and block until it reaches a
  * terminal status. Throws on any failure status. All swap-provider specifics
  * (Lendaswap SDK calls, status handling, claim-on-serverfunded) live here so
  * that swapping out the provider is a self-contained change.
@@ -162,7 +162,7 @@ export async function payCrypto(params) {
                     unsub();
             })
                 .catch((err) => settle(() => reject(err instanceof Error ? err : new Error(String(err)))));
-            // Pay the Lightning invoice. Failure here propagates as the
+            // Pay the lightning invoice. Failure here propagates as the
             // overall swap failure; success doesn't resolve us — only a
             // terminal swap status does.
             params

package/build/test/amount-model.test.js

@@ -0,0 +1,111 @@
+import { describe, test, expect } from "vitest";
+import { runCli } from "./helpers.js";
+// Exercises the shared amount model (src/amount.ts) wired into every
+// amount-bearing command. Every check here resolves *before* network I/O or
+// wallet load: structural validation (currency/network/unit rules) and the
+// BTC sats/BTC arithmetic are all synchronous. We sanitize the environment so
+// that, when an input is fully valid, the command fails only at wallet load
+// ("No wallet connection found") — proving the input cleared every gate.
+//
+// The two cross-rail *currency* mismatches that need a downstream resolver to
+// surface (a token on the lightning rail → rate lookup; a fiat code's live
+// rate) are intentionally covered by the live suites, not here, since the
+// model is network-first (the rail is chosen by --network alone, with no
+// hardcoded currency/token catalog).
+const SANITIZED_ENV = {
+    HOME: "/tmp/nonexistent-alby-cli-test-home",
+    NWC_URL: "",
+};
+function run(command) {
+    return runCli(command, SANITIZED_ENV);
+}
+describe("amount model — currency and network are always required", () => {
+    test("amount without --currency is rejected", () => {
+        const result = run("pay alice@getalby.com --amount 100 --network lightning");
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain("--currency");
+    });
+    test("amount without --network is rejected", () => {
+        const result = run("pay alice@getalby.com --amount 100 --currency BTC --unit sats");
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain("--network");
+    });
+});
+describe("amount model — --unit is required for BTC, rejected otherwise", () => {
+    test("BTC without --unit is rejected (sats vs BTC must be explicit)", () => {
+        const result = run("pay alice@getalby.com --amount 1 --currency BTC --network lightning");
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain("--unit");
+    });
+    test("--unit on a fiat currency is rejected", () => {
+        const result = run("pay alice@getalby.com --amount 5 --currency USD --unit sats --network lightning");
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain("--unit is not valid");
+    });
+    test('an invalid --unit value is rejected', () => {
+        const result = run("pay alice@getalby.com --amount 1 --currency BTC --unit bits --network lightning");
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain('--unit must be "sats" or "BTC"');
+    });
+});
+describe("amount model — BTC --unit sats is whole-number only", () => {
+    test.each(["1.5", "1abc", "0"])("make-invoice rejects --amount %s for BTC/sats", (value) => {
+        const result = run(`make-invoice --amount ${value} --currency BTC --unit sats --network lightning`);
+        expect(result.success).toBe(false);
+        // "1.5" is rejected by the sats whole-number check; "1abc"/"0" by the
+        // strict --amount parser at parse time.
+        expect(result.output.error).toMatch(/whole number|Amount must be a positive number/);
+    });
+});
+describe("amount model — BTC --unit BTC converts to sats", () => {
+    test("a fractional-sat BTC amount is rejected", () => {
+        // 0.000000001 BTC = 0.1 sats — not a whole number of sats.
+        const result = run("make-invoice --amount 0.000000001 --currency BTC --unit BTC --network lightning");
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain("whole number of sats");
+    });
+    test("a whole-sat BTC amount clears validation (fails only at wallet load)", () => {
+        // 0.000001 BTC = 100 sats. Resolution is synchronous, so the only thing
+        // left to fail is the (absent) wallet.
+        const result = run("make-invoice --amount 0.000001 --currency BTC --unit BTC --network lightning");
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain("No wallet connection found");
+    });
+});
+describe("amount model — rail mismatch on a lightning-only command", () => {
+    test("BTC on a chain network is rejected", () => {
+        const result = run("make-invoice --amount 1 --currency BTC --network arbitrum");
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain("only supported on --network lightning");
+    });
+    test("a chain network is rejected (invoices settle over Lightning)", () => {
+        const result = run("make-invoice --amount 10 --currency USDC --network arbitrum");
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain("lightning");
+    });
+});
+// Representative coverage proving the shared helper is wired into more than
+// one command, not just make-invoice / pay.
+describe("amount model — wired across commands", () => {
+    test("make-hold-invoice enforces --unit for BTC", () => {
+        const result = run("make-hold-invoice --amount 1 --currency BTC --network lightning --payment-hash " +
+            "a".repeat(64));
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain("--unit");
+    });
+    test("pay-keysend enforces --unit for BTC", () => {
+        const result = run(`pay-keysend -p 02${"a".repeat(64)} --amount 1 --currency BTC --network lightning`);
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain("--unit");
+    });
+    test("request-invoice-from-lightning-address rejects --unit for fiat", () => {
+        const result = run("request-invoice-from-lightning-address -a a@b.com --amount 5 --currency USD --unit sats --network lightning");
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain("--unit is not valid");
+    });
+    test("sats-to-fiat rejects an invalid --unit", () => {
+        const result = run("sats-to-fiat --amount 1000 --unit bits --currency USD");
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain('--unit must be "sats" or "BTC"');
+    });
+});

package/build/test/fetch-max-amount.test.js

@@ -0,0 +1,30 @@
+import { describe, test, expect } from "vitest";
+import { runCli } from "./helpers.js";
+// fetch's `--max-amount` is the unified spend-cap flag. Its value is a strict
+// sats integer (see `parseMaxAmountSats` in src/commands/fetch.ts) because the
+// cap is currently restricted to BTC/sats over lightning; the denomination flags are
+// validated through the shared amount model (src/amount.ts). Parsing happens at
+// commander parse time — before any network I/O — so these assertions are
+// deterministic and need no wallet. Payment/invoice amounts are covered by
+// amount-model.test.ts.
+describe("fetch --max-amount strict parsing", () => {
+    // The cap is a positive whole number of sats. Malformed input must be
+    // rejected, not coerced (parseInt("abc") → NaN, parseInt("0.5") → 0), so a
+    // typo can't silently weaken the limit. Negatives are rejected by the
+    // digits-only check, and 0 is no longer a "no limit" escape hatch.
+    test.each(["0.5", "abc", "-1", "1e3", "0"])("rejects malformed/non-positive --max-amount %s", (value) => {
+        const result = runCli(`fetch http://example.invalid --max-amount ${value}`);
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain("Sats must be");
+    });
+    test("a positive --max-amount requires its denomination (--currency)", () => {
+        const result = runCli("fetch http://example.invalid --max-amount 1000");
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain("--currency");
+    });
+    test("a positive --max-amount rejects a non-BTC/sats/lightning denomination", () => {
+        const result = runCli("fetch http://example.invalid --max-amount 5 --currency USD --network lightning");
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain("currently supports only --currency BTC --unit sats --network lightning");
+    });
+});

package/build/test/lightning-tools.test.js

@@ -4,13 +4,26 @@ const exampleInvoice = "lnbc1u1p5hlrr8dqqnp4qwmtpr4p72ms7gnq3pkfk2876y2msvl33s38
 const exampleLightningAddress = "nwc1779952113427@getalby.com";
 describe("Lightning Tools (no wallet required)", () => {
     test("fiat-to-sats converts USD to sats", () => {
-        const result = runCli("fiat-to-sats -a 1 --currency USD");
+        const result = runCli("fiat-to-sats --amount 1 --currency USD");
         expect(result.success).toBe(true);
         expect(result.output.amount_in_sats).toBeTypeOf("number");
         expect(result.output.amount_in_sats).toBeGreaterThan(0);
     });
+    test("fiat-to-sats accepts a decimal --amount", () => {
+        const result = runCli("fiat-to-sats --amount 10.5 --currency USD");
+        expect(result.success).toBe(true);
+        expect(result.output.amount_in_sats).toBeGreaterThan(0);
+    });
+    // --amount is parsed by the shared strict parser (parseAmountNumber), so
+    // partial/invalid input is rejected rather than silently truncated (e.g.
+    // "10abc" → 10), as are non-positive values.
+    test.each(["10abc", "abc", "0", "-5"])("fiat-to-sats rejects invalid --amount %s", (value) => {
+        const result = runCli(`fiat-to-sats --amount ${value} --currency USD`);
+        expect(result.success).toBe(false);
+        expect(result.output.error).toContain("Amount must be a positive number");
+    });
     test("sats-to-fiat converts sats to USD", () => {
-        const result = runCli("sats-to-fiat -a 1000 --currency USD");
+        const result = runCli("sats-to-fiat --amount 1000 --unit sats --currency USD");
         expect(result.success).toBe(true);
         expect(result.output.amount).toBeTypeOf("number");
         expect(result.output.amount).toBeGreaterThan(0);
@@ -29,7 +42,7 @@ describe("Lightning Tools (no wallet required)", () => {
         expect(result.output.valid).toBe(false);
     });
     test("request-invoice-from-lightning-address requests invoice from lightning address", async () => {
-        const result = runCli(`request-invoice-from-lightning-address -a "${exampleLightningAddress}" -s 100`);
+        const result = runCli(`request-invoice-from-lightning-address -a "${exampleLightningAddress}" --amount 100 --currency BTC --unit sats --network lightning`);
         expect(result.success).toBe(true);
         expect(result.output.paymentRequest.toLowerCase()).toMatch(/^lnbc/);
     });