phoenixd
phoenixd is not a Nostr client and not the Phoenix social app. It is a small Lightning wallet daemon from ACINQ, built for servers and apps that want Phoenix-style liquidity automation behind an API.
phoenixd is Phoenix for servers
phoenixd is easiest to understand if you already know Phoenix Wallet. Phoenix is ACINQ's self-custodial Lightning wallet for mobile users; phoenixd brings the same family of ideas to a server daemon. The README describes phoenixd as the server equivalent of the Phoenix wallet for mobile, written in Kotlin Multiplatform and running natively on Linux, macOS and Windows through WSL.
That does not make phoenixd a general-purpose Lightning node in the same shape as LND or CLN. It is a specialized payment daemon. It is meant for sending and receiving payments, not for manually managing peers, running a public routing node, tuning channel strategy or exposing every low-level Lightning control. It trades breadth for a simpler operating model.
For a Nostr reader, the important distinction is this: phoenixd is not the Phoenix social client, not the mobile Phoenix wallet app and not a Nostr Wallet Connect service by itself. It is the Lightning backend that can sit under another service. If you use Alby Hub with phoenixd, Alby Hub is the NWC-facing wallet service and phoenixd is the payment engine underneath.
That makes phoenixd a very useful bridge between two worlds. On one side are developers who want a server process and an API. On the other side are normal Nostr users who want zaps, subscriptions, paid actions and Lightning Address behavior without learning channel management. phoenixd can help the server side stay small enough that the user-facing wallet service can focus on permissions and product clarity.
ACINQ is the operator behind the design
ACINQ is a long-running Lightning company best known for Eclair and Phoenix. Its own site lists Phoenix Wallet as a self-custodial Bitcoin wallet with native Lightning support and phoenixd as a minimal, specialized Lightning node designed to send and receive payments. That framing is helpful because it explains the product's boundaries.
phoenixd inherits the Phoenix philosophy: make Lightning usable without forcing every user or small business to become a channel operator. That does not mean ACINQ takes custody of the seed. The server keeps the wallet seed locally. It does mean the payment model depends on ACINQ's LSP and infrastructure for liquidity, channel management and routing assumptions.
This is why phoenixd can feel magical in small deployments and still deserve careful review. You get a smaller operational surface, automatic liquidity and a simple API. In exchange, you accept a more opinionated relationship with ACINQ than you would have with a fully self-directed LND or CLN node connected to arbitrary peers.
The right question is not whether that tradeoff is good or bad in the abstract. It is whether the user understands it before they rely on it. For a small creator server, automatic liquidity may be exactly the missing piece. For a business that needs independent node policy, its own Bitcoin backend and peer choice, the same design may be too constrained.
The active project state is clear
GitHub API data checked on June 13, 2026 showed the `ACINQ/phoenixd` repository with 175 stars, 18 forks, 16 open issues or pull requests, Apache-2.0 licensing, creation on March 8, 2024, update and push activity on June 11, 2026, and `master` as the default branch.
The latest release checked was `v0.8.0`, published on May 20, 2026. Its release note was short but meaningful: it upgraded `lightning-kmp` to `1.12.0`, provided signed release assets for Linux, macOS and JVM builds, and documented checksum verification with ACINQ's release signing key `E434ED292E85643A`.
Docker Hub also showed an official `acinq/phoenixd` image, with `latest` and `0.8.0` pushed in late May 2026 for `linux/amd64` and `linux/arm64`. The Dockerfile builds from Eclipse Temurin 21, compiles the native binaries from the selected phoenixd tag, exposes port `9740`, stores data in `/phoenix/.phoenix` and starts the daemon with `--agree-to-terms-of-service` and an HTTP bind address.
Version awareness matters because this is money software. The repository's `gradle.properties` had moved to `0.8.1-SNAPSHOT` on the development branch, while the latest published release was still `v0.8.0`. A reader should distinguish a release they can install and verify from a development snapshot in the branch. Use tagged releases, pinned Docker tags and checksum verification when possible.
The API is the product surface
The official API page is linked from the README, and the implementation in `Api.kt` shows the working surface. phoenixd installs a Ktor server with JSON serialization, status handling, basic authentication, websocket support and webhook delivery. The result is a daemon that other software can call rather than a wallet with its own full graphical interface.
The API includes read endpoints such as `getinfo`, `getbalance`, `estimateliquidityfees` and `listchannels`. It also includes invoice and offer endpoints: `createinvoice`, `createoffer`, `getoffer`, `decodeinvoice` and `decodeoffer`. For an app developer, that is the difference between manually copying invoices and building a payment flow around server calls.
Payment history is first-class too. The code exposes `payments/incoming`, `payments/incoming/{paymentHash}`, `payments/outgoing`, `payments/outgoing/{uuid}` and `payments/outgoingbyhash/{paymentHash}`. That matters for commerce, subscriptions and Nostr app connections, because a backend needs more than a send button. It needs to reconcile what happened.
The API also reveals a product philosophy. phoenixd does not ask the caller to orchestrate every channel detail. It asks the caller to create invoices, pay invoices, inspect balances and react to payment events. That is exactly the surface a hub, merchant plugin or Nostr payment service wants, as long as it also handles permissions, limits and error interpretation.
Sending and receiving are intentionally narrow
phoenixd supports common payment actions directly: `payinvoice`, `payoffer`, `paylnaddress`, `lnurlpay`, `lnurlwithdraw`, `lnurlauth`, `sendtoaddress`, `bumpfee` and `closechannel`. It also supports `export`, which writes successful payments to CSV. This is a practical API for receiving money, paying invoices, handling Lightning Address and connecting to services that need accounting data.
The narrowness is a feature and a limitation. You do not get the full remote-control shape of a general Lightning daemon. You get the operations ACINQ has chosen to expose for the Phoenix server use case. That makes phoenixd easier to wrap, but it means a higher-level wallet service must decide how to translate user expectations into the API.
For Nostr, this is exactly where Alby Hub or another wallet service becomes important. A NWC request such as `pay_invoice`, `make_invoice`, `lookup_invoice` or `get_balance` needs a wallet service that maps NIP-47 semantics onto phoenixd calls, enforces budgets and keeps relay-facing credentials away from the raw daemon.
That mapping is not only naming. NWC clients expect consistent error codes, permission failures, payment hashes, invoice lookups and balances at the level of an app connection. phoenixd may know the real Lightning result, but the NWC layer has to translate it into a safe app-facing contract. Good integration hides daemon credentials, not daemon state that the user needs.
NWC is a bridge, not the daemon itself
Nostr Wallet Connect is a protocol for communicating with a Lightning wallet via Nostr. Alby's developer guide describes it as a way for apps to make backend or native payments without requiring the user to switch to a wallet for every action. phoenixd does not automatically become that service just because it can pay invoices.
The common pattern is phoenixd plus Alby Hub. The `getAlby/hub` repository lists Phoenixd as one of the optional external backends, beside LND, Cashu and CLN. Alby Hub then becomes the NWC wallet service, while phoenixd does the Lightning work. Nodana even offers an Alby Hub and Phoenixd template that pairs those layers.
There is also evidence in the phoenixd repository that NWC-shaped needs influenced API discussion. Discussion #55 asked for additions useful when implementing Nostr Wallet Connect for phoenixd, including preimage handling, invoice expiry and payment-hash lookup. That is a good sign for integration, but it is not the same as built-in NWC.
This is the clean way to describe phoenixd in the Nostr ecosystem: it is NWC-relevant infrastructure. It can power an NWC wallet service. It can sit behind Alby Hub. It can be part of a creator, merchant or relay-paid stack. But the protocol boundary still lives in the wallet service that speaks Nostr relays and signs or responds to NIP-47 requests.
Alby Hub gives phoenixd a Nostr face
A Nostr user usually wants app permissions, not raw daemon access. Alby Hub supplies that layer. It can manage wallet connections, NWC secrets, sub-wallets and app-facing permissions, then talk to a Lightning backend. When phoenixd is selected as that backend, the user gets Phoenix-style liquidity with an NWC-facing hub on top.
The Alby Hub Phoenixd script documents both Docker and non-Docker setups. It tells users to create separate data directories for phoenixd and Alby Hub and says those directories must be backed up. It also notes that the default Docker compose uses a preconfigured phoenixd password for simplicity and should not be publicly exposed unchanged.
That warning is the whole architecture in miniature. The Nostr app should never receive the phoenixd password. The app should receive a limited NWC connection from the hub. The hub should know which app can spend how much. phoenixd should sit behind the hub, reachable only by the service that is supposed to operate the wallet.
A practical setup might therefore have three secrets with different meanings: the phoenixd HTTP password, the Alby Hub account or admin credentials, and one NWC connection secret for each connected app. Mixing those secrets is a serious design smell. The daemon password belongs to the backend. The NWC secret belongs to a single app connection and should be revocable without changing the daemon.
Authentication is simple and therefore sensitive
The API implementation uses HTTP basic authentication with full-access and limited-access passwords. The status handler even tells failed callers to use basic auth with the HTTP password set in `phoenix.conf`. Websocket authentication uses the `Sec-WebSocket-Protocol` header as a workaround because browsers do not support basic auth for websocket in the same way.
This is practical, but it is not something to expose casually. If the HTTP port is reachable from the public internet with a weak password, you have not built a sovereign payment stack; you have built a hot wallet API waiting to be found. Put phoenixd behind a local network boundary, reverse proxy, firewall or trusted service boundary.
Limited access can reduce blast radius, but the security model still starts with deployment hygiene. Change default passwords, keep them out of repositories, avoid logging secrets, restrict network access, rotate credentials after incidents and avoid giving a Nostr-facing app any credential that can bypass the wallet-service permission layer.
The websocket workaround deserves special care in browser-adjacent software. Passing a password through a protocol header is practical for a daemon API, but it should not become a pattern where front-end code can see backend credentials. If a web app needs live payment events, terminate that need at a trusted service and pass only the minimum app event downstream.
The seed is local, but backups are more than a phrase
The `Seed.kt` code shows phoenixd reading an existing seed file or generating 16 bytes of entropy, converting it to mnemonic words, writing them to the seed path and then deriving the wallet seed. That is self-custodial in the key sense: the seed is local to the server and must be protected by the operator.
A seed phrase is not the whole operational backup story for Lightning. Channel state, payment databases, configuration and the service's data directory matter. Start9's phoenixd package is blunt about this: the mounted data volume contains wallet data, seed, channels and database, and backups must be secure because Lightning funds depend on them.
For a Nostr payment stack, backup discipline is easy to forget because the front end may feel like a normal web account. It is not. If Alby Hub talks to phoenixd and phoenixd stores the keys and channel state, then the server's data directory is money infrastructure. Back it up, test restore, and do not treat the host as disposable.
The backup conversation should happen before the wallet receives meaningful funds. Where is the seed stored? Where is the data directory mounted? Is the backup encrypted? Who can restore it? Does a restore require the same service version? What happens if the VPS disappears? Those are not advanced concerns when the server is holding spendable Lightning funds.
Automated liquidity is the main attraction
The reason phoenixd keeps appearing in Nostr payment setups is liquidity. A traditional Lightning node asks the operator to think about channels, peers, inbound liquidity, outbound liquidity, routing and uptime. phoenixd tries to make the receive-and-pay use case feel closer to Phoenix mobile: the operator focuses on the application and ACINQ handles much of the channel complexity.
Nodana's Phoenixd page describes it as a Lightning node with automated channels and liquidity, and says it has no channel management, no peer management and no firewall configuration for the user. The Plan B Academy tutorial explains the same tradeoff in more operational language: phoenixd uses ACINQ as its LSP for automatic liquidity, with on-the-fly capacity carrying liquidity and mining-fee costs.
That convenience is real, especially for creators, small merchants, donation pages, Nostr zaps and personal servers. It is also not free of dependency. The user controls the seed, but ACINQ remains the LSP path. If ACINQ infrastructure, policy, fees or availability matter to your business, that dependency belongs in the risk review.
Liquidity automation also changes how fees are experienced. A user may not buy a channel in advance, but they may still pay for incoming capacity, splice-related operations or on-chain movement when the backend needs it. A wallet service should not merely say automatic. It should explain when liquidity fees can appear and whether tiny payments, large receipts or on-chain events behave differently.
It is not a full peer-management node
The Start9 package documentation makes the limitations explicit: phoenixd requires connection to ACINQ's LSP, cannot use arbitrary Lightning peers, has no local Bitcoin node requirement, relies on ACINQ infrastructure for blockchain data, offers no built-in web UI and charges liquidity-related fees. Those are not footnotes; they define the product.
This makes phoenixd very different from running CLN or LND as a public node. If your goal is to route payments, experiment with peers, run a public node, connect to your own Bitcoin Core, tune channels or build node-management software, phoenixd is probably the wrong primary backend. If your goal is to run a simple self-custodial payment server, it may be excellent.
Nostr apps need this distinction because the word node can mislead users. A user may hear self-hosted Lightning node and assume full autonomy over peers and routing. phoenixd gives self-custodial wallet control with a managed-liquidity model. That is powerful, but it is a specific product category, not a synonym for every Lightning daemon.
This also affects privacy expectations. A node connected only through an opinionated LSP path leaks and protects different things than a node with arbitrary peers and a local chain backend. The user may gain simplicity and avoid public node management, while still depending on external infrastructure for liquidity and chain awareness. Those tradeoffs should be named in serious deployments.
The open issues show the edges
Open issues checked in June 2026 were a useful map of the product's rough edges. They included LNURL trouble, CSV accounting separation for channel opens, a channel-funding error during dual funding, lower minimum auto-liquidity, Electrum backend support, SOCKS proxy support, webhook or websocket behavior for invoice expiry, invoice cancellation, standardized websocket messages and HTTP status behavior for failed payment calls.
None of those issues makes phoenixd unusable by itself. They do show where a production integration should test carefully. If you run a shop, CSV exports and channel-open accounting matter. If you depend on LNURL, test it. If your integration treats HTTP 200 as success without parsing the response body, issue #42 is exactly the kind of trap that can become a support incident.
A good NWC-facing wrapper should normalize these edges for the user. It should translate daemon errors into wallet-service errors, distinguish pending from failed payments, show invoice expiry, avoid double-spending retries and keep an auditable payment record. phoenixd gives useful building blocks; the wrapper decides whether users experience them as clarity or confusion.
The issue list is also useful for deciding what to test after every upgrade. If a release touches `lightning-kmp`, LNURL, websocket events, CSV export or liquidity behavior, a merchant should test the exact workflow that makes money. Do not assume one successful send proves the receive-heavy or webhook-heavy path is healthy.
Webhooks and websockets help apps react
phoenixd is not limited to polling. The API implementation includes webhook delivery and a `/websocket` route that streams API events. It can notify general webhook URLs and per-invoice webhook URLs, and the code signs webhook requests with an HMAC-style signature header using the configured webhook secret.
This matters for commerce and Nostr apps because payment state is event-driven. A shop wants to know when an invoice is paid. A Nostr service wants to update a creator balance, unlock access, mark a zap, credit a subscription or reconcile a paid action. Webhooks and websockets reduce the need to hammer the daemon with polling loops.
The same event surface creates security obligations. Webhook endpoints should verify signatures, reject unexpected payloads, handle retries safely and avoid treating an unauthenticated callback as a payment proof. A Nostr app should also consider relay state separately from payment state. A paid action may need both a confirmed wallet event and a successfully published Nostr event.
For subscriptions and paid access, idempotency is just as important as speed. A webhook may be delivered twice, a websocket may reconnect, a relay event may fail to publish, and a user may retry from the front end. The integration should key state by payment hash or stable payment identifier and make repeated notifications harmless.
The deployment story is small-server friendly
The Docker image is intentionally simple: a compiled daemon, a `phoenix` user, port `9740`, and a mounted `/phoenix/.phoenix` data directory. Nodana offers phoenixd directly. Start9 offers a package. Alby Hub ships scripts for pairing with phoenixd through Docker compose or a non-Docker install. This is the kind of backend that can live on a small VPS or home server.
Small does not mean unserious. You still need uptime, disk backups, host security, upgrade discipline, logs, firewall rules, monitoring and a plan for secrets. A creator who receives zaps through a Nostr profile may be fine with occasional downtime; a merchant checkout flow may not. The same daemon can serve both, but the operating standard is different.
The best first deployment is boring: bind locally, use a wallet service or reverse proxy intentionally, back up the data directory, keep the host patched, test a tiny invoice, test a tiny payment, stop and restart the daemon, then check whether balances, payment history and webhooks behave as expected.
Small servers are often operated by people who are comfortable with apps but not with incident response. That is fine as long as the stack is honest about maintenance. Document where the daemon lives, how it starts, how to upgrade it, how to stop it, how to read logs, how to restore from backup and who has access to the host.
How to evaluate it for a Nostr stack
First identify who is speaking NWC. If the answer is Alby Hub, then check the Alby Hub connection settings, sub-wallet limits, NWC relay, app permissions and revocation UI. If the answer is a custom service, ask how it maps NIP-47 methods to phoenixd, how it stores NWC secrets and how it prevents a connected app from spending more than allowed.
Then inspect the phoenixd side. Confirm the version, release signature path, Docker tag, data directory, seed backup, `phoenix.conf`, full and limited passwords, port exposure, webhook secret, websocket usage and upgrade path. Do not connect a public Nostr app to an unreviewed daemon just because it paid one test invoice.
Finally test real failure modes: bad invoice, expired invoice, unpaid invoice lookup, low liquidity, webhook downtime, websocket reconnect, daemon restart, host reboot, restore from backup, revoked NWC connection and a payment that returns an error payload. The point is not to make Phoenixd look fragile. The point is to know where the product boundary is before real money is involved.
If the stack will serve other people, also test disclosure. Can the operator explain who holds the keys, what ACINQ does, what Alby Hub does, what NWC permits, what data is backed up and what happens during downtime? A user does not need every internal detail, but they should not be surprised by the custody, liquidity or permission model.
Who phoenixd fits best
phoenixd fits developers, creators, small merchants and technically curious Nostr users who want a self-custodial Lightning backend without manually managing channels. It is especially attractive when paired with a hub that exposes NWC, because the user can get app-to-wallet connections while the backend stays comparatively simple.
It is less suited to operators who want full peer choice, routing-node economics, local Bitcoin-node sovereignty, deep channel control or a daemon API that mirrors LND and CLN. Those users should look at LND, CLN, LDK-based stacks or other node designs. phoenixd is opinionated; that is part of why it is easy.
The practical takeaway is simple: phoenixd can make a Nostr payment stack feel approachable without handing keys to a custodian. But it does not erase Lightning risk. Use it behind a permissioning layer, protect the API, back up the data directory, understand the ACINQ LSP dependency and test every app connection with small amounts before trusting it with meaningful balances.
When it fits, phoenixd is one of the cleanest answers to a very real Nostr problem: people want self-custodial Lightning that can stay online for apps. It gives that problem a small daemon and an API. The final user experience still depends on the layer above it: the hub, permissions, UI, backup language and failure handling.
Sources worth opening
Open the ACINQ repository, README, latest release, Docker image, API implementation and Alby Hub backend material first. phoenixd is a backend, so the useful reading path is product boundary, API surface, key custody, liquidity model, deployment shape, NWC bridge, backup obligations and known open issues.
- ACINQ official website
- Phoenix Wallet official website
- phoenixd official server page
- phoenixd official API documentation
- ACINQ/phoenixd repository
- phoenixd README raw
- phoenixd GitHub API metadata
- phoenixd releases
- phoenixd v0.8.0 release
- phoenixd Docker Hub image tags
- phoenixd Dockerfile
- phoenixd API implementation
- phoenixd websocket authentication provider
- phoenixd seed handling
- phoenixd config file reader
- phoenixd Gradle build
- phoenixd gradle.properties
- phoenixd open issues
- phoenixd issue 231 LNURL
- phoenixd issue 229 CSV accounting
- phoenixd issue 228 channel funding
- phoenixd issue 222 lower minimum auto-liquidity
- phoenixd issue 212 Electrum backend
- phoenixd issue 194 webhook expiry
- phoenixd issue 178 cancel invoices
- phoenixd issue 42 HTTP status behavior
- phoenixd discussion 55 NWC API additions
- phoenixd discussion 111 webhook payer note
- NIP-47 Nostr Wallet Connect
- Alby NWC developer guide
- nwc.dev
- getAlby/hub repository
- Alby Hub phoenixd script
- Alby Hub with Phoenixd on Nodana
- Nodana Phoenixd template
- Start9 phoenixd package
- Plan B Academy Phoenixd tutorial
- Setting up Payments on Nostr with phoenixd and Alby Hub
- ACINQ Phoenix swaproot article
- ACINQ Phoenix wallet repository
- Phoenix Android app listing
- Phoenix iOS app listing
- Lightning BOLTs repository
