Stash Labs

中文

English

中文

English

Appearance

支付操作 ​

闪电网络支付接口的完整参考。所有路径均带 /api/v1 前缀。金额字段中 _msat 为毫聪，_sats 为聪，注意区分。

BOLT11 发票 ​

POST /api/v1/bolt11/receive ​

生成固定金额的 BOLT11 发票。

请求:

json
{
  "amount_msat": "10000000",
  "description": "服务付款",
  "expiry_secs": 3600
}

响应:

json
{
  "invoice": "lntb100u1..."
}

POST /api/v1/bolt11/receive_var ​

生成可变金额的 BOLT11 发票（不含金额，由付款方决定）。

请求:

json
{
  "description": "打赏",
  "expiry_secs": 3600
}

响应: 与 receive 相同。

POST /api/v1/bolt11/receive_for_hash ​

使用指定的 payment_hash 生成发票，用于自行管理支付哈希的场景。

请求:

json
{
  "amount_msat": "10000000",
  "description": "服务付款",
  "expiry_secs": 3600,
  "payment_hash": "abc123..."
}

响应: 与 receive 相同。

POST /api/v1/bolt11/pay ​

支付 BOLT11 发票，等待完成后返回支付结果。

请求:

json
{
  "invoice": "lntb100u1...",
  "amount_msat": "10000000",
  "channel_id": "abc123..."
}

amount_msat 可选，仅用于可变金额发票；channel_id 可选，用于指定优先使用的通道。

响应:

json
{
  "payment_id": "pay_abc123",
  "preimage": "def456...",
  "amount_sats": "10000",
  "destination": "02def456...",
  "fee_paid_msat": "1000"
}

POST /api/v1/bolt11/send ​

发送固定金额发票，立即返回 payment_id，不等待完成。

请求:

json
{
  "invoice": "lntb100u1..."
}

响应:

json
{
  "payment_id": "pay_abc123"
}

POST /api/v1/bolt11/send_using_amount ​

为可变金额发票指定金额并发送。

请求:

json
{
  "invoice": "lntb100u1...",
  "amount_msat": "50000000"
}

响应: 与 bolt11/send 相同。

POST /api/v1/bolt11/decode ​

解析 BOLT11 发票。

请求:

json
{
  "invoice": "lntb100u1..."
}

响应:

json
{
  "payment_hash": "abc123...",
  "destination": "02def456...",
  "amount_msat": "10000000",
  "expiry_secs": "3600"
}

amount_msat 在发票未含金额时可能为空。

POST /api/v1/bolt11/claim_for_hash ​

以提供的原像领取一个按哈希锁定的入站 HTLC。

请求:

json
{
  "payment_hash": "abc123...",
  "preimage": "def456...",
  "claimable_amount_msat": "10000000"
}

响应:

json
{ "ok": true }

POST /api/v1/bolt11/fail_for_hash ​

使一个按哈希锁定的入站 HTLC 失败。

请求:

json
{
  "payment_hash": "abc123..."
}

响应:

json
{ "ok": true }

BOLT12 Offer ​

POST /api/v1/bolt12/offer/receive ​

创建固定金额的 BOLT12 Offer（可复用支付请求）。

请求:

json
{
  "amount_msat": "50000000",
  "description": "订阅服务",
  "expiry_secs": 86400,
  "quantity": "1"
}

expiry_secs 与 quantity 可选。

响应:

json
{
  "offer": "lno1..."
}

POST /api/v1/bolt12/offer/receive_var ​

创建可变金额的 BOLT12 Offer。

请求:

json
{
  "description": "订阅服务",
  "expiry_secs": 86400
}

响应: 与 offer/receive 相同。

POST /api/v1/bolt12/offer/send ​

支付一个 BOLT12 Offer。

请求:

json
{
  "offer": "lno1...",
  "amount_msat": "50000000",
  "quantity": "1",
  "payer_note": "订单 #123"
}

响应:

json
{
  "payment_id": "pay_abc123"
}

POST /api/v1/bolt12/offer/decode ​

解析 BOLT12 Offer。

请求:

json
{
  "offer": "lno1..."
}

响应:

json
{
  "offer_id": "offer_abc123",
  "signing_pubkey": "02def456...",
  "description": "订阅服务",
  "issuer": "Example",
  "amount_msat": "50000000",
  "absolute_expiry_unix_secs": "1704067200",
  "chain_hashes": ["000000000019d668..."],
  "paths_count": 1,
  "expects_quantity": false
}

BOLT12 Refund ​

POST /api/v1/bolt12/refund/initiate ​

