Setting Up Alby Hub for SatsRail: Your Lightning Wallet Connection

Why Alby Hub?

SatsRail is non-custodial. We never touch your money. But we need a way to generate Lightning invoices and detect when they get paid. That's where Alby Hub comes in.

Alby Hub is an open-source Lightning wallet that runs on your machine and connects to SatsRail through a standard protocol called NWC (Nostr Wallet Connect). It does two critical things for your integration:

1. Generates invoices — When a customer clicks "Pay," SatsRail asks your Alby Hub to create a Lightning invoice with the right amount
2. Confirms payments — Alby Hub listens for incoming transactions and tells SatsRail when an invoice has been paid

No Alby Hub, no invoices. No invoices, no payments. It needs to be running.

Download & Install

Alby Hub is available for all major platforms:

→ Download at getalby.com/hub

Choose your platform:

• macOS — .dmg installer
• Windows — .exe installer
• Linux — AppImage, .deb, or Docker
• Raspberry Pi — ARM builds available
• Umbrel / Start9 — Available as a one-click app in their stores

Cloud Option

If you don't want to run hardware, Alby offers a hosted version at albyhub.com. Same functionality, they handle the infrastructure. Good for getting started quickly.

Setup Steps

1. Install and open Alby Hub
2. Create a new wallet or connect an existing Lightning node (LND, Core Lightning, etc.)
3. Fund your wallet — You'll need some inbound liquidity to receive payments. Alby Hub can help you open channels.
4. Generate an NWC connection string — Go to Settings → Connections → Create New Connection
5. Copy the NWC URL — It looks like nostr+walletconnect://...
6. Paste it into SatsRail — In your SatsRail merchant dashboard under Wallet Settings, paste the NWC connection string

That's it. SatsRail will use this connection to request invoices and listen for payments.

Keep It Running

This is the most important part: Alby Hub must be running for your SatsRail integration to work.

Here's what happens when a customer pays:

1. Customer clicks your SatsRail payment button
2. SatsRail connects to your Alby Hub via NWC
3. Alby Hub generates a Lightning invoice
4. Customer pays the invoice
5. Alby Hub detects the payment and notifies SatsRail
6. SatsRail marks the order as paid

If Alby Hub is offline at step 2, SatsRail can't generate an invoice — the checkout fails. If it goes offline between steps 3 and 5, the payment confirmation may be delayed.

Best practices:

• Run Alby Hub on a machine that stays on (desktop, server, Raspberry Pi, or cloud)
• Enable "Start on boot" / auto-launch so it survives restarts
• If using the Alby Cloud option, this is handled for you
• Check your Alby Hub periodically to make sure channels are healthy and you have inbound liquidity

Troubleshooting

Checkout says "Unable to generate invoice"
→ Alby Hub is likely offline or the NWC connection expired. Open Alby Hub, check it's running, and verify the connection in SatsRail dashboard.

Payment stuck on "Waiting for payment"
→ The invoice was generated but Alby Hub may have gone offline before confirming. Restart Alby Hub — it will sync and pick up the payment.

"Insufficient inbound liquidity"
→ Your Lightning channels don't have enough capacity to receive payments. Open a new channel or use Alby Hub's liquidity tools to get more inbound capacity.

What's Next

We're building toward supporting more wallet backends in future phases — including managed Lightning nodes that remove the need to run your own infrastructure. But right now, Alby Hub is the integration point, and it works great.

If you haven't already, create your SatsRail account and connect your Alby Hub:

→ Get started at satsrail.com

SatsRail is non-custodial Bitcoin payment infrastructure. Your keys, your money, no middleman.