Introduction

Use the Nodana API to create and manage hosted nodes and webhook receivers. Use your node’s Phoenixd API for invoices, Lightning payments, balances, channels and LNURL services.

API addresses

API	Base URL	Authentication
Nodana management	`https://api.nodana.io/v1`	Bearer API key
Phoenixd	Your node’s HTTPS URL	HTTP Basic with an empty username and Phoenixd password

Host attestation uses your node’s HTTPS URL without an Authorization header.

Examples use https://node-a1b2.nodana.app as a dummy node URL. Replace it with your node’s complete HTTPS connection URL. Keep API keys and passwords in your backend’s secret configuration.

Nodana management endpoint paths are relative to https://api.nodana.io/v1; requests use JSON bodies. Phoenixd endpoint paths are relative to your node URL; POST parameters use form data and payment-history filters use query parameters. See Authentication.

Manage hosted nodes

Create a node: start provisioning and save the one-time credentials returned in the response.
List nodes: find your node IDs and statuses.
Update a node: select and apply an available release.
Webhooks: receive and verify payment notifications.
Attestation: request evidence for client-side verification of a protected Nodana host.

Work with Phoenixd

Payments: create invoices and offers, send funds, track payments and export history.
Node: inspect balances and channels, decode payment requests and estimate liquidity fees.
LNURL: pay, withdraw and authenticate with LNURL services.
WebSocket: subscribe to incoming payments.

The upstream reference describes the daemon API.

See Responses, Error handling and Rate limiting. Compact endpoint lists are available for the Nodana API and Phoenixd API.

List your hosted nodes

curl "https://api.nodana.io/v1/nodes" \
  -H "Authorization: Bearer $NODANA_API_KEY"

Read Phoenixd node information

curl "https://node-a1b2.nodana.app/getinfo" \
  -u ":$PHOENIXD_PASSWORD"

Authentication

Choose credentials for the API you are calling: a Nodana account API key for hosted-node and webhook management, or your node’s Phoenixd password for payments and node information.

Nodana

For direct API integrations, authenticate node operations with an API key in the Authorization header.

Create an API key

In the dashboard, open Developers, then API Keys. Create a key for your integration and select the permissions it needs. Save the full key when it is shown; it cannot be retrieved later.

Send authenticated requests

Send your key as Authorization: Bearer YOUR_API_KEY. Replace the placeholder with your API key.

For Lightning operations, use your node URL and Phoenixd password with the Phoenixd API or CLI.

Permissions

Permission	Scope	Operations
Nodes → Read	`nodes:read`	List nodes, read details, check available updates and read webhook settings and deliveries
Nodes → Write	`nodes:write`	Create, rename, start, stop, restart, update or delete nodes; create, change or delete their webhook endpoint

Write also requires Read. Choose the minimum permissions your integration needs.

Keys belong to one account. The API uses the key to determine your account; you do not need to send an account ID. The key must include the required permission. Missing, invalid, disabled, or revoked keys and insufficient permissions return 401 Unauthorized. Nodes belonging to another account return 404 Not Found.

Keep keys private

Use keys from your backend or trusted scripts. Store them in secret storage, keep them out of browser code and source control, and revoke or replace them if exposed.

A Nodana API key authenticates calls to the Nodana API. Your node's Phoenixd password is a separate credential for direct calls to its Phoenixd API.

Phoenixd

Use HTTP Basic authentication with an empty username and your Phoenixd password. Replace the dummy URL with your node’s connection URL and keep PHOENIXD_PASSWORD in your backend’s environment or secret storage. JavaScript examples in this reference run on the server with Node.js.

Phoenixd creates its passwords on first start. For a self-hosted daemon, find http-password and http-password-limited-access in ~/.phoenix/phoenix.conf, or the corresponding directory on your persistent volume.

The full password permits all operations, including spending funds. Prefer the limited password for reading information and creating invoices. Each endpoint page states the access it needs. Use the full password for spending, channel closure and other operations marked as full access.

For remote requests, use the complete HTTPS connection URL and leave certificate verification enabled. Keep both passwords private, including the limited password. Store them in backend secret settings and replace exposed credentials on the node. Do not put credentials in browser code, URLs or source control.

Attestation

The node’s attestation endpoint does not require a Phoenixd password or Nodana API key. Supply the challenge described on its endpoint page without an Authorization header.

Nodana API

Authenticated request

curl "https://api.nodana.io/v1/nodes" \
  -H "Authorization: Bearer YOUR_API_KEY"

Your API key

Create a key in Developers → API Keys in the dashboard. The example reads nodes and requires Nodes → Read.

Your key selects the account; you do not need an account ID in the request. Never put the key in browser code or shared examples.

Phoenixd API

Request

curl "https://node-a1b2.nodana.app/getbalance" \
  -u ":$PHOENIXD_PASSWORD"

Responses

Read the response format on each endpoint page. Nodana management and Phoenixd return different response shapes and timestamp units.

Nodana

Node reads and start, stop, restart and update operations return node metadata. Lists wrap objects in nodes. Creation returns {node, credentials}; save the one-time recovery seed and passwords from credentials when the response arrives. Node creation and lifecycle operations continue in the background after 202 Accepted. Node deletion returns 202 with no body.

Node response fields

Field	Type	Description
`id`	string	Nodana node ID
`name`	string	Display name
`region`	string	Hosting region
`image`	string	Node software image identifier
`accessMode`	string	Node access mode
`status`	string	Node lifecycle state
`publicUrl`	string or null	Phoenixd HTTPS URL, or null while being set up
`failureMessage`	string or null	Public failure message
`updateStatus`	string or null	Update progress or outcome
`updateCompletedAt`	integer or null	Update completion time in Unix seconds
`lastCheckedAt`	integer or null	Last status check in Unix seconds
`createdAt`	integer	Creation time in Unix seconds
`updatedAt`	integer	Last change time in Unix seconds

Node states

