• 1. What Is phoenixd and Why Use It?
  • Key Features
  • Use Cases
• 2. Installation & Basic Setup
  • Step 1: Download & Run phoenixd
  • Step 2: Secure Your Seed & API Password
  • Step 3: Configure for Mainnet or Testnet
• 3. Automated Liquidity Management
  • How It Works
  • Checking Fees
  • Manual Channel Management (Optional)
• 4. Using the HTTP API for Payments
  • Authentication
  • Key API Endpoints
  • Example: Receiving a Payment
  • Example: Sending a Payment
  • Modern Standards: Bolt12 & LNURL
• 5. Adding a User Interface (Optional)
  • Example: Connecting LNbits to phoenixd
• 6. phoenixd vs. Phoenix Wallet: Which Should You Use?
  • When to Use phoenixd
  • When to Use Phoenix Wallet
• 7. Advanced Tips & Tricks
  • Optimizing for Low Fees
  • Backup & Recovery
  • Security Best Practices
  • Monitoring & Alerts
• 8. Real-World Use Cases
  • Case Study 1: E-Commerce Store
  • Case Study 2: Podcaster (Value4Value)
  • Case Study 3: Self-Hosted Lightning Node
• 9. Troubleshooting Common Issues
• 10. Future of phoenixd & Lightning
  • How to Stay Updated
• Final Thoughts: Is phoenixd Right for You?
  • Next Steps
  • Further Reading & Resources
  • Start Building A Project With Whatever You Have

While the Phoenix Wallet mobile app provides a user-friendly interface, its server-side counterpart, phoenixd, offers a headless, API-driven Lightning node designed for automation, 24/7 uptime, and programmatic control.

Unlike the mobile app, phoenixd is optimized for servers, automated payments, and liquidity management, making it ideal for: ✅ E-commerce businesses accepting Lightning payments ✅ Developers building Lightning-powered applications ✅ Self-hosters running personal Lightning nodes ✅ Content creators monetizing via Value4Value (V4V) streams

In this guide, we’ll cover:

1. What phoenixd is and why you’d use it
2. Step-by-step installation & setup
3. Automated liquidity management
4. Using the HTTP API for payments
5. Adding a UI (LNbits, Zeus, StartOS)
6. Comparison: phoenixd vs. Phoenix Wallet

§1. What Is phoenixd and Why Use It?

phoenixd is a headless Lightning Network node developed by ACINQ, the team behind the Phoenix Wallet. While the mobile app is designed for casual users, phoenixd is built for:

• 24/7 uptime (critical for receiving payments)
• Automated liquidity management (no manual channel rebalancing)
• Programmatic control via HTTP API (ideal for developers)
• Server deployment (Linux, Docker, or bare metal)

§Key Features

§Use Cases

🔹 E-commerce stores (accept Lightning payments without custodial risk) 🔹 Self-hosted Lightning nodes (for sovereignty and privacy) 🔹 Automated micropayments (e.g., API-based tipping, paywalls) 🔹 Value4Value (V4V) streaming (Podcasting 2.0, content monetization) 🔹 Lightning Network development (testing, building apps)

§2. Installation & Basic Setup

§Step 1: Download & Run phoenixd

phoenixd is available for Linux, macOS, and Windows (though Linux is recommended for servers).

§Linux/macOS (Terminal)

1. Download the latest release from GitHub Releases.
2. Extract the archive:

   tar -xzf phoenixd-<version>.tar.gz
   cd phoenixd-<version>
   

3. Run the daemon:

   ./phoenixd
   

   (First run generates a 12-word seed—BACK THIS UP!)

§Windows

1. Download the .zip file from GitHub.
2. Extract and run phoenixd.exe in Command Prompt.
3. Backup the seed (located in %APPDATA%\Phoenix\seed.dat).

§Docker (Recommended for Servers)

docker run -d --name phoenixd -v phoenix_data:/root/.phoenix -p 9740:9740 acinq/phoenixd

§Step 2: Secure Your Seed & API Password

• Seed Backup:

  • Located at ~/.phoenix/seed.dat (Linux/macOS) or %APPDATA%\Phoenix\seed.dat (Windows).
  • Write it down offline—this is your only recovery method.

• API Password:

  • Found in ~/.phoenix/phoenix.conf (auto-generated on first run).
  • Required for all HTTP API requests.

§Step 3: Configure for Mainnet or Testnet

By default, phoenixd runs on Mainnet. To switch to Testnet (for testing):

./phoenixd --testnet

(Useful for developers experimenting without real funds.)

§3. Automated Liquidity Management

One of phoenixd’s killer features is automated liquidity management, which eliminates the need for manual channel rebalancing.

§How It Works

• When you receive a payment that exceeds your inbound capacity, phoenixd automatically opens or resizes a channel to accommodate it.
• Uses “splicing” (a Lightning feature that adjusts channel sizes without closing them).
• Fees apply (~1% + mining fees), but this is cheaper than manual management.

§Checking Fees

Use the /getfees API endpoint (or check the official docs) for current rates.

§Manual Channel Management (Optional)

If you prefer manual control, you can:

• Open channels via /openchannel
• Close channels via /closechannel
• Check balance with /getbalance

(Most users let phoenixd handle liquidity automatically.)

§4. Using the HTTP API for Payments

phoenixd does not have a GUI—instead, you interact with it via HTTP API (default port: 9740).

§Authentication

All requests require:

• API Password (from phoenix.conf)
• Basic Auth in headers:

  curl -u "api-password:" http://localhost:9740/getinfo
  

§Key API Endpoints

§Example: Receiving a Payment

