runes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Runes Skill

Runes 操作脚本

Provides Bitcoin rune operations using the Unisat API for rune indexing and mempool.space for fee estimation and broadcasting. Rune transfers use Runestone OP_RETURN encoding with explicit change pointers to prevent accidental rune burning.

Requires

UNISAT_API_KEY

environment variable. Works on both mainnet and testnet.

提供比特币Rune操作功能，使用Unisat API进行Rune索引，借助mempool.space进行手续费估算和交易广播。Rune转移采用带有明确找零指针的Runestone OP_RETURN编码，以防止意外烧毁Rune。

需要设置

UNISAT_API_KEY

环境变量。支持主网和测试网。

Usage

使用方法

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

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

Subcommands

子命令

balance

查询余额

Get rune balances for a Bitcoin address. Returns all rune token balances held by the address.

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

Options:

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

Output:

json

{
  "address": "bc1p...",
  "network": "mainnet",
  "balances": [
    {
      "rune": "UNCOMMONGOODS",
      "runeId": "1:0",
      "spacedRune": "UNCOMMON•GOODS",
      "amount": "1000000",
      "formatted": "1000000 ⧫",
      "symbol": "⧫",
      "divisibility": 0
    }
  ],
  "summary": { "runeCount": 1 },
  "explorerUrl": "https://mempool.space/address/bc1p..."
}

查询比特币地址的Rune余额。返回该地址持有的所有Rune代币余额。

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

选项：

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

输出：

json

{
  "address": "bc1p...",
  "network": "mainnet",
  "balances": [
    {
      "rune": "UNCOMMONGOODS",
      "runeId": "1:0",
      "spacedRune": "UNCOMMON•GOODS",
      "amount": "1000000",
      "formatted": "1000000 ⧫",
      "symbol": "⧫",
      "divisibility": 0
    }
  ],
  "summary": { "runeCount": 1 },
  "explorerUrl": "https://mempool.space/address/bc1p..."
}

utxos

列出UTXO

List rune-bearing UTXOs for a specific rune on a Bitcoin address.

bun run runes/runes.ts utxos --rune-id <id> [--address <addr>]

Options:

```
--rune-id
```
(required) — Rune ID (e.g.,
```
840000:1
```
)
```
--address
```
(optional) — Bitcoin address to check (uses active wallet's Taproot address if omitted)

Output:

json

{
  "address": "bc1p...",
  "network": "mainnet",
  "runeId": "840000:1",
  "utxos": [
    {
      "txid": "abc123...",
      "vout": 0,
      "satoshis": 546,
      "runes": [
        {
          "runeId": "840000:1",
          "spacedRune": "UNCOMMON•GOODS",
          "amount": "1000000",
          "formatted": "1000000 ⧫",
          "symbol": "⧫"
        }
      ]
    }
  ],
  "summary": { "utxoCount": 1, "totalSatoshis": 546 }
}

列出比特币地址中持有特定Rune的UTXO。

bun run runes/runes.ts utxos --rune-id <id> [--address <addr>]

选项：

```
--rune-id
```
（必填）——Rune ID（例如：
```
840000:1
```
）
```
--address
```
（可选）——要查询的比特币地址（如果省略则使用当前钱包的Taproot地址）

输出：

json

{
  "address": "bc1p...",
  "network": "mainnet",
  "runeId": "840000:1",
  "utxos": [
    {
      "txid": "abc123...",
      "vout": 0,
      "satoshis": 546,
      "runes": [
        {
          "runeId": "840000:1",
          "spacedRune": "UNCOMMON•GOODS",
          "amount": "1000000",
          "formatted": "1000000 ⧫",
          "symbol": "⧫"
        }
      ]
    }
  ],
  "summary": { "utxoCount": 1, "totalSatoshis": 546 }
}

transfer

转移Rune

Transfer runes to a recipient address. Builds a transaction with a Runestone OP_RETURN that directs runes to the recipient and returns remaining runes to the sender via an explicit change pointer.

bun run runes/runes.ts transfer --rune-id <id> --amount <amount> --recipient <addr> [--fee-rate fast|medium|slow|<number>]

Options:

```
--rune-id
```
(required) — Rune ID (e.g.,
```
840000:1
```
)
```
--amount
```
(required) — Amount of runes to transfer (in smallest unit)
```
--recipient
```
(required) — Recipient address
```
--fee-rate
```
(optional) — Fee rate (default:
```
medium
```
)

Output:

json

{
  "success": true,
  "txid": "def456...",
  "explorerUrl": "https://mempool.space/tx/def456...",
  "rune": { "runeId": "840000:1", "amount": "500000" },
  "recipient": "bc1p...",
  "fee": { "satoshis": 1800, "rateUsed": "10 sat/vB" },
  "btcChange": { "satoshis": 5000 },
  "network": "mainnet"
}

将Rune转移至接收地址。构建带有Runestone OP_RETURN的交易，将Rune定向到接收方，并通过明确的找零指针将剩余Rune返回给发送方。

bun run runes/runes.ts transfer --rune-id <id> --amount <amount> --recipient <addr> [--fee-rate fast|medium|slow|<number>]

选项：

```
--rune-id
```
（必填）——Rune ID（例如：
```
840000:1
```
）
```
--amount
```
（必填）——要转移的Rune数量（以最小单位计）
```
--recipient
```
（必填）——接收地址
```
--fee-rate
```
（可选）——手续费率（默认：
```
medium
```
）

输出：

json

{
  "success": true,
  "txid": "def456...",
  "explorerUrl": "https://mempool.space/tx/def456...",
  "rune": { "runeId": "840000:1", "amount": "500000" },
  "recipient": "bc1p...",
  "fee": { "satoshis": 1800, "rateUsed": "10 sat/vB" },
  "btcChange": { "satoshis": 5000 },
  "network": "mainnet"
}

Safety

安全说明

Rune transfers always include an explicit change pointer in the Runestone to avoid burning remaining rune balances
Cardinal UTXOs from the SegWit address pay fees — rune-bearing UTXOs are never used for fee payment
The transfer command validates rune balance before building the transaction

Rune转移在Runestone中始终包含明确的找零指针，以避免烧毁剩余Rune余额
来自SegWit地址的核心UTXO用于支付手续费——持有Rune的UTXO绝不会用于支付手续费
转移命令在构建交易前会验证Rune余额

Notes

注意事项

Runes are typically held at Taproot (bc1p) addresses
Fee payment comes from the SegWit (bc1q) address
Requires an unlocked wallet (use
```
bun run wallet/wallet.ts unlock
```
first)
Set
```
UNISAT_API_KEY
```
environment variable for Unisat API access

Runes通常存储在Taproot（bc1p）地址中
手续费由SegWit（bc1q）地址支付
需要解锁钱包（先执行
```
bun run wallet/wallet.ts unlock
```
）
需设置
```
UNISAT_API_KEY
```
环境变量以访问Unisat API