Protocol guide

Runes Etch Quickstart

Runes is a Bitcoin-native fungible token protocol built around UTXOs and OP_RETURN runestones. If you want to create a new rune, the first operation to understand is the etch: the transaction that defines the rune name and its immutable token parameters.

This quickstart is for builders who already know what Runes is and want the shortest practical path from protocol awareness to execution. It focuses on how etching works, which parameters become permanent, what tools are commonly used, and which failure modes can destroy or strand assets.

Section

What etching means in Runes

In Runes, an etch is the Bitcoin transaction that creates a new rune definition. That transaction establishes metadata and supply rules such as rune name, divisibility, symbol, premine, and total supply.

Those choices are not something you casually revise later. Supply, divisibility, and symbol should be treated as fixed at etch time, so the setup step deserves the same caution you would give to any irreversible production change.

Section

When a Runes etch workflow is the right next step

A Runes etch workflow is most relevant when you want to:

launch a Bitcoin-native fungible token
experiment with UTXO-based token issuance mechanics
create a token that can later be minted and transferred through the Runes model
understand how Runes differs from account-based token standards
prototype Bitcoin-native token flows before building wallet, explorer, or market integrations

If you want the broader protocol overview first, the main Runes protocol page is the better starting point. If your immediate question is how to etch Runes on Bitcoin, this is the narrower workflow guide.

Section

The shortest setup path

The current protocol context points to two common starting tools:

cargo install ord
pnpm add runelib

In practice, they serve different roles:

ord is the common CLI path for wallet-driven etch, mint, and send flows
runelib is useful when you want to build runestones programmatically and attach them to a PSBT before signing

For many builders, the simplest first pass is:

First-pass workflow

01install ord
02prepare a funded Bitcoin wallet with spendable UTXOs
03etch the rune with explicit parameters
04wait for confirmations
05mint or transfer only after the etched state is reliably visible

Section

A practical Runes etching workflow

1. Decide the rune parameters before touching the chain

Before you broadcast anything, write down the parameters you intend to use:

rune name
divisibility
symbol
premine
total supply

Example shape from the current protocol notes:

ord wallet etch   --rune NAME   --divisibility 8   --premine 0   --supply 21000000   --symbol R

This command shape matters because the transaction is not just creating a token label. It is defining the economic structure of the asset.

Do you want indivisible units or decimal-style units?
Should any supply exist at etch time through premine?
Is the total supply meant to be fixed from the start?
Is the symbol actually worth locking in permanently?

2. Fund the wallet with the right UTXO shape

Runes inherits Bitcoin’s UTXO model, so wallet state matters more than builders from account-based chains often expect.

whether the wallet has enough BTC for miner fees
which UTXOs are being spent
how change outputs are created
whether later mint or transfer steps will accidentally consume rune-bearing outputs incorrectly

Good UTXO hygiene is part of the protocol workflow, not a separate wallet concern.

3. Etch the rune

Once the parameters are final and the wallet is funded, broadcast the etch transaction.

ord wallet etch --rune NAME --divisibility 8 --premine 0 --supply 21000000 --symbol R

What this does conceptually:

creates a runestone payload
embeds the rune definition into a Bitcoin transaction
publishes the initial asset definition on-chain

This is the point where mistakes become expensive. A malformed runestone can become a cenotaph, which is one of the most important safety concepts to understand before moving quickly.

4. Wait for confirmations before trusting balances

A practical operating rule is to wait at least 1 to 3 confirmations before crediting balances or assuming downstream systems should treat the asset state as settled.

internal dashboards
explorer indexing assumptions
app-side balance display
mint eligibility checks
transfer status updates

5. Mint only after the etched state is established

Once the rune exists and the wallet or supporting tooling can see the etched state clearly, the next protocol action is minting.

ord wallet mint

The exact mint invocation depends on your setup and asset details, but the operational lesson is simple: etch first, confirm it, then mint.

6. Transfer with UTXO awareness

