Introduction

Use nd to manage your Nodana-hosted nodes and webhook receivers, and to work with your node's Phoenixd API.

For invoices, payments, balances, channels and LNURL services, use nd pxd or its pxd alias. Both are provided by the same installer.

Commands such as nd create-node and nd create-webhook manage your hosted services. Commands such as pxd create-invoice and pxd get-balance work directly with Phoenixd.

Configure access

Install the CLI, then follow Authentication to configure your node URL and Phoenixd password, or an API key for Nodana management commands.

Commands

Hosted nodes: create, inspect and manage hosted nodes with nd.
Webhook receivers: configure payment notifications with nd.
Host verification: verify the protected host and node bundle with nd attest.
Payments: create invoices and offers, send payments, read incoming and outgoing history, and export payments.
Node: inspect node state, balance and channels, decode payment requests and estimate liquidity fees.
LNURL: pay, withdraw and authenticate with LNURL services.
Attestation: verify a protected Nodana host and its approved node bundle.

Pass connection options before the command, followed by the command’s options. Run pxd --help or pxd create-invoice --help for usage.

To update a node hosted by Nodana, use the Nodana dashboard.

Read results

Nodana management commands return JSON. Node and webhook creation include one-time credentials or signing secrets; save these securely when returned. Phoenixd commands return JSON for structured results and text for addresses, offers and some node actions. Amount options ending in -sat use satoshis. History date filters and payment timestamps use Unix milliseconds.

Save payment hashes and IDs. Confirm incoming payments and their amounts before fulfilling an order. After an interrupted outgoing payment, look it up before sending another payment.

Use WebSocket or Nodana webhooks when integrating payment notifications into an application.

List hosted nodes

Terminal

nd list-nodes

Read node information

Terminal

pxd get-info

Create an invoice

Terminal

pxd create-invoice --amount-sat 1000 --description "Order 1042" --external-id order-1042

Check balance

Terminal

pxd get-balance

Override the node URL

Terminal

pxd --url https://node-a1b2.nodana.app get-info

Install the CLI

Install the Nodana CLI on macOS or Linux with the installer:

curl -fsSL https://nodana.io/cli | sh

The installer supports macOS on Apple silicon or Intel, and Linux on x86-64. It installs nd and the pxd alias in /usr/local/bin when that directory is writable, or in ~/.local/bin otherwise.

pxd is shorthand for nd pxd. For example, pxd get-info and nd pxd get-info run the same command. This reference uses pxd for Phoenixd commands.

If pxd is not found after installation, add the directory printed by the installer to your PATH, then open a new terminal.

Upgrade

Run the same installer again to replace your installed binary with the latest release.

Connect to your node

Follow the CLI overview to supply your node URL and Phoenixd password, then read its node information.

Authentication

Phoenixd commands use your node's URL and Phoenixd password. Nodana management commands use an account API key. Configure the credentials for the commands you want to run.

Phoenixd commands

For pxd commands, set NODANA_PHOENIXD_URL to your node's complete HTTPS connection URL and NODANA_PHOENIXD_PASSWORD to its Phoenixd password. The CLI reads both automatically. These settings also apply when using nd pxd.

For a Nodana-hosted node, copy the URL from its details in the dashboard and use the password you saved when creating the node. Replace the example URL and password with your own values.

Use the limited Phoenixd password for reading node information and creating invoices. Use the full password for spending, channel closure, fee bumps and LNURL authentication. Each command page states the access it needs.

Connection options

--urlstringOptional: Override NODANA_PHOENIXD_URL for one command. Use your node's complete HTTPS URL. If neither the variable nor flag is supplied, the command exits without making a request.
--passwordstringOptional: Override NODANA_PHOENIXD_PASSWORD for one command. Prefer the environment variable or secret configuration to keep the password out of command arguments. Phoenixd payment and node commands require a password.

Attestation

nd attest requires the HTTPS node URL and an independently approved release checksum. It does not require a Phoenixd password or Nodana API key. See Attestation for the checksum instructions.

Nodana management commands

For Nodana commands such as nd create-node and nd create-webhook, create an API key in the dashboard under Developers → API Keys, then set NODANA_API_KEY in the environment where you run nd.

Enable Nodes → Read (nodes:read) to list or inspect nodes, check updates, read webhook settings and list deliveries. Add Nodes → Write (nodes:write) to create, change or delete nodes and webhooks.

The key selects the account to manage. Use a key from the account containing your nodes. Delete the key in the dashboard to revoke access.

Keep credentials private

Set passwords and API keys in your terminal or secret configuration. For automated jobs, inject them from your job's secret settings. Keep them out of chat, logs and source control. Unset the variables when you finish on a shared terminal.

Troubleshooting

Missing connection settings: set NODANA_PHOENIXD_URL and NODANA_PHOENIXD_PASSWORD in the same terminal as your pxd command.
Phoenixd password rejected: check the password and use the full password if the command requires spending or other full access.
Missing Nodana API key: set NODANA_API_KEY before running a management command.
Nodana API 401: check the key is enabled, has the required permissions and has not been deleted.
Nodana API 403: check the key's permissions and account.
Nodana API 402 when creating a node: add account credit in the dashboard.

Connect to Phoenixd

Terminal

export NODANA_PHOENIXD_URL="https://node-a1b2.nodana.app"
export NODANA_PHOENIXD_PASSWORD="YOUR_PHOENIXD_PASSWORD"
pxd get-info

Override the node URL

Terminal

pxd --url https://node-a1b2.nodana.app get-info

Configure a Nodana API key

For node and webhook management commands:

Terminal

export NODANA_API_KEY='YOUR_API_KEY'

Clear credentials from this terminal

Terminal

