runes

Original：🇺🇸 English

Translated

1 scriptsChecked / no sensitive code detected

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.

3installs

Sourceaibtcdev/skills

Added on2026-03-28

NPX Install

npx skill4agent add aibtcdev/skills runes

SKILL.md Content

View Translation Comparison →

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:

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

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

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:

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

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

NPX Install

Tags

SKILL.md Content

Runes Skill

Usage

Subcommands

balance

utxos

transfer

Safety

Notes