---
name: nodana
description: Create, inspect, and manage Nodana-hosted Phoenixd nodes through the Nodana API. Use for node lifecycle tasks, not Lightning payments. Requires a scoped NODANA_API_KEY.
---

# Nodana

Use the Nodana API at `https://api.nodana.io/v1` to manage hosted Phoenixd nodes. Use the [Phoenixd skill](https://nodana.io/skills/phoenixd/SKILL.md) for balances, invoices, and payments inside a node. A Nodana API key does not authenticate to Phoenixd.

For the complete compact endpoint list, scopes, and response shapes, read the [Nodana API text reference](https://nodana.io/nodana-api.txt).

## Access and boundaries

- Read `NODANA_API_KEY` from the agent runtime's secret configuration. If missing, ask the user to configure it there. Never request the key in chat, print it, log it, or write it to source control or a shell profile.
- Send it as `Authorization: Bearer $NODANA_API_KEY` over HTTPS. Every key has `nodes:read`; enable `nodes:write` for creating, changing, or deleting nodes. Deletion still requires explicit user authorization.
- Node creation may incur charges. Check the user's request and account credit before creating. An API `402` indicates Nodana account credit or billing, not an L402 payment challenge.
- Do not expose node recovery words or passwords to a conversation, tool log, or generic command output. The create response is the only time these credentials are returned. Save them in the user's approved secret store before reporting the node ID or status.

## Inspect nodes

These read requests return node metadata without the recovery seed or passwords:

```bash
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $NODANA_API_KEY" \
  "https://api.nodana.io/v1/nodes"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $NODANA_API_KEY" \
  "https://api.nodana.io/v1/nodes/$NODE_ID"
```

`GET /nodes` returns an object with a `nodes` array. `GET /nodes/{nodeId}` returns one node with fields such as `id`, `status`, and `endpointUrl`. Deleted nodes are excluded from the list.

## Create a node

Use `POST /nodes` with JSON. Both fields are optional: `name` is at most 16 characters after trimming, and `autoLiquidity` is `2m`, `5m`, or `10m` (default `2m`). For example:

```http
POST /v1/nodes HTTP/1.1
Host: api.nodana.io
Authorization: Bearer <API key from secret store>
Content-Type: application/json

{"name":"Agent node","autoLiquidity":"2m"}
```

Run creation through a trusted client that handles the response in memory and immediately stores `credentials.seed`, `credentials.password`, and `credentials.restrictedPassword` in the user's approved secret store. Do not send the raw response to an agent transcript, terminal, or telemetry. The `202 Accepted` response also includes a `node` object; report only safe node fields after the credentials have been saved. If secure capture is unavailable, ask the user to create the node in the dashboard instead.

Creation starts provisioning. Poll `GET /nodes/{nodeId}` at a modest interval until `status` is `ready` or `failed`; set a time limit and report if it remains in progress. Do not treat `202` as a ready node. After an uncertain timeout, list nodes and reconcile before trying to create again. Node creation has no idempotency key.

## Manage an existing node

The API supports `PATCH /nodes/{nodeId}` to rename, `POST /nodes/{nodeId}/start`, `/stop`, `/restart`, and `/update`, and `GET /nodes/{nodeId}/update` to check availability. Check the [Nodana API reference](https://nodana.io/docs/api) for request bodies and required node states before calling a mutation. Read the node again to confirm its final state after a timeout or background update.

Stopping a node makes its payment API unavailable and does not pause billing. Deleting a node is permanent: require explicit authorization for that node and confirm the user's recovery information and remaining funds have been handled before calling `DELETE /nodes/{nodeId}`. Do not delete automatically as cleanup.

On `429`, wait for `Retry-After`. Retry reads with bounded backoff; reconcile the result of any mutation before repeating it. See [API errors](https://nodana.io/docs/api/errors) and [rate limits](https://nodana.io/docs/api/rate-limits).