SuperAPI AI Directory

bitcoin-inscription-guide

General & other

View repository

Updated 10-16 02:31

About this skill

Bitcoin Inscription Guide

Bitcoin inscriptions (Ordinals) let you permanently embed content — text, images, HTML, code — directly on the Bitcoin blockchain. This guide covers the full lifecycle from creation to marketplace.

What Are Inscriptions?

Inscriptions use the Ordinals protocol to embed arbitrary content into individual satoshis:

Bitcoin Transaction
    │
    └── Witness Data (SegWit)
            │
            └── Inscription Envelope
                    ├── Content-Type: "text/plain"
                    └── Body: "Hello, Bitcoin!"

Inscription Types

Type Content-Type Max Size Use Case
Text text/plain ~390KB Messages, poems, data
Image image/png, image/webp ~390KB Art, pfps, memes
HTML text/html ~390KB Interactive content
SVG image/svg+xml ~390KB Vector art
JSON application/json ~390KB BRC-20 tokens, metadata
JavaScript text/javascript ~390KB Recursive inscriptions
Audio audio/wav ~390KB Music
Video video/mp4 ~390KB Short clips

Creating Inscriptions

CLI Tool

# Install
npm install -g @nirholas/bitcoin-inscription

# Inscribe text
btc-inscribe text "Sperax <> Bitcoin" --fee-rate 10

# Inscribe image
btc-inscribe image ./my-art.png --fee-rate 10

# Inscribe HTML
btc-inscribe html ./interactive-art.html --fee-rate 10

Programmatic

import { Inscriber } from '@nirholas/bitcoin-inscription';

const inscriber = new Inscriber({
  network: 'mainnet',
  wallet: process.env.BTC_WALLET_WIF,
  feeRate: 10  // sats/vByte
});

// Inscribe text
const result = await inscriber.inscribeText('Hello from Sperax!');
console.log(`Inscription ID: ${result.inscriptionId}`);
console.log(`TX: ${result.txId}`);

BRC-20 Tokens

BRC-20 is a token standard built on inscriptions:

Deploy

{
  "p": "brc-20",
  "op": "deploy",
  "tick": "SPAX",
  "max": "21000000",
  "lim": "1000"
}

Mint

{
  "p": "brc-20",
  "op": "mint",
  "tick": "SPAX",
  "amt": "1000"
}

Transfer

{
  "p": "brc-20",
  "op": "transfer",
  "tick": "SPAX",
  "amt": "500"
}

Recursive Inscriptions

Inscriptions that reference other inscriptions:

<!-- This HTML inscription references an image inscription -->
<html>
  <body>
    <img src="/content/abc123...inscriptionId" />
    <script src="/content/def456...jsLibInscriptionId"></script>
  </body>
</html>

This enables:

  • On-chain libraries (inscribe jQuery once, reference from many)
  • Generative art with shared rendering code
  • Composable content

Fee Estimation

// Estimate inscription cost
const estimate = await inscriber.estimateFee({
  content: Buffer.from('Hello World'),
  contentType: 'text/plain',
  feeRate: 10
});

console.log(`Size: ${estimate.size} vBytes`);
console.log(`Fee: ${estimate.fee} sats ($${estimate.feeUSD})`);
console.log(`Total: ${estimate.total} sats`);

Marketplace Integration

// List inscription for sale
await inscriber.list({
  inscriptionId: 'abc123...',
  price: 100000,  // sats
  marketplace: 'magic-eden'  // or 'ordinals-wallet'
});

// Search inscriptions
const results = await inscriber.search({
  contentType: 'image/png',
  minSats: 1000,
  maxSats: 1000000,
  sort: 'newest'
});

Links