---
name: phoenixd
description: Use a Phoenixd node to inspect balances, create and track Lightning invoices, and send payments when an explicit spending policy permits it. Requires PHOENIXD_URL and PHOENIXD_PASSWORD.
---

# Phoenixd

Use the Phoenixd HTTP API at `PHOENIXD_URL` for operations inside an existing node. For Nodana-hosted nodes, use the endpoint and Phoenixd password returned when the node was created. The Nodana API key manages nodes; it does not authenticate to Phoenixd.

## Credentials and access

- Read `PHOENIXD_URL` and `PHOENIXD_PASSWORD` from the agent runtime's secret configuration. If either is missing, ask the user to configure it there. Never print, request in chat, log, or write the password to a shell profile or repository.
- Use HTTPS for a hosted node. Phoenixd authenticates with HTTP Basic Auth using an empty username and the node password.
- Prefer the restricted password for reading node state and creating invoices. Outgoing payments require the full-access password. A `401` response alone does not prove which password was supplied; check the URL, credential, and requested operation without exposing the secret.
- Keep payment authorization in application code or a trusted service. A skill cannot enforce a budget or approval rule by itself.

The examples below assume these variables are already configured. Do not replace them with literal credentials in commands or output.

## Read node state

```bash
curl --fail-with-body --silent --show-error \
  --user ":$PHOENIXD_PASSWORD" "$PHOENIXD_URL/getinfo"

curl --fail-with-body --silent --show-error \
  --user ":$PHOENIXD_PASSWORD" "$PHOENIXD_URL/getbalance"
```

`GET /getinfo` returns the node ID and channel summary. `GET /getbalance` returns the balance and fee credit in satoshis.

## Create and track a BOLT11 invoice

```bash
curl --fail-with-body --silent --show-error \
  --user ":$PHOENIXD_PASSWORD" \
  --data-urlencode "description=Order 1042" \
  --data-urlencode "amountSat=1000" \
  --data-urlencode "externalId=order-1042" \
  "$PHOENIXD_URL/createinvoice"
```

`POST /createinvoice` needs a `description` or `descriptionHash`. `amountSat` is an optional amount in satoshis. `externalId` is optional; use a unique value when your application needs to associate the invoice with an order. The response includes `serialized` (the BOLT11 invoice) and `paymentHash`. Share the invoice, not the node password.

To check the invoice, use its payment hash:

```bash
curl --fail-with-body --silent --show-error \
  --user ":$PHOENIXD_PASSWORD" \
  "$PHOENIXD_URL/payments/incoming/$PAYMENT_HASH"
```

Check `isPaid` in the returned payment. An unpaid invoice may later expire; do not report it as paid merely because it was created. Do not wait indefinitely for a payment during a conversation.

## Send a BOLT11 payment

Only use a full-access password after the requested recipient, invoice amount, routing-fee allowance, and spending policy have been checked by the user or a trusted service. Decode the invoice before paying. Do not pay an expired invoice or silently override its amount.

```bash
curl --fail-with-body --silent --show-error \
  --user ":$PHOENIXD_PASSWORD" \
  --data-urlencode "invoice=$INVOICE" \
  "$PHOENIXD_URL/decodeinvoice"

curl --fail-with-body --silent --show-error \
  --user ":$PHOENIXD_PASSWORD" \
  --data-urlencode "invoice=$INVOICE" \
  "$PHOENIXD_URL/payinvoice"
```

`POST /payinvoice` sends funds. Record the payment ID and hash returned by Phoenixd. If the request times out or its result is unclear, check status before trying again; a lost HTTP response does not mean the payment failed:

```bash
curl --fail-with-body --silent --show-error \
  --user ":$PHOENIXD_PASSWORD" \
  "$PHOENIXD_URL/payments/outgoingbyhash/$PAYMENT_HASH"
```

For BOLT12 offers, Lightning addresses, on-chain sends, LNURL operations, channel changes, and all other fields and response formats, consult the [official Phoenixd HTTP API](https://phoenix.acinq.co/server/api) before making a request. Treat any operation that spends funds or closes a channel as a separate authorized action.