unset NODANA_PHOENIXD_URL NODANA_PHOENIXD_PASSWORD NODANA_API_KEY

Create a node

Create a Phoenixd node in your account. Creation needs available capacity and sufficient account credit.

Usage

nd create-node

Required permission: Nodes → Write. Set NODANA_API_KEY before running this command.

The command prints JSON containing node metadata and one-time credentials: the recovery seed, full-access password and restrictedPassword. Save them securely when they are printed; they are returned only once. Keep this output out of shared logs and chats.

Your node continues launching in the background. Use nd get-node <node-id> to check its status and wait until it is ready before making payments. If launch fails, discard these credentials and create a new node. If the creation request is interrupted, check nd list-nodes before trying again; the node may already exist.

Options

--namestringOptional

Node name, up to 16 characters after trimming. Quote names containing spaces. Omit it to use a generated name.

--auto-liquiditystringOptional

Choose 2m, 5m or 10m for automatic liquidity.

Defaults to 2m.

List nodes

List the nodes in your authenticated account, including their IDs, names, and statuses.

Required permission: Nodes → Read. Set NODANA_API_KEY before running this command.

Usage

nd list-nodes

Inspect a node

Show a node's ID, name, status, connection URL and update status.

Required permission: Nodes → Read. Set NODANA_API_KEY before running this command.

Usage

nd get-node <node-id>

Replace node-123 with your node ID. Passwords and recovery information are not included.

Arguments

node-idstringRequired: ID of the node in your account. Use List nodes to find it.

Rename a node

Change a node's display name.

Usage

nd rename-node <node-id> --name <name>

Required permission: Nodes → Write. Set NODANA_API_KEY before running this command.

Arguments

node-idstringRequired: ID of the node in your account. Use List nodes to find it.

Options

--namestringRequired: New display name, up to 16 characters after trimming. Quote names containing spaces.

Start a node

Start a stopped Phoenixd node.

Required permission: Nodes → Write. Set NODANA_API_KEY before running this command.

Usage

nd start-node <node-id>

Replace node-123 with your node ID. The node keeps its existing identity and data.

Arguments

node-idstringRequired: ID of the node in your account. Use List nodes to find it.

Stop a node

Stop a Phoenixd node, retaining its data for later use.

Required permission: Nodes → Write. Set NODANA_API_KEY before running this command.

Usage

nd stop-node <node-id>

Replace node-123 with your node ID. The node's API is unavailable while it is stopped.

Arguments

node-idstringRequired: ID of the node in your account. Use List nodes to find it.

Restart a node

Restart a Phoenixd node.

Required permission: Nodes → Write. Set NODANA_API_KEY before running this command.

Usage

nd restart-node <node-id>

Replace node-123 with your node ID. The node's API is temporarily unavailable during the restart.

Arguments

node-idstringRequired: ID of the node in your account. Use List nodes to find it.

Check for an update

Check the current Phoenixd version and the next available release for a node.

Usage

nd check-node-update <node-id>

Required permission: Nodes → Read. Set NODANA_API_KEY before running this command.

Arguments

node-idstringRequired: ID of the node in your account. Use List nodes to find it.

If an update is available, review its version and save its releaseSha256 checksum for Update a node. If availableUpdate is null, there is no update to apply.

Update a node

Apply an available Phoenixd update you have selected.

Usage

nd update-node <node-id> --release-sha256 <checksum>

Required permission: Nodes → Write. Set NODANA_API_KEY before running this command.

Run Check for an update first. Review the available release and pass its releaseSha256 checksum. The server checks that the release is still available when you submit the update.

The node must be ready. Updating retains its data; its API may be temporarily unavailable. Use nd get-node <node-id> to check progress until the node is ready and updateStatus is succeeded.

Arguments

node-idstringRequired: ID of the node in your account. Use List nodes to find it.

Options

--release-sha256stringRequired: Checksum of the release returned by nd check-node-update.

Delete a node

Permanently delete a Phoenixd node. The command returns once deletion is accepted. Use nd list-nodes to check when the node has been removed.

Required permission: Nodes → Write. Set NODANA_API_KEY before running this command.

Usage

nd delete-node <node-id>

Replace node-123 with your node ID. The CLI asks for confirmation. Handle any remaining funds and save your recovery information before deleting the node.

Arguments

node-idstringRequired: ID of the node in your account. Use List nodes to find it.

Options

--forceflagOptional: Skip the node ID confirmation prompt.

List webhooks

List the webhook receivers configured for a node, including their URLs, descriptions and enabled states. Each node currently supports one receiver, so the list contains zero or one entry. Signing secrets are only returned when creating a webhook.

Usage

nd list-webhooks <node-id>

Required permission: Nodes → Read. Set NODANA_API_KEY before running this command.

Arguments

node-idstringRequired: ID of the node in your account. Use List nodes to find it.

Create webhook

Configure a public HTTPS URL to receive payment notifications from your node. Each node supports one webhook receiver. Save the returned signing secret in your receiver's secret settings; it is shown only when the webhook is created. See Webhook authentication to verify notifications before processing them.

Usage

nd create-webhook <node-id> --url <url>

Required permission: Nodes → Write. Set NODANA_API_KEY before running this command.

Arguments

node-idstringRequired: ID of the node in your account. Use List nodes to find it.

Options

--urlstringRequired: Public HTTPS receiver URL, up to 2048 characters, without embedded credentials.
--descriptionstringOptional: Description, up to 500 characters after trimming.

Get webhook

Read the webhook receiver configured for a node. The result contains its URL, description and enabled state, or no receiver if one has not been created. The signing secret is only returned when creating a webhook.

Usage

nd get-webhook <node-id>

