Stash Labs

中文

English

中文

English

Appearance

RGB 操作 ​

节点上 RGB 资产操作的完整参考。所有路径均带 /api/v1 前缀。资产数量为原始资产单位，BTC 相关字段以 _sats 表示聪。

RGB 钱包与地址 ​

POST /api/v1/rgb/address/new ​

生成新的 RGB 钱包接收地址（推进 RGB 派生索引）。

响应:

json
{
  "address": "tb1q..."
}

GET /api/v1/rgb/address/current ​

返回最近一次生成的 RGB 地址，不推进派生索引。节点尚未初始化 RGB 地址时返回 404。

响应: 与 rgb/address/new 相同。

GET /api/v1/rgb/descriptor ​

获取 RGB 钱包的描述符。

响应:

json
{
  "descriptor": "wpkh([fingerprint/84'/1'/0']xpub.../0/*)",
  "derived_descriptors": [
    {
      "fingerprint": "a1b2c3d4",
      "derivation_path": "m/84'/1'/0'",
      "xpub": "xpub6...",
      "descriptor": "wpkh([a1b2c3d4/84'/1'/0']xpub6.../0/*)"
    }
  ]
}

derived_descriptors 可选。

POST /api/v1/rgb/sign_message ​

使用 RGB 钱包密钥签名消息。

请求:

json
{
  "message": "hello",
  "algorithm": "bitcoin_signed_message",
  "encoding": "hex",
  "compact": false
}

algorithm 取 bitcoin_signed_message 或 ecdsa；encoding 取 hex 或 base64；三者均为可选。

响应:

json
{
  "message": "hello",
  "algorithm": "bitcoin_signed_message",
  "signature": "3045...",
  "pubkey": "02def456...",
  "derivation_path": "m/84'/1'/0'/0/0",
  "digest_hex": "abc123...",
  "encoding": "hex",
  "compact": false
}

POST /api/v1/rgb/sync ​

同步 RGB 运行时状态。

响应:

json
{ "ok": true }

RGB UTXO 查询 ​

GET /api/v1/rgb/utxos ​

列出 RGB 钱包域的颜色载体 UTXO，包含确认状态、锁定状态与 RGB 分配。

查询参数: refresh=true 时先与索引器核对确认高度。只有显式 refresh 才会更新确认高度；/rgb/sync 与 /wallet/sync 不会刷新该域。

响应:

json
{
  "utxos": [
    {
      "outpoint": "txid:1",
      "value_sats": "10000",
      "confirmation": { "status": "confirmed", "height": 250000 },
      "lock": { "locked": false, "kind": "none", "operation_id": null },
      "rgb": {
        "allocations": [
          { "contract_id": "contract:...", "amount": "1000", "layer": "base" }
        ],
        "has_mixed_asset_allocations": false,
        "spend_roles": ["rgb-state"]
      }
    }
  ]
}

字段说明:

  • value_sats：该载体 UTXO 的 BTC 金额（聪）
  • confirmation.status：confirmed 或 mempool
  • lock.kind：none、manual_reservation 或 operation
  • rgb.allocations[].layer：RGB 状态层，例如 base、active、pending
  • rgb.has_mixed_asset_allocations：是否同时承载多个合约的分配
  • rgb.spend_roles：该 UTXO 可承担的角色，例如 rgb-state、fee-support

GET /api/v1/rgb/utxos/summary ​

返回 RGB 钱包域颜色载体 UTXO 的摘要，含确认高度，便于快速汇总可用与已占用容量。

查询参数: refresh=true 时先执行一次本地核对。

响应:

json
{
  "utxos": [
    {
      "outpoint": "txid:1",
      "value_sats": "10000",
      "confirmed_height": 250000,
      "reserved": false,
      "reserved_until_unix_secs": "1704067200",
      "assets": [
        { "contract_id": "contract:...", "amount": "1000" }
      ]
    }
  ]
}

容量操作 ​

RGB 链上转账与 RGB 通道都需要颜色载体 UTXO。下列接口用于显式准备与回收载体容量，均为显式输入输出，不使用自动选币。

POST /api/v1/rgb/utxos/fund ​

用普通 BTC 钱包输入创建专属的 RGB 钱包 UTXO。

请求:

json
{
  "inputs": [
    { "outpoint": "txid:0" }
  ],
  "outputs": [
    { "address": "tb1q...", "value_sats": "10000" }
  ],
  "change_address": "tb1q...",
  "fee_rate_sats_per_vb": 1.5
}