Node states include provisioning, ready, starting, stopping, stopped, restarting, updating, failed, deleting, deleted and cordoned. stopped means the user took the node offline; cordoned means it was suspended because the account ran out of credit.

For shared response handling, see Error handling and Rate limiting.

Webhook responses

Reading a receiver returns {endpoint: {...}}, or {endpoint: null} when none is configured. Creating one returns {endpoint, signingSecret}; save the secret immediately because it is only returned once. Updating returns the endpoint object, and deleting returns 204 No Content without a body.

Delivery history wraps the latest 50 records in deliveries. Its timestamps, and node metadata timestamps, use Unix seconds.

Phoenixd

Read the response format on each endpoint page. Phoenixd returns JSON objects or arrays for structured results, and plain text for offers, addresses and some node actions. Invoice creation returns the invoice in serialized alongside its paymentHash.

Payment lists are arrays, paginated with limit and offset. Date filters and payment timestamps use Unix milliseconds. Fields named amountSat, balanceSat, receivedSat and feeCreditSat use satoshis. Payment-history fees values use millisatoshis; do not infer their unit from the routingFeeSat field returned by a payment attempt.

Optional fields can be absent. Read isPaid to confirm a payment and check receivedSat against the expected order amount. Preserve the payment hash or ID so you can look up an uncertain result. See Error handling.

Nodana API

Example node response

{
  "id": "node-123",
  "name": "Website payments",
  "status": "ready",
  "publicUrl": "https://node-abcd.nodana.app",
  "failureMessage": null,
  "updateStatus": null,
  "updateCompletedAt": null,
  "createdAt": 1790852400,
  "updatedAt": 1790852400
}

Response shapes

Listing returns {nodes: [...]}. Creation returns {node, credentials} with seed, password and restrictedPassword. Save these values securely immediately; creation credentials are returned only once.

Background operations

A 202 Accepted response means the operation is still running. Use Get a node to check its status.

Phoenixd API

Balance

{
  "balanceSat": 104228,
  "feeCreditSat": 391
}

Error handling

Check the HTTP status and response body before treating an operation as successful. Handle errors according to the API you called.

Nodana

Check the HTTP status before reading a response as a successful result. API errors return an error object containing a stable code and a human-readable message.

Use the code and status for application logic. Keep the message for diagnostics rather than matching its wording.

Status codes

For 400, check the input and the operation's state requirements. For 401, check your key and permissions. For 404, check the node ID and whether it was deleted. For 429, wait for the Retry-After interval.

If credit or billing prevents the operation (402), resolve the account's credit or billing state. Server and upstream failures (500, 502, 503) require checking the outcome before retrying a mutation.

Malformed JSON or unsupported request content types may be rejected before the endpoint runs. Handle unexpected or non-JSON error bodies as well.

Retry carefully

Retry reads after transient failures using bounded exponential backoff. For 429 responses, follow the rate limiting guidance.

A timeout or connection error does not establish that a mutation failed. Check node state before repeating a lifecycle operation. After an interrupted create request, list your nodes and reconcile the outcome before trying again. Each creation attempt requires a new requestId; repeating an accepted request returns 409 Conflict. Credentials are returned only once. If the node was created but you did not receive its credentials, contact Nodana before attempting another creation.

A 202 Accepted creation response means provisioning is still in progress. A successful update request also starts background work; inspect the node to determine the final outcome.

Phoenixd

Check the HTTP status and the endpoint's response body before treating an operation as successful. Response bodies vary by operation.

For 401, check the Phoenixd password, empty Basic-auth username and the endpoint's required access. For invalid parameters, check the field names, amount units and form encoding. If a payment lookup returns 404, check the hash or payment ID and the node URL.

A successful HTTP response alone does not establish that money moved. Inspect the returned payment or action result and use Get incoming payment or Get outgoing payment to confirm its outcome.

Interrupted requests

If an outgoing payment times out, look it up before submitting another payment. A lost response does not mean the payment failed. Save payment IDs and hashes in your backend so you can reconcile them.

Keep your application's invoice creation and fulfilment records. Use externalId to associate invoices with orders and list incoming payments to find them after an interrupted request. Reusing an external ID does not prevent another invoice from being created.

Nodana API

Example error response

{
  "error": {
    "code": "unauthorized",
    "message": "authentication required"
  }
}

HTTP status codes

Status	Meaning	What to do
`400`	Invalid input or node state	Check request fields and the operation's state requirements.
`401`	Authentication or permission mismatch	Check the API key and permissions.
`402`	Account credit or billing prevents the operation	Check account credit and billing.
`409`	Request conflicts with an existing resource or accepted creation	Check the original request and its settings.
`404`	Node not found	Check the identifiers and whether the node was deleted.
`429`	Rate limit exceeded	Wait for `Retry-After` before retrying.
`500`	Unexpected server error	Record the failure and reconcile the operation's outcome.
`502`	Upstream request failed	Retry reads with backoff; reconcile mutations first.
`503`	A dependency or required service is unavailable	Retry with backoff when the service recovers.

Rate limiting

Limit concurrency and avoid tight polling loops. The Nodana management API and your node’s Phoenixd connection have separate throttling behaviour.

Nodana

Node operations share a request limit per client IP address. Requests from applications behind the same outbound IP count towards the same limit, even when they use different API keys.

Most Nodana operations default to 180 requests per 60-second window. Node creation uses a separate default limit of 10 requests per 60 seconds. Use the response headers to decide when to retry; deployed limits can change.

Rate-limit responses

When the limit is exceeded, the API returns 429 Too Many Requests with these headers:

Retry-After tells you how many seconds to wait before retrying. X-RateLimit-Limit and X-RateLimit-Remaining describe the window, while X-RateLimit-Reset is a reset interval in seconds rather than a Unix timestamp.

These headers are returned on rate-limit errors. Do not rely on receiving them with every successful request.

View response headers

Use curl -i to include response headers when inspecting a request.

Handle throttling

Wait at least the Retry-After interval before retrying, and add a small random delay when multiple workers share an IP. Limit concurrent requests and avoid tight polling loops during node provisioning or updates.

