getalby/alby-agent-skill

Overview

This skill adds Bitcoin Lightning wallet capabilities to your app using Nostr Wallet Connect (NIP-47), LNURL, and WebLN. It provides endpoints and client utilities to send and receive payments, parse BOLT-11 invoices, verify preimages, and convert between BTC and fiat. It is designed to integrate with browser and server environments and to minimize hallucination by relying on typed APIs and test wallets.

How this skill works

The skill exposes a client for Nostr Wallet Connect to connect, request invoices, pay invoices, listen for payment notifications, and fetch wallet balance and transaction history. It also provides Lightning Tools for parsing BOLT-11 invoices, verifying preimages, handling LNURL flows, querying lightning addresses, and performing BTC↔fiat conversions. Browser UI components are available for quick integration (React, Vue, or plain HTML) to connect wallets and accept payments.

When to use it

• Add send/receive Lightning payments to web or server apps using NWC, LNURL, or WebLN
• Parse and validate BOLT-11 invoices and confirm payment preimages for settlement logic
• Implement hold invoices and conditional settlement workflows (HOLD invoices)
• Build wallet connection flows and in-browser payment acceptance with minimal frontend work
• Automate testing of payment flows using dedicated testing wallets and self-tests

Best practices

• Prefer TypeScript for client and server code to use the provided typings and avoid API misuse
• Use testing wallets for automated tests so the agent can run and validate payment flows
• Avoid importing from dist directories; import from the package entrypoints and read type definitions
• Handle user consent and explicit wallet connect prompts in browser flows to maintain security
• Validate and verify BOLT-11 invoices and preimages on the server before marking orders fulfilled

Example use cases

• A checkout flow that requests an invoice, displays it in the browser, listens for on-chain/Lightning confirmations, and settles an order only after preimage verification
• A subscription service that charges periodic Lightning invoices and reconciles transactions using the wallet transaction list
• A tipping widget that queries a lightning address, requests an invoice via LNURL, and accepts payments via WebLN
• A merchant portal that displays wallet balance, recent transactions, and performs BTC-to-fiat conversions for reporting
• Automated CI that uses testing wallets to validate payment logic and fixes failures without manual intervention