Learn-skills.dev runes

Bitcoin rune operations — check rune balances, list rune-bearing UTXOs, and transfer runes between addresses with Runestone OP_RETURN encoding. Uses the Unisat API for indexing.

install

source · Clone the upstream repo

git clone https://github.com/NeverSight/learn-skills.dev

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/NeverSight/learn-skills.dev "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/skills-md/aibtcdev/skills/runes" ~/.claude/skills/neversight-learn-skills-dev-runes && rm -rf "$T"

manifest: data/skills-md/aibtcdev/skills/runes/SKILL.md

source content

Runes Skill

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.

Usage

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:

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

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:

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

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:

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

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