aibtcdev/ordinals

Ordinals Skill

Provides Bitcoin ordinals operations using the micro-ordinals library, mempool.space API, and Unisat API. Creating inscriptions follows the two-step commit/reveal pattern — first inscribe broadcasts the commit transaction, then after it confirms, inscribe-reveal broadcasts the reveal transaction to finalize the inscription.

Inscription transfers use the Unisat API to look up inscription UTXOs and build mixed-input transactions (P2TR inscription + P2WPKH fees).

All write operations require an unlocked wallet with Taproot key support.

Usage

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

Subcommands

get-taproot-address

Get the wallet's Taproot (P2TR) address for receiving inscriptions. Requires an unlocked wallet.

bun run ordinals/ordinals.ts get-taproot-address

estimate-fee

Calculate the total cost (in satoshis) for creating an inscription.

bun run ordinals/ordinals.ts estimate-fee --content-type <type> --content-base64 <base64> [--fee-rate <rate>]

Options:

• --content-type (required) — MIME type (e.g., text/plain, image/png)
• --content-base64 (required) — Content as base64-encoded string
• --fee-rate (optional) — Fee rate in sat/vB (default: current medium fee)

inscribe

Create a Bitcoin inscription — STEP 1: Broadcast commit transaction.

bun run ordinals/ordinals.ts inscribe --content-type <type> --content-base64 <base64> [--fee-rate fast|medium|slow|<number>]

Options:

• --content-type (required) — MIME type
• --content-base64 (required) — Content as base64-encoded string
• --fee-rate (optional) — fast, medium, slow, or number in sat/vB (default: medium)

inscribe-reveal

Complete a Bitcoin inscription — STEP 2: Broadcast reveal transaction.

bun run ordinals/ordinals.ts inscribe-reveal \
  --commit-txid <txid> \
  --reveal-amount <satoshis> \
  --content-type <type> \
  --content-base64 <base64> \
  [--fee-rate fast|medium|slow|<number>]

Options:

• --commit-txid (required) — Transaction ID of the confirmed commit (64 hex chars)
• --reveal-amount (required) — Amount in the commit output (satoshis)
• --content-type (required) — MIME type (must match commit step)
• --content-base64 (required) — Content (must match commit step)
• --fee-rate (optional) — Fee rate for reveal tx (default: medium)

transfer-inscription

Transfer an inscription to a new owner. Looks up the inscription UTXO via Unisat, uses cardinal UTXOs from the SegWit address for fees, and sends the inscription to the recipient's Taproot address.

bun run ordinals/ordinals.ts transfer-inscription \
  --inscription-id <id> \
  --recipient <bc1p...> \
  [--fee-rate fast|medium|slow|<number>]

Options:

• --inscription-id (required) — Inscription ID (e.g., abc123...i0)
• --recipient (required) — Recipient Taproot address (bc1p... or tb1p...)
• --fee-rate (optional) — Fee rate (default: medium)

Output:

{
  "success": true,
  "txid": "def456...",
  "explorerUrl": "https://mempool.space/tx/def456...",
  "inscription": {
    "id": "abc123...i0",
    "contentType": "text/plain",
    "output": "abc123...:0"
  },
  "recipient": "bc1p...",
  "fee": { "satoshis": 1200, "rateUsed": "8 sat/vB" },
  "change": { "satoshis": 5000 },
  "network": "mainnet"
}

get-inscription

Fetch and parse inscription content from a Bitcoin reveal transaction.

bun run ordinals/ordinals.ts get-inscription --txid <txid>

Options:

• --txid (required) — Transaction ID of the reveal transaction (64 hex chars)

Two-Step Inscription Workflow

# Step 1: Inscribe (broadcasts commit tx)
CONTENT_B64=$(echo -n "Hello, Bitcoin!" | base64)
bun run ordinals/ordinals.ts inscribe --content-type text/plain --content-base64 "$CONTENT_B64"

# Wait for commit to confirm

# Step 2: Reveal (broadcasts reveal tx, creates inscription)
bun run ordinals/ordinals.ts inscribe-reveal \
  --commit-txid <commitTxid> \
  --reveal-amount <revealAmount> \
  --content-type text/plain \
  --content-base64 "$CONTENT_B64"

Notes

• inscribe and inscribe-reveal require a wallet unlocked via bun run wallet/wallet.ts unlock
• The wallet must have BTC balance on the SegWit (bc1q/tb1q) address for funding
• Inscriptions are received at the Taproot (bc1p/tb1p) address
• transfer-inscription requires UNISAT_API_KEY for inscription UTXO lookup
• Works on both mainnet and testnet (Unisat supports both)