Phoenixd

---
name: lightning-phoenixd
description: |
  Phoenixd by ACINQ: headless server build of Phoenix wallet for
  self-hosting. Single-node Lightning daemon with batteries-included
  ACINQ swap-in / swap-out, BOLT12 receive, WebSocket payments API.
  USE WHEN: deploying a self-hosted minimal Lightning daemon for a
  service (point-of-sale, donation page, micro-merchant), avoiding
  full LND/CLN complexity.
allowed-tools: Read, Grep, Glob
---

# 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

```bash
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`:
```ini
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>`):
```bash
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:
```js
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:
```ini
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 |

## See also

- [eclair/SKILL.md](../eclair/SKILL.md)
- [consumer-wallets/SKILL.md](../consumer-wallets/SKILL.md)
- [lsp/SKILL.md](../lsp/SKILL.md)