Required permission: Nodes → Read. Set NODANA_API_KEY before running this command.

Arguments

node-idstringRequired: ID of the node in your account. Use List nodes to find it.

Update webhook

Change a webhook's URL, description or enabled state. Supply at least one option. Omitted options keep their current values. An empty description clears it. Disabling cancels queued deliveries; enabling resumes delivery for future events.

Usage

nd update-webhook <node-id>

Required permission: Nodes → Write. Set NODANA_API_KEY before running this command.

Arguments

node-idstringRequired: ID of the node in your account. Use List nodes to find it.

Options

--urlstringOptional: Public HTTPS receiver URL, up to 2048 characters, without embedded credentials.
--descriptionstringOptional: Description, up to 500 characters after trimming. Use an empty string to clear it.
--enabledbooleanOptional: Use true to enable delivery or false to disable it.

Delete webhook

Remove the node's webhook receiver and its delivery history. Future payment notifications stop. Save any delivery records you need before deleting it.

Usage

nd delete-webhook <node-id>

Required permission: Nodes → Write. Set NODANA_API_KEY before running this command.

Arguments

node-idstringRequired: ID of the node in your account. Use List nodes to find it.

List webhook deliveries

List the latest 50 webhook deliveries for a node, newest first. Use the delivery status, response status and last error to troubleshoot your receiver. Status can be pending, retrying, delivered, failed or cancelled. See Webhooks for delivery payload fields and payment reconciliation.

Usage

nd list-webhook-deliveries <node-id>

Required permission: Nodes → Read. Set NODANA_API_KEY before running this command.

Arguments

node-idstringRequired: ID of the node in your account. Use List nodes to find it.

Attestation

Usage

nd attest --approve-release-sha256 CHECKSUM [--url NODE_URL] [--json]

Verify that your node is running on a protected host whose boot measurements match an approved Nodana image, and that its running bundle matches your approved release checksum. Supply your node's HTTPS URL through --url or NODANA_PHOENIXD_URL.

The check requests POST /attestation through the same node URL used for payments, on the standard HTTPS port 443.

This check does not require a Phoenixd password or Nodana account login. It does not send a password, change your node or make a payment.

What is checked

The CLI requests fresh evidence from the host and verifies it locally. It checks the AWS signature and certificate chain, the freshness of the response, the approved image measurements, the running bundle identity and the connection covered by the proof.

Approved host measurements are included with the CLI release. Supply the exact bundle checksum you have independently approved using --approve-release-sha256. The node's response cannot choose either approval.

See Attestation and protected hosts for what the result tells you and the trust involved.

Get the release checksum

Open nodana-phoenixd releases, select the exact node bundle version you intend to trust and review its release notes. Under Assets, download release-sha256.txt. Copy the 64-character lowercase hexadecimal checksum from that file and pass it to --approve-release-sha256.

Use the release you expect your node to be running. A newer release's checksum will not match a node that has not been updated. release-sha256.txt identifies the canonical manifest; SHA256SUMS contains checksums of downloadable files and is not the value this command needs.

Options

--approve-release-sha256stringRequired: The approved bundle's canonical manifest SHA-256 checksum, as 64 lowercase hexadecimal characters. Verification fails if the running bundle differs.
--jsonbooleanOptional: Return the verification result as JSON for use in scripts.

Read the result

A verified result means the evidence is valid, matches this connection and identifies an approved host image and node bundle. It does not guarantee that the software is free of vulnerabilities.

The command exits with status 0 only when verification succeeds. An unavailable endpoint, invalid proof, unapproved image or mismatched bundle checksum produces an error and a non-zero exit status.

If the image is unapproved, check that you are using the correct node URL and update the CLI from the official release. If verification still fails, contact Nodana with the error message and CLI version. Do not share your password or recovery material, or disable verification to work around the error.

Verify a node

Terminal

nd attest --url https://node-a1b2.nodana.app --approve-release-sha256 APPROVED_RELEASE_SHA256

Replace the example URL with your node's HTTPS URL and APPROVED_RELEASE_SHA256 with the checksum from your selected release's release-sha256.txt file. See Get the release checksum.

Use your configured node URL

Terminal

export NODANA_PHOENIXD_URL="https://node-a1b2.nodana.app"
nd attest --approve-release-sha256 APPROVED_RELEASE_SHA256

Read the result in a script

Terminal

nd attest --approve-release-sha256 APPROVED_RELEASE_SHA256 --json

Check the command's exit status before continuing with an operation that requires a verified host.

Create BOLT11 invoice

Usage

pxd create-invoice [--description DESCRIPTION] [--description-hash DESCRIPTION_HASH] [--amount-sat AMOUNT_SAT] [--expiry-seconds EXPIRY_SECONDS] [--external-id EXTERNAL_ID] [--webhook-url WEBHOOK_URL]

Creates a Bolt11 invoice with a description.

In an interactive terminal, the command also displays a QR code for the payment request. Scan it with a Lightning wallet to pay. Redirected or piped output contains only the JSON response.

A Bolt11 invoice is a non-reusable, expirable payment request for Lightning, well suited for a retail payment flow. It can only be paid once.

Use a full or limited Phoenixd password. See Connect to your node.

Options

--descriptionstringOptional: Invoice description, up to 128 characters. Supply either --description or --description-hash.
--description-hashstringOptional: SHA-256 hash of the description, as an alternative to description.
--amount-satintegerOptional: Amount requested in satoshis. Omit to allow the payer to choose the amount.
--expiry-secondsintegerOptional: Invoice lifetime in seconds. Defaults to 3600 (one hour).
--external-idstringOptional: Your order or payment reference. Use it when looking up incoming invoices.
--webhook-urlstringOptional: Additional callback URL for this invoice, called directly by Phoenixd. Configure Nodana webhooks for notifications delivered by Nodana.

