phoenixd-client

phoenixd-client

A Node.js TypeScript client for the phoenixd Lightning API. This package provides a complete interface to interact with phoenixd Lightning nodes, including creating invoices, making payments, managing channels, and real-time notifications.

phoenixd is the server equivalent of the popular Phoenix wallet for mobile, written in Kotlin Multiplatform and running natively on Linux, MacOS, and Windows.

Features

• 🔌 Complete TypeScript support with full type definitions
• 💰 Create and pay Lightning invoices (BOLT11)
• 🎯 Create and pay Lightning offers (BOLT12)
• 📧 Lightning address payments
• 🔗 LNURL support (pay, withdraw, auth)
• 📊 Payment history and export
• 🌐 Real-time WebSocket notifications
• 🔐 Secure authentication
• 🛡️ Error handling and validation

Installation

npm install phoenixd-client

Quick Start

import { PhoenixdClient } from 'phoenixd-client';

// Initialize the client
const client = new PhoenixdClient({
  host: 'localhost',
  port: 9740,
  password: 'your_phoenixd_password',
  useHttps: false
});

// Create an invoice
const invoice = await client.createInvoice({
  description: 'Coffee payment',
  amountSat: 1000,
  expirySeconds: 3600
});

console.log('Invoice created:', invoice.serialized);

Configuration

interface PhoenixdConfig {
  host?: string;        // Default: 'localhost'
  port?: number;        // Default: 9740
  password: string;     // Required: Your phoenixd API password
  useHttps?: boolean;   // Default: false
  timeout?: number;     // Default: 30000ms
}

API Reference

Invoices

Create Invoice

const invoice = await client.createInvoice({
  description: 'Payment for services',
  amountSat: 5000,
  expirySeconds: 3600,
  externalId: 'order-123',
  webhookUrl: 'https://your-webhook.com/payment'
});

Pay Invoice

const payment = await client.payInvoice({
  invoice: 'lntb1u1pjlsjnqpp57svjqly7mh5sy84lk67sma4apfnqdm90jdf40np0xchrpq6uxajscqpjsp592kp0fs2ssgpq9h54tsfaj5w34287v8fezgaw6cr56f076c05glq9q7sqqqqqqqqqqqqqqqqqqqsqqqqqysgqdq6d4ujqenfwfehggrfdemx76trv5mqz9grzjqwfn3p9278ttzzpe0e00uhyxhned3j5d9acqak5emwfpflp8z2cnflcyamh4dcuhwqqqqqlgqqqqqeqqjqnjpjvnv0p3wvwc6vhzkkgm8kl9r837x4p9qupk5ln5tqlm7prrlsy5xd8cf5agae64f53dvm9el0z5hvgcnta4stgmrg7zwfah0nqrqph4ts8l'
});

Offers (BOLT12)

Create Offer

const offer = await client.createOffer({
  description: 'Donation for the project',
  amountSat: 1000
});

Pay Offer

const payment = await client.payOffer({
  offer: 'lno1qgsyxjtl6luzd9t3pr62xr7eemp6awnejusgf6gw45q75vcfqqqqqqqgqvqcdgq2zdskugr0venx2u3qvehhygzsd9jhyun9zrhq8yecsj40r443pquhuhh7tjrteukce2xj7uqwm2vahys5lsn39vf5q2fyfxsw6xn824393en87nre87xcectkgcj85trcu5hn9r9703645qsrxtcq785whraquh5atw89w5scg707fz23405ygk7jn9uek3tkmvdqqvc8yz8xm2yme6hjx3x02csmq6pfzaejqr3kzg7u8am96txu95z8am8zgvfvfcnzk27ylwk43ut48xv2vrkhqtj3wes32glw5ft5h7f4p8ytwey4cqjsks55zcmr3hka0p8e50thjqpjytmt5wsa4ylhavdmewv7jmj2ppy9daujfmfvpmnw9cf75cymjffzh2nafn883vsqr3a8u2l797mayh3p',
  amountSat: 1000,
  message: 'Thank you for your work!'
});

Lightning Address

Pay Lightning Address

const payment = await client.payLnAddress({
  address: '[e-mail]',
  amountSat: 500,
  message: 'For lunch'
});

Payments

List Incoming Payments

const payments = await client.listIncomingPayments({
  limit: 10,
  offset: 0,
  all: true
});

List Outgoing Payments

const payments = await client.listOutgoingPayments({
  limit: 10,
  offset: 0,
  all: true
});

Get Specific Payment

const payment = await client.getIncomingPayment('payment_hash_here');
const outgoingPayment = await client.getOutgoingPayment('payment_id_here');

Node Information

Get Node Info