The current protocol notes also point to:

ord wallet send

Transfers in Runes are not modeled like ERC-20 approvals plus transfers. There is no approve primitive here.

direct movement of rune-bearing outputs
wallet selection of the correct UTXOs
change-output behavior after the send
indexer or app-side confirmation timing

Section

Programmatic path: building runestones with a library

If you want more control than the CLI offers, the current protocol notes suggest a programmatic path with runelib.

construct runestones in application code
prepare a PSBT instead of relying only on a local CLI wallet flow
integrate external signing from wallets such as Xverse, Leather, or UniSat
keep transaction assembly logic inside a larger product workflow

At a high level, the pattern is:

Programmatic PSBT flow

01build the runestone programmatically
02append it to a PSBT
03pass the PSBT to a compatible signer
04sign and broadcast the resulting Bitcoin transaction
05wait for confirmation before reflecting balances or status

Section

The gotchas that matter most

Cenotaph risk is real

Malformed runestones can become cenotaphs and burn runes. Keep the first etch simple, avoid improvising the payload format, and test with small-value scenarios first.

UTXO change handling is part of correctness

Change output behavior affects how assets move and whether later actions behave as expected. Builders who ignore this often think they have a protocol bug when they actually have a transaction-construction bug.

Confirmations matter for app logic

Balance updates, transfer-complete UI states, mint availability, and accounting flows should wait for a confirmed state instead of treating mempool visibility as final.

Supply choices are permanent

Supply, divisibility, and symbol should be treated as immutable after etch, so a quickstart should never encourage thoughtless speed over parameter review.

Fee pressure can change the workflow

Runes lives on Bitcoin, so miner fee conditions can make etch or mint transactions expensive or slow enough to change launch timing and user expectations.

Section

When the CLI path is enough and when it is not

Use ord first when you want to learn the lifecycle end to end

validate the protocol manually
run a direct wallet-based experiment
understand the minimum viable etch, mint, and send flow

Use a programmatic path when you want to operationalize it

embed the workflow into an app
generate runestones in code
pass PSBTs to external wallets
control transaction construction more precisely
support custom signing or product-side transaction flows

Section

FAQ

What is a Runes etch?

A Runes etch is the Bitcoin transaction that creates a new rune definition. It establishes the rune name and core token parameters such as supply, divisibility, symbol, and premine.

How do you etch Runes on Bitcoin?

A common starting path is to install ord, fund a Bitcoin wallet, and run an etch command with explicit rune parameters. After broadcast, wait for confirmations before treating the etched state as settled.

What parameters matter most when etching a rune?

The important early decisions are rune name, divisibility, premine, total supply, and symbol. Supply, divisibility, and symbol should be treated as immutable after etch.

Can you change a rune after etching it?

Not in the ways most builders care about. Supply, divisibility, and symbol should be treated as fixed at etch time.

What is a cenotaph in Runes?

A cenotaph is a malformed runestone outcome that can burn runes. It is one of the main reasons to avoid careless transaction construction or unreviewed custom payload handling.

Why does UTXO handling matter in Runes transfers?

Runes is Bitcoin-native, so token movement follows Bitcoin transaction structure. Output selection and change handling can affect asset correctness in ways that builders from account-based systems may not expect.

How many confirmations should you wait for?

A practical operating rule is to wait at least 1 to 3 confirmations before crediting balances or assuming app-visible state is final.

Is there an approve step like ERC-20?

No. Runes does not use an approve primitive. Builders need to design around direct UTXO-based asset movement instead.

What does it cost to use Runes?

Runes is a protocol, not a paid platform. The main direct cost is Bitcoin miner fees, while ord is free and open-source.

Next step

Start with this workflow, then move back to the broader Runes protocol context

For most builders, the right sequence is to validate the lifecycle with small-value transactions, then use the main protocol page for broader context, adjacent tooling, and comparison against other Bitcoin or token standards.

Read the Runes protocol page Compare standards