JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 211
  • Score
    100M100P100Q69162F
  • License MIT

CLI for Nostr Wallet Connect (NIP-47) with a few additional useful lightning tools

Package Exports

  • @getalby/cli
  • @getalby/cli/build/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@getalby/cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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 "hello@getalby.com" --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.