1. Generate an invoice (Bolt11):

   curl -u "api-password:" -X POST http://localhost:9740/createinvoice \
     -H "Content-Type: application/json" \
     -d '{"amountMsat": 1000000, "description": "My Store - Order #123"}'
   

   (Returns a bolt11 invoice string.)

2. Customer pays via any Lightning wallet (e.g., Phoenix, Muun, Wallet of Satoshi).

3. Check payment status:

   curl -u "api-password:" http://localhost:9740/listinvoices
   

§Example: Sending a Payment

curl -u "api-password:" -X POST http://localhost:9740/payinvoice \
  -H "Content-Type: application/json" \
  -d '{"invoice": "lnbc100n1...", "maxFeeMsat": 5000}'

§Modern Standards: Bolt12 & LNURL

• Bolt12: Enables recurring payments (e.g., subscriptions).
• LNURL: Simplifies payments with static QR codes (e.g., donations, PoS systems).

(See Phoenix API Docs for full details.)

§5. Adding a User Interface (Optional)

While phoenixd is headless, you can add a UI layer for easier management:

§Example: Connecting LNbits to phoenixd

1. Install LNbits:

   git clone https://github.com/lnbits/lnbits.git
   cd lnbits
   docker-compose up -d
   

2. Configure LNbits to use phoenixd as a funding source.
3. Now you have a web dashboard for invoices, users, and extensions!

§6. phoenixd vs. Phoenix Wallet: Which Should You Use?

§When to Use phoenixd

✔ You need 24/7 uptime (e.g., accepting payments for a business). ✔ You want automated liquidity management without manual intervention. ✔ You’re a developer building Lightning apps. ✔ You prefer self-custody and programmatic control.

§When to Use Phoenix Wallet

✔ You’re a casual user making occasional payments. ✔ You don’t want to manage a server. ✔ You prefer a simple, mobile-friendly UI.

§7. Advanced Tips & Tricks

§Optimizing for Low Fees

• Use /getfees to check current liquidity costs.
• Set maxFeeMsat in /payinvoice to avoid overpaying.
• Monitor routing fees via 1ML or Amboss.

§Backup & Recovery

• Seed phrase (seed.dat) is critical—store it offline.
• Channel backups (channel.backup) can restore funds if the node crashes.
• Test recovery on Testnet before relying on Mainnet.

§Security Best Practices

• Run phoenixd behind a firewall (only expose port 9740 to trusted IPs).
• Use Tor for additional privacy:

  ./phoenixd --proxy=socks5://127.0.0.1:9050
  

• Regularly update to the latest version.

§Monitoring & Alerts

• Use /getinfo to check node status.
• Set up cron jobs to log balance changes:

  curl -u "api-password:" http://localhost:9740/getbalance >> /var/log/phoenixd_balance.log
  

• Integrate with Telegram/Discord alerts using webhooks.

§8. Real-World Use Cases

§Case Study 1: E-Commerce Store

• Problem: High credit card fees (3%) and chargeback fraud.
• Solution:
  • Deploy phoenixd on a VPS.
  • Integrate BTCPay Server for Lightning payments.
  • Use LNbits for a customer-facing checkout.
• Result: 1% fees, instant settlements, no chargebacks.

§Case Study 2: Podcaster (Value4Value)

• Problem: Monetizing content without ads.
• Solution:
  • Run phoenixd on a Raspberry Pi.
  • Generate LNURL-pay links for listeners to stream sats.
  • Use Alby Extension for browser-based tips.
• Result: Direct fan funding with no middlemen.

§Case Study 3: Self-Hosted Lightning Node

• Problem: Want full control over Lightning funds.
• Solution:
  • Install phoenixd on StartOS.
  • Connect Zeus Wallet for mobile management.
  • Use Ride The Lightning (RTL) for a web dashboard.
• Result: Sovereign Lightning node with automated liquidity.

§9. Troubleshooting Common Issues

For more help, check:

• Phoenixd FAQ

§10. Future of phoenixd & Lightning

phoenixd is actively developed by ACINQ, with upcoming features like:

• Better Bolt12 support (recurring payments).
• Improved liquidity algorithms (lower fees).
• Pluggable backends (e.g., LDK integration).
• Enhanced privacy (e.g., trampoline payments).

§How to Stay Updated

• Follow ACINQ on Twitter.
• Join the Lightning Dev Kit (LDK) community.
• Monitor Phoenix GitHub.

§Final Thoughts: Is phoenixd Right for You?

phoenixd is a powerful tool for anyone who needs: ✅ 24/7 Lightning payments (businesses, content creators). ✅ Automated liquidity (no manual channel management). ✅ Programmatic control (API-driven payments). ✅ Self-custody & privacy (no third-party risk).

If you’re new to Lightning, start with the Phoenix Wallet mobile app. But if you’re ready to take control of your payments, phoenixd is the ultimate self-hosted solution.

§Next Steps

1. Install phoenixd on a test machine (or Testnet).
2. Experiment with the API (/createinvoice, /payinvoice).
3. Integrate with LNbits or BTCPay Server for a full payments stack.
4. Join the Lightning community for support and ideas.

§Further Reading & Resources

• Phoenixd Official Docs
• Lightning Network Explainer
• BTCPay Server + Phoenixd Guide
• LNbits Documentation
• StartOS Phoenixd Base Hub Cache

§Start Building A Project With Whatever You Have

Now that you understand phoenixd, what will you build with it?

• A self-hosted Lightning PoS system?
• A Value4Value podcasting setup?
• An automated Bitcoin savings plan?

The possibilities are endless—happy stacking! 🚀