See Create BOLT11 invoice for the Phoenixd endpoint and response fields.

Command

Terminal

pxd create-invoice \
  --description "Order 1042" \
  --amount-sat "1000" \
  --expiry-seconds "600" \
  --external-id "order-1042"

Output

{
  "amountSat": 1000,
  "paymentHash": "f419207c9edde9021ebfb6bd0df6bd0a6606ecaf935357cc2f362e30835c3765",
  "serialized": "<BOLT11 invoice>"
}

Create BOLT12 offer

Usage

pxd create-offer [--description DESCRIPTION] [--amount-sat AMOUNT_SAT]

Creates a Bolt12 offer with an optional description and amount.

An offer is a static and reusable payment request that does not expire. It can be paid many times. It's well suited for donations or tips.

Note: a getoffer call is also available but it is deprecated. This getoffer endpoint returns an offer, but always the same one. createoffer should be used instead.

Use a full or limited Phoenixd password. See Connect to your node.

Options

--descriptionstringOptional: Offer description, up to 128 characters. Required when --amount-sat is provided.
--amount-satintegerOptional: Amount requested in satoshis. Omit to allow the payer to choose the amount.

See Create BOLT12 offer for the Phoenixd endpoint and response fields.

Command

Terminal

pxd create-offer \
  --description "Tips" \
  --amount-sat "100"

Output

lno1qgsyxjtl6luzd9t3pr62xr7eemp6awnejusgf6gw45q75vcfqqqqqqqgqvqcdgq2zdskugr0venx2u3qvehhygzsd9jhyun9zrhq8yecsj40r443pquhuhh7tjrteukce2xj7uqwm2vahys5lsn39vf5q2fyfxsw6xn824393en87nre87xcectkgcj85trcu5hn9r9703645qsrxtcq785whraquh5atw89w5scg707fz23405ygk7jn9uek3tkmvdqqvc8yz8xm2yme6hjx3x02csmq6pfzaejqr3kzg7u8am96txu95z8am8zgvfvfcnzk27ylwk43ut48xv2vrkhqtj3wes32glw5ft5h7f4p8ytwey4cqjsks55zcmr3hka0p8e50thjqpjytmt5wsa4ylhavdmewv7jmj2ppy9daujfmfvpmnw9cf75cymjffzh2nafn883vsqr3a8u2l797mayh3p

Get Lightning address

Usage

pxd get-ln-address

Gets a BIP-353 Lightning address from the LSP. Only works if you have a channel.

Note you can also use third-party services or self-host the address.

Use a full or limited Phoenixd password. See Connect to your node.

See Get Lightning address for the Phoenixd endpoint and response fields.

Get swap-in address

Usage

pxd get-swap-in-address

Gets an on-chain address to swap on-chain funds into Lightning.

Use a full or limited Phoenixd password. See Connect to your node.

See Get swap-in address for the Phoenixd endpoint and response fields.

Pay BOLT11 invoice

Usage

pxd pay-invoice --invoice INVOICE [--amount-sat AMOUNT_SAT] [--send-all]

Pays a BOLT11 Lightning invoice. A 0.4% fee applies. Response includes the internal paymentId for that payment.

Use the full Phoenixd password for this command.

Options

--invoicestringRequired: BOLT11 invoice to pay.
--amount-satintegerOptional: Amount in satoshis. If omitted, uses the amount in the payment request. Supply --amount-sat or --send-all for an amountless request.
--send-allbooleanOptional: Send the wallet balance when there is a single channel. Mutually exclusive with --amount-sat.

A payment_failed result means the payment failed. Check the result before treating the payment as sent. A successful result has type: "payment_sent".

See Pay BOLT11 invoice for the Phoenixd endpoint and response fields.

Command

Terminal

pxd pay-invoice \
  --invoice "$BOLT11_INVOICE"

Output

{
  "type": "payment_sent",
  "recipientAmountSat": 1,
  "routingFeeSat": 4,
  "paymentId": "961d413c-91ca-4f3d-9d91-760a08405901",
  "paymentHash": "9586b2819f3c6d3c3e087984b97dcf4b74babfcaa5da4bc4207f47c6c1cc71e0",
  "paymentPreimage": "6a3e65d9a05113864c9c27e430cc99751359ccbfa8fd5869aea46405df657986"
}

Pay BOLT12 offer

Usage

pxd pay-offer --offer OFFER [--amount-sat AMOUNT_SAT] [--send-all] [--message MESSAGE]

Pays a BOLT12 Lightning offer. A 0.4% fee applies. Response includes the internal paymentId for that payment.

Use the full Phoenixd password for this command.

Options

--offerstringRequired: BOLT12 offer to pay.
--amount-satintegerOptional: Amount in satoshis. If omitted, uses the amount in the payment request. Supply --amount-sat or --send-all for an amountless request.
--send-allbooleanOptional: Send the wallet balance when there is a single channel. Mutually exclusive with --amount-sat.
--messagestringOptional: Optional message for the recipient; the receiving service may restrict its length.

A payment_failed result means the payment failed. Check the result before treating the payment as sent. A successful result has type: "payment_sent".

See Pay BOLT12 offer for the Phoenixd endpoint and response fields.

Command

Terminal

pxd pay-offer \
  --offer "$BOLT12_OFFER" \
  --amount-sat "123"

Output

{
  "type": "payment_sent",
  "recipientAmountSat": 123,
  "routingFeeSat": 4,
  "paymentId": "889c26f1-3028-4fae-9bd9-130c6e93542f",
  "paymentHash": "54ed3cadcd102a475f7e7bd25a89223b46514df72c01c4fa9880aed7a795eb16",
  "paymentPreimage": "09820bd4915f91ab21377879d5182c1bcf35feabdda5933266a99b4126f32b9b"
}

