Alby Bitcoin Payments Skill

intent

this skill enables agents to operate a self-custodial or custodial bitcoin lightning wallet using @getalby/cli, which talks to wallets via nostr wallet connect (NIP-47). use it whenever a user needs to send money (lightning address, BOLT-11 invoice, crypto address, keysend), receive money (lightning address or invoice), check balance, list transactions, convert currencies, pay for a 402 Payment Required resource, or discover paid API services. the skill also handles hold invoices and standalone lightning utilities. it works with both named wallets (multi-wallet setups) and a default wallet connection.

inputs

connection secret (required for wallet operations)

• source: NWC_URL environment variable, -c/--connection-secret flag (file path or raw nostr+walletconnect:// URL), -w/--wallet-name flag (named wallet), or default ~/.alby-cli/connection-secret.key
• format: plaintext file or nostr+walletconnect:// URI
• resolution order: explicit -c flag → explicit -w flag → NWC_URL env var → default file
• setup guidance: if no secret exists, run auth (1-click, requires wallet support) or connect "<secret>" (manual paste of NWC URL, never share in chat)

npx

• required: npx binary must be available (comes with Node.js/npm)
• version pinned: @getalby/cli@0.8.0 (always use this version to avoid drift)

wallet services (optional, no secret needed)

• discover command hits 402index.io (requires outbound HTTPS)
• auth command opens a browser for human confirmation (requires wallet at specified URL to be online and support NWC 1-click)

external wallets for obtaining a connection secret (if none exists)

• alby hub (https://getalby.com/alby-hub): self-custodial, best NWC support, multiple sub-wallets
• lncurl (https://lncurl.lol/llms.txt): custodial, agent-friendly, 1 sat/hour fee
• coinos (https://coinos.io): custodial, free to start
• rizful (https://rizful.com): custodial, multiple vaults, email verification required

procedure

1. check for wallet connection

inputs: check for NWC_URL env var, -w wallet name arg, -c connection secret arg, or ~/.alby-cli/connection-secret.key file

process: attempt resolution in order: explicit flag → env var → default file

outputs: connection secret available (silent pass) or missing (go to step 2)

---

2. if no connection, guide wallet setup

inputs: none available yet

process:

• inform user no wallet is connected
• suggest auth <wallet-url> if their wallet supports 1-click NWC (alby hub, lncurl, coinos, rizful all support this)
• or suggest connect "<nwc-url>" if they have a raw connection secret from their wallet
• never ask user to paste the secret in chat; tell them to use the flag or env var
• if user has no wallet yet, list the four options (alby hub, lncurl, coinos, rizful) with brief notes (self vs custodial, fees, features)

outputs: user either completes auth flow in browser, runs connect, or sets NWC_URL env var

---

3. run wallet command

inputs:

• command name (pay, receive, get-balance, list-transactions, get-info, get-wallet-service-info, get-budget, lookup-invoice, sign-message, wait-for-payment, list-wallets, make-hold-invoice, settle-hold-invoice, cancel-hold-invoice)
• command flags: always run npx -y @getalby/cli@0.8.0 <command> --help first to see exact flags before constructing the command
• optional: -w <wallet-name> to select a named wallet (preferred over -c for multi-wallet setups)
• optional: -c <file-or-url> to override connection secret source
• context from user request (amount, recipient, fiat currency, etc.)

process: construct command with flags from --help, execute via npx

outputs: command stdout (JSON, text table, or success message), or error (see decision points)

---

4. if pay/receive, handle fiat conversion if requested

inputs: user asked for amount in fiat (e.g. "$5", "€10")

process:

• include native fiat flag in pay or receive command (check --help for exact flag name)
• OR use standalone fiat-to-sats or sats-to-fiat command for currency lookup only
• when displaying fiat-converted amounts to user, avoid excessive decimal places (e.g. "0.00015 BTC" → ~$6.50 usd, not $6.497853)

outputs: command with fiat amount embedded, or sats/fiat lookup result

---

5. if user hits 402 Payment Required (or explicit paid API request)

inputs:

• either: unexpected 402 from unrelated task (stop and ask user first)
• or: user explicitly asked to fetch/consume paid resource (proceed directly)
• URL of the 402/paid resource
• optional: max spend cap (e.g. 10000 sats) to prevent overspend

process:

• if unexpected 402: inform user of URL and expected cost, ask for confirmation before paying
• if explicit request: use fetch command with optional -m/--max-spend flag to cap per-request cost
• fetch auto-detects L402, X402, and MPP payment protocols
• on success, return the fetched resource content and cost to user

outputs: fetched content and sats spent, or error if payment failed (see decision points)

---

6. if user asks to discover paid services

inputs: user asked to "find", "explore", or "discover" paid APIs; capability gap identified (e.g. image generation, specialized model, real-time feed)

process:

• run discover <keyword> (queries 402index.io)
• evaluate results: check price, health status, service description
• pick one or report top 3 to user with price
• if user approves, use fetch command on the returned service URL (step 5)

outputs: list of services with price and description, or fetched result after fetch

---

7. output results to user

inputs: command output (stdout/stderr), transaction hash, balance in sats, invoice string, etc.

process:

• for balance/amounts: display in "sats" (e.g. "21 sats", not "21 satoshis" or "0.00021 BTC")
• for fiat conversions: round reasonably (e.g. "$6.50", not "$6.4978531")
• for invoices: return the full BOLT-11 string or lightning address
• for transaction lists: format as table if multiple rows
• for paid API results: show both the fetched content and sats cost
• never print or log the connection secret or any part of it (pubkey, relay, etc.)

outputs: user-facing message with result data and next-step suggestions

---

decision points

if no connection secret found

• user never ran auth or connect: guide them through step 2 (wallet setup)
• file exists but is corrupted: ask them to re-run connect --force with a fresh secret
• env var set but invalid: tell them to check the NWC_URL value (must be nostr+walletconnect://...)

if connection timeout or wallet unreachable

• wallet is offline or relay is down: ask user to check wallet is online, then retry
• auth browser tab not completed: remind user to confirm in the browser window, then re-run the wallet command to finalize
• retry with exponential backoff (first retry after 1s, second after 3s) before giving up

if insufficient balance

• command failed with "insufficient balance" or similar: user needs to fund the wallet
• suggest deposit via lightning address or on-chain address (run receive to get it)
• do not attempt to pay with a partially-sufficient balance; abort and ask user to fund first

if 402 payment unexpectedly encountered during unrelated task

• do not pay automatically
• inform user of the URL and cost, ask for explicit approval before running fetch
• offer to search discover for a free alternative if one might exist

if 402 payment fails (invoice expired, amount mismatch, etc.)

• retry once after 3 seconds
• if retry fails, ask user to increase max-spend amount (-m) in case prices fluctuated
• if max-spend was already high, ask user to check wallet balance (get-balance) before retrying

if user asks to pay to a crypto address (0x..., bc1..., etc.)

• pay command auto-swaps from bitcoin balance to the target chain/token
• confirm swap fee with user before executing (check pay --help for fee disclosure flag)
• this works for USDC, USDT, ETH, and other tokens; edge case: some blockchains may not be supported (check pay --help)

if user explicitly requests hold invoices

• hold invoices require three separate commands: make-hold-invoice (create), settle-hold-invoice (accept), cancel-hold-invoice (reject)
• these are advanced; only use if user specifically asks for "escrow", "hold", or "conditional" invoices

if user asks for standalone lightning tools (no wallet needed)

• fiat-to-sats, sats-to-fiat, parse-invoice, verify-preimage, request-invoice-from-lightning-address do not need a connection secret
• safe to run even if wallet is not connected

if discover returns no results

• the service category may not exist on 402index.io or is not lightning-payable
• offer to try a different keyword or suggest user search 402index.io directly
• do not attempt to use a non-lightning service with fetch; it will fail

if user asks for help

• first resort: run npx -y @getalby/cli@0.8.0 --help or npx -y @getalby/cli@0.8.0 <command> --help to show exact flags and options
• last resort: direct user to https://getalby.com/help (alby support page)

output contract

success criteria for all wallet commands

• command exit code 0
• stdout contains either: JSON object (most commands), plain text (simple lookups), or structured table (list commands)
• connection secret is never printed or logged

for balance queries (get-balance)

• output: integer sats amount
• format in response: "your balance is X sats"

for invoices (receive, lookup-invoice, make-hold-invoice)

• output: BOLT-11 invoice string (long alphanumeric starting with lnbc, lntb, etc.)
• also return: lightning address if applicable

for pay operations (pay, settle-hold-invoice)

• output: transaction hash or preimage, timestamp, amount paid in sats, optional fiat equivalent
• file location: not applicable (results in stdout only)

for transactions (list-transactions)

• output: table or JSON array with columns: date, amount (sats), direction (in/out), status (completed/pending), description/invoice

for paid API fetch (fetch command)

• output: response body from the service (JSON, HTML, binary, etc.), plus one line summary: "paid X sats for this response"
• file location: returned in stdout; caller may redirect to file with > file.json if needed

for discover

• output: JSON array of services with: name, description, price (in sats), health status, endpoint URL

error contract (non-zero exit)

• stderr includes human-readable error message (e.g. "insufficient balance", "invalid invoice", "connection timeout")
• agent must parse and report this to user, then guide next steps (step 2, retry, fund wallet, etc.)

outcome signal

• user asked to pay / receive / check balance / list transactions: user sees the result (balance in sats, transaction list, invoice string, or confirmation of payment sent)
• user asked for fiat conversion: user sees sats and fiat amount side-by-side (e.g. "that's 10000 sats, about $2.50 usd")
• user asked to set up wallet: user sees confirmation that the connection is saved (e.g. "wallet connected! try 'show me my balance'")
• user hit a 402 Payment Required: user sees cost and result of the paid request, or confirmation of payment failure with retry guidance
• user asked to discover paid services: user sees top results with prices and links, or (if user picked one) sees the fetched content with cost
• error occurred: user sees a clear error message (e.g. "insufficient balance: you need 50000 sats but only have 10000") and next steps to resolve

---

Credits: original author getAlby; enriched per Implexa standards.