@getalby/cli 0.6.1 → 0.8.0

package/build/commands/pay-keysend.js

@@ -1,15 +1,27 @@
 import { payKeysend } from "../tools/nwc/pay_keysend.js";
 import { getClient, handleError, output } from "../utils.js";
+import { parseAmountNumber, resolveLightningSats } from "../amount.js";
 export function registerPayKeysendCommand(program) {
     program
         .command("pay-keysend")
         .description("Send a keysend payment to a node")
         .requiredOption("-p, --pubkey <hex>", "Destination node public key")
-        .requiredOption("-a, --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("--preimage <hex>", "Preimage (optional, will be generated if not provided)")
         .option("--tlv-records <json>", "TLV records as JSON array [{type, value}]")
+        .addHelpText("after", "\nExample:\n" +
+        "  $ npx @getalby/cli pay-keysend -p 02abc... --amount 100 --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 client = await getClient(program);
             let tlvRecords;
             if (options.tlvRecords) {
@@ -17,11 +29,15 @@ export function registerPayKeysendCommand(program) {
             }
             const result = await payKeysend(client, {
                 pubkey: options.pubkey,
-                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 }),
+            });
         });
     });
 }

package/build/commands/pay.js

@@ -0,0 +1,237 @@
+import { LN_ADDRESS_REGEX } from "@getalby/lightning-tools";
+import { payInvoice } from "../tools/nwc/pay_invoice.js";
+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";
+    // BOLT-11 prefixes: lnbc = mainnet, lntb = testnet/signet, lnbcrt = regtest, lntbs = signet (e.g. mutinynet).
+    if (/^ln(bcrt|tbs|bc|tb)/i.test(destination))
+        return "invoice";
+    if (LN_ADDRESS_REGEX.test(destination))
+        return "lightning-address";
+    if (/^0[23][0-9a-fA-F]{64}$/.test(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", "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",
+};
+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) {
+        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 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("--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}]")
+        .addHelpText("after", "\nExamples:\n" +
+        "  $ npx @getalby/cli pay lnbc1...\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 () => {
+            const type = detectDestinationType(destination);
+            if (!type) {
+                throw new Error(`Could not detect destination type for: ${destination}\n` +
+                    "Expected one of:\n" +
+                    "  - BOLT-11 invoice (starts with lnbc, lntb, lnbcrt, or lntbs)\n" +
+                    "  - Lightning address (user@domain)\n" +
+                    "  - Node pubkey for keysend (66-char hex, compressed secp256k1: starts with 02/03)\n" +
+                    "  - EVM address (0x + 40 hex characters)");
+            }
+            // Track which options the user *explicitly* set (vs. defaults from
+            // commander) so we only reject stray flags the user actually typed.
+            const providedKeys = new Set();
+            for (const opt of cmd.options) {
+                const key = opt.attributeName();
+                const src = cmd.getOptionValueSource(key);
+                if (src === "cli" || src === "env") {
+                    providedKeys.add(key);
+                }
+            }
+            rejectUnusedOpts(type, options, providedKeys);
+            switch (type) {
+                case "invoice": {
+                    // 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: amountInSats,
+                        metadata: {},
+                    });
+                    output({ ...result, ...(fiat && { fiat }) });
+                    return;
+                }
+                case "lightning-address": {
+                    if (options.amount === undefined) {
+                        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: resolved.sats,
+                        comment: options.comment,
+                    });
+                    const client = await getClient(program);
+                    // Stash identifier + comment on the payment record so the wallet
+                    // can show who was paid even when the LNURL server drops them
+                    // from the invoice memo.
+                    const metadata = {
+                        ...(options.comment && { comment: options.comment }),
+                        recipient_data: { identifier: destination },
+                    };
+                    const result = await payInvoice(client, {
+                        invoice: invoice.paymentRequest,
+                        metadata,
+                    });
+                    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 <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);
+                    }
+                    const client = await getClient(program);
+                    const result = await payKeysend(client, {
+                        pubkey: destination,
+                        amount_in_sats: resolved.sats,
+                        preimage: options.preimage,
+                        tlv_records: tlvRecords,
+                    });
+                    output({
+                        ...result,
+                        amount_in_sats: resolved.sats,
+                        ...(resolved.fiat && { fiat: resolved.fiat }),
+                    });
+                    return;
+                }
+                case "crypto": {
+                    if (options.amount === undefined) {
+                        throw new Error("EVM address payments require --amount <n> --currency <token> --network <chain>");
+                    }
+                    // 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.");
+                    }
+                    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(rail.currency, rail.network);
+                    const nwc = await getClient(program);
+                    const { swapId } = await payCrypto({
+                        pair,
+                        amount: options.amount,
+                        targetAddress: destination,
+                        payInvoice: async (bolt11Invoice) => {
+                            await payInvoice(nwc, { invoice: bolt11Invoice });
+                        },
+                    });
+                    output({
+                        swap_id: swapId,
+                        status: "completed",
+                        target: {
+                            address: destination,
+                            currency: pair.symbol,
+                            network: pair.network,
+                            amount: options.amount,
+                        },
+                    });
+                    return;
+                }
+            }
+        });
+    });
+}