Pay Lightning address

Usage

pxd pay-ln-address --address ADDRESS [--amount-sat AMOUNT_SAT] [--send-all] [--message MESSAGE]

Pays an email-like Lightning address, either based on BIP-353 or LNURL. A 0.4% fee applies. Response includes the internal paymentId for that payment.

Use the full Phoenixd password for this command.

Options

--addressstringRequired: Lightning address using BIP-353 or LNURL.
--amount-satintegerOptional: Amount in satoshis. Supply --amount-sat or --send-all; Lightning addresses do not supply a default amount.
--send-allbooleanOptional: Send the wallet balance when there is a single channel. Mutually exclusive with --amount-sat.
--messagestringOptional: Optional message for the recipient; the receiving service may restrict its length.

A payment_failed result means the payment failed. Check the result before treating the payment as sent. A successful result has type: "payment_sent".

See Pay Lightning address for the Phoenixd endpoint and response fields.

Command

Terminal

pxd pay-ln-address \
  --address "$LIGHTNING_ADDRESS" \
  --amount-sat "123"

Output

{
  "type": "payment_sent",
  "recipientAmountSat": 123,
  "routingFeeSat": 4,
  "paymentId": "a9b1b8f8-bfdb-4299-9979-18e616bc9259",
  "paymentHash": "bfa554308df2f397cd23ba724316660aaa398b2044b3e4e15ed79b8f2b278679",
  "paymentPreimage": "dc4a8e059599d464d9ea10dfc0ffe6ad23a898c897c42dad973716e85c26a920"
}

Pay on-chain

Usage

pxd send-to-address --amount-sat AMOUNT_SAT --address ADDRESS --feerate-sat-byte FEERATE_SAT_BYTE

Sends part of your current balance to a Bitcoin address. The spliced channel is not closed and remains active. Returns the transaction id if the splice was successful.

Use the full Phoenixd password for this command.

Options

--amount-satintegerRequired: Amount to send in satoshis.
--addressstringRequired: Destination Bitcoin address.
--feerate-sat-byteintegerRequired: Fee rate in satoshis per virtual byte.

The response is plain text. Check that it contains a transaction ID: an unsuccessful action can return an explanatory message.

See Pay on-chain for the Phoenixd endpoint and response fields.

Bump fee

Usage

pxd bump-fee --feerate-sat-byte FEERATE_SAT_BYTE

Makes all your unconfirmed transactions use a higher fee rate, using CPFP. Returns the ID of the child transaction.

Use the full Phoenixd password for this command.

Options

--feerate-sat-byteintegerRequired: Fee rate in satoshis per virtual byte.

The response is plain text. Check that it contains a transaction ID: an unsuccessful action can return an explanatory message.

See Bump fee for the Phoenixd endpoint and response fields.

List incoming payments

Usage

pxd list-incoming-payments [--from FROM] [--to TO] [--limit LIMIT] [--offset OFFSET] [--all] [--external-id EXTERNAL_ID]

Lists incoming payments.

Use a full or limited Phoenixd password. See Connect to your node.

Options

--fromintegerOptional: Start time in Unix milliseconds. Defaults to 0.
--tointegerOptional: End time in Unix milliseconds. Defaults to now.
--limitintegerOptional: Number of payments to return. Defaults to 20.
--offsetintegerOptional: Pagination offset. Defaults to 0.
--allbooleanOptional: Include unpaid invoices.
--external-idstringOptional: Only return payments with this external ID.

See List incoming payments for the Phoenixd endpoint and response fields.

Command

Terminal

pxd list-incoming-payments \
  --all \
  --limit "5" \
  --offset "0"

Output

[
  {
    "type": "incoming_payment",
    "subType": "lightning",
    "paymentHash": "5307f75da2a466d75c43593f45d4452853ba745860c008c61d3d0d0f24789b6d",
    "preimage": "bfad93c6eff005d7d130a3a88fa7be269da26861063c20ad41e935fd5d174c3f",
    "description": "1000 sat expiry 100s",
    "invoice": "lntb10u1p5960u8pp52vrlwhdz53ndwhzrtyl5t4z99pfm5azcvrqq33sa85xs7frcndkscqzyssp58...",
    "isPaid": false,
    "isExpired": true,
    "requestedSat": 1000,
    "receivedSat": 0,
    "fees": 0,
    "expiresAt": 1750941675827,
    "createdAt": 1750941575827
  },
  {
    "type": "incoming_payment",
    "subType": "lightning",
    "paymentHash": "595a3f4824254c6fdbf0b07ba5bcc3953abbdce94e583085683d102e5e85338a",
    "preimage": "ccfbc77a825d37a4f82b3a4ff3f278e92a46e232e7310efd5836a6bccf845528",
    "description": "1000 sat expiry 250s",
    "invoice": "lntb10u1p596skepp5t9dr7jpyy4xxlklskpa6t0xrj5athh8ffevrpptg85gzuh59xw9qcqzyssp59...",
    "isPaid": true,
    "isExpired": false,
    "requestedSat": 1000,
    "receivedSat": 1050,
    "fees": 0,
    "expiresAt": 1750942676001,
    "completedAt": 1750942477605,
    "createdAt": 1750942426001
  },
  {
    "type": "incoming_payment",
    "subType": "lightning",
    "paymentHash": "1399476fe927fd02523ae203d05e3badeb27ee951c4d5dfdd06ba7f2d713864f",
    "preimage": "a17e7be515418882adf36fbafae20d5bcf6e17bf17b6e08a1b4b5912e537574a",
    "description": "amountless invoice",
    "invoice": "lntb1p5963w3pp5zwv5wmlfyl7sy536ugpaqh3m4h4j0m54r3x4mlwsdwnl94cnse8scqzyssp5tc5j...",
    "isPaid": true,
    "isExpired": false,
    "receivedSat": 1500,
    "fees": 0,
    "expiresAt": 1751029585548,
    "completedAt": 1750943212490,
    "createdAt": 1750943185548
  },
  {
    "type": "incoming_payment",
    "subType": "lightning",
    "paymentHash": "b215bf7745a7d5250be2535b723dd881368c4c4dbd44819cbb0ca7d2d02ee140",
    "preimage": "2ddcc7fd888f5c524e69c2a6e5ddd89a701b60c73746697568d438aa1cdbdafa",
    "isPaid": true,
    "receivedSat": 352,
    "fees": 0,
    "payerKey": "02da45cf516282e6959e48c26d6ed5f98bf7c32248193439bd1d22de81ae897426",
    "completedAt": 1738677427800,
    "createdAt": 1738677427800
  },
  {
    "type": "incoming_payment",
    "subType": "lightning",
    "paymentHash": "9d1f404813f02b86ef177cffd2405f76010fafa98728d0c6ba57ba66f3736f7f",
    "preimage": "1bd574c090c1214299449a6a0a23a7dc906b310b6e2d2afcabeb2d707205abb9",
    "isPaid": true,
    "receivedSat": 100000,
    "fees": 0,
    "payerKey": "02da45cf516282e6959e48c26d6ed5f98bf7c32248193439bd1d22de81ae897426",
    "completedAt": 1738676523881,
    "createdAt": 1738676523881
  }
]