发起一个 BOLT12 退款，生成退款请求。

请求:

json
{
  "amount_msat": "50000000",
  "expiry_secs": 86400,
  "quantity": "1",
  "payer_note": "退款"
}

响应:

json
{
  "refund": "lnr1...",
  "payment_id": "pay_abc123"
}

POST /api/v1/bolt12/refund/decode ​

解析 BOLT12 退款请求。

请求:

json
{
  "refund": "lnr1..."
}

响应:

json
{
  "description": "退款",
  "issuer": "Example",
  "amount_msat": "50000000",
  "absolute_expiry_unix_secs": "1704067200",
  "chain_hash": "000000000019d668...",
  "payer_signing_pubkey": "02def456...",
  "payer_note": "退款",
  "quantity": "1",
  "paths_count": 1
}

POST /api/v1/bolt12/refund/request_payment ​

按退款请求生成对应发票。

请求:

json
{
  "refund": "lnr1..."
}

响应:

json
{
  "invoice": "lni1...",
  "invoice_hex": "6c6e6931...",
  "payment_id": "pay_abc123"
}

自发支付 ​

POST /api/v1/spontaneous/send ​

发送自发支付（keysend），无需发票，直接向目标节点公钥付款。

请求:

json
{
  "counterparty_node_id": "02def456...",
  "amount_msat": "10000000",
  "custom_tlvs": [
    { "type": "5482373484", "value_hex": "0102..." }
  ]
}

custom_tlvs 可选，每项包含 type（u64 字符串）与 value_hex。

响应:

json
{
  "payment_id": "pay_abc123"
}

支付状态 ​

GET /api/v1/payments ​

列出节点的支付记录。

响应:

json
[
  {
    "id": "pay_abc123",
    "direction": "Outbound",
    "status": "Succeeded",
    "amount_msat": "10000000",
    "kind": "bolt11",
    "fee_paid_msat": "1000",
    "htlc_locked": false,
    "payment_hash": "abc123..."
  }
]

字段说明:

  • direction：Inbound 或 Outbound
  • status：Pending、Succeeded 或 Failed
  • kind：支付类型
  • htlc_locked：入站 HTLC 是否已锁定、等待领取或失败
  • payment_hash：顶层支付哈希（32 字节 hex）；链上或 BOLT12 支付可能为 null

GET /api/v1/payment/ ​

查询单个支付的详情。

响应: 与列表中单个对象相同的结构。

POST /api/v1/payment/{paymentId}/wait ​

阻塞等待支付进入终态或超时。

请求:

json
{
  "timeout_secs": 30
}

响应:

json
{
  "ok": true,
  "payment": {
    "id": "pay_abc123",
    "direction": "Outbound",
    "status": "Succeeded",
    "amount_msat": "10000000"
  }
}

POST /api/v1/payment/{paymentId}/abandon ​

放弃一个卡住的支付尝试。

响应:

json
{ "ok": true }

错误处理 ​

  • 400：请求参数无效
  • 402：余额或通道容量不足
  • 404：找不到路由或支付不存在
  • 408：支付或等待超时
  • 500：节点内部错误
  • 503：节点未就绪或正在同步

支付接口在超时或连接中断后可能已经改变节点状态，应通过 GET /payment/{paymentId} 或 GET /payments 核对实际结果，而不是直接重试付款。

示例 ​

生成发票并支付 ​

bash
# 生成发票
curl -X POST https://<你的节点域名>/api/v1/bolt11/receive \
  -H "Authorization: Bearer <节点凭证>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_msat": "10000000",
    "description": "咖啡付款",
    "expiry_secs": 3600
  }'

# 支付发票
curl -X POST https://<你的节点域名>/api/v1/bolt11/pay \
  -H "Authorization: Bearer <节点凭证>" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice": "lntb100u1..."
  }'

发送自发支付 ​

bash
curl -X POST https://<你的节点域名>/api/v1/spontaneous/send \
  -H "Authorization: Bearer <节点凭证>" \
  -H "Content-Type: application/json" \
  -d '{
    "counterparty_node_id": "02def456...",
    "amount_msat": "50000000"
  }'

等待支付完成 ​

bash
curl -X POST https://<你的节点域名>/api/v1/payment/pay_abc123/wait \
  -H "Authorization: Bearer <节点凭证>" \
  -H "Content-Type: application/json" \
  -d '{ "timeout_secs": 30 }'

交易并保护您的 RGB 资产 | 释放 RGB 协议的全部潜力

© 2026 Stash Labs. All rights reserved.