Alby Bitcoin Payments Agent Skill

Build lightning apps with your favorite agent, without hallucinations or even needing a wallet setup.

Before you start, try Alby Sandbox to see what you can build!

This repository contains an agent skill that helps agents use the Alby JS SDK and Alby Lightning Tools.

Getting Started

🚀 Install with single command

npx skills add getAlby/alby-agent-skill

Manual Install

Download this repository and extract it, then follow instructions for your specific agent.

Double check the skill is activated by asking your agent "What Skills are available?". It should include "Alby Agent Skill"

Claude Code

Make a .claude/skills folder in your project and put the extracted skills folder there (see other options)

Gemini CLI

Make a .gemini/skills folder in your project and put the extracted skills folder there (see other options)

Roo Code

Make a .roo/skills folder in your project and put the extracted skills folder there (see other options)

Test / Dummy Wallets

Alby Agent skill has the knowledge to create dummy wallets for testing. You can build and test your app end-to-end without creating a wallet. Once you are ready, the agent skill can also help you setup a wallet to use in production.

Example prompts

Explore more prompts in the Alby Sandbox

Console Apps

Listen to received payments and send a payment to a lightning address with USD amounts

Create a Typescript console app that when receives a notification of an incoming payment, sends $0.10 USD to [email protected]. The NWC_URL is in the .env file.

Conditionally receive payments (NOTE: only supported by Alby Hub)

Create a Typescript console app that creates a hold invoice of $1 and asks the user to provide a lightning address and choose heads or tails. Once the hold invoice is accepted, flip a coin. If the user guessed correctly, cancel the hold invoice and pay the user $1 to their lightning address. If the user guessed incorrectly, settle the hold invoice. The NWC_URL is in the .env file.

Frontend Apps

Streamer QR page with payment notifications

Create a single page HTML app that listens to incoming payments, and each time one comes in, shows a confetti animation and the payment amount and message. It should also have a QR code of the receiving lightning address that should be displayed on the corner of the screen so people watching can easily send payments. When I first open the page it should prompt me for a NWC connection secret so it can connect to my wallet to listen for payments, and also extract the lightning address from the NWC connection secret for the QR code.

Testing

Example test for a backend or console app

Create a Typescript console app where Alice creates an invoice and Bob pays it. Write tests for it using jest.

Example test for a frontend app (vitest + Playwright)

Create a Vite Typescript React app where a user can connect their wallet and then purchase fake cat pictures (simple canvas art) with a single click. Each picture costs 5000 sats. Show the total the shop has earned and their remaining stock of cat pictures. There should only be 21. Write tests for the app using vitest and playwright. Also take screenshots and review the screenshots.

Development

Examples are hand-written, but lack the necessary typing information. Types are copied directly from the referenced projects using this script