For network failures and other transient errors, use bounded backoff rather than continuously retrying. See Error handling for reconciling requests whose outcome is uncertain.

Phoenixd

Control concurrency in your client and avoid tight polling loops. Use WebSocket for incoming payment notifications, and query payment history to reconcile missed events.

Handle throttling

If your connection endpoint returns 429 Too Many Requests, pause requests and follow Retry-After when present. It tells you how many seconds to wait. Reduce concurrency if requests continue to be throttled.

For network failures and other transient errors, use bounded backoff. Check the outcome of an interrupted payment before sending it again. See Error handling.

Inspect response headers

Use curl -i to include response headers when inspecting a request.

Nodana API

Rate-limit response

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 180
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 60

{
  "error": {
    "code": "rate_limited",
    "message": "rate limit exceeded"
  }
}

Header reference

Header	Meaning
`Retry-After`	Seconds to wait before retrying
`X-RateLimit-Limit`	Request limit for the window
`X-RateLimit-Remaining`	Remaining requests; `0` when limited
`X-RateLimit-Reset`	Reset interval in seconds, not a Unix timestamp

Inspect response headers

curl -i "https://api.nodana.io/v1/nodes" \
  -H "Authorization: Bearer YOUR_API_KEY"

Phoenixd API

Rate-limit response

HTTP/1.1 429 Too Many Requests
Retry-After: 1

Inspect response headers

curl -i "https://node-a1b2.nodana.app/getinfo" \
  -u ":$PHOENIXD_PASSWORD"

List nodes

List the active nodes in your account. Deleted nodes are excluded.

GET/nodes

Required permission: Nodes → Read.

Request

curl "https://api.nodana.io/v1/nodes" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "nodes": [
    {
      "id": "node-123",
      "name": "Website payments",
      "status": "ready",
      "publicUrl": "https://node-abcd.nodana.app",
      "failureMessage": null,
      "updateStatus": null,
      "updateCompletedAt": null,
      "createdAt": 1790852400,
      "updatedAt": 1790852400
    }
  ]
}

Create a node

Start setting up a Phoenixd node in your account.

POST/nodes

Required permission: Nodes → Write.

Body parameters

requestIdstringRequired: A random 128-bit identifier encoded as 32 hexadecimal characters. Use a new identifier for each creation attempt. Repeating an accepted request returns a conflict.
namestringOptional: Display name, up to 16 characters after trimming. Omit it or leave it blank to use a generated name.
autoLiquiditystringRequired: Choose 2m, 5m or 10m for automatic liquidity.

The response contains node metadata and one-time credentials: the recovery seed, full-access password and restrictedPassword. Save the credentials in your secret store when this response arrives. Keep them out of logs and conversation output. The node continues launching in the background; use Get a node to check its status before sending payments. If launch fails, discard these credentials and create a new node.

Creation requires sufficient account credit and available capacity. A 402 response means you need to add credit; a 503 node_capacity_unavailable response means capacity is currently full.

Request

Set NODANA_REQUEST_ID to a new random 128-bit hexadecimal identifier for this attempt.

const response = await fetch("https://api.nodana.io/v1/nodes", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.NODANA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    requestId: process.env.NODANA_REQUEST_ID,
    name: "Payments",
    autoLiquidity: "2m",
  }),
});
if (!response.ok) throw new Error("Create failed: " + response.status);
const created = await response.json();
// Save created.credentials in your application's secret store.
console.log({ nodeId: created.node.id, status: created.node.status });

Response

{
  "node": {
    "id": "node-abcd",
    "name": "Payments",
    "status": "provisioning",
    "publicUrl": "https://heron-abcd.nodana.app"
  },
  "credentials": {
    "seed": "YOUR_12_WORD_RECOVERY_SEED",
    "password": "YOUR_FULL_ACCESS_PASSWORD",
    "restrictedPassword": "YOUR_RESTRICTED_ACCESS_PASSWORD"
  }
}

Get a node

Return a node's details without its passwords or recovery seed.

GET/nodes/{nodeId}

Required permission: Nodes → Read.

Path parameters

nodeIdstringRequired: ID of the node in your account. Use List nodes to find its ID.

Request

curl "https://api.nodana.io/v1/nodes/node-123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "node-123",
  "name": "Website payments",
  "status": "ready",
  "publicUrl": "https://node-abcd.nodana.app",
  "failureMessage": null,
  "updateStatus": null,
  "updateCompletedAt": null,
  "createdAt": 1790852400,
  "updatedAt": 1790852400
}

Rename a node

Change the display name of a node.

PATCH/nodes/{nodeId}

Required permission: Nodes → Write.

Path parameters

nodeIdstringRequired: ID of the node in your account. Use List nodes to find its ID.

Body parameters

namestringRequired: New display name for the node. Must be non-blank and contain no more than 16 characters after trimming.

Request

curl -X PATCH "https://api.nodana.io/v1/nodes/node-123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Checkout"}'

Response

{
  "id": "node-123",
  "name": "Checkout",
  "status": "ready",
  "publicUrl": "https://node-abcd.nodana.app",
  "failureMessage": null,
  "updateStatus": null,
  "updateCompletedAt": null,
  "createdAt": 1790852400,
  "updatedAt": 1790852400
}

Start a node

Start a stopped or failed node. The node starts in the background.

POST/nodes/{nodeId}/start

Required permission: Nodes → Write.

Path parameters

nodeIdstringRequired: ID of the node in your account. Use List nodes to find its ID.

The node must have status stopped or failed. Other states return 400 Bad Request.

Request

curl -X POST "https://api.nodana.io/v1/nodes/node-123/start" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Use Get a node to check when its status becomes ready.

{
  "id": "node-123",
  "name": "Website payments",
  "status": "starting",
  "publicUrl": "https://node-abcd.nodana.app",
  "failureMessage": null,
  "updateStatus": null,
  "updateCompletedAt": null,
  "createdAt": 1790852400,
  "updatedAt": 1790852400
}

