Ordinals

Skill based on ord (Ordinals) from sources/ordinals (docs/ and repo root), generated 2026-02-24. Docs: sources/ordinals/docs/src/, docs.ordinals.com.

ord is an index, block explorer, and CLI wallet for Bitcoin Ordinals. It tracks sat locations via Bitcoin Core (with -txindex), serves inscriptions and explorer UI, and provides wallet subcommands for inscribing and sat-aware sends. It supports inscriptions (digital artifacts on sats), recursion, runes (fungible tokens), and a JSON API.

Core References

Features

Inscriptions

Runes

Wallet and API

Best Practices

External Links

• Ordinals docs
• ord GitHub
• Ordinal theory BIP

Generation Info

• Source: sources/ordinals (https://github.com/ordinals/ord)
• Git SHA: 2cbd9bac519e3478dc82e8db4351121e660941e8
• Generated: 2026-02-24
• Docs used: docs/src/ (overview, inscriptions/, runes, guides/wallet, api, settings, reindexing, batch-inscribing, security), README.md, bip.mediawiki

Batch Inscribing

Create multiple inscriptions in one go with a single command. Use a batch file (YAML) and the pointer so each inscription is on a different sat; optional parent links all to one parent inscription (e.g. for collections).

Command

ord wallet batch --fee-rate 21 --batch batch.yaml

Adjust --fee-rate and add other wallet/inscribe options as needed.

Batch file (batch.yaml)

The batch file lists entries (files and optional metadata). Each entry can specify:

• File (or content) to inscribe.
• Parent inscription ID so all batch children share the same parent.
• Pointer (or rely on default ordering) so each inscription lands on a distinct sat in the reveal tx.

Example structure (see repo batch.yaml for full include):

# Multiple items; parent and pointer set so each is a child of one parent
# and on a different sat in the batch tx

When parent is set, the reveal transaction that creates the batch inscriptions can include that parent; pointer values assign each inscription to a different sat, avoiding collisions.

When to use

• Collections: One parent inscription; many child inscriptions (e.g. 100 items) in one batch, same parent, pointers 0..99 (or equivalent).
• Efficiency: One transaction fee for many inscriptions instead of one tx per inscription.
• Atomicity: All inscriptions in the batch confirm together or not at all.

Ensure the wallet has enough cardinal sats for fees and enough UTXOs for the batch size; use ord wallet balance and plan fee rate.

<!-- Source references:

• sources/ordinals/docs/src/guides/batch-inscribing.md
• sources/ordinals/docs/src/inscriptions/pointer.md

-->

Reindexing ord

Reindexing means deleting the ord index and rebuilding it with ord index update or ord server. Do this when:

1. A new major release of ord changes the database schema. 2. The database is corrupted.

Index location

Default index file: index.redb (redb). Default directory by OS:

Full path example (macOS): ~/Library/Application Support/ord/index.redb.

Steps

1. Stop any running ord server (or other ord process using the index). 2. Delete the index file: rm "<data_dir>/index.redb" (or use --datadir / --index if you overrode paths.) 3. Rebuild: ord index update or start ord server (which will rebuild the index).

Custom paths:

ord --datadir /path/to/dir index update
ord --index /path/to/index.redb index update

Reindexing from scratch can take a long time on a full chain; ensure enough disk space and that bitcoind is synced with txindex.

<!-- Source references:

• sources/ordinals/docs/src/guides/reindexing.md

-->

Ordinal Theory

Ordinals are a numbering scheme for satoshis: each sat is assigned a serial number in the order it was mined. Numbers transfer from transaction inputs to outputs in first-in-first-out order according to input/output order and sizes. No separate token or protocol change is required; it works on Bitcoin as-is.

Key concepts

• Ordinal number: Serial number of a sat (e.g. integer 2099994106992659).
• Satpoint: Location of a sat in an output: TXID:OUTPUT_INDEX:OFFSET. Example: 680df1e4...d22:0:6 is offset 6 in the first output of that tx.
• Transfer: In a block, coinbase creates new sats; for other txs, input ordinals are concatenated and assigned to outputs in order. Unassigned ordinals from fee-paying txs go to the coinbase.

Notation

Rarity (degree notation)

Rarity is derived from periodic Bitcoin events:

• common: Not first sat of block
• uncommon: First sat of each block
• rare: First sat of each difficulty adjustment (2016 blocks)
• epic: First sat of each halving (210,000 blocks)
• legendary: First sat of each cycle (6 halvings)
• mythic: First sat of genesis block

Degree format A°B′C″D‴ maps to cycle, block-in-period, block-in-epoch, sat-in-block. When block offset is zero it may be omitted.

Usage for agents

• Use integer or satpoint when referring to a specific sat in code or APIs.
• Use degree when displaying or filtering by rarity.
• Transfer logic: ordinals in inputs are spent in order; outputs receive ordinals in order. Splits/merges require care for dust limits (see BIP).

<!-- Source references:

• https://github.com/ordinals/ord/blob/master/bip.mediawiki
• sources/ordinals/docs/src/overview.md

-->

ord Overview

ord is an index, block explorer, and command-line wallet for Ordinals. It consists of:

• Index: Tracks location of all satoshis by talking to a Bitcoin Core node (requires -txindex).
• Block explorer: ord server serves inscriptions and explorer UI.
• Wallet: ord wallet subcommands use Bitcoin Core for keys and signing; ord handles sat control and inscription creation.
• Inscribing: Create and manage Bitcoin-native digital artifacts on sats.

Requirements

• Bitcoin Core: Must be synced with txindex=1. ord uses RPC (and optionally REST).
• Authentication: By default ord uses the .cookie file from Bitcoin Core's datadir. Override with --cookie-file, --bitcoin-rpc-username / --bitcoin-rpc-password, or env ORD_BITCOIN_RPC_USERNAME / ORD_BITCOIN_RPC_PASSWORD.

# Cookie file
ord --cookie-file /path/to/.cookie server

# Config file (data_dir, bitcoin_rpc_username, bitcoin_rpc_password)
ord --config /path/to/ord.yaml server

Important caveats

• Bitcoin Core is not inscription-aware; mixing bitcoin-cli/RPC sends with ord wallets can move inscribed sats unintentionally.
• ord wallet loads the ord wallet (default name ord); after a wallet command that wallet may remain loaded in Bitcoin Core.
• Do not use ord with wallets holding large amounts; keep ordinal and cardinal wallets separate.

Syncing

Run bitcoind -txindex and leave it running. ord builds its index from the node. Index is stored in the data directory (e.g. ~/.local/share/ord/index.redb on Linux). Use ord index update or ord server to build/update the index.

Logging

ord uses env_logger. Example:

RUST_LOG=info ord server
RUST_LOG=debug RUST_BACKTRACE=1 ord server

<!-- Source references:

• sources/ordinals/README.md
• sources/ordinals/docs/src/overview.md
• sources/ordinals/docs/src/guides/wallet.md

-->

ord Settings

Configuration precedence (highest to lowest): command line → environment variables → config file → defaults.

Config file location

• Explicit: --config <CONFIG_PATH> (errors if file missing).
• Directory: --config-dir <DIR> or --datadir <DIR> → looks for ord.yaml in that directory (no error if missing).
• Default: if --config, --config-dir, and --datadir are not set, ord loads ord.yaml from the default data directory if present.

Naming

• CLI: --setting-name
• Env: ORD_SETTING_NAME (e.g. ORD_DATA_DIR)
• Config: setting_name (snake_case)

View current config

ord settings

Output is JSON of the resolved configuration.

Hiding inscription content

Inscription content can be hidden from ord server so it is not served. Only config file or environment variables (not CLI).

Environment:

export ORD_HIDDEN='id1i0 id2i0'

Config file:

hidden:
  - 6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0
  - 703e5f7c49d82aab99e605af306b9a30e991e57d42f982908a962a81ac439832i0

Space-separated list of inscription IDs in the env var; YAML list in the file.

<!-- Source references:

• sources/ordinals/docs/src/guides/settings.md

-->

ord Server JSON API

By default ord server returns HTML. Send `Accept: application/json` to get JSON from the same endpoints. Response shape mirrors the HTML structure.

Key endpoints

Many more exist (output, tx, children, parents, etc.). Recursive endpoints live under /r/ (see features-inscriptions-recursion).

Example

curl -s -H "Accept: application/json" "http://0.0.0.0:80/block/0"
curl -s -H "Accept: application/json" "http://0.0.0.0:80/address/bc1p..."

Index flags

• --index-addresses: Enable address balance and inscription listing by address.
• --index-sats: Enable sat-level index (inscriptions per sat, /sat/<N>, /r/sat/...).
• Without these, endpoints that depend on them return 404 or empty data.

<!-- Source references:

• sources/ordinals/docs/src/guides/api.md

-->

Pointer and Delegate

Pointer (tag 2)

By default the inscription is on the first sat of the inscribe transaction's output(s). To target another sat, use the pointer: a zero-based index into the total sats of the transaction outputs. Tag 2, value = little-endian integer (trailing zeroes omitted).

• If pointer ≥ total sats in outputs, it is ignored and the inscription is made on the first sat as usual.
• Use pointer to create multiple inscriptions in one transaction, each on a different sat.

Example (pointer 255): include OP_PUSH 2 and OP_PUSH 0xff. For 256: OP_PUSH 0x0001 (little-endian).

Used with batch inscribing: parent can be set so multiple children share the same parent; pointer assigns each inscription to a different sat.

Delegate (tag 11)

An inscription can delegate to another inscription. Requests for the delegating inscription's content return the delegate's content, content type, and encoding instead. Used to cheaply create many "copies" that point at one on-chain content.

• Tag 11, value = serialized inscription ID: 32-byte TXID (bitcoin txid byte order, i.e. reversed from hex display) + 4-byte little-endian index, trailing zeroes omitted.
• Delegate inscription D may be inscribed after I; until D exists, content of I returns 404.

Example (delegate to 000102...1fi0): in I's envelope, OP_PUSH 11 and OP_PUSH <32-byte txid + 4-byte index> (binary). Note: hex display of txid is reversed from serialized bytes.

Practical use

• Pointer: Batch inscribe N items in one tx; set pointer 0, 1, 2, ... (or offsets) so each inscription lands on a distinct sat. Use with ord wallet batch and batch YAML.
• Delegate: Inscribe one large asset (image, HTML); inscribe many small inscriptions that delegate to it so they all display the same content without duplicating data.

<!-- Source references:

• sources/ordinals/docs/src/inscriptions/pointer.md
• sources/ordinals/docs/src/inscriptions/delegate.md
• sources/ordinals/docs/src/guides/batch-inscribing.md

-->

Inscription Recursion

Recursion is an exception to sandboxing: whitelisted endpoints allow inscriptions to fetch on-chain data and other inscriptions' content. Recursive endpoints have backwards-compatibility guarantees: they will not be removed, and returned object fields will not be renamed or change type. New fields may be added or order changed; clients must tolerate extra fields and not rely on field order.

Use cases

• Remixing or composing content from other inscriptions.
• Publishing shared resources (code, images, styles) referenced by many inscriptions.
• Generative art: algorithm inscribed as JS, instantiated with unique seeds from multiple inscriptions.
• Profile/collection art: assets in separate inscriptions combined in one (e.g. collage).

Key endpoints (recursive)

Plain-text variants (no JSON): /blockheight, /blockhash, /blockhash/<HEIGHT>, /blocktime.

Example (fetch content)

curl -s "http://0.0.0.0:80/content/6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0" -o skull.jpg

Inscription HTML/JS can request these URLs from the same origin as the server; the server resolves them and returns on-chain data.

<!-- Source references:

• sources/ordinals/docs/src/inscriptions/recursion.md

-->

Inscriptions

Inscribing attaches arbitrary content to a satoshi in a transaction that reveals that content on-chain. The content is permanently tied to that sat, creating a Bitcoin-native digital artifact that can be transferred with the sat.

Creating inscriptions

Use ord wallet inscribe to inscribe a file (or stdin) onto sats in the wallet. The transaction has a reveal that contains the inscription; the inscribed sat is sent to the first output of the reveal (or as configured).

ord wallet inscribe --fee-rate 10 image.png
# Batch: ord wallet inscribe --batch batch.yaml

Content type is inferred (e.g. image/png) or set via inscription options. Inscription data is in the witness of a taproot output (OP_FALSE OP_IF "ord" ... OP_ENDIF).

Content types

Common types: image/*, text/plain, application/json, model/gltf-binary, audio/*, video/*, application/pdf, etc. Browsers and ord server use content type for rendering (e.g. images, HTML, PDF viewer).

Metadata and properties

• Metadata (tag 5): Optional CBOR in data pushes. Multiple tag-5 pushes are concatenated then decoded. Max 520 bytes per push; split for longer metadata. Rendered as HTML on the inscription page (maps → <dl>, arrays → <ul>, etc.).
• Properties (tag 17): Structured CBOR with protocol-defined schema (e.g. items, attributes, traits). Must be definite-length. Optional Brotli (tag 19 = "br") for compression.

Use metadata for free-form display; use properties for structured data (e.g. collections, traits).

Burning

Inscriptions can be burned by sending the sat to an OP_RETURN or otherwise unspendable output. Burned content is no longer considered "live" by the index.

Practical use

• Inscribe files with ord wallet inscribe <file>; use --destination for the inscribed sat output.
• For collections, use batch inscribing and the pointer to target specific sats; use parent to link to a parent inscription.
• Recursive inscriptions can reference other inscriptions' content via /content/<INSCRIPTION_ID> in the server (see features-inscriptions-recursion).

<!-- Source references:

• sources/ordinals/docs/src/overview.md
• sources/ordinals/docs/src/inscriptions.md (concepts)
• sources/ordinals/docs/src/inscriptions/metadata.md
• sources/ordinals/docs/src/inscriptions/properties.md
• sources/ordinals/docs/src/inscriptions/burning.md

-->

Runes Runestone Encoding

The normative specification is the ord codebase. This reference summarizes runestone layout and encoding for agents that parse or generate runes.

Locating and decoding

1. Find first output with script pubkey starting with OP_RETURN OP_13. 2. Concatenate all following data pushes (opcodes 0–78) into a payload. Any non-push opcode (≥79) → cenotaph. 3. Decode payload as a sequence of 128-bit LEB128 integers. Overflow, >18 bytes per varint, or truncated stream → cenotaph. 4. Parse integer sequence as tag/value pairs into an untyped message; tag 0 starts edicts: groups of four integers (rune id block, rune id tx, amount, output). Delta-encode edict rune IDs (see below).

Message shape

• Etching: divisibility, premine, rune (name), spacers, symbol, terms (amount, cap, height start/end, offset start/end).
• Mint: rune ID to mint.
• Pointer: default output index for remaining runes.
• Edicts: after tag 0, quadruples (block_delta, tx_or_tx_delta, amount, output). Edicts must be sorted by (block, tx) before encoding.

Edict delta encoding

Base: block=0, tx=0. For each edict: add block delta to base block; if block delta is 0, next integer is tx delta; if block delta > 0, next integer is absolute tx index. Then update base to current (block, tx).

Example: edicts (10,5,5,1), (10,5,10,3), (10,7,1,8), (50,1,25,4) → sorted then encoded as block_delta, tx_delta, amount, output: (10,5,5,1), (0,0,10,3), (0,2,1,8), (40,1,25,4).

Rune names

Names are modified base-26 (A–Z) encoded as 128-bit integer. Spacers do not affect the integer.

Practical use

• When building runestones, sort edicts by (block, tx) and use delta encoding for rune IDs.
• Use LEB128 for all integer fields. Validate payload size and varint bounds to avoid cenotaphs.
• For authoritative behavior, rely on ord (e.g. ord wallet for creating txs, index for state).

<!-- Source references:

• sources/ordinals/docs/src/runes/specification.md

-->

Runes

Runes are Bitcoin-native fungible tokens. Messages are runestones in transaction outputs (script pubkey: OP_RETURN OP_13 + data pushes). Each tx has at most one runestone. Runes protocol activates at block 840,000.

Concepts

• Rune ID: BLOCK:TX (block height and tx index of the etch tx). Example: 500:20.
• Etching: Creates a rune and sets immutable properties (name, divisibility, symbol, premine, terms).
• Minting: When mint terms are open, anyone can mint a fixed amount per mint (subject to cap, height, offset rules).
• Transfer: Input runes + premine/mint output runes are allocated to outputs via edicts and pointer.

Etching

• Name: A–Z, 1–26 letters. Spacers (•) allowed for readability; uniqueness is by letter sequence only.
• Divisibility: Decimal places (0 = indivisible).
• Symbol: Single Unicode character (e.g. ⧉, ¤ if unset).
• Premine: Optional allocation to etcher at creation.
• Terms: Optional open-mint rules: cap (total mints), amount per mint, start/end height, start/end offset (relative to etch block).

Transfer (edicts and pointer)

• Edicts: List of (rune_id, amount, output_index). Processed in order; allocate runes to that output. Same rune can appear in multiple edicts.
• Pointer: After edicts, remaining unallocated runes go to the first non-OP_RETURN output; pointer can specify another output index.
• Burning: Send runes to an OP_RETURN (via edict or pointer) to burn.

Cenotaphs

Malformed runestones (e.g. non-push opcodes, invalid varints, unknown fields) are cenotaphs. Effect: input runes are burned; etched runes in that tx are unmintable; mints in that tx count toward cap but minted runes are burned. Cenotaphs allow protocol upgrades without misleading old clients about rune locations.

ord usage

• Index runes with ord (index includes runes when built after block 840,000).
• ord server and JSON API expose rune balances and rune info.
• Wallet: use ord wallet rune commands for etching, minting, and sending runes (see ord wallet --help).

<!-- Source references:

• sources/ordinals/docs/src/runes.md
• sources/ordinals/docs/src/runes/specification.md

-->

ord Server Security

ord server serves untrusted content: anyone can publish inscriptions, including arbitrary HTML/JS, at /content/<ID>, /r/undelegated-content/<ID>, and /r/sat/<N>/at/<INDEX>/content. This creates XSS and spoofing risks. A domain hosting ord server should be treated as untrusted unless mitigated.

Cross-site scripting (XSS)

Scripts in inscriptions run in the browser with the same origin as the page. Vanilla ord server has no private resources or privileged actions, so injected JS has no meaningful privilege there. Risk appears if:

• ord server is on the same domain as another app (e.g. exchange, dashboard) that has session cookies or privileged actions.
• A malicious inscription then can request that app on the user’s behalf (with cookies) and perform actions as the user.

Mitigation: Do not serve ord server on the same domain/port as a sensitive app. Use a separate subdomain or port for the explorer.

Spoofing

If the explorer is at a well-known domain (e.g. ordinals.com), an attacker can publish an inscription that:

• Mimics a mint or official page and tricks users into sending funds.
• Uses the History API to change the URL path so the page appears under a trusted path (e.g. /mint).

Mitigation: Do not imply that the domain is trusted for anything beyond serving the explorer. Users should not rely on the domain for mints or payments; only for viewing inscription content.

Hiding content

Use hidden (config or ORD_HIDDEN) to stop specific inscription IDs from being served (see core-settings). This reduces exposure of known-malicious or sensitive content but does not replace domain isolation.

<!-- Source references:

• sources/ordinals/docs/src/security.md

-->

ord Wallet

ord does not implement a wallet; ord wallet subcommands operate on Bitcoin Core wallets. ord handles sat control and inscription construction; Bitcoin Core holds keys and signs. Requires Bitcoin Core 28+ with txindex=1 and cookie (or RPC user/pass) auth.

Main subcommands (capabilities)

Use --name <WALLET> to target a wallet other than ord. After running a wallet command, that wallet may remain loaded in Bitcoin Core.

Batch inscribing

ord wallet batch --fee-rate 21 --batch batch.yaml

Batch YAML lists files and optional parent/pointer/metadata. Multiple inscriptions in one tx; pointer assigns each to a different sat. Useful for collections.

Safety

• Do not use bitcoin-cli send / RPC sends from the same wallet without sat awareness—you may move inscribed sats as fee or change.
• Keep ordinal and cardinal wallets separate; do not hold large amounts in the ord wallet.
• ord loads the ord wallet automatically for wallet commands; be aware which wallet is loaded in Bitcoin Core after use.

<!-- Source references:

• sources/ordinals/docs/src/guides/wallet.md
• sources/ordinals/README.md

-->