参数说明:

  • inputs：来自 GET /wallet/utxos 的普通 BTC 输入
  • outputs：要创建的 RGB 钱包输出，地址来自 POST /rgb/address/new
  • change_address：找零地址，来自 POST /wallet/address/new，必须不同于所有 RGB 输出脚本
  • fee_rate_sats_per_vb：正数费率（聪/vB）

响应:

json
{
  "txid": "abc123...",
  "status": "broadcast",
  "outputs": [
    { "address": "tb1q...", "value_sats": "10000", "vout": 1 }
  ],
  "fee_sats": "500",
  "change": { "address": "tb1q...", "value_sats": "89000", "vout": 2 }
}

status 表示交易当前状态（已签名并交由广播器）。change 可选。

POST /api/v1/rgb/utxos/top_up ​

在不新建 UTXO 的前提下扩容现有 RGB UTXO（替换式转移）。

请求:

json
{
  "rgb_input": { "outpoint": "txid:1" },
  "l1_inputs": [
    { "outpoint": "txid:0" }
  ],
  "rgb_output": { "address": "tb1q...", "target_value_sats": "20000" },
  "change_address": "tb1q...",
  "fee_rate_sats_per_vb": 1.5
}

rgb_output.target_value_sats 必须大于原 RGB UTXO 的 BTC 金额。

响应:

json
{
  "txid": "abc123...",
  "status": "broadcast",
  "old_outpoint": "txid:1",
  "new_rgb_output": { "address": "tb1q...", "value_sats": "20000", "vout": 1 },
  "fee_sats": "600",
  "consignment_key": "consign_abc123",
  "change": { "address": "tb1q...", "value_sats": "78000", "vout": 2 }
}

POST /api/v1/rgb/utxos/sweep ​

回收无 RGB 分配的空 RGB UTXO，把 BTC 扫回普通 BTC 钱包，减少碎片化与锁定资金。

请求:

json
{
  "input": { "outpoint": "txid:1" },
  "destination_address": "tb1q...",
  "fee_rate_sats_per_vb": 1.5
}

响应:

json
{
  "txid": "abc123...",
  "status": "broadcast",
  "input": { "outpoint": "txid:1" },
  "destination": { "address": "tb1q...", "value_sats": "9400", "vout": 0 },
  "fee_sats": "600"
}

UTXO 预留的释放（POST /rgb/utxos/release）与单 outpoint 状态查询见 UTXO 管理。

RGB 合约 ​

GET /api/v1/rgb/contracts ​

列出节点已知的 RGB 合约。

响应:

json
{
  "contracts": [
    {
      "contract_id": "contract:...",
      "name": "Example Asset",
      "ticker": "EXA",
      "precision": 8,
      "issued_supply": "1000000",
      "details": "可选说明"
    }
  ]
}

name、ticker、precision、issued_supply、details 均为可选字段。

GET /api/v1/rgb/contract/{contract_id}/balance ​

查询单个合约的余额。合约未在本地导入时返回 404（ContractNotFound）。

响应:

json
{
  "contract_id": "contract:...",
  "balance": {
    "mined": "1000",
    "tentative": "0",
    "offchain": "500",
    "archived": "0",
    "total": "1500"
  }
}

GET /api/v1/rgb/contract/{contract_id}/known ​

检查某个合约是否已在本地已知。

响应:

json
{
  "contract_id": "contract:...",
  "known": true
}

POST /api/v1/rgb/contracts/issue ​

发行新的 RGB 资产。

请求:

json
{
  "issuer_name": "example-issuer",
  "contract_name": "Example Asset",
  "ticker": "EXA",
  "precision": 8,
  "issued_supply": "1000000",
  "utxo": "txid:0"
}

ticker、precision、utxo 可选；utxo 用于指定发行的载体 outpoint。

响应:

json
{
  "ok": true,
  "contract_id": "contract:...",
  "issued_supply": "1000000"
}

POST /api/v1/rgb/contracts/export ​

导出合约。

请求:

json
{
  "contract_id": "contract:..."
}

响应:

json
{
  "ok": true,
  "contract_id": "contract:...",
  "consignment_key": "consign_abc123"
}

POST /api/v1/rgb/contracts/import ​

导入合约文件。请求体为二进制归档（Content-Type: application/octet-stream），通过查询参数指定合约与格式。

查询参数: contract_id=<合约 ID>、format=zip|raw（ZIP 归档以 PK\x03\x04 开头，否则为 raw）。

响应:

json
{
  "ok": true,
  "contract_id": "contract:...",
  "consignment_key": "consign_abc123"
}