Stop a node

Stop a node while retaining its data.

POST/nodes/{nodeId}/stop

Required permission: Nodes → Write.

Path parameters

nodeIdstringRequired: ID of the node in your account. Use List nodes to find its ID.

The node must have status ready. Its payment API is unavailable while stopped, and incoming requests cannot restart it. Stopping a node does not pause billing.

Request

curl -X POST "https://api.nodana.io/v1/nodes/node-123/stop" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Use Get a node to check when its status becomes stopped.

{
  "id": "node-123",
  "name": "Website payments",
  "status": "stopping",
  "publicUrl": "https://node-abcd.nodana.app",
  "failureMessage": null,
  "updateStatus": null,
  "updateCompletedAt": null,
  "createdAt": 1790852400,
  "updatedAt": 1790852400
}

Restart a node

Stop and start an existing node.

POST/nodes/{nodeId}/restart

Required permission: Nodes → Write.

Path parameters

nodeIdstringRequired: ID of the node in your account. Use List nodes to find its ID.

The node must have status ready. Its payment API is temporarily unavailable during the restart.

Request

curl -X POST "https://api.nodana.io/v1/nodes/node-123/restart" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Use Get a node to check when its status becomes ready.

{
  "id": "node-123",
  "name": "Website payments",
  "status": "restarting",
  "publicUrl": "https://node-abcd.nodana.app",
  "failureMessage": null,
  "updateStatus": null,
  "updateCompletedAt": null,
  "createdAt": 1790852400,
  "updatedAt": 1790852400
}

Check for an update

Return the current node release and any supported update, using the same availability check as the dashboard.

GET/nodes/{nodeId}/update

Required permission: Nodes → Read.

Path parameters

nodeIdstringRequired: ID of the node in your account. Use List nodes to find its ID.

Review the target release before submitting its releaseSha256 to Update a node.

availableUpdate is null when there is no supported update. Its version identifies the node release. currentRelease contains the running release identity. currentVersion is the bundle version; currentRelease.phoenixdVersion identifies Phoenixd. The current version may be null while the node is unavailable.

Request

curl "https://api.nodana.io/v1/nodes/node-123/update" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "currentVersion": "0.1.0",
  "currentRelease": {
    "releaseSha256": "<current-release-checksum>",
    "version": "0.1.0",
    "phoenixdVersion": "0.9.3",
    "stateFormat": "phoenixd-0.9.3"
  },
  "availableUpdate": {
    "version": "0.2.0",
    "releaseSha256": "<release-checksum>"
  }
}

Update a node

Begin the supported node update you have approved. The update continues in the background.

POST/nodes/{nodeId}/update

Required permission: Nodes → Write.

Path parameters

nodeIdstringRequired: ID of the node in your account. Use List nodes to find its ID.

Use Check for an update first. If availableUpdate is null, there is no update to apply. Otherwise, review that release and send its releaseSha256 in the JSON body. This uses the same update flow as the dashboard. The server checks availability again before accepting the request.

The node must have status ready and an available update. The initial response has status updating; it does not indicate that the update has completed. Node data is retained.

Request

curl -X POST "https://api.nodana.io/v1/nodes/node-123/update" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"releaseSha256":"<approved-release-checksum>"}'

Response

Use Get a node to check when its status becomes ready and updateStatus becomes succeeded.

{
  "id": "node-123",
  "name": "Website payments",
  "status": "updating",
  "publicUrl": "https://node-abcd.nodana.app",
  "failureMessage": null,
  "updateStatus": "updating",
  "updateCompletedAt": null,
  "createdAt": 1790852400,
  "updatedAt": 1790852400
}

Delete a node

Permanently remove a node.

DELETE/nodes/{nodeId}

Required permission: Nodes → Write.

Path parameters

nodeIdstringRequired: ID of the node in your account. Use List nodes to find its ID.

Reconcile outstanding payments, handle remaining funds, and retain recovery information before deleting. Bearer API-key requests do not require a two-factor code.

Request

curl -X DELETE "https://api.nodana.io/v1/nodes/node-123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

No response body. Deletion continues in the background. Use Get a node to check its status. If deletion fails, retry the delete request. Once deleted, the node is no longer returned.

Get webhook endpoint

Read the webhook receiver configured for your node.

GET/nodes/{nodeId}/webhook-endpoint

Required permission: nodes:read. See Authentication.

Path parameters

nodeIdstringRequired: ID of the node in your account. Find it with List nodes.

Returns { "endpoint": null } if no endpoint is configured. The signing secret is returned only when creating an endpoint.

Request

curl "https://api.nodana.io/v1/nodes/node-abcd/webhook-endpoint" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "endpoint": {
    "id": "webhook-endpoint-example",
    "url": "https://payments.example.com/events",
    "description": "Order payments",
    "enabled": true,
    "createdAt": 1790852400
  }
}

Create webhook endpoint

Configure your node to deliver payment notifications to your application.

POST/nodes/{nodeId}/webhook-endpoint

Required permission: nodes:write. See Authentication.

Path parameters

nodeIdstringRequired: ID of the node in your account. Find it with List nodes.

Body parameters

urlstringRequired: A public HTTPS receiver URL, up to 2048 characters, without embedded credentials.
descriptionstringOptional: Optional description, up to 500 characters after trimming.

Each node supports one endpoint. An existing endpoint returns 409 webhook_endpoint_already_exists. Save the returned signingSecret in your receiver’s secret settings before processing events. See Webhook authentication.

Request

curl -X POST "https://api.nodana.io/v1/nodes/node-abcd/webhook-endpoint" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://payments.example.com/events","description":"Order payments"}'

Response

{
  "endpoint": {
    "id": "webhook-endpoint-example",
    "url": "https://payments.example.com/events",
    "description": "Order payments",
    "enabled": true,
    "createdAt": 1790852400
  },
  "signingSecret": "whsec_<save-this-secret>"
}