package/build/commands/receive.js

@@ -0,0 +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 <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 --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) {
+                // 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 <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;
+            }
+            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: resolved.sats,
+                description: options.description,
+            });
+            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

@@ -8,6 +8,8 @@ import { registerMakeInvoiceCommand } from "./commands/make-invoice.js";
 import { registerMakeHoldInvoiceCommand } from "./commands/make-hold-invoice.js";
 import { registerSettleHoldInvoiceCommand } from "./commands/settle-hold-invoice.js";
 import { registerCancelHoldInvoiceCommand } from "./commands/cancel-hold-invoice.js";
+import { registerPayCommand } from "./commands/pay.js";
+import { registerReceiveCommand } from "./commands/receive.js";
 import { registerPayInvoiceCommand } from "./commands/pay-invoice.js";
 import { registerPayKeysendCommand } from "./commands/pay-keysend.js";
 import { registerLookupInvoiceCommand } from "./commands/lookup-invoice.js";
@@ -20,8 +22,10 @@ import { registerParseInvoiceCommand } from "./commands/parse-invoice.js";
 import { registerVerifyPreimageCommand } from "./commands/verify-preimage.js";
 import { registerRequestInvoiceFromLightningAddressCommand } from "./commands/request-invoice-from-lightning-address.js";
 import { registerFetch402Command } from "./commands/fetch.js";
+import { registerPayCryptoCommand } from "./commands/pay-crypto.js";
 import { registerConnectCommand } from "./commands/connect.js";
 import { registerAuthCommand } from "./commands/auth.js";
+import { registerListWalletsCommand } from "./commands/list-wallets.js";
 import { registerDiscoverCommand } from "./commands/discover.js";
 const program = new Command();
 program
@@ -32,8 +36,12 @@ program
     "    $ npx @getalby/cli auth https://my.albyhub.com --app-name OpenClaw\n" +
     '    $ npx @getalby/cli connect "nostr+walletconnect://..."\n' +
     "    $ npx @getalby/cli get-balance\n" +
-    "    $ npx @getalby/cli pay-invoice --invoice lnbc...")
-    .version("0.6.1")
+    "    $ npx @getalby/cli pay lnbc...\n" +
+    "    $ 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.8.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)")
     .option("-v, --verbose", "Print status messages to stderr")
@@ -52,6 +60,8 @@ Security:
     as this can be used to gain access to your wallet or reduce your wallet's privacy.`);
 // Register common wallet commands
 program.commandsGroup("Wallet Commands (requires wallet connection):");
+registerPayCommand(program);
+registerReceiveCommand(program);
 registerGetBalanceCommand(program);
 registerGetBudgetCommand(program);
 registerGetInfoCommand(program);
@@ -78,6 +88,9 @@ 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)
+program.commandsGroup("Cross-Currency Payments (requires wallet connection):");
+registerPayCryptoCommand(program);
 // Register service discovery
 program.commandsGroup("Service Discovery:");
 registerDiscoverCommand(program);
@@ -85,4 +98,5 @@ registerDiscoverCommand(program);
 program.commandsGroup("Setup:");
 registerAuthCommand(program);
 registerConnectCommand(program);
+registerListWalletsCommand(program);
 program.parse();

package/build/lendaswap/swap.js

