https://github.com/bob6664569/phoenixd-client
Node.js TypeScript client for the phoenixd Lightning API
https://github.com/bob6664569/phoenixd-client
api-client bitcoin client javascript lightning-network nodejs npm
Last synced: 5 months ago
JSON representation
Node.js TypeScript client for the phoenixd Lightning API
- Host: GitHub
- URL: https://github.com/bob6664569/phoenixd-client
- Owner: bob6664569
- License: mit
- Created: 2025-07-29T19:41:14.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-07-29T19:53:31.000Z (11 months ago)
- Last Synced: 2025-07-29T20:44:11.805Z (11 months ago)
- Topics: api-client, bitcoin, client, javascript, lightning-network, nodejs, npm
- Language: TypeScript
- Homepage:
- Size: 0 Bytes
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# phoenixd-client
A Node.js TypeScript client for the [phoenixd](https://github.com/ACINQ/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](https://phoenix.acinq.co/server) 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
```bash
npm install phoenixd-client
```
## Quick Start
```typescript
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
```typescript
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
```typescript
const invoice = await client.createInvoice({
description: 'Payment for services',
amountSat: 5000,
expirySeconds: 3600,
externalId: 'order-123',
webhookUrl: 'https://your-webhook.com/payment'
});
```
#### Pay Invoice
```typescript
const payment = await client.payInvoice({
invoice: 'lntb1u1pjlsjnqpp57svjqly7mh5sy84lk67sma4apfnqdm90jdf40np0xchrpq6uxajscqpjsp592kp0fs2ssgpq9h54tsfaj5w34287v8fezgaw6cr56f076c05glq9q7sqqqqqqqqqqqqqqqqqqqsqqqqqysgqdq6d4ujqenfwfehggrfdemx76trv5mqz9grzjqwfn3p9278ttzzpe0e00uhyxhned3j5d9acqak5emwfpflp8z2cnflcyamh4dcuhwqqqqqlgqqqqqeqqjqnjpjvnv0p3wvwc6vhzkkgm8kl9r837x4p9qupk5ln5tqlm7prrlsy5xd8cf5agae64f53dvm9el0z5hvgcnta4stgmrg7zwfah0nqrqph4ts8l'
});
```
### Offers (BOLT12)
#### Create Offer
```typescript
const offer = await client.createOffer({
description: 'Donation for the project',
amountSat: 1000
});
```
#### Pay Offer
```typescript
const payment = await client.payOffer({
offer: 'lno1qgsyxjtl6luzd9t3pr62xr7eemp6awnejusgf6gw45q75vcfqqqqqqqgqvqcdgq2zdskugr0venx2u3qvehhygzsd9jhyun9zrhq8yecsj40r443pquhuhh7tjrteukce2xj7uqwm2vahys5lsn39vf5q2fyfxsw6xn824393en87nre87xcectkgcj85trcu5hn9r9703645qsrxtcq785whraquh5atw89w5scg707fz23405ygk7jn9uek3tkmvdqqvc8yz8xm2yme6hjx3x02csmq6pfzaejqr3kzg7u8am96txu95z8am8zgvfvfcnzk27ylwk43ut48xv2vrkhqtj3wes32glw5ft5h7f4p8ytwey4cqjsks55zcmr3hka0p8e50thjqpjytmt5wsa4ylhavdmewv7jmj2ppy9daujfmfvpmnw9cf75cymjffzh2nafn883vsqr3a8u2l797mayh3p',
amountSat: 1000,
message: 'Thank you for your work!'
});
```
### Lightning Address
#### Pay Lightning Address
```typescript
const payment = await client.payLnAddress({
address: 'alice@lightning.com',
amountSat: 500,
message: 'For lunch'
});
```
### Payments
#### List Incoming Payments
```typescript
const payments = await client.listIncomingPayments({
limit: 10,
offset: 0,
all: true
});
```
#### List Outgoing Payments
```typescript
const payments = await client.listOutgoingPayments({
limit: 10,
offset: 0,
all: true
});
```
#### Get Specific Payment
```typescript
const payment = await client.getIncomingPayment('payment_hash_here');
const outgoingPayment = await client.getOutgoingPayment('payment_id_here');
```
### Node Information
#### Get Node Info
```typescript
const info = await client.getInfo();
console.log('Node ID:', info.nodeId);
console.log('Channels:', info.channels);
```
#### Get Balance
```typescript
const balance = await client.getBalance();
console.log('Balance:', balance.balanceSat, 'sats');
console.log('Fee Credit:', balance.feeCreditSat, 'sats');
```
#### List Channels
```typescript
const channels = await client.listChannels();
channels.forEach(channel => {
console.log('Channel:', channel.channelId, 'Balance:', channel.balanceSat);
});
```
### On-chain Operations
#### Send to Address
```typescript
const txId = await client.sendToAddress({
amountSat: 100000,
address: 'bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh',
feerateSatByte: 12
});
```
#### Bump Fee
```typescript
const childTxId = await client.bumpFee({
feerateSatByte: 15
});
```
### LNURL Operations
#### LNURL Pay
```typescript
const payment = await client.lnUrlPay({
amountSat: 1000,
lnurl: 'LNURL1DP68GURN8GHJ7MRWW4EXCTNXD9SHG6NPVCHXXMMD9AKXUATJDSKHQCTE8AEK2UMND9HKU0TZV9JR2VM9XV6RVV3JVSUNWDRYXUCNVDFHV43KVE3KXQCRJDFHX33XGDENX9NRSVTRXCENVC3KV33NGWR9XQURWC3N8YEN2WP4V4JNZV8XSUH',
message: 'Payment for service'
});
```
#### LNURL Withdraw
```typescript
const withdraw = await client.lnUrlWithdraw({
lnurl: 'lightning:LNURL1DP68GURN8GHJ7MRWW4EXCTNXD9SHG6NPVCHXXMMD9AKXUATJDSKHW6T5DPJ8YCTH8AEK2UMND9HKU0T9893XYVF5XQMX2EP4VYCNJWR9X56RSCEE893NYVP3VC6KGEPNX5UNGDFCV9NRJDNXXCMNXENZXPJXVCFS89NRWVFJXYCNXD3K89JNGAXMZVT'
});
```
#### LNURL Auth
```typescript
const result = await client.lnUrlAuth({
lnurl: 'lnurl1dp68gurn8ghj7um5v93kketj9ehx2amn9ashq6f0d3hxzat5dqlhgct884kx7emfdcnxkvfav3nxxcehxyckvdrpxsexyden8qexywrpv33nvdmpxsukzdpnvgungct9xesnvcf3x9jnsenxvvurvcmzvd3rwdfevgmnwdpjxp3nqvg50j329'
});
```
### Utilities
#### Decode Invoice
```typescript
const decoded = await client.decodeInvoice({
invoice: 'lntb1u1pjlsjnqpp57svjqly7mh5sy84lk67sma4apfnqdm90jdf40np0xchrpq6uxajscqpjsp592kp0fs2ssgpq9h54tsfaj5w34287v8fezgaw6cr56f076c05glq9q7sqqqqqqqqqqqqqqqqqqqsqqqqqysgqdq6d4ujqenfwfehggrfdemx76trv5mqz9grzjqwfn3p9278ttzzpe0e00uhyxhned3j5d9acqak5emwfpflp8z2cnflcyamh4dcuhwqqqqqlgqqqqqeqqjqnjpjvnv0p3wvwc6vhzkkgm8kl9r837x4p9qupk5ln5tqlm7prrlsy5xd8cf5agae64f53dvm9el0z5hvgcnta4stgmrg7zwfah0nqrqph4ts8l'
});
```
#### Estimate Liquidity Fees
```typescript
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:
```typescript
// 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
```typescript
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
```bash
# 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:
1. Check the [phoenixd documentation](https://github.com/ACINQ/phoenixd)
2. Open an issue on [GitHub](https://github.com/bob6664569/phoenixd-client/issues)
3. Review the examples in the `examples/` directory
## Related Projects
- [phoenixd](https://github.com/ACINQ/phoenixd) - The official phoenixd server
- [phoenix.acinq.co/server](https://phoenix.acinq.co/server) - Official phoenixd website