Update webhook endpoint

Change the receiver URL, description or whether delivery is enabled.

PATCH/nodes/{nodeId}/webhook-endpoint

Required permission: nodes:write. See Authentication.

Path parameters

nodeIdstringRequired: ID of the node in your account. Find it with List nodes.

Body parameters

urlstringOptional: A public HTTPS receiver URL, up to 2048 characters, without embedded credentials.
descriptionstringOptional: Optional description, up to 500 characters after trimming.
enabledbooleanOptional: Whether to deliver payment notifications.

Supply at least one field. Omitted fields keep their current values. Use an empty description to clear it. Disabling cancels queued deliveries and stops new notifications. Re-enabling starts delivery for future events.

Request

curl -X PATCH "https://api.nodana.io/v1/nodes/node-abcd/webhook-endpoint" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

Response

{
  "id": "webhook-endpoint-example",
  "url": "https://payments.example.com/events",
  "description": "Order payments",
  "enabled": false,
  "createdAt": 1790852400
}

Delete webhook endpoint

Remove the webhook receiver configured for your node.

DELETE/nodes/{nodeId}/webhook-endpoint

Required permission: nodes:write. See Authentication.

Path parameters

nodeIdstringRequired: ID of the node in your account. Find it with List nodes.

Deleting the endpoint also removes its delivery history. Use Update webhook endpoint to pause delivery or change the URL while keeping the configuration. A missing endpoint returns 404 webhook_endpoint_not_found.

List webhook deliveries

Read the latest 50 deliveries for your node, newest first.

GET/nodes/{nodeId}/webhook-deliveries

Required permission: nodes:read. See Authentication.

Path parameters

nodeIdstringRequired: ID of the node in your account. Find it with List nodes.

The response wraps records in deliveries. Each record includes id, eventType, payload, status, attemptCount, lastResponseStatus, lastError, createdAt, lastAttemptAt and deliveredAt. See Webhooks for event payload fields.

Use this history to troubleshoot your receiver. Status is pending, retrying, delivered, failed or cancelled. Timestamps use Unix seconds; lastAttemptAt, deliveredAt, lastResponseStatus and lastError may be null.

Attestation

Request fresh evidence of a protected host's boot state and running node bundle before trusting its connection. The response contains an AWS-signed attestation document and the host's TLS certificate. Receiving a successful response does not mean the evidence has been verified; verification happens in your client.

POST/attestation

This is a Nodana protected-host endpoint. Use your node's normal HTTPS URL, such as https://node-a1b2.nodana.app. Attestation and Phoenixd requests use the same URL on the standard HTTPS port, 443.

Authentication: none. Do not send a Phoenixd password, Nodana API key or Authorization header.

JSON body

noncestringRequired: A cryptographically random 32-byte challenge encoded as standard Base64. Generate a new challenge for every request and retain it to verify the response. Send only this field, with Content-Type: application/json.

Response

Field	Type	Description
`certificate`	string	The protected host's TLS certificate in PEM format.
`attestationDocument`	string	The AWS-signed attestation document, encoded as Base64.
`identity`	object	The node identity and connection details covered by the proof.

The document contains boot measurements, a timestamp, your challenge and a signed binding to the certificate, node, owner and bundle identity. Your verifier must check the AWS signature and certificate chain, freshness, challenge, expected identity, approved host measurements and independently approved bundle checksum before trusting the returned certificate or sending credentials.

The identity object contains version (2), hostname, nodeId, nodePublicKey, ownerPublicKey, certificateSha256 and release. Compare its hostname with the URL you requested. If you have saved node or owner public keys, compare those too; an identity supplied by the response alone does not establish that it is your original wallet.

The release object contains releaseSha256, version, phoenixdVersion and stateFormat. Compare releaseSha256 with the canonical manifest checksum you have independently approved. The measured host software checks the installed bundle and running process before reporting this identity.

The signed binding is SHA-256 of nodana-public-tls-v1 followed by a null byte and the canonical JSON encoding of identity (keys sorted, no whitespace). certificateSha256 is the lowercase SHA-256 hex digest of the exact UTF-8 PEM string in certificate. Verify the binding and compare the certificate's leaf with the certificate on your TLS connection.

Keep approved measurements in your client rather than accepting them from the response. Do not trust a certificate merely because it arrived alongside an attestation document. See Security: attestation for what verification establishes.

Errors

Status	Error	Action
`400`	`invalid_request`	Send a JSON body containing only `nonce`, without credentials.
`400`	`invalid_encoding`	Encode exactly 32 random bytes as standard Base64.
`404`	`node_not_ready`	Check the node ID and wait until the node is ready.
`429`	`busy`	Wait before requesting new evidence.
`503`	`attestation_unavailable`	Retry later; connection evidence is unavailable.
`502`	`node_unavailable`	Retry later; verification has not succeeded.

Generate a challenge

import { randomBytes } from "node:crypto";

const nonce = randomBytes(32).toString("base64");
const body = JSON.stringify({ nonce });

Request

The hostname below is illustrative. Use your node's HTTPS URL. Replace the nonce with the fresh challenge you generated.

POST /attestation HTTP/1.1
Host: node-a1b2.nodana.app
Content-Type: application/json

{"nonce":"AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8="}

Response

{
  "certificate": "-----BEGIN CERTIFICATE-----\n<PEM certificate data>\n-----END CERTIFICATE-----\n",
  "attestationDocument": "<Base64-encoded attestation document>",
  "identity": {
    "version": 2,
    "hostname": "node-a1b2.nodana.app",
    "nodeId": "node-a1b2",
    "nodePublicKey": "<Lightning public key>",
    "ownerPublicKey": "<Base64 owner public key>",
    "certificateSha256": "<SHA-256 hex digest of certificate>",
    "release": {
      "releaseSha256": "<Approved canonical manifest SHA-256 checksum>",
      "version": "0.1.0",
      "phoenixdVersion": "0.9.3",
      "stateFormat": "phoenixd-0.9.3"
    }
  }
}

