Alby NWC CLI

CLI for Nostr Wallet Connect (NIP-47) with lightning tools.

Built for agents - use with the Alby Bitcoin Payments CLI Skill

Usage

# Pass a file path to a connection secret (preferred)
npx @getalby/cli -c /path/to/secret.txt <command> [options]

# Or pass connection string directly
npx @getalby/cli -c "nostr+walletconnect://..." <command> [options]

The -c option auto-detects whether you're passing a connection string or a file path. You can get a connection string from your NWC-compatible wallet (e.g., Alby).

You can also pass a connection string via the NWC_URL environment variable instead of using the -c option:

NWC_URL="nostr+walletconnect://..."

Testing Wallet

For testing the CLI without using real funds, you can create a test wallet using the NWC Faucet:

curl -X POST "https://faucet.nwc.dev?balance=10000"

This returns a connection string for a test wallet with 10,000 sats. Test wallets can send payments to each other but cannot interact with the real lightning network.

To top up an existing test wallet:

curl -X POST "https://faucet.nwc.dev/wallets/<username>/topup?amount=5000"

Commands

Wallet Commands

These commands require --connection-secret:

# Get wallet balance
npx @getalby/cli -c "nostr+walletconnect://..." get-balance

# Get wallet info
npx @getalby/cli -c "nostr+walletconnect://..." get-info

# Get wallet service capabilities
npx @getalby/cli -c "nostr+walletconnect://..." get-wallet-service-info

# Create an invoice
npx @getalby/cli -c "nostr+walletconnect://..." make-invoice --amount 1000 --description "Payment"

# Pay an invoice
npx @getalby/cli -c "nostr+walletconnect://..." pay-invoice --invoice "lnbc..."

# Send a keysend payment
npx @getalby/cli -c "nostr+walletconnect://..." pay-keysend --pubkey "02abc..." --amount 100

# Look up an invoice by payment hash
npx @getalby/cli -c "nostr+walletconnect://..." lookup-invoice --payment-hash "abc123..."

# List transactions
npx @getalby/cli -c "nostr+walletconnect://..." list-transactions --limit 10

# Get wallet budget
npx @getalby/cli -c "nostr+walletconnect://..." get-budget

# Sign a message
npx @getalby/cli -c "nostr+walletconnect://..." sign-message --message "Hello, World!"

# Fetch L402-protected resource
npx @getalby/cli -c "nostr+walletconnect://..." fetch-l402 --url "https://example.com/api"

# Wait for a payment notification
npx @getalby/cli -c "nostr+walletconnect://..." wait-for-payment --payment-hash "abc123..."

HOLD Invoices

HOLD invoices allow you to accept payments conditionally - the payment is held until you settle or cancel it.

# Create a HOLD invoice (you provide the payment hash)
npx @getalby/cli -c "nostr+walletconnect://..." make-hold-invoice --amount 1000 --payment-hash "abc123..."

# Settle a HOLD invoice (claim the payment)
npx @getalby/cli -c "nostr+walletconnect://..." settle-hold-invoice --preimage "def456..."

# Cancel a HOLD invoice (reject the payment)
npx @getalby/cli -c "nostr+walletconnect://..." cancel-hold-invoice --payment-hash "abc123..."

Lightning Tools

These commands don't require a wallet connection:

# Convert USD to sats
npx @getalby/cli fiat-to-sats --currency USD --amount 10

# Convert sats to USD
npx @getalby/cli sats-to-fiat --amount 1000 --currency USD

# Parse a BOLT-11 invoice
npx @getalby/cli parse-invoice --invoice "lnbc..."

# Verify a preimage against an invoice
npx @getalby/cli verify-preimage --invoice "lnbc..." --preimage "abc123..."

# Request invoice from lightning address
npx @getalby/cli request-invoice-from-lightning-address --address "[email protected]" --amount 1000

Command Reference

Wallet Commands

These require -c or --connection-secret:

| Command | Description | Required Options | | ------------------------- | ------------------------------ | ------------------------------- | | get-balance | Get wallet balance | - | | get-info | Get wallet info | - | | get-wallet-service-info | Get wallet capabilities | - | | get-budget | Get wallet budget | - | | make-invoice | Create a lightning invoice | --amount | | pay-invoice | Pay a lightning invoice | --invoice | | pay-keysend | Send a keysend payment | --pubkey, --amount | | lookup-invoice | Look up an invoice | --payment-hash or --invoice | | list-transactions | List transactions | - | | sign-message | Sign a message with wallet key | --message | | wait-for-payment | Wait for payment notification | --payment-hash | | fetch-l402 | Fetch L402-protected resource | --url |

HOLD Invoice Commands

These require -c or --connection-secret:

| Command | Description | Required Options | | --------------------- | --------------------- | ---------------------------- | | make-hold-invoice | Create a HOLD invoice | --amount, --payment-hash | | settle-hold-invoice | Settle a HOLD invoice | --preimage | | cancel-hold-invoice | Cancel a HOLD invoice | --payment-hash |

Lightning Tools

These don't require a wallet connection:

| Command | Description | Required Options | | ---------------------------------------- | -------------------------------------- | ------------------------- | | fiat-to-sats | Convert fiat to sats | --currency, --amount | | sats-to-fiat | Convert sats to fiat | --amount, --currency | | parse-invoice | Parse a BOLT-11 invoice | --invoice | | verify-preimage | Verify preimage against invoice | --invoice, --preimage | | request-invoice-from-lightning-address | Request invoice from lightning address | --address, --amount |

Output

All commands output JSON to stdout. Errors are output to stderr as JSON with an error field.