节点管理

本页仅介绍第三方 API Key 支持的节点管理操作。API 基址由部署提供，例如 https://api.stashcloud.net；网络不是 URL 前缀。

鉴权与请求标识

使用 Authorization: Bearer <API_KEY>。所有节点管理请求必须带 X-Network: regtest|testnet|mainnet，且网络必须匹配 Key 与资源。读取需要 nodes:read；创建、启停、删除、P2P 申请需要 nodes:write，没有单独的删除 scope。

创建、启停、删除接受 Request-Id 或 X-Request-Id UUID，推荐主动提供并保存。两者同时提供时必须相同；无效、全零或冲突的 UUID 返回 400。省略时服务端生成 UUID，但重试要使用原 UUID 才能复用幂等结果。响应带 X-Request-Id，命中缓存时带 X-Idempotent-Cached: true；相同标识不得用于不同请求。P2P 申请可重复调用，不使用上述幂等缓存。

创建节点

POST /v3/nodes — createNode，成功 202 Accepted。

请求体仅含可选 name（最多 64 字符），或传 {}。body 最长 4096 字节；无效 JSON、null、非对象，或任何非 name 字段均返回 400。不接受节点类型选择、资源规格选择或同步等待选项。

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":"demo-node"}'

响应直接为 NodeDetails，不是 data wrapper。下面是字段结构示例，值不是部署的默认规格：

{
  "id": "example-node",
  "network": "regtest",
  "name": "demo-node",
  "status": "pending",
  "public_dns": "example-node-regtest.stashcloud.net",
  "api_base_url": "https://example-node-regtest.stashcloud.net",
  "provision_retryable": false,
  "version": 0,
  "cpu_cores": "1.0",
  "memory_mb": 1024,
  "storage_gb": 1,
  "created_at": "2026-10-01T00:00:00Z"
}

这些字段均为必需字段；identity_pubkey、provision_failure、provisioned_at、stopped_at 以及已持有时的 p2p_host、p2p_port、p2p_address 为可选字段。读取详情不会主动申请 P2P 端口。public_dns / api_base_url 是 HTTPS API 地址，不能用作 Lightning P2P 连接地址，也不表示 API Key 获得节点运行时访问权限。

status 是字符串，不是封闭枚举。域名已分配不表示节点已就绪；通过详情查询观察状态和失败信息，不要把 202 当作节点可用承诺。

查询与分页

• GET /v3/nodes — listNodes，200，返回 { "nodes": [...], "next_cursor": "..." }；nodes 可为 null，客户端可规范化为空数组。
• 可选 query：cursor（最多 64 字符）、limit（默认 20，范围 1–100）。将返回的 next_cursor 原样用于下一页，空字符串表示无下一页。
• GET /v3/nodes/{id} — getNode，200，直接返回 NodeDetails。

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

启动、停止与删除

• POST /v3/nodes/{id}/start — startNode，200，NodeDetails。
• POST /v3/nodes/{id}/stop — stopNode，200，NodeDetails。
• DELETE /v3/nodes/{id} — deleteNode，200，{ "id": "...", "network": "regtest", "deleted": true }。

这些接口无 JSON 请求体，仍需 Key、X-Network，并建议携带稳定请求 UUID。不同操作必须用不同 UUID。状态/幂等冲突可返回 409；响应不是 202 或 204。删除后没有第三方恢复/撤销删除操作，请先确认备份与迁出安排。

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"

P2P 地址申请

POST /v3/nodes/{id}/p2p — applyNodeP2P，需要 nodes:write 与 X-Network，无 JSON body，成功 200。

节点必须是运行中的用户节点，否则 409。目标节点不存在或不属于当前用户/网络时返回 404。P2P 未启用、端口池耗尽或分配失败返回 503。可重复调用；不使用创建/启停/删除的请求 UUID 幂等缓存。

成功直接返回：

{
  "id": "example-node",
  "network": "regtest",
  "p2p_host": "example-node-regtest-p2p.example.net",
  "p2p_port": 9735,
  "p2p_address": "example-node-regtest-p2p.example.net:9735"
}

p2p_address 是 Lightning P2P 连接地址，不是 HTTPS API 地址。

错误与能力边界

通用错误结构、认证错误、权限错误和限流处理见 鉴权。第三方 API 不提供节点重命名、规格调整、节点类型选择或一键恢复备份操作。节点运行时访问不在本页范围内；API Key 本身不授予该权限。