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

runes

Runes Skill

Usage

Subcommands

balance