claude-dev-suite phoenixd (ACINQ)
phoenixd is the headless version of the Phoenix wallet. Designed
for individuals and small services who want a self-hosted LN daemon
without the operational complexity of LND/CLN.
Phoenix mobile = consumer wallet. phoenixd = same engine, no UI, HTTP API for integration.
Architecture
- Built on top of Eclair core (so JVM-based).
- Self-hosts; single node, no cluster.
- Auto-channel management via ACINQ swap-in / swap-out.
- Default to BOLT12 offers for receiving.
- Lightning-Address support out of the box.
Why phoenixd
- No bitcoind required — uses Electrum servers (configurable).
- No on-chain wallet UI — auto-handles funding and channel mgmt.
- API-first — HTTP REST + WebSocket for payment events.
- Reasonable defaults — anchor channels, MPP, BOLT12, all enabled by default.
- Liquidity from ACINQ — auto channel-open via swap-in.
Install
curl -L https://github.com/ACINQ/phoenixd/releases/download/.../phoenixd-... > phoenixd.zip
unzip phoenixd.zip; cd phoenixd-...
./phoenixd --version
./phoenixd # first run: generates seed, prompts to backup
Config at ~/.phoenix/phoenix.conf:
chain=mainnet
http-bind-ip=127.0.0.1
http-bind-port=9740
http-password=<auto-generated, in seed.dat or set explicitly>
auto-liquidity=2m # auto manage liquidity, allow 2M sats inbound
API
Default localhost:9740. Auth via HTTP basic (_:<password>):
curl -u _:$(cat ~/.phoenix/phoenix.conf | grep http-password | cut -d= -f2) \
http://127.0.0.1:9740/getinfo
curl -u _:pass -X POST -d "amountSat=5000&description=Coffee" \
http://127.0.0.1:9740/createinvoice
curl -u _:pass -X POST -d "invoice=lnbc..." \
http://127.0.0.1:9740/payinvoice
WebSocket events
Real-time payment notifications:
const ws = new WebSocket("ws://_:pass@127.0.0.1:9740/websocket");
ws.onmessage = (e) => {
const event = JSON.parse(e.data);
if (event.type === "payment-received") {
console.log("Got", event.amountSat, "sats");
}
};
Liquidity
phoenixd auto-manages liquidity via ACINQ:
- Splice-in: when more inbound liquidity needed.
- Splice-out: when receiving on-chain back.
- Fees charged by ACINQ (typically small percentage of channel size).
For higher volume, run alongside LSP:
liquidity-provider=acinq # default
Use cases
- Self-hosted POS terminals (Donation page, micro-merchant).
- Private API for backends (no need for LND complexity).
- Lightning Address servers (low setup overhead).
- Integration with NWC providers.
Limitations
- Only one channel at a time (vs LND/CLN which support many).
- ACINQ as sole LSP (others possible but tested less).
- No BOLT12 send in some early versions (check current docs).
- Eclair lineage: heavy JVM, ~500 MB RAM.
Backup
~/.phoenix/seed.dat is the seed (encrypted with empty password
unless set). Backup this file + phoenix.conf.
Channel state recovery: if seed restored to a different machine, phoenixd attempts to recover via SCB-like flow with peers.
Comparison
| Feature | phoenixd | LND | CLN | LDK Node |
|---|---|---|---|---|
| Setup complexity | ★ (very simple) | ★★★★ | ★★★ | ★★ |
| Multiple channels | no | yes | yes | yes |
| Plugin ecosystem | no | rich | rich | code-level |
| Memory | ~500 MB | 100-200 MB | ~150 MB | 10-50 MB |
| LSP integration | ACINQ-native | manual | manual | flexible |
| BOLT12 receive | yes | partial | yes | yes |