Get incoming payment

Usage

pxd get-incoming-payment --payment-hash PAYMENT_HASH

Look up an incoming payment by its payment hash. Check isPaid and receivedSat before fulfilling an order. isExpired indicates that an unpaid invoice can no longer be paid.

Use a full or limited Phoenixd password. See Connect to your node.

Payment lookup

--payment-hashstringRequired: Payment hash as a hexadecimal string.

See Get incoming payment for the Phoenixd endpoint and response fields.

Command

Terminal

pxd get-incoming-payment \
  --payment-hash "$PAYMENT_HASH"

Output

{
  "type": "incoming_payment",
  "subType": "lightning",
  "paymentHash": "1399476fe927fd02523ae203d05e3badeb27ee951c4d5dfdd06ba7f2d713864f",
  "preimage": "a17e7be515418882adf36fbafae20d5bcf6e17bf17b6e08a1b4b5912e537574a",
  "description": "amountless invoice",
  "invoice": "lntb1p5963w3pp5zwv5wmlfyl7sy536ugpaqh3m4h4j0m54r3x4mlwsdwnl94cnse8scqzyssp5tc5j...",
  "isPaid": true,
  "isExpired": false,
  "receivedSat": 1500,
  "fees": 0,
  "expiresAt": 1751029585548,
  "completedAt": 1750943212490,
  "createdAt": 1750943185548
}

List outgoing payments

Usage

pxd list-outgoing-payments [--from FROM] [--to TO] [--limit LIMIT] [--offset OFFSET] [--all]

Lists outgoing payments.

Use a full or limited Phoenixd password. See Connect to your node.

Options

--fromintegerOptional: Start time in Unix milliseconds. Defaults to 0.
--tointegerOptional: End time in Unix milliseconds. Defaults to now.
--limitintegerOptional: Number of payments to return. Defaults to 20.
--offsetintegerOptional: Pagination offset. Defaults to 0.
--allbooleanOptional: Include failed payments.

See List outgoing payments for the Phoenixd endpoint and response fields.

Command

Terminal

pxd list-outgoing-payments \
  --all \
  --limit "5" \
  --offset "0"

Output

[
  {
    type: "outgoing_payment",
    subType: "auto_liquidity",
    paymentId: "7ad2ac96-1ff9-47ae-9013-b02203c55b93",
    txId: "53d85c7e1c5c667f5358666bafd0bce78295d6a87946f984133c9d8efe0b357d",
    isPaid: true,
    sent: 26850,
    fees: 26850000,
    completedAt: 1728565522629,
    createdAt: 1728565522382,
  },
  {
    type: "outgoing_payment",
    subType: "lightning",
    paymentId: "9c020753-795c-40a9-b30e-b898b2ba80f5",
    paymentHash: "8125523666c317232342a6c01cc1f22a00affa958428eb9b8d7dc174fd4c2ddf",
    preimage: "0d9074340788444faca4a64d587febaac8bfb4cb811aabdf7ad2a2671647e425",
    isPaid: true,
    sent: 5,
    fees: 4004,
    completedAt: 1738348590680,
    createdAt: 1738348589678,
  },
  {
    type: "outgoing_payment",
    subType: "lightning",
    paymentId: "dddfb160-f5dc-4930-b0d9-bc7a2ebf7b21",
    paymentHash: "9727389e1c776f4efb315c4effae02affcb723883d13433ea74cc9e3f2034a93",
    preimage: "e21f2f734d298a28fb77474ba11510c425566203daa0f9820706d6bfa75e4faa",
    isPaid: true,
    sent: 8,
    fees: 4016,
    invoice: "lntb1pne6xpnpp5junn38suwah5a7e3t380ltsz4l7twgug85f5x048fny78usrf2fscqzyssp5d4wu...",
    completedAt: 1738348627503,
    createdAt: 1738348626053,
  },
];

Get outgoing payment

Usage

pxd get-outgoing-payment (--payment-id PAYMENT_ID | --payment-hash PAYMENT_HASH)

