lightning-bitcoin-query

Lightning-fast Bitcoin blockchain queries with automatic micropayments

Query Bitcoin mempool, fees, transactions, and addresses using the Lightning Network for instant micropayments. Pay only for what you use - no API keys, no subscriptions.

Features

✅ Pay-per-query - Pay 10-50 sats per request via Lightning Network
✅ No API keys - Automatic L402 payment authentication
✅ Real-time data - Live mempool monitoring and fee estimation
✅ Smart caching - Avoid repaying for same data within TTL
✅ Zero setup - Works out of the box with any Lightning wallet

Installation

npm install lightning-bitcoin-query

Quick Start

const BitcoinQuery = require('lightning-bitcoin-query');

// Initialize with your Lightning wallet NWC URI
const bitcoin = new BitcoinQuery({
  nwcUri: 'nostr+walletconnect://...' // Your Nostr Wallet Connect URI
});

// Get current mempool status (10 sats)
const mempool = await bitcoin.getMempool();
console.log('Pending transactions:', mempool.count);
console.log('Total fees:', mempool.total_fee);

// Get recommended fees (10 sats)
const fees = await bitcoin.getFees();
console.log('Next block fee:', fees.fastestFee, 'sat/vB');

// Get transaction details (20 sats)
const tx = await bitcoin.getTransaction('txid_here');
console.log('Confirmations:', tx.status.confirmed);

// Get address balance (20 sats)
const address = await bitcoin.getAddressBalance('bc1q...');
console.log('Balance:', address.chain_stats.funded_txo_sum, 'sats');

API Reference

new BitcoinQuery(options)

Initialize the client with Lightning wallet connection.

Options:

• nwcUri (string) - Your Nostr Wallet Connect URI from Alby, Mutiny, or other NWC wallet

getMempool()

Get current mempool status. Cost: 10 sats

Returns: { count, vsize, total_fee, fee_histogram }

getFees()

Get recommended transaction fees. Cost: 10 sats

Returns: { fastestFee, halfHourFee, hourFee, economyFee, minimumFee }

getTransaction(txid)

Get transaction details by ID. Cost: 20 sats

Returns: Transaction object with confirmations, inputs, outputs, fees

getAddressBalance(address)

Get address balance and transaction history. Cost: 20 sats

Returns: Address stats with funded/spent totals and transaction list

How It Works

1. You make a query - Call any method like getMempool()
2. L402 challenge - API returns 402 Payment Required with Lightning invoice
3. Auto payment - Your Lightning wallet automatically pays the invoice (10-50 sats)
4. Data returned - Authenticated request retrieves your data
5. Smart caching - Payment hash cached for 5 minutes to avoid repayment

Get NWC URI

Alby: https://getalby.com → Settings → Nostr Wallet Connect → Create new connection
Mutiny: https://app.mutinywallet.com → Settings → Connections → Nostr Wallet Connect
Phoenix: Settings → Lightning address → Show connection string

Pricing

• Mempool status: 10 sats (~$0.01)
• Fee estimation: 10 sats (~$0.01)
• Transaction lookup: 20 sats (~$0.02)
• Address balance: 20 sats (~$0.02)

No subscriptions. No minimums. Pay only for what you use.

Why Micropayments?

Traditional API providers charge $29-199/month for unlimited requests. Most developers only need a few queries per day. Why pay for unused quota?

With Lightning micropayments:

• 1,000 mempool checks = 10,000 sats = $9 (vs $29/month minimum)
• No credit card required
• No rate limits
• No API key management
• Works worldwide instantly

License

MIT

Support

• API Status: http://138.197.6.58:3000/health
• Issues: https://github.com/yourusername/lightning-bitcoin-query/issues
• Lightning Node: ⚡ seaadventurous413599@getalby.com