The certificate and document above are placeholders. The document must be verified against your original challenge and expected node identity before you trust the certificate.

Webhooks

Receive an HTTP POST when your Nodana-hosted node receives a payment. Configure one public HTTPS receiver per node to notify your application.

Add your endpoint

Open your node in the dashboard and select Webhooks.
Choose Add endpoint and enter your receiver’s public HTTPS URL.
Copy the signing secret when it is shown and store it in your receiver’s secret settings. It is shown once.
Keep the endpoint enabled to receive notifications.

You can also create the endpoint through the API using a Nodana key with nodes:write. Read, update or delete it using the same node ID.

Handle a payment

Verify webhook authentication before parsing the request. Match nodeId and paymentHash to your saved payment, then check the amount before fulfilling the order. Use Get incoming payment if you need to look up the invoice or confirm its current state.

Field	Type	Meaning
`id`	string	Event identifier
`type`	string	`payment_received`
`nodeId`	string	Nodana ID for the receiving node
`paymentHash`	string	Payment hash as a hexadecimal string
`amountSat`	integer	Amount received in satoshis
`amountMsat`	string	Amount received in millisatoshis, encoded as a decimal string
`receivedAt`	integer	Time received, in Unix seconds
`payerNote`	string	Optional message from the payer
`payerKey`	string	Optional public key identifying the payer

Acknowledge delivery

Return a 2xx response after you have safely recorded the event. Nodana retries failed deliveries, so make processing repeatable: use the event ID or node and payment hash to prevent duplicate fulfilment.

Check recent deliveries or the node’s Webhooks tab when troubleshooting. Confirm that the endpoint is enabled, reachable over HTTPS and returning a successful status. Use incoming payment history to reconcile payments if your receiver was unavailable.

Received request

POST /payments/events HTTP/1.1
Host: payments.example.com
Content-Type: application/json
X-Nodana-Signature: <hexadecimal HMAC-SHA256 signature>
X-Nodana-Event-Id: webhook-delivery-example
X-Nodana-Event-Type: payment_received

{"id":"node-abcd-1","type":"payment_received","nodeId":"node-abcd","paymentHash":"7db610f2b418394f12ba84927868a4b98e6bca6a82dd644c905f4f0c257d336a","amountSat":1000,"amountMsat":"1000000","receivedAt":1748269006}

Delivery headers

Header	Meaning
`X-Nodana-Signature`	HMAC-SHA256 signature of the raw request body
`X-Nodana-Event-Id`	Identifier for this delivery; retained on retries
`X-Nodana-Event-Type`	Event type, such as `payment_received`

Webhook authentication

Verify the X-Nodana-Signature header before accepting a webhook. Use the signing secret returned when you create the endpoint, or shown when you add it in the dashboard. Store it in your receiver’s secret configuration as NODANA_WEBHOOK_SECRET.

Nodana signs the complete request body with HMAC-SHA256 and sends the signature as a hexadecimal string. Use the entire signing secret as UTF-8 text, including its whsec_ prefix.

Verify a request

Capture the raw request body before JSON parsing.
Calculate its HMAC-SHA256 using your endpoint’s signing secret.
Compare it with X-Nodana-Signature using a constant-time comparison.
Reject a missing or invalid signature. Parse and process the JSON only after verification succeeds.

Use the original request bytes: parsing and reserializing JSON can change the signature. Keep the secret private. If it is lost or exposed, replace the webhook endpoint and configure your receiver with the new signing secret.

After verification, check the node, payment hash and amount against your order, and record fulfilment once. A valid signature does not make a repeated delivery a new payment.

Node.js verification

Pass the raw request body as a Buffer and the X-Nodana-Signature header as a string. Capture the body before your framework’s JSON parser runs.

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyWebhook(rawBody, signature, secret) {
  if (!secret || typeof signature !== "string" || !/^[a-f0-9]{64}$/i.test(signature)) {
    return false;
  }
  const expected = createHmac("sha256", secret).update(rawBody).digest();
  const received = Buffer.from(signature, "hex");
  return received.length === expected.length && timingSafeEqual(received, expected);
}

const valid = verifyWebhook(rawBody, signatureHeader, process.env.NODANA_WEBHOOK_SECRET);
if (!valid) throw new Error("Invalid Nodana webhook signature");
const event = JSON.parse(rawBody.toString("utf8"));

Create BOLT11 invoice

Creates a Bolt11 invoice with a description.

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.

POST/createinvoice

Authentication: full or limited Phoenixd password. See Authentication.

Form parameters

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

Send parameters as application/x-www-form-urlencoded.

Request

curl "https://node-a1b2.nodana.app/createinvoice" \
  -u ":$PHOENIXD_PASSWORD" \
  -X POST \
  --data-urlencode "description=Order 1042" \
  --data-urlencode "amountSat=1000" \
  --data-urlencode "expirySeconds=600" \
  --data-urlencode "externalId=order-1042"

Response

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

Create BOLT12 offer

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.

POST/createoffer

Authentication: full or limited Phoenixd password. See Authentication.

Form parameters

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

Send parameters as application/x-www-form-urlencoded.

Request

curl "https://node-a1b2.nodana.app/createoffer" \
  -u ":$PHOENIXD_PASSWORD" \
  -X POST \
  --data-urlencode "description=Tips" \
  --data-urlencode "amountSat=100"

Response

lno1qgsyxjtl6luzd9t3pr62xr7eemp6awnejusgf6gw45q75vcfqqqqqqqgqvqcdgq2zdskugr0venx2u3qvehhygzsd9jhyun9zrhq8yecsj40r443pquhuhh7tjrteukce2xj7uqwm2vahys5lsn39vf5q2fyfxsw6xn824393en87nre87xcectkgcj85trcu5hn9r9703645qsrxtcq785whraquh5atw89w5scg707fz23405ygk7jn9uek3tkmvdqqvc8yz8xm2yme6hjx3x02csmq6pfzaejqr3kzg7u8am96txu95z8am8zgvfvfcnzk27ylwk43ut48xv2vrkhqtj3wes32glw5ft5h7f4p8ytwey4cqjsks55zcmr3hka0p8e50thjqpjytmt5wsa4ylhavdmewv7jmj2ppy9daujfmfvpmnw9cf75cymjffzh2nafn883vsqr3a8u2l797mayh3p