const info = await client.getInfo();
console.log('Node ID:', info.nodeId);
console.log('Channels:', info.channels);

Get Balance

const balance = await client.getBalance();
console.log('Balance:', balance.balanceSat, 'sats');
console.log('Fee Credit:', balance.feeCreditSat, 'sats');

List Channels

const channels = await client.listChannels();
channels.forEach(channel => {
  console.log('Channel:', channel.channelId, 'Balance:', channel.balanceSat);
});

On-chain Operations

Send to Address

const txId = await client.sendToAddress({
  amountSat: 100000,
  address: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
  feerateSatByte: 12
});

Bump Fee

const childTxId = await client.bumpFee({
  feerateSatByte: 15
});

LNURL Operations

LNURL Pay

const payment = await client.lnUrlPay({
  amountSat: 1000,
  lnurl: 'LNURL1DP68GURN8GHJ7MRWW4EXCTNXD9SHG6NPVCHXXMMD9AKXUATJDSKHQCTE8AEK2UMND9HKU0TZV9JR2VM9XV6RVV3JVSUNWDRYXUCNVDFHV43KVE3KXQCRJDFHX33XGDENX9NRSVTRXCENVC3KV33NGWR9XQURWC3N8YEN2WP4V4JNZV8XSUH',
  message: 'Payment for service'
});

LNURL Withdraw

const withdraw = await client.lnUrlWithdraw({
  lnurl: 'lightning:LNURL1DP68GURN8GHJ7MRWW4EXCTNXD9SHG6NPVCHXXMMD9AKXUATJDSKHW6T5DPJ8YCTH8AEK2UMND9HKU0T9893XYVF5XQMX2EP4VYCNJWR9X56RSCEE893NYVP3VC6KGEPNX5UNGDFCV9NRJDNXXCMNXENZXPJXVCFS89NRWVFJXYCNXD3K89JNGAXMZVT'
});

LNURL Auth

const result = await client.lnUrlAuth({
  lnurl: 'lnurl1dp68gurn8ghj7um5v93kketj9ehx2amn9ashq6f0d3hxzat5dqlhgct884kx7emfdcnxkvfav3nxxcehxyckvdrpxsexyden8qexywrpv33nvdmpxsukzdpnvgungct9xesnvcf3x9jnsenxvvurvcmzvd3rwdfevgmnwdpjxp3nqvg50j329'
});

Utilities

Decode Invoice

const decoded = await client.decodeInvoice({
  invoice: 'lntb1u1pjlsjnqpp57svjqly7mh5sy84lk67sma4apfnqdm90jdf40np0xchrpq6uxajscqpjsp592kp0fs2ssgpq9h54tsfaj5w34287v8fezgaw6cr56f076c05glq9q7sqqqqqqqqqqqqqqqqqqqsqqqqqysgqdq6d4ujqenfwfehggrfdemx76trv5mqz9grzjqwfn3p9278ttzzpe0e00uhyxhned3j5d9acqak5emwfpflp8z2cnflcyamh4dcuhwqqqqqlgqqqqqeqqjqnjpjvnv0p3wvwc6vhzkkgm8kl9r837x4p9qupk5ln5tqlm7prrlsy5xd8cf5agae64f53dvm9el0z5hvgcnta4stgmrg7zwfah0nqrqph4ts8l'
});

Estimate Liquidity Fees

const fees = await client.estimateLiquidityFees(2000000);
console.log('Mining fee:', fees.miningFeeSat, 'sats');
console.log('Service fee:', fees.serviceFeeSat, 'sats');

Real-time Notifications

The client extends EventEmitter and provides WebSocket support for real-time payment notifications:

// Listen for payment events
client.on('payment_received', (event) => {
  console.log('Payment received:', event.amountSat, 'sats');
  console.log('Payment hash:', event.paymentHash);
});

// Connect to WebSocket
const ws = client.connectWebSocket();

// Handle WebSocket events
client.on('websocket_closed', () => {
  console.log('WebSocket connection closed');
});

client.on('error', (error) => {
  console.error('Client error:', error);
});

Error Handling

try {
  const invoice = await client.createInvoice({
    description: 'Test invoice',
    amountSat: 1000
  });
} catch (error) {
  if (error instanceof Error) {
    console.error('Failed to create invoice:', error.message);
  }
}

Security

⚠️ Important Security Notes:

• The phoenixd API gives access to your funds
• Always use HTTPS in production
• Never expose the API to the internet
• Keep your API password secure
• Use the limited access password when possible

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions:

• Check the phoenixd documentation
• Open an issue on GitHub
• Review the examples in the examples/ directory

Related Projects

• phoenixd - The official phoenixd server
• phoenix.acinq.co/server - Official phoenixd website