Cowrie Research

phoenixd-primary-sources-2026-05-02

4 min read

phoenixd primary sources — 2026-05-02

Project status in this pass

  • No canonical standalone whitepaper or litepaper surfaced.
  • The clearest current source of truth is ACINQ’s phoenixd FAQ, getting-started guide, API reference, auto-liquidity explainer, and the public phoenixd README.
  • The materials consistently frame phoenixd as a self-custodial, API-first Lightning server optimized for easy payment integration rather than as a routing node or hosted wallet service.

Primary-source snapshots

1) Server FAQ

  • URL: https://phoenix.acinq.co/content/server/faq.md
  • Key excerpt:
    • The FAQ defines phoenixd as a “minimal, specialized Lightning node designed for sending and receiving Lightning payments.”
    • It says phoenixd uses the same software as Phoenix Wallet, but runs on a server, exposes an HTTP API instead of a GUI, and has fully automated liquidity management for receive-heavy uses such as merchants and crowdfunding.
    • It says phoenixd is for developers and businesses who want to build on Lightning with minimum hassle and maximum reliability without compromising on self-custody.
    • It explicitly contrasts phoenixd with Eclair, describing Eclair as a scalable general-purpose routing node and phoenixd as the minimal specialized payments node.
    • It also says phoenixd is self-custodial, stores a 12-word recovery phrase in ~/.phoenix/seed.dat, and warns not to reuse the same seed across Phoenix instances.

2) Getting-started guide

  • URL: https://phoenix.acinq.co/content/server/get-started.md
  • Key excerpt:
    • The guide shows phoenixd being downloaded and started in just a few shell commands.
    • It immediately pairs the daemon with phoenix-cli, demonstrating getinfo, createinvoice, and sendtoaddress commands.
    • This is strong evidence that the intended user experience is an application/backend integration surface, not a GUI wallet or a manually operated routing node.

3) API reference

  • URL: https://phoenix.acinq.co/content/server/api.md
  • Key excerpt:
    • The API docs say the API “must not be accessible from the outside world,” uses Basic authentication, and generates passwords on first start.
    • They define both a primary password and a limited-access secondary password, with the latter barred from sensitive endpoints such as payinvoice, payoffer, paylnaddress, lnurlpay, lnurlauth, sendtoaddress, closechannel, and export.
    • The endpoint inventory spans Bolt11 invoices, Bolt12 offers, BIP-353 Lightning addresses, LNURL flows, incoming/outgoing payment lookup, CSV export, websockets, webhooks, node/balance/channel queries, and onchain operations such as splice-out and CPFP fee bumping.
    • The websocket section says WS /websocket streams JSON payment-received events and can authenticate via either basic auth or Sec-WebSocket-Protocol.
    • The webhook section says phoenixd can POST payment notifications to configured endpoints and authenticate them with an X-Phoenix-Signature header.

4) Auto-liquidity explainer

  • URL: https://phoenix.acinq.co/content/server/liquidity.md
  • Key excerpt:
    • The liquidity docs say management is fully automated and extends Phoenix Wallet’s on-the-fly channel model with “auto liquidity” plus a “fee credit” mechanism.
    • They say phoenixd is “always” accepting payments with “seemingly infinite inbound liquidity, with no threshold effect.”
    • They explain that small incoming payments can accumulate as a non-refundable fee credit until there is enough value to buy inbound liquidity, while larger payments trigger immediate channel creation or enlargement.
    • They also give concrete economics: default auto-liquidity is 2 million sat and the cost of liquidity is 1% plus mining fees.

5) Repository README

  • URL: https://raw.githubusercontent.com/ACINQ/phoenixd/master/README.md
  • Key excerpt:
    • The README calls phoenixd “the server equivalent” of Phoenix Wallet.
    • It says the project is written in Kotlin Multiplatform and runs natively on Linux x86/ARM, macOS x86/ARM, and Windows via WSL.
    • The README also links directly to the homepage and API docs, reinforcing that the public docs corpus is the real operational reference.

Working conclusion

phoenixd is best cataloged as an API-first Lightning payments control plane: a minimal self-custodial server daemon that packages modern Lightning payment surfaces and automated inbound-liquidity handling for developers and businesses. The crucial evidence in this pass was the repeated combination of (1) explicit self-custody, (2) a zero-config and payment-focused operating model, and (3) a backend-facing API surface spanning invoices, offers, Lightning addresses, LNURL, webhooks, websockets, and onchain channel-management actions.

Graph View