Get Lightning 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.

GET/getlnaddress

Authentication: full or limited Phoenixd password. See Authentication.

Get swap-in address

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

GET/getswapinaddress

Authentication: full or limited Phoenixd password. See Authentication.

Request

curl "https://node-a1b2.nodana.app/getswapinaddress" \
  -u ":$PHOENIXD_PASSWORD"

Response

{
  "address": "tb1pyjfhx93wd0qf4dhe8fqgvqsfhef5ffr7e05gczn9yaluulu5jhxsp59dlr",
  "index": 1
}

Pay BOLT11 invoice

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

POST/payinvoice

Authentication: full Phoenixd password. See Authentication.

Form parameters

invoicestringRequired: BOLT11 invoice to pay.
amountSatintegerOptional: Amount in satoshis. If omitted, uses the amount in the payment request. Supply amountSat or sendAll for an amountless request.
sendAllbooleanOptional: Send the wallet balance when there is a single channel. Mutually exclusive with amountSat.

Send parameters as application/x-www-form-urlencoded.

Payment attempts can return HTTP 200 with type: "payment_failed". Check the result before treating the payment as sent. A successful result has type: "payment_sent".

Request

curl "https://node-a1b2.nodana.app/payinvoice" \
  -u ":$PHOENIXD_PASSWORD" \
  -X POST \
  --data-urlencode "invoice=$BOLT11_INVOICE"

Response

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

Pay BOLT12 offer

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

POST/payoffer

Authentication: full Phoenixd password. See Authentication.

Form parameters

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

Send parameters as application/x-www-form-urlencoded.

Payment attempts can return HTTP 200 with type: "payment_failed". Check the result before treating the payment as sent. A successful result has type: "payment_sent".

Request

curl "https://node-a1b2.nodana.app/payoffer" \
  -u ":$PHOENIXD_PASSWORD" \
  -X POST \
  --data-urlencode "offer=$BOLT12_OFFER" \
  --data-urlencode "amountSat=123"

Response

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

Pay Lightning address

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.

POST/paylnaddress

Authentication: full Phoenixd password. See Authentication.

Form parameters

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

Send parameters as application/x-www-form-urlencoded.

Payment attempts can return HTTP 200 with type: "payment_failed". Check the result before treating the payment as sent. A successful result has type: "payment_sent".

Request

curl "https://node-a1b2.nodana.app/paylnaddress" \
  -u ":$PHOENIXD_PASSWORD" \
  -X POST \
  --data-urlencode "address=$LIGHTNING_ADDRESS" \
  --data-urlencode "amountSat=123"

Response

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

Pay on-chain

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.

POST/sendtoaddress

Authentication: full Phoenixd password. See Authentication.

Form parameters

amountSatintegerRequired: Amount to send in satoshis.
addressstringRequired: Destination Bitcoin address.
feerateSatByteintegerRequired: Fee rate in satoshis per virtual byte.

Send parameters as application/x-www-form-urlencoded.

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

Request

curl "https://node-a1b2.nodana.app/sendtoaddress" \
  -u ":$PHOENIXD_PASSWORD" \
  -X POST \
  --data-urlencode "amountSat=100000" \
  --data-urlencode "address=$BITCOIN_ADDRESS" \
  --data-urlencode "feerateSatByte=12"

Response

05a28b4972560655eeedaaf72c4d8e9f1a285e47e2d347734853b5e49ae9ead0

Bump fee

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

POST/bumpfee

Authentication: full Phoenixd password. See Authentication.

Form parameters

feerateSatByteintegerRequired: Fee rate in satoshis per virtual byte.

Send parameters as application/x-www-form-urlencoded.

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

Request

curl "https://node-a1b2.nodana.app/bumpfee" \
  -u ":$PHOENIXD_PASSWORD" \
  -X POST \
  --data-urlencode "feerateSatByte=11"

Response

758b3df67c62c9cd9ebbde1ff6eaadc1c51f94d5b1a3efb2548236b9a6f1c659

List incoming payments

Lists incoming payments.

GET/payments/incoming

Authentication: full or limited Phoenixd password. See Authentication.

Query parameters

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.
externalIdstringOptional: Only return payments with this external ID.

Request

curl "https://node-a1b2.nodana.app/payments/incoming" \
  -u ":$PHOENIXD_PASSWORD" \
  -G \
  --data-urlencode "all=true" \
  --data-urlencode "limit=5" \
  --data-urlencode "offset=0"

Response

