@getalby/cli 0.6.1 → 0.8.0

package/README.md

@@ -2,7 +2,11 @@
 
 CLI for Nostr Wallet Connect (NIP-47) with lightning tools.
 
-Built for agents - use with the [Alby Bitcoin Payments CLI Skill](https://github.com/getAlby/alby-cli-skill)
+Built for agents - best used with the [Alby Bitcoin Payments CLI Skill](https://github.com/getAlby/alby-cli-skill)
+
+## What this CLI can do
+
+Bitcoin lightning wallet operations using Nostr Wallet Connect (NIP-47). Use when the user needs to send/receive bitcoin payments, pay to crypto/stablecoin addresses, check wallet balance, create invoices, convert between fiat and sats, work with lightning addresses, when an HTTP request returns a 402 Payment Required status code and the user wants to pay for and retry the request, or discover paid API services.
 
 ## Usage
 
@@ -27,6 +31,8 @@ npx @getalby/cli auth --complete
 npx @getalby/cli connect "nostr+walletconnect://..."
 ```
 
+Already have a connection secret? Pass it per-command with `-c <secret-or-file>`, or set the `NWC_URL` environment variable.
+
 ### Multiple wallets
 
 Use `--wallet-name` when setting up to save named connections:
@@ -40,33 +46,13 @@ Then pass `--wallet-name` to any command to use that wallet:
 
 ```bash
 npx @getalby/cli --wallet-name work get-balance
-npx @getalby/cli --wallet-name personal pay-invoice --invoice lnbc...
+npx @getalby/cli --wallet-name personal pay lnbc...
 ```
 
-### Connection secret resolution (in order of priority)
-
-1. `--connection-secret` flag (value or path to file)
-2. `--wallet-name` flag (`~/.alby-cli/connection-secret-<name>.key`)
-3. `NWC_URL` environment variable
-4. `~/.alby-cli/connection-secret.key` (default file location)
+List the wallets you've configured (names and connection status only, never the secrets):
 
 ```bash
-# Use the default saved wallet connection (preferred)
-npx @getalby/cli <command> [options]
-
-# Use a named wallet
-npx @getalby/cli --wallet-name alice <command> [options]
-
-# Or pass a connection secret directly
-npx @getalby/cli -c /path/to/secret.txt <command> [options]
-```
-
-The `-c` option auto-detects whether you're passing a connection string or a file path. You can get a connection string from your NWC-compatible wallet (e.g., [Alby](https://getalby.com)).
-
-You can also set the `NWC_URL` environment variable instead of using the `-c` option:
-
-```txt
-NWC_URL="nostr+walletconnect://..."
+npx @getalby/cli list-wallets
 ```
 
 ## Testing Wallet
@@ -87,93 +73,9 @@ curl -X POST "https://faucet.nwc.dev/wallets/<username>/topup?amount=5000"
 
 ## Commands
 
-### Wallet Commands
-
-These commands require a wallet connection - either default connection, or specify a custom connection with `-w`, '-c', or `NWC_URL` environment variable:
-
-```bash
-# Get wallet balance
-npx @getalby/cli get-balance
-
-# Get wallet info
-npx @getalby/cli get-info
-
-# Get wallet service capabilities
-npx @getalby/cli get-wallet-service-info
-
-# Create an invoice
-npx @getalby/cli make-invoice --amount 1000 --description "Payment"
-
-# Pay an invoice
-npx @getalby/cli pay-invoice --invoice "lnbc..."
-
-# Send a keysend payment
-npx @getalby/cli pay-keysend --pubkey "02abc..." --amount 100
-
-# Look up an invoice by payment hash
-npx @getalby/cli lookup-invoice --payment-hash "abc123..."
-
-# List transactions
-npx @getalby/cli list-transactions --limit 10
-
-# Get wallet budget
-npx @getalby/cli get-budget
-
-# Sign a message
-npx @getalby/cli sign-message --message "Hello, World!"
-
-# Fetch a payment-protected resource (auto-detects L402, X402, MPP)
-npx @getalby/cli fetch "https://example.com/api"
-
-# Fetch with custom method, headers, and body
-npx @getalby/cli fetch "https://example.com/api" --method POST --body '{"query":"hello"}' --headers '{"Accept":"application/json"}'
-
-# Fetch with a custom max amount (default: 5000 sats, 0 = no limit)
-npx @getalby/cli fetch "https://example.com/api" --max-amount 1000
-
-# Wait for a payment notification
-npx @getalby/cli wait-for-payment --payment-hash "abc123..."
-```
-
-### HOLD Invoices
-
-HOLD invoices allow you to accept payments conditionally - the payment is held until you settle or cancel it.
-
-```bash
-# Create a HOLD invoice (you provide the payment hash)
-npx @getalby/cli make-hold-invoice --amount 1000 --payment-hash "abc123..."
-
-# Settle a HOLD invoice (claim the payment)
-npx @getalby/cli settle-hold-invoice --preimage "def456..."
-
-# Cancel a HOLD invoice (reject the payment)
-npx @getalby/cli cancel-hold-invoice --payment-hash "abc123..."
-```
-
-### Lightning Tools
-
-These commands don't require a wallet connection:
-
-```bash
-# Convert USD to sats
-npx @getalby/cli fiat-to-sats --currency USD --amount 10
-
-# Convert sats to USD
-npx @getalby/cli sats-to-fiat --amount 1000 --currency USD
-
-# Parse a BOLT-11 invoice
-npx @getalby/cli parse-invoice --invoice "lnbc..."
-
-# Verify a preimage against an invoice
-npx @getalby/cli verify-preimage --invoice "lnbc..." --preimage "abc123..."
-
-# Request invoice from lightning address
-npx @getalby/cli request-invoice-from-lightning-address --address "hello@getalby.com" --amount 1000
-```
-
-## Command Reference
+Run `npx @getalby/cli help` for the full list of commands and their arguments, or `npx @getalby/cli help <command>` for one command.
 
-Run `npx @getalby/cli help` for a full list of commands and possible arguments.
+Amounts are always given as `--amount` with `--currency` and `--network`; `--currency BTC` additionally requires `--unit sats|BTC`.
 
 ## Output
 

package/build/amount.js

@@ -0,0 +1,141 @@
+import { InvalidArgumentError } from "commander";
+import { getSatoshiValue } from "@getalby/lightning-tools";
+/**
+ * Shared amount model for every amount-bearing command. One axis each for
+ * *what* (`--currency`), *where* (`--network`), and — for BTC only — the
+ * sub-unit (`--unit`): denomination and rail are never guessed, and the
+ * BTC/sats split is made explicit so a bare `--amount 1 --currency BTC` can
+ * never be silently interpreted as 1 sat vs 1 whole bitcoin.
+ *
+ * Rail dispatch is keyed purely on `--network`, so no catalog of currencies or
+ * tokens is hardcoded here. BTC is the only special-cased currency (a protocol
+ * constant with sub-units); every other code is resolved by the rail it lands
+ * on — a fiat code by the rate converter on the lightning rail, a token symbol
+ * by the Lendaswap catalog on a chain rail. A currency that doesn't belong on
+ * the chosen rail therefore surfaces its error from that downstream resolver.
+ */
+export const SATS_PER_BTC = 100_000_000;
+/**
+ * Commander coercion for `--amount`: a strict positive number. Rejects `NaN`,
+ * unit-suffixed input (`"10abc"`), and values `<= 0` instead of silently
+ * truncating them. Replaces the ad-hoc `Number`/`parseInt`/`parseFloat`
+ * coercions that previously let the same flag resolve to different values
+ * across commands.
+ */
+export function parseAmountNumber(value) {
+    const num = Number(value);
+    if (!Number.isFinite(num) || num <= 0) {
+        throw new InvalidArgumentError(`Amount must be a positive number (got "${value}")`);
+    }
+    return num;
+}
+const LIGHTNING_NETWORK = "lightning";
+/**
+ * Validate a (currency, unit, network) triple and decide the payment rail.
+ * Keyed on `--network`, which selects the *destination*: `lightning` pays a
+ * lightning invoice/address (amount denominated in BTC, or in a fiat code
+ * converted to sats); any other value is the chain of a crypto/stablecoin
+ * address — still funded from the lightning wallet, then swapped to the token.
+ * The payer always pays with lightning. The only currency interpreted here is
+ * `BTC` — every other code is passed through for the downstream resolver (rate
+ * converter for fiat, Lendaswap catalog for tokens) to validate. Pure /
+ * synchronous — no network I/O — so the structural checks run at validation
+ * time before any wallet load.
+ */
+export function classifyRail({ currency, unit, network, }) {
+    if (!currency) {
+        throw new Error("An amount requires --currency <BTC|USD|EUR|USDC|…> so the denomination is never guessed");
+    }
+    if (!network) {
+        throw new Error('An amount requires --network <name>. Use "lightning" to pay a lightning ' +
+            "invoice or address (amount in --currency BTC, or a fiat code like USD " +
+            "that's converted to sats). Use a chain name (e.g. arbitrum) to pay a " +
+            "crypto/stablecoin address on that chain — still paid from your lightning " +
+            "wallet, then swapped to the token.");
+    }
+    const code = currency.toUpperCase();
+    const isBtc = code === "BTC";
+    const isLightning = network.toLowerCase() === LIGHTNING_NETWORK;
+    // --unit is meaningful only for BTC (the one currency with sub-units).
+    if (!isBtc && unit !== undefined) {
+        throw new Error(`--unit is not valid for --currency ${code} — only BTC has sub-units (sats/BTC). Drop --unit.`);
+    }
+    if (isLightning) {
+        if (isBtc) {
+            return { kind: "bitcoin", currency: "BTC", unit: parseUnit(unit), network };
+        }
+        // Fiat code (or, if mis-routed, a token) — the rate converter validates it.
+        return { kind: "fiat", currency: code, network };
+    }
+    // Chain network → crypto swap rail. BTC has no chain rail today.
+    if (isBtc) {
+        throw new Error(`--currency BTC is only supported on --network lightning, not "${network}"`);
+    }
+    // Token symbol (or, if mis-routed, a fiat code) — the catalog validates it.
+    return { kind: "crypto", currency: code, network };
+}
+/**
+ * Normalize and validate `--unit` for BTC. Case-insensitive; canonical forms
+ * are `sats` and `BTC`. Required (no default) because the sats/BTC split is
+ * dangerous and must be stated explicitly.
+ */
+function parseUnit(unit) {
+    if (unit === undefined) {
+        throw new Error("--unit <sats|BTC> is required when --currency is BTC (1 BTC = 100,000,000 sats, so the amount can't be guessed)");
+    }
+    const normalized = unit.toLowerCase();
+    if (normalized === "sats")
+        return "sats";
+    if (normalized === "btc")
+        return "BTC";
+    throw new Error(`--unit must be "sats" or "BTC" (got "${unit}")`);
+}
+/**
+ * Resolve a bitcoin- or fiat-denominated amount to whole sats. For BTC, does
+ * the sats/BTC arithmetic and enforces a whole-sat result. For fiat, converts
+ * at the live rate and surfaces the resolved sats alongside the original fiat
+ * amount. Crypto-token amounts are handled by the swap path, not here.
+ */
+export async function resolveToSats({ amount, currency, unit, }) {
+    if (currency.toUpperCase() === "BTC") {
+        if (unit === "sats") {
+            if (!Number.isInteger(amount)) {
+                throw new Error(`Amount in sats must be a whole number (got ${amount}). Use --unit BTC for fractional bitcoin.`);
+            }
+            return { sats: amount };
+        }
+        // unit === "BTC"
+        const raw = amount * SATS_PER_BTC;
+        const sats = Math.round(raw);
+        if (Math.abs(raw - sats) > 1e-6) {
+            throw new Error(`Amount ${amount} BTC is not a whole number of sats (1 BTC = 100,000,000 sats)`);
+        }
+        if (sats < 1) {
+            throw new Error(`Amount ${amount} BTC is less than 1 sat`);
+        }
+        return { sats };
+    }
+    // Fiat → sats at the live rate. A non-fiat code (e.g. a token mistakenly put
+    // on the lightning rail) surfaces the converter's own rate-lookup error.
+    const sats = await getSatoshiValue({ amount, currency });
+    return { sats, fiat: { amount, currency: currency.toUpperCase() } };
+}
+/**
+ * For commands that can only settle over lightning (invoices, lightning-address
+ * / keysend payments): classify the rail, reject a chain (crypto) rail with a
+ * pointer to `pay-crypto`, and resolve BTC/fiat to whole sats.
+ */
+export async function resolveLightningSats({ amount, currency, unit, network, }) {
+    const rail = classifyRail({ currency, unit, network });
+    if (rail.kind === "crypto") {
+        throw new Error(`--network "${network}" is a chain network for crypto-token payments. ` +
+            "This command settles over lightning — use --network lightning with " +
+            "--currency BTC (and --unit sats|BTC) or a fiat code (e.g. --currency USD). " +
+            "For on-chain crypto, see the pay-crypto command.");
+    }
+    return resolveToSats({
+        amount,
+        currency: rail.currency,
+        unit: rail.kind === "bitcoin" ? rail.unit : undefined,
+    });
+}

package/build/commands/auth.js

@@ -1,8 +1,6 @@
 import { NWCClient } from "@getalby/sdk";
 import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-import { getConnectionSecretPath, getPendingConnectionRelayPath, getPendingConnectionSecretPath, handleError, } from "../utils.js";
+import { getAlbyCliDir, DEFAULT_RELAY_URLS, getConnectionSecretPath, getPendingConnectionRelayPath, getPendingConnectionSecretPath, handleError, } from "../utils.js";
 import { generateSecretKey, getPublicKey } from "nostr-tools";
 import { bytesToHex, hexToBytes } from "@noble/hashes/utils.js";
 export function registerAuthCommand(program) {
@@ -12,7 +10,7 @@ export function registerAuthCommand(program) {
         "  Step 1: npx @getalby/cli auth https://my.albyhub.com --app-name MyApp\n" +
         "  Step 2: after human confirmation, run any command to finalize the connection")
         .option("--app-name <name>", 'Name of the agent or app that will use this wallet (e.g. "Claude Code")')
-        .option("--relay-url <url>", "Relay URL for the pending connection", "wss://relay.getalby.com/v1")
+        .option("--relay-url <url>", `Relay URL for the pending connection (repeat to use multiple relays, default: ${DEFAULT_RELAY_URLS.join(", ")})`, (value, previous) => previous.concat([value]), [])
         .option("--force", "Overwrite existing connection secret")
         .option("--remove-pending", "Remove a pending connection and start fresh")
         .action(async (walletUrl, options) => {
@@ -43,18 +41,24 @@ export function registerAuthCommand(program) {
             }
             if (existsSync(connectionSecretPath) && !options.force) {
                 console.error(`Error: Already connected. Connection secret exists at ${connectionSecretPath}\n` +
-                    `To overwrite, use --force.`);
+                    `To overwrite, use --force.\n` +
+                    `To connect an additional wallet, use --wallet-name <name>.`);
                 process.exit(1);
             }
+            const relayUrls = options.relayUrl.length > 0 ? options.relayUrl : DEFAULT_RELAY_URLS;
             const secret = bytesToHex(generateSecretKey());
             const pubkey = getPublicKey(hexToBytes(secret));
             const authUrl = NWCClient.getAuthorizationUrl(`${walletUrl}/apps/new`, { name: options.appName }, pubkey).toString();
-            const dir = join(homedir(), ".alby-cli");
+            const dir = getAlbyCliDir();
             if (!existsSync(dir)) {
                 mkdirSync(dir, { recursive: true });
             }
             writeFileSync(pendingSecretPath, secret, { mode: 0o600 });
-            writeFileSync(pendingRelayPath, options.relayUrl, { mode: 0o600 });
+            // Store one relay per line so multiple relays survive the
+            // round-trip to the completion step.
+            writeFileSync(pendingRelayPath, relayUrls.join("\n"), {
+                mode: 0o600,
+            });
             console.log("Click the following URL to approve the connection in your wallet:\n" +
                 authUrl);
             const retryCmd = walletName

package/build/commands/connect.js

@@ -11,7 +11,8 @@ export function registerConnectCommand(program) {
             const connectionSecretPath = getConnectionSecretPath(program.opts().walletName);
             if (existsSync(connectionSecretPath) && !options.force) {
                 console.error(`Error: Already connected. Connection secret exists at ${connectionSecretPath}\n` +
-                    `To overwrite, use --force.`);
+                    `To overwrite, use --force.\n` +
+                    `To connect an additional wallet, use --wallet-name <name>.`);
                 process.exit(1);
             }
             if (!connectionSecret) {

package/build/commands/fetch.js

@@ -1,5 +1,28 @@
+import { InvalidArgumentError } from "commander";
 import { fetch402 } from "../tools/lightning/fetch.js";
 import { getClient, handleError, output } from "../utils.js";
+import { classifyRail } from "../amount.js";
+/**
+ * Commander coercion for `--max-amount`, fetch's spend cap. The value is in
+ * sats (`--unit` is restricted to sats), so only a positive base-10 whole
+ * number is accepted. Unlike `parseInt`, this rejects partial/odd input —
+ * `"1abc"`, `"1e3"`, `"1.5"`, `"0x10"`, `"abc"`, `"0"` — instead of silently
+ * coercing it (`parseInt("abc")` → `NaN`, `parseInt("0.5")` → `0`), which would
+ * weaken the cap.
+ */
+function parseMaxAmountSats(value) {
+    if (!/^\d+$/.test(value.trim())) {
+        throw new InvalidArgumentError(`Sats must be a whole number (got "${value}")`);
+    }
+    const sats = Number(value);
+    if (!Number.isSafeInteger(sats)) {
+        throw new InvalidArgumentError(`Sats value is too large (got "${value}")`);
+    }
+    if (sats === 0) {
+        throw new InvalidArgumentError("Sats must be greater than 0");
+    }
+    return sats;
+}
 export function registerFetch402Command(program) {
     program
         .command("fetch")
@@ -8,15 +31,41 @@ export function registerFetch402Command(program) {
         .option("-X, --method <method>", "HTTP method (GET, POST, etc.)")
         .option("-b, --body <json>", "Request body (JSON string)")
         .option("-H, --headers <json>", "Additional headers (JSON string)")
-        .option("--max-amount <sats>", "Maximum amount in sats to pay per request. Aborts if the endpoint requests more. (default: 5000, 0 = no limit)", parseInt)
+        .option("--max-amount <amount>", "Maximum amount to auto-pay per request. Aborts if the endpoint requests more. " +
+        "When set, requires --currency BTC --unit sats --network lightning. (default: 5000 sats)", parseMaxAmountSats)
+        .option("--currency <code>", "Denomination of --max-amount — currently must be BTC")
+        .option("--unit <sats|BTC>", "Sub-unit of --max-amount — currently must be sats")
+        .option("--network <name>", "Rail for --max-amount — currently must be lightning")
+        .addHelpText("after", "\nExample:\n" +
+        '  $ npx @getalby/cli fetch "https://example.com/api" --max-amount 1000 --currency BTC --unit sats --network lightning\n')
         .action(async (url, options) => {
         await handleError(async () => {
+            // A cap must state its denomination, like every other amount. For now
+            // the only supported rail is BTC/sats over lightning — the cap is
+            // inherently a sats spend limit — but it goes through the shared
+            // classifier so the surface matches the rest of the CLI and can grow.
+            if (options.maxAmount !== undefined) {
+                const rail = classifyRail({
+                    currency: options.currency,
+                    unit: options.unit,
+                    network: options.network,
+                });
+                if (rail.kind !== "bitcoin" || rail.unit !== "sats") {
+                    throw new Error("fetch's --max-amount spend cap currently supports only " +
+                        "--currency BTC --unit sats --network lightning");
+                }
+            }
+            else if (options.currency || options.unit || options.network) {
+                throw new Error("--currency/--unit/--network only apply together with a positive --max-amount");
+            }
             const client = await getClient(program);
             const result = await fetch402(client, {
                 url: url,
                 method: options.method,
                 body: options.body,
                 headers: options.headers ? JSON.parse(options.headers) : undefined,
+                // --unit is restricted to sats above, so --max-amount is already the
+                // sats cap. When omitted, the tool applies its default.
                 maxAmountSats: options.maxAmount,
             });
             output(result);

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

@@ -1,11 +1,12 @@
 import { fiatToSats } from "../tools/lightning/fiat_to_sats.js";
 import { handleError, output } from "../utils.js";
+import { parseAmountNumber } from "../amount.js";
 export function registerFiatToSatsCommand(program) {
     program
         .command("fiat-to-sats")
         .description("Convert fiat to sats")
         .requiredOption("--currency <code>", "Currency code (e.g., USD, EUR)")
-        .requiredOption("-a, --amount <n>", "Fiat amount", parseFloat)
+        .requiredOption("--amount <n>", "Fiat amount", parseAmountNumber)
         .action(async (options) => {
         await handleError(async () => {
             const result = await fiatToSats({

package/build/commands/list-wallets.js

@@ -0,0 +1,12 @@
+import { getAlbyCliDir, handleError, listWallets, output } from "../utils.js";
+export function registerListWalletsCommand(program) {
+    program
+        .command("list-wallets")
+        .description("List configured wallets (names and connection status only, no secrets)")
+        .action(async () => {
+        await handleError(async () => {
+            const wallets = listWallets();
+            output({ directory: getAlbyCliDir(), wallets });
+        });
+    });
+}

package/build/commands/make-hold-invoice.js

@@ -1,23 +1,35 @@
 import { makeHoldInvoice } from "../tools/nwc/make_hold_invoice.js";
 import { getClient, handleError, output } from "../utils.js";
+import { parseAmountNumber, resolveLightningSats } from "../amount.js";
 export function registerMakeHoldInvoiceCommand(program) {
     program
         .command("make-hold-invoice")
         .description("Create a HOLD invoice that requires manual settlement")
-        .requiredOption("-a, --amount <sats>", "Amount in sats", parseInt)
+        .requiredOption("--amount <number>", "Invoice 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" for invoices')
+        .option("--unit <sats|BTC>", "Sub-unit (required when --currency is BTC)")
         .requiredOption("--payment-hash <hex>", "Payment hash (32 bytes hex)")
         .option("-d, --description <text>", "Invoice description")
         .option("-e, --expiry <seconds>", "Expiry time in seconds", parseInt)
+        .addHelpText("after", "\nExample:\n" +
+        "  $ npx @getalby/cli make-hold-invoice --amount 1000 --currency BTC --unit sats --network lightning --payment-hash abc123...\n")
         .action(async (options) => {
         await handleError(async () => {
+            const resolved = await resolveLightningSats({
+                amount: options.amount,
+                currency: options.currency,
+                unit: options.unit,
+                network: options.network,
+            });
             const client = await getClient(program);
             const result = await makeHoldInvoice(client, {
-                amount_in_sats: options.amount,
+                amount_in_sats: resolved.sats,
                 payment_hash: options.paymentHash,
                 description: options.description,
                 expiry: options.expiry,
             });
-            output(result);
+            output({ ...result, ...(resolved.fiat && { fiat: resolved.fiat }) });
         });
     });
 }

package/build/commands/make-invoice.js

@@ -1,21 +1,34 @@
 import { makeInvoice } from "../tools/nwc/make_invoice.js";
 import { getClient, handleError, output } from "../utils.js";
+import { parseAmountNumber, resolveLightningSats } from "../amount.js";
 export function registerMakeInvoiceCommand(program) {
     program
         .command("make-invoice")
         .description("Create a lightning invoice")
-        .requiredOption("-a, --amount <sats>", "Amount in sats", parseInt)
+        .requiredOption("--amount <number>", "Invoice 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" for invoices')
+        .option("--unit <sats|BTC>", "Sub-unit (required when --currency is BTC)")
         .option("-d, --description <text>", "Invoice description")
         .option("-e, --expiry <seconds>", "Expiry time in seconds", parseInt)
+        .addHelpText("after", "\nExamples:\n" +
+        "  $ npx @getalby/cli make-invoice --amount 1000 --currency BTC --unit sats --network lightning\n" +
+        "  $ npx @getalby/cli make-invoice --amount 5 --currency USD --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 client = await getClient(program);
             const result = await makeInvoice(client, {
-                amount_in_sats: options.amount,
+                amount_in_sats: resolved.sats,
                 description: options.description,
                 expiry: options.expiry,
             });
-            output(result);
+            output({ ...result, ...(resolved.fiat && { fiat: resolved.fiat }) });
         });
     });
 }

package/build/commands/pay-crypto.js

@@ -0,0 +1,58 @@
+import { payInvoice } from "../tools/nwc/pay_invoice.js";
+import { getClient, handleError, output } from "../utils.js";
+import { isPlausibleEvmAddress, payCrypto, findSupportedPair, } from "../lendaswap/swap.js";
+import { parseAmountNumber, classifyRail } from "../amount.js";
+export function registerPayCryptoCommand(program) {
+    program
+        .command("pay-crypto")
+        .description("Pay any supported crypto or stablecoin address from your bitcoin lightning wallet.\n\n" +
+        "If the requested currency/network pair isn't supported you'll get an error listing the pairs that are.")
+        .argument("<address>", "Recipient address on the target network")
+        .requiredOption("--amount <number>", "Amount to send in target-currency units (e.g. 10 = 10 USDC)", parseAmountNumber)
+        .requiredOption("--currency <name>", "Target currency (e.g. USDC)")
+        .requiredOption("--network <name>", "Target chain network (chain name or id, e.g. arbitrum / 42161)")
+        .addHelpText("after", "\nExample:\n" +
+        "  $ npx @getalby/cli pay-crypto 0xabc... --amount 10 --currency USDC --network arbitrum\n")
+        .action(async (address, options) => {
+        await handleError(async () => {
+            // Shared rail classifier: rejects --unit, rejects --network lightning,
+            // rejects BTC/fiat on a chain network — leaving only a crypto token on
+            // a chain network, which findSupportedPair then validates.
+            const rail = classifyRail({
+                currency: options.currency,
+                unit: options.unit,
+                network: options.network,
+            });
+            if (rail.kind !== "crypto") {
+                throw new Error("pay-crypto only sends crypto tokens over a chain network " +
+                    "(e.g. --currency USDC --network arbitrum). For BTC/fiat over " +
+                    "lightning, use the pay command.");
+            }
+            if (!isPlausibleEvmAddress(address)) {
+                throw new Error(`Recipient address does not look valid (expected 0x + 40 hex chars): ${address}`);
+            }
+            // Validate the pair against the live Lendaswap catalog before
+            // asking the user for their wallet — fast feedback on typos.
+            const pair = await findSupportedPair(rail.currency, rail.network);
+            const nwc = await getClient(program);
+            const { swapId } = await payCrypto({
+                pair,
+                amount: options.amount,
+                targetAddress: address,
+                payInvoice: async (bolt11Invoice) => {
+                    await payInvoice(nwc, { invoice: bolt11Invoice });
+                },
+            });
+            output({
+                swap_id: swapId,
+                status: "completed",
+                target: {
+                    address,
+                    currency: pair.symbol,
+                    network: pair.network,
+                    amount: options.amount,
+                },
+            });
+        });
+    });
+}

package/build/commands/pay-invoice.js

@@ -1,19 +1,37 @@
 import { payInvoice } from "../tools/nwc/pay_invoice.js";
 import { getClient, handleError, output } from "../utils.js";
+import { parseAmountNumber, resolveLightningSats } from "../amount.js";
 export function registerPayInvoiceCommand(program) {
     program
         .command("pay-invoice")
         .description("Pay a lightning invoice")
-        .requiredOption("-i, --invoice <bolt11>", "Invoice to pay")
-        .option("-a, --amount <sats>", "Amount (for zero-amount invoices)", parseInt)
-        .action(async (options) => {
+        .argument("<bolt11>", "Invoice to pay")
+        .option("--amount <number>", "Amount (only for zero-amount invoices)", 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)")
+        .addHelpText("after", "\nExample (zero-amount invoice):\n" +
+        "  $ npx @getalby/cli pay-invoice lnbc1... --amount 1000 --currency BTC --unit sats --network lightning\n")
+        .action(async (invoice, options) => {
         await handleError(async () => {
+            let amountInSats;
+            let fiat;
+            if (options.amount !== undefined) {
+                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: options.invoice,
-                amount_in_sats: options.amount,
+                invoice,
+                amount_in_sats: amountInSats,
             });
-            output(result);
+            output({ ...result, ...(fiat && { fiat }) });
         });
     });
 }