Wallet and app developers
Build a payload that survives
The specification gives the exact grammar and every condition that turns a transaction into a cenotaph. The validator checks a draft payload before you spend a satoshi on it.
Bitcoin mainnet · fungible tokens · OP_RETURN JSON
Mezcal, poured into an OP_RETURN.
A Mezcal transaction says what it means in plain UTF-8 JSON. One output carries the instruction, the other outputs carry the balances, and an indexer replays both to decide who owns what.
At a glance
- Chain
- Bitcoin
- Network
- mainnet
- Carrier
- OP_RETURN push data
- Encoding
- UTF-8 JSON
- Asset id
- block:tx
- Genesis block
- 898750
- Divisibility
- 0 to 18
- Amount range
- u128
Mezcal did not originate at Bitcoin Universe. The protocol and its reference indexer are the work of bitapeslabs/mezcal, and mezcal.sh is the project's own site. This repository documents the protocol as the ecosystem uses it, and marks every Universe-specific decision as such.
Who this is for
Indexer implementers
Match the reference behaviour
The reference covers ordering, allocation, burns, confirmation, and reorg handling. The test vectors give valid and invalid payloads with the outcome each one must produce.
Holders and traders
Read the transaction you sign
The guide walks an etch, a mint, a transfer, and a burn line by line, so you can tell where a balance is going before the transaction is broadcast.
The shape of a payload
A Mezcal instruction, a mezcalstone, is one JSON object. The protocol tag is required. Everything else is optional, and a transaction may combine an etching, a mint, and edicts in a single object.
{
"p": "https://mezcal.sh",
"edicts": [ ["899284:20", "7700000000", 0] ],
"mint": "898750:0",
"etching": { "mezcal": "taco", "symbol": "🌮", "divisibility": 8,
"premine": "0", "terms": null, "turbo": true },
"pointer": 2
}An edict is a triple: the asset id, the amount in base units as a decimal string, and the output index that receives it. Amounts are always base units, never display units, so 77 units of an asset with 8 decimals is written "7700000000".
Marketplace transfers in Bitcoin Universe use one exact form. A purchase built by the Core marketplace carries {"p":"https://mezcal.sh","edicts":[[ticker,baseUnits,0]]} derived from the verified listing, and the server refuses any payload that differs from it by a single byte. See Core marketplace behaviour.
Bitcoin Universe support
Bitcoin Universe indexes Mezcal and shows it across its products. Every claim below is taken from the org's own code, not from a roadmap.
| Surface | State | What that means |
|---|---|---|
| Discovery and explorer | Available | View assets, holders, activity, and transactions. |
| Marketplace mutations | Read-only | The registry sets Mezcal marketplace availability to read-only. List, update, unlist, and buy are declared unsupported until authoritative ownership, transferability, builder, signed-transaction validation, broadcast, settlement, and reorg recovery are deployed and proven. |
| Wallet | Declared | View, send, and receive are declared capabilities of the wallet surface. |
| Token explorer indexing | Available | Confirmed deployments, mints, transfers, burns, and holder balances, verified against Bitcoin Core before publication. There is no complete mempool feed, so coverage is reported as partial. |
See the full support matrix, including the exact code paths behind each row.
Entry points
Read the rules
- Specification: numbered normative rules
- Reference: indexer semantics and limits
- Test vectors: valid and invalid cases
Work with payloads
- Validator and builder, entirely client-side
- Guide with worked transactions
- llms.txt for machine readers
Sources
Reporting a problem
Report a documentation error as a GitHub issue on this repository. Report a security issue privately through GitHub private vulnerability reporting on this repository, and read SECURITY.md first. A protocol-level flaw in Mezcal itself belongs upstream at bitapeslabs/mezcal.