RGB 发行方 ​

GET /api/v1/rgb/issuers ​

列出本地发行方注册表中的有效发行方名称。

响应:

json
{
  "issuers": ["example-issuer"],
  "invalid_issuers": [
    { "name": "broken-issuer", "error": "failed to parse" }
  ]
}

invalid_issuers 为可选数组，列出扫描时加载失败的发行方文件。

POST /api/v1/rgb/issuers/import ​

导入发行方文件。请求体为原始二进制（Content-Type: application/octet-stream）。

查询参数: name=<发行方名称>、format=raw。

响应:

json
{
  "ok": true,
  "issuer_name": "example-issuer"
}

RGB 闪电支付 ​

POST /api/v1/rgb/ln/invoice/create ​

创建 RGB 闪电发票。

请求:

json
{
  "contract_id": "contract:...",
  "asset_amount": "100",
  "description": "RGB 支付",
  "expiry_secs": 3600,
  "btc_carrier_amount_msat": "3000000"
}

expiry_secs 与 btc_carrier_amount_msat 可选；省略载体金额时由节点自动计算并提升。

响应:

json
{
  "invoice": "lnbcrt1...",
  "btc_carrier_amount_msat": "3000000"
}

btc_carrier_amount_msat 为发票中实际嵌入的载体金额，可能高于请求值。

POST /api/v1/rgb/ln/invoice/create_for_hash ​

使用指定 payment_hash 创建 RGB 闪电发票。

请求:

json
{
  "contract_id": "contract:...",
  "asset_amount": "100",
  "payment_hash": "abc123...",
  "description": "RGB 支付",
  "expiry_secs": 3600
}

响应: 与 rgb/ln/invoice/create 相同。

POST /api/v1/rgb/ln/invoice/decode ​

解析 RGB 闪电发票。

请求:

json
{
  "invoice": "lnbcrt1..."
}

响应:

json
{
  "payment_hash": "abc123...",
  "destination": "02def456...",
  "carrier_amount_msat": "3000000",
  "expiry_secs": "3600",
  "contract_id": "contract:...",
  "asset_amount": "100"
}

carrier_amount_msat、contract_id、asset_amount 可选。

POST /api/v1/rgb/ln/invoice/estimate_carrier ​

预估创建 RGB 闪电发票所需的 BTC 载体金额。该接口为非约束性快照估算，不改变节点状态。

请求:

json
{
  "contract_id": "contract:...",
  "asset_amount": "100",
  "description": "RGB 支付",
  "expiry_secs": 3600
}

响应:

json
{
  "receive_available": true,
  "can_create_rgb_invoice": true,
  "minimum_viable_carrier_amount_msat": "3000000",
  "minimum_viable_reason": "...",
  "default_create_carrier_amount_msat": "3000000",
  "default_create_reason": "...",
  "carrier_admission_threshold_msat": "...",
  "minimum_allowed_carrier_amount_msat": "...",
  "holder_reserve_threshold_msat": "...",
  "channels": [
    {
      "channel_id": "abc123...",
      "user_channel_id": "user_abc123",
      "is_usable": true,
      "inbound_capacity_msat": "500000000",
      "inbound_htlc_minimum_msat": "1000",
      "inbound_htlc_maximum_msat": "490000000",
      "local_balance_output_sats": "200000",
      "has_holder_reserve": true,
      "receive_available": true,
      "can_receive_rgb_invoice": true,
      "blocking_reason": null,
      "minimum_viable_carrier_amount_msat": "3000000",
      "default_create_carrier_amount_msat": "3000000",
      "required_carrier_msat": null,
      "suggested_action": null
    }
  ],
  "estimate_only": true,
  "warning": "",
  "blocking_reason": null,
  "required_carrier_msat": null,
  "suggested_action": null
}

channels 为该时刻各通道的载体接收能力快照。

POST /api/v1/rgb/ln/pay ​

支付 RGB 闪电发票。

请求:

json
{
  "invoice": "lnbcrt1...",
  "contract_id": "contract:...",
  "asset_amount": "100"
}

contract_id 与 asset_amount 可选，通常由发票推导。

响应:

json
{
  "payment_id": "pay_abc123"
}

支付是否成功以 支付状态 的 GET /payment/{paymentId} 结果为准。RGB 支付同时消耗同一条通道上的 RGB 资产与 BTC 载体，付款前应确认该合约通道的本地资产余额与可发出容量。

RGB 链上转账 ​

POST /api/v1/rgb/onchain/invoice/create ​