[
  {
    "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

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.

GET/payments/incoming/{paymentHash}

Authentication: full or limited Phoenixd password. See Authentication.

Path parameters

paymentHashstringRequired: Payment hash as a hexadecimal string.

Request

curl "https://node-a1b2.nodana.app/payments/incoming/$PAYMENT_HASH" \
  -u ":$PHOENIXD_PASSWORD"

Response

{
  "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

Lists outgoing payments.

GET/payments/outgoing

Authentication: full or limited Phoenixd password. See Authentication.

Query parameters

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.

Request

curl "https://node-a1b2.nodana.app/payments/outgoing" \
  -u ":$PHOENIXD_PASSWORD" \
  -G \
  --data-urlencode "all=true" \
  --data-urlencode "limit=5" \
  --data-urlencode "offset=0"

Response

[
  {
    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

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.

GET/payments/outgoing/{paymentId}

GET/payments/outgoingbyhash/{paymentHash}

Authentication: full or limited Phoenixd password. See Authentication.

Path parameters

paymentIdstringRequired: Internal payment UUID.
paymentHashstringOptional: Payment hash for the alternative outgoingbyhash route.

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

Request

curl "https://node-a1b2.nodana.app/payments/outgoing/$PAYMENT_ID" \
  -u ":$PHOENIXD_PASSWORD"

Response

{
  "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

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.

POST/export

Authentication: full or limited Phoenixd password. See Authentication.

Query parameters

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

Request

curl "https://node-a1b2.nodana.app/export" \
  -u ":$PHOENIXD_PASSWORD" \
  -X POST \
  --url-query "from=0" \
  --url-query "to=1750943212490"

Response

payment history has been exported to /data/.phoenix/exports/export-1750943212.csv

Get node info

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

GET/getinfo

Authentication: full or limited Phoenixd password. See Authentication.

Request

curl "https://node-a1b2.nodana.app/getinfo" \
  -u ":$PHOENIXD_PASSWORD"

Response

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

Get balance

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

GET/getbalance

Authentication: full or limited Phoenixd password. See Authentication.

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.

GET/listchannels

Authentication: full or limited Phoenixd password. See Authentication.

Request

curl "https://node-a1b2.nodana.app/listchannels" \
  -u ":$PHOENIXD_PASSWORD"

Response

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

Close channel

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.

POST/closechannel

Authentication: full Phoenixd password. See Authentication.

Form parameters

channelIdstringRequired: ID of the channel to close.
addressstringRequired: Bitcoin address to receive the channel balance.
feerateSatByteintegerRequired: Fee rate in satoshis per virtual byte.

Send parameters as application/x-www-form-urlencoded.

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

Request

curl "https://node-a1b2.nodana.app/closechannel" \
  -u ":$PHOENIXD_PASSWORD" \
  -X POST \
  --data-urlencode "channelId=$CHANNEL_ID" \
  --data-urlencode "address=$BITCOIN_ADDRESS" \
  --data-urlencode "feerateSatByte=12"

Response

758b3df67c62c9cd9ebbde1ff6eaadc1c51f94d5b1a3efb2548236b9a6f1c659

Decode invoice

POST/decodeinvoice

Authentication: full or limited Phoenixd password. See Authentication.

Form parameters

invoicestringRequired: BOLT11 invoice to decode.

Send parameters as application/x-www-form-urlencoded.

Request

curl "https://node-a1b2.nodana.app/decodeinvoice" \
  -u ":$PHOENIXD_PASSWORD" \
  -X POST \
  --data-urlencode "invoice=$BOLT11_INVOICE"

Response

{
  "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

POST/decodeoffer

Authentication: full or limited Phoenixd password. See Authentication.

Form parameters

offerstringRequired: BOLT12 offer to decode.

Send parameters as application/x-www-form-urlencoded.

Request

curl "https://node-a1b2.nodana.app/decodeoffer" \
  -u ":$PHOENIXD_PASSWORD" \
  -X POST \
  --data-urlencode "offer=$BOLT12_OFFER"

Response

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

Estimate liquidity fees

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.

GET/estimateliquidityfees

Authentication: full or limited Phoenixd password. See Authentication.

Query parameters

amountSatintegerRequired: Liquidity amount in satoshis.

Request

curl "https://node-a1b2.nodana.app/estimateliquidityfees" \
  -u ":$PHOENIXD_PASSWORD" \
  -G \
  --data-urlencode "amountSat=1000000"

Response

{
  "miningFeeSat": 1219,
  "serviceFeeSat": 20000
}

LNURL Pay

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.

POST/lnurlpay

Authentication: full Phoenixd password. See Authentication.

Form parameters

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

Send parameters as application/x-www-form-urlencoded.

Payment attempts can return type: "payment_failed" with HTTP 200. Check the returned type and reconcile uncertain attempts using Get outgoing payment.

Request

curl "https://node-a1b2.nodana.app/lnurlpay" \
  -u ":$PHOENIXD_PASSWORD" \
  -X POST \
  --data-urlencode "lnurl=$LNURL" \
  --data-urlencode "amountSat=123"

Response

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

LNURL Withdraw

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

POST/lnurlwithdraw

Authentication: full or limited Phoenixd password. See Authentication.

Form parameters

lnurlstringRequired: LNURL-withdraw resource.

Send parameters as application/x-www-form-urlencoded.

Request

curl "https://node-a1b2.nodana.app/lnurlwithdraw" \
  -u ":$PHOENIXD_PASSWORD" \
  -X POST \
  --data-urlencode "lnurl=$LNURL"

Response

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

LNURL Auth

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!

POST/lnurlauth

Authentication: full Phoenixd password. See Authentication.

Form parameters

lnurlstringRequired: LNURL-auth resource.

Send parameters as application/x-www-form-urlencoded.

WebSocket

WS /websocket

Subscribe to received-payment events. Use the full or limited Phoenixd password. For an HTTPS node URL, connect with wss://; a daemon on the same machine uses ws://127.0.0.1:9740/websocket.

Authentication

Phoenixd accepts Basic authentication on the WebSocket handshake or authentication through Sec-WebSocket-Protocol. The example uses a server-side client with Basic authentication and an empty username. Keep the password on your backend.

Events

Each JSON message has type: "payment_received", the payment hash and the amount in satoshis. Events can include externalId for an invoice or payerKey and payerNote for an offer. Match the payment hash or external ID to your saved order.

After reconnecting, use incoming payment history to reconcile receipts. Confirm the payment and expected amount before fulfilment, and record fulfilment once for each order.

Install the websocat command and replace the dummy hostname with your node’s hostname.

websocat --basic-auth ":$PHOENIXD_PASSWORD" "wss://node-a1b2.nodana.app/websocket"

Payment event

{
  "type": "payment_received",
  "amountSat": 15,
  "payerNote": "hello",
  "payerKey": "02ad95a81c1865ddb41a49f07b11a70b3f8fcd68ae161e0eb561a074f6a223ff84",
  "paymentHash": "5ad2185b67c6ba2e65987ab22abf5b4f8c25049d1a3b5dda76f050bc7726aab3"
}