Look up an outgoing payment by its internal payment ID or payment hash. Use the ID returned by the payment request. Check isPaid and completedAt when reconciling an interrupted request.

Use a full or limited Phoenixd password. See Connect to your node.

Payment lookup

--payment-idstringOptional: Internal payment UUID.
--payment-hashstringOptional: Payment hash to look up instead of the internal payment ID.

For outgoing Lightning payments, isPaid: true with completedAt indicates success. isPaid: false with no completedAt is pending; isPaid: false with completedAt indicates failure.

Supply either --payment-id or --payment-hash to choose the lookup.

See Get outgoing payment for the Phoenixd endpoint and response fields.

Command

Terminal

pxd get-outgoing-payment \
  --payment-id "$PAYMENT_ID"

Look up by payment hash

Terminal

pxd get-outgoing-payment --payment-hash "$PAYMENT_HASH"

Output

{
  "type": "outgoing_payment",
  "subType": "lightning",
  "paymentId": "dddfb160-f5dc-4930-b0d9-bc7a2ebf7b21",
  "paymentHash": "9727389e1c776f4efb315c4effae02affcb723883d13433ea74cc9e3f2034a93",
  "preimage": "e21f2f734d298a28fb77474ba11510c425566203daa0f9820706d6bfa75e4faa",
  "isPaid": true,
  "sent": 8,
  "fees": 4016,
  "invoice": "lntb1pne6xpnpp5junn38suwah5a7e3t380ltsz4l7twgug85f5x048fny78usrf2fscqzyssp5d4wu...",
  "completedAt": 1738348627503,
  "createdAt": 1738348626053
}

CSV export

Usage

pxd export-payments [--from FROM] [--to TO]

Exports your successful payments history in a CSV file. Returns the path of the generated file on your file system.

The resulting CSV allows precise tracking of the balance and fee credit, and shows the split between mining and service fees:

balance: sum of all amount_msat;
fee credit: sum of all fee_credit_msat.

The returned path is on the machine or container running Phoenixd. Retrieve the file there; the response body is a message containing its path.

Use a full or limited Phoenixd password. See Connect to your node.

Options

--fromintegerOptional: Start time in Unix milliseconds. Defaults to 0.
--tointegerOptional: End time in Unix milliseconds. Defaults to now.

See CSV export for the Phoenixd endpoint and response fields.

Get node info

Usage

pxd get-info

Read the Lightning node ID and a compact summary of its channels. Channel balances, inbound liquidity and capacity are expressed in satoshis.

Use a full or limited Phoenixd password. See Connect to your node.

See Get node info for the Phoenixd endpoint and response fields.

Command

Terminal

pxd get-info

Output

{
  "nodeId": "023a882b070d0b9b1c8db2975f2dcc65d1ffa22e00085506ab24799d6d95d658a2",
  "channels": [
    {
      "state": "Normal",
      "channelId": "853c38dae30b4252cddcf3c87fc69f63313813cc5a0d06921d8a8d1f4c5f0692",
      "balanceSat": 10,
      "inboundLiquiditySat": 1013562,
      "capacitySat": 1015160,
      "fundingTxId": "3ed12fe931d1bc32ba94de8311f21016443ff6af338ac4e58b1b9ce2bd07dbf6"
    }
  ]
}

Get balance

Usage

pxd get-balance

Read the available balance and fee credit, both in satoshis.

Use a full or limited Phoenixd password. See Connect to your node.

See Get balance for the Phoenixd endpoint and response fields.

List channels

Usage

pxd list-channels

Read detailed channel state. For a compact channel summary, use Get node info. The example shows an excerpt; available fields depend on channel state.

Use a full or limited Phoenixd password. See Connect to your node.

See List channels for the Phoenixd endpoint and response fields.

Command

Terminal

pxd list-channels

Output

[
  {
    "type": "fr.acinq.lightning.channel.states.Normal",
    "commitments": {
      "params": {
        "channelId": "caeda5a5ad278221c0ec995d667a607b7f7e006f7c092872783acf2015fa6455"
      }
    },
    "shortChannelId": "0x7410060x0"
  }
]

Close channel

Usage

pxd close-channel --channel-id CHANNEL_ID --address ADDRESS --feerate-sat-byte FEERATE_SAT_BYTE

Closes a given channel, and send all funds to an on-chain address. Returns the ID of the closing transaction.

Attention: closing a channel is final, it cannot be cancelled.

Use the full Phoenixd password for this command.

Options

--channel-idstringRequired: ID of the channel to close.
--addressstringRequired: Bitcoin address to receive the channel balance.
--feerate-sat-byteintegerRequired: Fee rate in satoshis per virtual byte.

The response is plain text. An unsuccessful action can return an explanatory message; confirm the closing transaction ID before reporting success.

See Close channel for the Phoenixd endpoint and response fields.

Decode invoice

Usage

pxd decode-invoice --invoice INVOICE

Use a full or limited Phoenixd password. See Connect to your node.

Options

--invoicestringRequired: BOLT11 invoice to decode.

See Decode invoice for the Phoenixd endpoint and response fields.

Command

Terminal

pxd decode-invoice \
  --invoice "$BOLT11_INVOICE"

Output

