phoenixd
Bitcoin Accounting
phoenixd + Clams
HTTP APIphoenixd is the server build of ACINQ's Phoenix wallet: a self-custodial Lightning wallet with automated channel management that you run on your own infrastructure. Clams connects natively over its HTTP API using a read-only credential, so your books stay current without any CSV export. Self-hosted Lightning accounting without the hassle.
What Clams tracks
- Lightning deposits and withdrawals with amounts, fees, and timestamps
- On-chain swap-out withdrawals mapped to their settling transaction
- Liquidity and channel-management fees, canonicalized into your journal
- Fee credits read from the balance API as prepaid liquidity
- Automatic cost basis tracking per transaction
How it works
Before you start, set up a Clams profile with a fiat currency and gains method, and select an on-chain source. phoenixd reconciles on-chain swap-outs, so a chain source is required for syncing. New to Clams? Start with the getting-started guide.
Run phoenixd on your server
On first launch, phoenixd generates its config and credentials at ~/.phoenix/phoenix.conf and listens on port 9740.
Copy your read-only password
From ~/.phoenix/phoenix.conf, copy the value of http-password-limited-access. This read-only credential lets Clams query your server but never send payments.
Add connection details in Clams
Create a phoenixd connection with the Clams CLI. Replace the password and address in the command below with yours.
$ clams connections create --label phoenixd --kind Phoenixd --configuration '{"base_url":"http://127.0.0.1:9740","password":"YOUR_READONLY_PASSWORD","timeout_secs":30,"page_size":100}'
Sync activity
Run the sync command below to import your full transaction history. Re-run anytime to pull the latest activity.
$ clams connections sync --label phoenixd
Generate journal entries
Process your imported transactions into accounting journals with the command below.
$ clams journals process
Frequently asked questions
What data does Clams import from phoenixd?
Clams imports Lightning deposits and withdrawals with their amounts, fees, and timestamps, maps on-chain swap-out withdrawals to their settling Bitcoin transaction, canonicalizes liquidity and channel-management fees, and reads fee credits from the balance API. Every transaction is automatically categorized for accounting.
Does Clams access my private keys or spend funds?
No. Clams connects with the read-only HTTP password (http-password-limited-access). That credential cannot send payments, and your seed stays on your own server. Clams cannot spend funds.
Which phoenixd password should I use?
Use http-password-limited-access from your phoenix.conf file (default location ~/.phoenix/phoenix.conf). It grants read-only access to query endpoints only. Do not use the full-access http-password.
Can I connect to a remote phoenixd server over Tor?
Yes. phoenixd connections support Tor proxy routing. Point base_url at your server's onion address and Clams routes the sync over Tor.
Can I track multiple phoenixd servers?
Yes. Add each phoenixd server as its own connection in Clams. Each one syncs and reports independently.
Why does sync say "no onchain data source configured"?
phoenixd reconciles on-chain swap-outs, so the profile needs a selected on-chain source before syncing. Add one with clams chain-sources (Electrum, Esplora, or Bitcoin RPC), select it, then re-run the sync.
Do I need my server online to sync?
Yes. Clams connects to your phoenixd HTTP API to fetch transaction data, so your server must be running and reachable for syncing. Once synced, you can view your data offline.
Start tracking your phoenixd server
Install Clams and connect your server in minutes.