@@ -0,0 +1,177 @@
+import { Asset, Client, InMemorySwapStorage, InMemoryWalletStorage, toChain, toChainName, } from "@lendasat/lendaswap-sdk-pure";
+// Allow tests (or local dev against staging) to override the API endpoint.
+const API_BASE_URL = process.env.LENDASWAP_API_URL || "https://api.satora.io";
+// Terminal statuses where the swap is irrecoverably done. Mirrors the same
+// constants used by the bitcoin-card-topup reference frontend.
+const SUCCESS_STATUSES = ["clientredeemed", "serverredeemed"];
+const FAILURE_STATUSES = [
+    "expired",
+    "clientrefunded",
+    "clientrefundedserverrefunded",
+    "clientrefundedserverfunded",
+    "clientinvalidfunded",
+    "clientfundedtoolate",
+    "serverwontfund",
+];
+let clientPromise = null;
+function getClient() {
+    if (!clientPromise) {
+        // In-memory storage: a single CLI invocation waits synchronously for a
+        // terminal swap status, so there's nothing to recover across runs. If the
+        // process is killed mid-swap, the HTLC refund timer is the safety net.
+        clientPromise = Client.builder()
+            .withBaseUrl(API_BASE_URL)
+            .withSignerStorage(new InMemoryWalletStorage())
+            .withSwapStorage(new InMemorySwapStorage())
+            .build();
+    }
+    return clientPromise;
+}
+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:
+ * `getTokens()` for the token universe, intersected with `getSwapPairs()`
+ * filtered to source = Lightning.
+ */
+export function getSupportedPairs() {
+    if (!supportedPairsPromise) {
+        supportedPairsPromise = (async () => {
+            const client = await getClient();
+            const [tokens, swapPairs] = await Promise.all([
+                client.getTokens(),
+                client.getSwapPairs(),
+            ]);
+            const lightningTargetChains = new Set(swapPairs.pairs
+                .filter((p) => p.source === "Lightning")
+                .map((p) => p.target));
+            return tokens.evm_tokens
+                .filter((t) => lightningTargetChains.has(t.chain))
+                .map((t) => ({
+                symbol: t.symbol,
+                network: toChainName(t.chain),
+                decimals: t.decimals,
+                chain: t.chain,
+                tokenId: t.token_id,
+            }));
+        })();
+    }
+    return supportedPairsPromise;
+}
+function formatPairsList(pairs) {
+    return pairs.map((p) => `  - ${p.symbol} on ${p.network}`).join("\n");
+}
+/**
+ * Resolve a (currency, network) pair against the live API list, or throw
+ * with a human-readable error listing every supported pair. Network can be
+ * a chain name ("arbitrum") or chain id ("42161"); matching is case-insensitive.
+ */
+export async function findSupportedPair(currency, network) {
+    const pairs = await getSupportedPairs();
+    const symbol = currency.toUpperCase();
+    // toChain normalizes "arbitrum"/"42161"/"Arbitrum" to the canonical chain id.
+    const chain = toChain(network);
+    const pair = pairs.find((p) => p.symbol.toUpperCase() === symbol && p.chain === chain);
+    if (!pair) {
+        throw new Error(`Unsupported currency/network combination: ${currency} on ${network}.\n` +
+            `Supported:\n${formatPairsList(pairs)}`);
+    }
+    return pair;
+}
+/**
+ * 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.
+ */
+export function isPlausibleEvmAddress(address) {
+    return /^0x[0-9a-fA-F]{40}$/.test(address);
+}
+function toSmallestUnit(amount, decimals) {
+    return Math.round(amount * 10 ** decimals);
+}
+async function createPaymentSwap(params) {
+    const client = await getClient();
+    const targetAmount = toSmallestUnit(params.amount, params.pair.decimals);
+    const targetAsset = {
+        chain: params.pair.chain,
+        tokenId: params.pair.tokenId,
+    };
+    const result = await client.createSwap({
+        source: Asset.BTC_LIGHTNING,
+        target: targetAsset,
+        targetAmount,
+        targetAddress: params.targetAddress,
+        gasless: true,
+        referralCode: "lnds_2c07e38f10a28d47",
+    });
+    // Source is BTC_LIGHTNING and target is an EVM token, so the SDK routes
+    // through its lightning→EVM path.
+    return result.response;
+}
+async function subscribeToSwap(swapId, onUpdate) {
+    const client = await getClient();
+    return client.subscribeToSwaps([swapId], onUpdate);
+}
+async function claimSwap(swapId) {
+    const client = await getClient();
+    return client.claim(swapId);
+}
+/**
+ * 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.
+ */
+export async function payCrypto(params) {
+    const swap = await createPaymentSwap({
+        pair: params.pair,
+        amount: params.amount,
+        targetAddress: params.targetAddress,
+    });
+    // Subscribe BEFORE paying so we don't miss the `serverfunded` event
+    // that triggers our claim. Unsubscribe in `finally` no matter what.
+    let unsubscribe;
+    try {
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const settle = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                fn();
+            };
+            let claimStarted = false;
+            subscribeToSwap(swap.id, (_id, status) => {
+                if (status === "serverfunded" && !claimStarted) {
+                    claimStarted = true;
+                    claimSwap(swap.id).catch((err) => settle(() => reject(err instanceof Error ? err : new Error(String(err)))));
+                }
+                if (SUCCESS_STATUSES.includes(status)) {
+                    settle(resolve);
+                }
+                else if (FAILURE_STATUSES.includes(status)) {
+                    settle(() => reject(new Error(`Swap ${status}`)));
+                }
+            })
+                .then((unsub) => {
+                unsubscribe = unsub;
+                // If the swap already terminated before subscribe resolved,
+                // tear down immediately.
+                if (settled)
+                    unsub();
+            })
+                .catch((err) => settle(() => reject(err instanceof Error ? err : new Error(String(err)))));
+            // Pay the lightning invoice. Failure here propagates as the
+            // overall swap failure; success doesn't resolve us — only a
+            // terminal swap status does.
+            params
+                .payInvoice(swap.bolt11_invoice)
+                .catch((err) => settle(() => reject(err instanceof Error ? err : new Error(String(err)))));
+        });
+    }
+    finally {
+        unsubscribe?.();
+    }
+    return { swapId: swap.id };
+}