创建 RGB 链上发票。

请求:

json
{
  "contract_id": "contract:...",
  "amount": "1000",
  "expiry_secs": "86400",
  "use_witness_utxo": true,
  "nonce": "0",
  "blinding_utxo": "txid:0"
}

除 contract_id 与 amount 外均为可选。

响应:

json
{
  "invoice": "rgb:tb1q.../12345",
  "blinding_utxo_used": "txid:0"
}

blinding_utxo_used 可选。

POST /api/v1/rgb/onchain/invoice/decode ​

解析 RGB 链上发票。

请求:

json
{
  "invoice": "rgb:tb1q.../12345"
}

响应:

json
{
  "contract_id": "contract:...",
  "amount": "1000",
  "beneficiary": "tb1q...",
  "use_witness_utxo": true,
  "expiry_unix_secs": "1704067200"
}

POST /api/v1/rgb/onchain/send ​

在链上按发票发送 RGB 资产。

请求:

json
{
  "invoice": "rgb:tb1q.../12345",
  "sats_for_fee_and_outputs": "1000",
  "fee_rate_sats_per_vb": 1.5
}

sats_for_fee_and_outputs 可选，用于覆盖手续费与输出的 BTC 金额。

响应:

json
{
  "txid": "abc123...",
  "consignment_key": "consign_abc123"
}

POST /api/v1/rgb/onchain/receive ​

接收一份 RGB consignment。

请求:

json
{
  "consignment_key": "consign_abc123",
  "payment_id": "pay_abc123",
  "invoice": "rgb:tb1q.../12345"
}

也可使用原始二进制方式提交归档：POST /api/v1/rgb/onchain/receive?format=zip&payment_id=<id>，请求体为 Content-Type: application/octet-stream 的归档字节。

响应:

json
{
  "contract_id": "contract:...",
  "amount": "1000"
}

GET /api/v1/rgb/onchain/payments ​

列出 RGB 链上支付记录。

响应:

json
{
  "payments": [
    {
      "id": "pay_abc123",
      "kind": "...",
      "status": "...",
      "created_at_unix_secs": "1704067200",
      "latest_update_timestamp": "1704067200",
      "expires_at_unix_secs": "1704067200",
      "invoice": "rgb:tb1q.../12345",
      "contract_id": "contract:...",
      "amount": "1000",
      "txid": "abc123...",
      "consignment_key": "consign_abc123",
      "consignment_download_path": "/api/v1/rgb/consignments/consign_abc123",
      "purpose": null
    }
  ]
}

purpose 为内部维护标记（utxo_merge / utxo_top_up），普通用户发起的支付为空。

GET /api/v1/rgb/consignments/ ​

下载 consignment。

查询参数: format=raw|gzip|zip（默认 raw）。

响应: 二进制归档流。开启 RGB 通道时 rgb.color_context_data 指向的下载地址即该接口的模板形式 .../rgb/consignments/{txid}?format=zip。

错误处理 ​

  • 400：RGB 数据或参数无效
  • 404：资产、合约或 consignment 不存在
  • 409：RGB 资产余额不足
  • 422：consignment 校验失败
  • 500：RGB 操作失败
  • 503：节点未就绪或正在同步

RGB 链上发送可能在返回 4xx 前已完成 RGB 状态提交，节点状态可能已改变；失败后应重新读取余额与 UTXO，而不是直接重试。

示例 ​

发行新的 RGB 资产 ​

bash
curl -X POST https://<你的节点域名>/api/v1/rgb/contracts/issue \
  -H "Authorization: Bearer <节点凭证>" \
  -H "Content-Type: application/json" \
  -d '{
    "issuer_name": "example-issuer",
    "contract_name": "我的代币",
    "ticker": "TEST",
    "precision": 8,
    "issued_supply": "1000000"
  }'

创建 RGB 闪电发票 ​

bash
curl -X POST https://<你的节点域名>/api/v1/rgb/ln/invoice/create \
  -H "Authorization: Bearer <节点凭证>" \
  -H "Content-Type: application/json" \
  -d '{
    "contract_id": "contract:...",
    "asset_amount": "100",
    "description": "RGB 支付",
    "expiry_secs": 3600
  }'

RGB 链上转账 ​

bash
curl -X POST https://<你的节点域名>/api/v1/rgb/onchain/send \
  -H "Authorization: Bearer <节点凭证>" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice": "rgb:tb1q.../12345",
    "fee_rate_sats_per_vb": 2.0
  }'

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

© 2026 Stash Labs. All rights reserved.