mcpField
R
runes

runes

github.com/aibtcdevOther11113 installsUpdated 1d ago
Repository

About runes

runes is a skill for checking Bitcoin Rune balances and UTXOs and transferring Runes. It uses Unisat for indexing and mempool.space for fee estimates and broadcasting, with explicit change handling to protect remaining Runes.

Key features

  1. 01Check Rune balances by address
  2. 02List UTXOs for a Rune ID
  3. 03Transfer Runes to a recipient
  4. 04Use explicit Runestone change pointers
  5. 05Support mainnet and testnet

Use cases

  1. 01Review Runes held at an address
  2. 02Find UTXOs for a specific Rune
  3. 03Send Runes while preserving the remainder

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/aibtcdev/skills --skill runes

After installing, type/runesin Claude Code to confirm it loaded.

Bundled filesAGENT.mdrunes.ts

Details

From the project README

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

Comments

Markdown supported