btc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

BTC Skill

BTC 工具

Provides Bitcoin L1 operations using mempool.space (free, no auth) and the Hiro Ordinals API (for inscription/cardinal classification on mainnet). Transfer operations require an unlocked wallet. Balance and fee queries work without a wallet.

本工具借助mempool.space（免费无需授权）和Hiro Ordinals API（用于主网的铭文/cardinal分类）提供比特币L1层操作。转账操作需要解锁钱包，而余额和手续费查询无需钱包即可使用。

Usage

使用方法

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

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

Subcommands

子命令

balance

余额查询

Get the BTC balance for a Bitcoin address. Returns total, confirmed, and unconfirmed balances.

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

Options:

```
--address
```
(optional) — Bitcoin address to check (uses active wallet's btcAddress if omitted)

Output:

json

{
  "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..."
}

查询比特币地址的BTC余额，返回总余额、已确认余额和未确认余额。

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

选项：

```
--address
```
（可选）——要查询的比特币地址（若省略则使用当前激活钱包的btcAddress）

输出：

json

{
  "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

手续费估算

Get current Bitcoin fee estimates for different confirmation targets.

bun run btc/btc.ts fees

Output:

json

{
  "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"
}

获取不同确认目标的当前比特币手续费估算值。

bun run btc/btc.ts fees

输出：

json

{
  "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

列出UTXO

List all UTXOs (Unspent Transaction Outputs) for a Bitcoin address.

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

Options:

```
--address
```
(optional) — Bitcoin address to check (uses active wallet if omitted)
```
--confirmed-only
```
(flag) — Only return confirmed UTXOs

Output:

json

{
  "address": "bc1q...",
  "network": "mainnet",
  "utxos": [
    {
      "txid": "abc123...",
      "vout": 0,
      "value": { "satoshis": 500000, "btc": "0.005 BTC" },
      "confirmed": true,
      "blockHeight": 800000,
      "blockTime": "2024-01-01T00:00:00.000Z"
    }
  ],
  "summary": {
    "count": 1,
    "totalValue": { "satoshis": 500000, "btc": "0.005 BTC" },
    "confirmedCount": 1,
    "unconfirmedCount": 0
  },
  "explorerUrl": "https://mempool.space/address/bc1q..."
}

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

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

选项：

```
--address
```
（可选）——要查询的比特币地址（若省略则使用当前激活钱包）
```
--confirmed-only
```
（标志）——仅返回已确认的UTXO

输出：

json

{
  "address": "bc1q...",
  "network": "mainnet",
  "utxos": [
    {
      "txid": "abc123...",
      "vout": 0,
      "value": { "satoshis": 500000, "btc": "0.005 BTC" },
      "confirmed": true,
      "blockHeight": 800000,
      "blockTime": "2024-01-01T00:00:00.000Z"
    }
  ],
  "summary": {
    "count": 1,
    "totalValue": { "satoshis": 500000, "btc": "0.005 BTC" },
    "confirmedCount": 1,
    "unconfirmedCount": 0
  },
  "explorerUrl": "https://mempool.space/address/bc1q..."
}

transfer

BTC转账

Transfer BTC to a recipient address. Requires an unlocked wallet with BTC balance.

By default only uses cardinal UTXOs (safe to spend — no inscriptions). Set

--include-ordinals

to allow spending ordinal UTXOs (advanced users only — WARNING: may destroy valuable inscriptions).

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

Options:

```
--recipient
```
(required) — Bitcoin address to send to
```
--amount
```
(required) — Amount in satoshis (1 BTC = 100,000,000 satoshis)
```
--fee-rate
```
(optional) —
```
fast
```
,
```
medium
```
,
```
slow
```
, or a number in sat/vB (default:
```
medium
```
)
```
--include-ordinals
```
(flag) — Include ordinal UTXOs (WARNING: may destroy inscriptions!)

Output:

json

{
  "success": true,
  "txid": "def456...",
  "explorerUrl": "https://mempool.space/tx/def456...",
  "transaction": {
    "recipient": "bc1q...",
    "amount": { "satoshis": 100000, "btc": "0.001 BTC" },
    "fee": { "satoshis": 1200, "btc": "0.000012 BTC", "rateUsed": "8 sat/vB" },
    "change": { "satoshis": 398800, "btc": "0.003988 BTC" },
    "vsize": 150,
    "utxoType": "cardinal-only"
  },
  "sender": "bc1q...",
  "network": "mainnet"
}

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

默认仅使用cardinal UTXO（可安全花费——无铭文）。设置

--include-ordinals

可允许使用ordinal UTXO（仅高级用户使用——警告：可能会销毁有价值的铭文）。

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

选项：

```
--recipient
```
（必填）——收款比特币地址
```
--amount
```
（必填）——转账金额，单位为聪（1 BTC = 100,000,000 聪）
```
--fee-rate
```
（可选）——
```
fast
```
、
```
medium
```
、
```
slow
```
，或自定义数值（单位：sat/vB），默认值为
```
medium
```
```
--include-ordinals
```
（标志）——允许使用ordinal UTXO（警告：可能会销毁铭文！）

输出：

json

{
  "success": true,
  "txid": "def456...",
  "explorerUrl": "https://mempool.space/tx/def456...",
  "transaction": {
    "recipient": "bc1q...",
    "amount": { "satoshis": 100000, "btc": "0.001 BTC" },
    "fee": { "satoshis": 1200, "btc": "0.000012 BTC", "rateUsed": "8 sat/vB" },
    "change": { "satoshis": 398800, "btc": "0.003988 BTC" },
    "vsize": 150,
    "utxoType": "cardinal-only"
  },
  "sender": "bc1q...",
  "network": "mainnet"
}

get-cardinal-utxos

获取Cardinal UTXO

Get cardinal UTXOs (safe to spend — no inscriptions). Only available on mainnet.

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

Options:

```
--address
```
(optional) — Bitcoin address to check (uses active wallet if omitted)
```
--confirmed-only
```
(flag) — Only return confirmed UTXOs

Output:

json

{
  "address": "bc1q...",
  "network": "mainnet",
  "type": "cardinal",
  "utxos": [...],
  "summary": { "count": 2, "totalValue": { "satoshis": 500000, "btc": "0.005 BTC" }, "confirmedCount": 2, "unconfirmedCount": 0 },
  "explorerUrl": "https://mempool.space/address/bc1q..."
}

获取cardinal UTXO（可安全花费——无铭文），仅支持主网。

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

选项：

```
--address
```
（可选）——要查询的比特币地址（若省略则使用当前激活钱包）
```
--confirmed-only
```
（标志）——仅返回已确认的UTXO

输出：

json

{
  "address": "bc1q...",
  "network": "mainnet",
  "type": "cardinal",
  "utxos": [...],
  "summary": { "count": 2, "totalValue": { "satoshis": 500000, "btc": "0.005 BTC" }, "confirmedCount": 2, "unconfirmedCount": 0 },
  "explorerUrl": "https://mempool.space/address/bc1q..."
}

get-ordinal-utxos

获取Ordinal UTXO

Get ordinal UTXOs (contain inscriptions — do not spend in regular transfers). Only available on mainnet.

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

Options:

```
--address
```
(optional) — Bitcoin address to check (uses active wallet if omitted)
```
--confirmed-only
```
(flag) — Only return confirmed UTXOs

Output:

json

{
  "address": "bc1q...",
  "network": "mainnet",
  "type": "ordinal",
  "utxos": [...],
  "summary": { "count": 1, "totalValue": { "satoshis": 546, "btc": "0.00000546 BTC" }, "confirmedCount": 1, "unconfirmedCount": 0 },
  "explorerUrl": "https://mempool.space/address/bc1q..."
}

获取ordinal UTXO（包含铭文——请勿在常规转账中花费），仅支持主网。

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

选项：

```
--address
```
（可选）——要查询的比特币地址（若省略则使用当前激活钱包）
```
--confirmed-only
```
（标志）——仅返回已确认的UTXO

输出：

json

{
  "address": "bc1q...",
  "network": "mainnet",
  "type": "ordinal",
  "utxos": [...],
  "summary": { "count": 1, "totalValue": { "satoshis": 546, "btc": "0.00000546 BTC" }, "confirmedCount": 1, "unconfirmedCount": 0 },
  "explorerUrl": "https://mempool.space/address/bc1q..."
}

get-inscriptions

查询铭文

Get all inscriptions owned by a Bitcoin address. Only available on mainnet (Hiro Ordinals API).

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

Options:

```
--address
```
(optional) — Bitcoin address to check (uses active wallet if omitted)

Output:

json

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

获取比特币地址拥有的所有铭文，仅支持主网（依赖Hiro Ordinals API）。

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

选项：

```
--address
```
（可选）——要查询的比特币地址（若省略则使用当前激活钱包）

输出:

json

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

Notes

注意事项

All fee queries use the public mempool.space API (no authentication required)
```
get-cardinal-utxos
```
,
```
get-ordinal-utxos
```
, and
```
get-inscriptions
```
require mainnet; on testnet no inscription indexing is available
```
transfer
```
is safe by default — it skips UTXOs that contain inscriptions
Wallet operations require an unlocked wallet (use
```
bun run wallet/wallet.ts unlock
```
first)

所有手续费查询均使用公开的mempool.space API（无需授权）
```
get-cardinal-utxos
```
、
```
get-ordinal-utxos
```
和
```
get-inscriptions
```
仅支持主网；测试网无铭文索引服务
默认情况下
```
transfer
```
操作是安全的——会跳过包含铭文的UTXO
钱包操作需要解锁钱包（请先执行
```
bun run wallet/wallet.ts unlock
```
）