{
  "chain": "testnet",
  "amount": 1000,
  "paymentHash": "06456ca4abe420d370791ccc1df06548b6a43d0097129e902c6a87edf4fc1deb",
  "description": "1 Blockaccino",
  "minFinalCltvExpiryDelta": 18,
  "paymentSecret": "e45a8da063257ad672198d3bfd355254e05e65d90703c76127cf26f0dbdba7f7",
  "paymentMetadata": "2a",
  "extraHops": [
    [
      {
        "nodeId": "03933884aaf1d6b108397e5efe5c86bcf2d8ca8d2f700eda99db9214fc2712b134",
        "shortChannelId": "16734014x14719942x36770",
        "feeBase": 1000,
        "feeProportionalMillionths": 100,
        "cltvExpiryDelta": 144
      }
    ]
  ],
  "features": {
    "activated": {
      "var_onion_optin": "Mandatory",
      "payment_secret": "Mandatory",
      "basic_mpp": "Optional",
      "option_payment_metadata": "Optional",
      "trampoline_payment_experimental": "Optional"
    },
    "unknown": []
  },
  "timestampSeconds": 1720025399
}

Decode offer

Usage

pxd decode-offer --offer OFFER

Use a full or limited Phoenixd password. See Connect to your node.

Options

--offerstringRequired: BOLT12 offer to decode.

See Decode offer for the Phoenixd endpoint and response fields.

Command

Terminal

pxd decode-offer \
  --offer "$BOLT12_OFFER"

Output

{
  "chain": "mainnet",
  "chainHashes": ["43497fd7f826957108f4a30fd9cec3aeba79972084e90ead01ea330900000000"],
  "path": [
    {
      "introductionNodeId": {
        "publicKey": "03933884aaf1d6b108397e5efe5c86bcf2d8ca8d2f700eda99db9214fc2712b134"
      },
      "blindingKey": "021aeddbf39bf6e9a69bf331c7a5a524a55efaffd6643c127f66378d0ace9529f4",
      "blindedNodes": [
        {
          "blindedPublicKey": "0339e5efc9f4935ae8f84f6db02abf2450422e1fe8ac2e2080f479b1eccf37e1a7",
          "encryptedPayload": "9361a42a22f03b70d5039b8f53db5a2e81b83079fe4301d0284b7c18b2ceba42d4b43c168672593ba126d32b88cafdf49c49e7"
        },
        {
          "blindedPublicKey": "031448f2aa7355336a93fe304a4e14642881d42df65ceae73008a2985840bf8295",
          "encryptedPayload": "00cc1620abfa6e70199fc10175c6c186"
        }
      ]
    }
  ]
}

Estimate liquidity fees

Usage

pxd estimate-liquidity-fees --amount-sat AMOUNT_SAT

Estimates a liquidity fee for a given amount. Note that it depends on the current mining feerate, which is volatile. The estimate returned is the full cost and does not take into account any fee credit you may have.

Use a full or limited Phoenixd password. See Connect to your node.

Options

--amount-satintegerRequired: Liquidity amount in satoshis.

See Estimate liquidity fees for the Phoenixd endpoint and response fields.

LNURL Pay

Usage

pxd lnurl-pay --lnurl LNURL [--amount-sat AMOUNT_SAT] [--send-all] [--message MESSAGE]

Pays a LNURL-pay resource. Note that the service may apply restrictions on the amount to pay or the message -- the lnurl-pay flow is usually interactive.

Use the full Phoenixd password for this command.

Options

--lnurlstringRequired: LNURL-pay resource.
--amount-satintegerOptional: Amount to pay in satoshis. If omitted with --send-all unset, uses the minimum accepted by the service.
--send-allbooleanOptional: Send the wallet balance when there is a single channel. Mutually exclusive with --amount-sat.
--messagestringOptional: Optional message for the recipient; the receiving service may restrict its length.

A payment_failed result means the payment failed. Check the returned type and reconcile uncertain attempts using Get outgoing payment.

See LNURL Pay for the Phoenixd endpoint and response fields.

Command

Terminal

pxd lnurl-pay \
  --lnurl "$LNURL" \
  --amount-sat "123"

Output

{
  "type": "payment_sent",
  "recipientAmountSat": 123,
  "routingFeeSat": 4,
  "paymentId": "2ff3c4f2-1d97-4dc0-a522-371591c058dc",
  "paymentHash": "6a0084471b2020373a89a81b5f7e34135154f24208e491d0122d99a686b1d58d",
  "paymentPreimage": "5746edcdbf872fc508939f31f18998f294d579668f334a023804b992b0fe4842"
}

LNURL Withdraw

Usage

pxd lnurl-withdraw --lnurl LNURL

Withdraws funds from a LNURL service. Phoenixd will withdraw the maximum amount authorized by the service.

Use a full or limited Phoenixd password. See Connect to your node.

Options

--lnurlstringRequired: LNURL-withdraw resource.

See LNURL Withdraw for the Phoenixd endpoint and response fields.

Command

Terminal

pxd lnurl-withdraw \
  --lnurl "$LNURL"

Output

{
  "url": "https://lnurl.fiatjaf.com/lnurl-withdraw?session=e9bb1406ed5a198e548c99c201f5dd359458af96f673fb0dfa09f712113669e4",
  "minWithdrawable": 1000,
  "maxWithdrawable": 4000,
  "description": "sample withdraw",
  "k1": "1649e2443dd004421e05e08a17e52ee1454e9f74aacedacc822777b9ff4ffbfb",
  "invoice": "lnbc40n1pnfqpstpp5npnnapuxylxelsat27q4dncgj...2f0tvfw33kspxfenxx"
}

LNURL Auth

Usage

pxd lnurl-auth --lnurl LNURL

Authenticates a LNURL-auth resource to allow an action on a remote service. See LUD-04 for details.

Note: The key used to sign is derived from the wallet's key (derivation depends on the lnurl service's domain). If you have different users using the same phoenixd instance, do not let them use this or they will share the same signature and pubkey!

Use the full Phoenixd password for this command.

Options

--lnurlstringRequired: LNURL-auth resource.

See LNURL Auth for the Phoenixd endpoint and response fields.