Quickstart

This page demonstrates only node management operations supported by third-party API Keys, not official product internal interfaces or node runtime access.

Prerequisites

• Obtain an API Key with nodes:read and nodes:write through the official console and securely set API_KEY.
• Set BASE_URL=https://api.stashcloud.net (or the deployment-provided base URL) and NETWORK (regtest, testnet or mainnet), matching the key's network.
• Install curl, jq and uuidgen. Do not place the key in source code or logs.

Step 1: Create a node

POST /v3/nodes accepts only optional name (or {}). Unknown fields return 400.

Supply a request UUID and save it to reuse when retrying the same request:

REQUEST_ID=$(uuidgen)
NODE=$(curl --fail-with-body -sS -X POST "$BASE_URL/v3/nodes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Network: $NETWORK" \
  -H "Request-Id: $REQUEST_ID" \
  -H 'Content-Type: application/json' \
  -d '{"name":"my-first-node"}')
NODE_ID=$(printf '%s' "$NODE" | jq -er '.id')

Success returns 202 Accepted with node details, without a generic data wrapper. An allocated hostname does not indicate readiness.

Step 2: Query a node and list nodes

curl --fail-with-body -sS "$BASE_URL/v3/nodes/$NODE_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Network: $NETWORK"

curl --fail-with-body -sS "$BASE_URL/v3/nodes?limit=20" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Network: $NETWORK"

Details return 200 with a node object; check status and failure information for readiness. Lists return 200 with { "nodes": [...], "next_cursor": "..." }. Use a nonempty next_cursor as the next page's cursor; limit defaults to 20 and ranges from 1–100. A returned api_base_url does not grant API Key access to the runtime.

Step 3: Allocate a P2P address

Once the node is a running user node, use nodes:write to allocate a Lightning P2P address:

curl --fail-with-body -sS -X POST "$BASE_URL/v3/nodes/$NODE_ID/p2p" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Network: $NETWORK"

Success returns 200 with id, network, p2p_host, p2p_port and p2p_address. An incompatible node state returns 409; service unavailability or port allocation failure may return 503. Do not use an HTTPS hostname as a P2P address. This request is repeatable and does not use lifecycle operation idempotency caching.

Step 4: Stop and start

Use a distinct UUID for each different operation; reuse the original UUID when retrying the same request:

STOP_REQUEST_ID=$(uuidgen)
curl --fail-with-body -sS -X POST "$BASE_URL/v3/nodes/$NODE_ID/stop" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Network: $NETWORK" \
  -H "Request-Id: $STOP_REQUEST_ID"

START_REQUEST_ID=$(uuidgen)
curl --fail-with-body -sS -X POST "$BASE_URL/v3/nodes/$NODE_ID/start" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Network: $NETWORK" \
  -H "Request-Id: $START_REQUEST_ID"

Both return 200 with node details on success and require no JSON body.

Step 5: Delete a node

Confirm backup and migration arrangements first; the third-party API does not provide undelete. Run this only when the node is no longer needed:

DELETE_REQUEST_ID=$(uuidgen)
curl --fail-with-body -sS -X DELETE "$BASE_URL/v3/nodes/$NODE_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Network: $NETWORK" \
  -H "Request-Id: $DELETE_REQUEST_ID"

Success returns 200 with { "id": "...", "network": "regtest", "deleted": true }.

Next steps

• Authentication: scopes, secure storage, request UUIDs and error handling.
• Node management: full parameters, responses and operation limits.