快速开始

本页仅演示第三方 API Key 支持的节点管理操作，不包含官方产品内部接口或节点运行时访问。

前置条件

• 通过官方控制台获取具有 nodes:read 和 nodes:write 权限的 API Key，安全设置 API_KEY。
• 设置 BASE_URL=https://api.stashcloud.net（或部署提供的基址）与 NETWORK（regtest、testnet 或 mainnet），网络必须匹配 Key。
• 安装 curl、jq 和 uuidgen。不要把 Key 写入源代码或日志。

第一步：创建节点

POST /v3/nodes 仅接受可选 name（或 {}）。未知字段返回 400。

推荐提供请求 UUID，并保存以便同一次请求重试时复用：

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')

成功返回 202 Accepted 和节点详情，不含通用 data 包装。分配域名不表示节点已就绪。

第二步：查询节点与列表

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"

详情成功返回 200 和节点对象，观察 status 及失败信息确认就绪。列表成功返回 200 和 { "nodes": [...], "next_cursor": "..." }，将非空 next_cursor 作为下一页的 cursor；limit 默认 20，范围 1–100。返回的 api_base_url 不表示 API Key 获得运行时访问权限。

第三步：申请 P2P 地址

节点为运行中的用户节点后，使用 nodes:write 申请 Lightning P2P 地址：

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

成功返回 200，包含 id、network、p2p_host、p2p_port 和 p2p_address。不满足节点状态条件返回 409，服务不可用或端口分配失败可返回 503。不要将 HTTPS 域名当作 P2P 地址。此请求可重复调用，不使用生命周期操作的幂等缓存。

第四步：停止与启动

每个不同操作使用独立 UUID；同一次请求重试时复用原 UUID：

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"

两者成功均返回 200 和节点详情，无需 JSON 请求体。

第五步：删除节点

删除前请确认备份与迁出安排；第三方 API 不提供撤销删除能力。只在确定不再需要该节点时执行：

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"

成功返回 200 和 { "id": "...", "network": "regtest", "deleted": true }。

下一步

• 鉴权：权限、安全存储、请求 UUID 与错误处理。
• 节点管理：完整参数、响应和操作限制。