btc

BTC 技能

使用 mempool.space（免费，无需身份验证）和 Unisat API（用于在主网和测试网上对铭文、符文和普通 UTXO 进行分类）执行 Bitcoin L1 操作。转账操作需要已解锁的钱包。查询余额和手续费无需钱包。

UTXO 分类命令需要设置 UNISAT_API_KEY 环境变量。

用法

bun run btc/btc.ts <subcommand> [options]

子命令

balance

查询 Bitcoin 地址的 BTC 余额。返回总余额、已确认余额和未确认余额。

bun run btc/btc.ts balance [--address <addr>]

选项：

• --address（可选）— 要查询的 Bitcoin 地址（若省略，则使用当前钱包的 btcAddress）

输出：

{
  "address": "bc1q...",
  "network": "mainnet",
  "balance": { "satoshis": 500000, "btc": "0.005 BTC" },
  "confirmed": { "satoshis": 500000, "btc": "0.005 BTC" },
  "unconfirmed": { "satoshis": 0, "btc": "0 BTC" },
  "utxoCount": 2,
  "explorerUrl": "https://mempool.space/address/bc1q..."
}

fees

获取针对不同确认目标的当前 Bitcoin 手续费估算。

bun run btc/btc.ts fees

输出：

{
  "network": "mainnet",
  "fees": {
    "fast": { "satPerVb": 15, "target": "~10 minutes (next block)" },
    "medium": { "satPerVb": 8, "target": "~30 minutes" },
    "slow": { "satPerVb": 3, "target": "~1 hour" }
  },
  "economy": { "satPerVb": 1, "target": "~24 hours" },
  "minimum": { "satPerVb": 1, "target": "minimum relay fee" },
  "unit": "sat/vB"
}

utxos

列出 Bitcoin 地址的所有 UTXO（未花费交易输出）。

bun run btc/btc.ts utxos [--address <addr>] [--confirmed-only]

选项：

• --address（可选）— 要查询的 Bitcoin 地址（若省略，则使用当前钱包）
• --confirmed-only（标志）— 仅返回已确认的 UTXO

transfer

向收款地址转账 BTC。需要已解锁且有 BTC 余额的钱包。

默认情况下仅使用普通 UTXO（可安全花费，不含铭文或符文）。设置 --include-ordinals 可允许花费所有 UTXO（仅限高级用户 — 警告：可能会销毁有价值的铭文或符文）。

bun run btc/btc.ts transfer --recipient <addr> --amount <satoshis> [--fee-rate fast|medium|slow|<number>] [--include-ordinals]

选项：

• --recipient（必需）— 要发送到的 Bitcoin 地址
• --amount（必需）— 金额，单位为聪（1 BTC = 100,000,000 聪）
• --fee-rate（可选）— fast、medium、slow 或以 sat/vB 为单位的数字（默认：medium）
• --include-ordinals（标志）— 包含所有 UTXO（警告：可能会销毁铭文或符文！）

get-cardinal-utxos

获取普通 UTXO（可安全花费，不含铭文或符文）。

bun run btc/btc.ts get-cardinal-utxos [--address <addr>] [--confirmed-only]

选项：

• --address（可选）— 要查询的 Bitcoin 地址（若省略，则使用当前钱包）
• --confirmed-only（标志）— 仅返回已确认的 UTXO

get-ordinal-utxos

获取序数 UTXO（包含铭文 — 不要在常规转账中花费）。

bun run btc/btc.ts get-ordinal-utxos [--address <addr>] [--confirmed-only]

选项：

• --address（可选）— 要查询的 Bitcoin 地址（若省略，则使用当前钱包）
• --confirmed-only（标志）— 仅返回已确认的 UTXO

get-rune-utxos

获取符文 UTXO（包含符文余额 — 不要在常规转账中花费）。

bun run btc/btc.ts get-rune-utxos [--address <addr>] [--confirmed-only]

选项：

• --address（可选）— 要查询的 Bitcoin 地址（若省略，则使用当前钱包）
• --confirmed-only（标志）— 仅返回已确认的 UTXO

get-inscriptions

通过 Unisat API 获取 Bitcoin 地址拥有的所有铭文。

bun run btc/btc.ts get-inscriptions [--address <addr>]

选项：

• --address（可选）— 要查询的 Bitcoin 地址（若省略，则使用当前钱包）

输出：

{
  "address": "bc1q...",
  "network": "mainnet",
  "inscriptions": [
    {
      "id": "abc123...i0",
      "number": 12345,
      "contentType": "text/plain",
      "contentLength": 42,
      "output": "abc123...:0",
      "location": "abc123...:0:0",
      "offset": 0,
      "outputValue": 546,
      "genesis": {
        "txid": "abc123...",
        "timestamp": "2024-01-01T00:00:00.000Z"
      }
    }
  ],
  "summary": { "count": 1, "contentTypes": ["text/plain"] },
  "explorerUrl": "https://mempool.space/address/bc1q..."
}

注意事项

• 所有手续费查询均使用公开的 mempool.space API（无需身份验证）
• UTXO 分类（普通／序数／符文）使用 Unisat API，在主网和测试网上均可使用
• transfer 默认安全 — 会跳过包含铭文或符文的 UTXO
• 钱包操作需要已解锁的钱包（请先运行 bun run wallet/wallet.ts unlock）
• 设置 UNISAT_API_KEY 环境变量以访问 Unisat API