unisat-dev-docs

Bitcoin BRC-20 Validity and Troubleshooting Guide

This guide explains the most common reasons a BRC-20 inscription is ignored by indexers on Bitcoin, with special attention to reinscriptions caused by reusing an already-inscribed satoshi.

Network scope: This page applies to Bitcoin. For Fractal Bitcoin, see the Fractal Bitcoin BRC-20 Validity and Reinscription Guide.

Creating and confirming an Ordinals inscription does not guarantee that its BRC-20 operation is valid. A transaction can confirm, and its inscription can be viewable, while the BRC-20 deploy, mint, or transfer operation is ignored by the BRC-20 indexer.

Preflight Checklist

Before broadcasting a BRC-20 reveal transaction, verify all of the following:

  1. The satoshi that will receive the inscription has not already been inscribed.
  2. The content type, JSON encoding, field names, and field values follow BRC-20 rules.
  3. The ticker and operation are valid for the current indexed BRC-20 state.
  4. The amount respects the ticker’s deployment rules and the sender’s available balance.
  5. The commit and reveal transactions do not send the BRC-20 operation to miner fees.

Passing the UTXO offset check described below only rules out one common reinscription problem. It does not guarantee that the resulting BRC-20 operation will be valid.

Critical Check: Do Not Reuse an Inscribed First Satoshi

In a conventional commit/reveal construction, the BRC-20 inscription is placed on the first satoshi of the commit UTXO, at offset 0.

If that satoshi already has an inscription, the new inscription is a reinscription. BRC-20 does not recognize cursed inscriptions as valid BRC-20 operations, so the reveal transaction may confirm while the deploy, mint, or transfer has no BRC-20 effect.

Use the following endpoint before constructing the commit transaction:

GET /v1/indexer/utxo-nft-offset/{txid}/{index}
Authorization: Bearer YOUR_API_KEY

Example:

curl --request GET \
  --url "https://open-api.unisat.io/v1/indexer/utxo-nft-offset/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef/0" \
  --header "Authorization: Bearer YOUR_API_KEY"

Example response that must be rejected for a conventional offset-0 inscription:

{
  "code": 0,
  "msg": "ok",
  "data": [0, 546]
}

The 0 means the first satoshi of this UTXO has already been inscribed. Do not use that first satoshi for a BRC-20 inscription. Select another UTXO or change the transaction construction and track the exact satoshi that will receive the inscription.

Example response with no recorded inscription at offset 0:

{
  "code": 0,
  "msg": "ok",
  "data": [546]
}

An empty data array also means that the indexer found no inscription offsets for the UTXO:

{
  "code": 0,
  "msg": "ok",
  "data": []
}

Safe Application Check

async function assertBrc20CommitUtxoIsUsable(txid, vout, apiKey) {
  const response = await fetch(
    `https://open-api.unisat.io/v1/indexer/utxo-nft-offset/${txid}/${vout}`,
    {
      headers: {
        Authorization: `Bearer ${apiKey}`,
      },
    },
  );

  if (!response.ok) {
    throw new Error(`UTXO offset check failed with HTTP ${response.status}`);
  }

  const result = await response.json();
  if (result.code !== 0 || !Array.isArray(result.data)) {
    throw new Error(result.msg || "UTXO offset check failed");
  }

  if (result.data.includes(0)) {
    throw new Error(
      "Do not use this UTXO: its first satoshi has already been inscribed.",
    );
  }

  return result.data;
}

Do not treat an API error, timeout, or unavailable indexer as a successful check. Fail closed and retry or select a different UTXO.

Important Limitations

Content and JSON Rules

The following checklist summarizes the base BRC-20 indexing rules for Bitcoin:

Do not apply permissive language conversions such as parseInt or floating-point parsing to decide whether a value is valid. Validate the original string exactly, and use integer or decimal arithmetic that does not lose precision.

State-Dependent Rules

A syntactically correct inscription may still be ignored because validity also depends on the indexed BRC-20 state and transaction lifecycle:

For balance and deposit verification, see BRC20 Balance and Transfer.

Troubleshooting an Invalid BRC-20 Inscription

Symptom What to check
The inscription exists, but no BRC-20 event appears Check the commit UTXO for offset 0, then validate MIME type and the original JSON body.
A deploy is ignored Check whether the ticker was already deployed, and validate max, lim, dec, and ticker byte length.
A mint is ignored Check the ticker’s deploy state, mint limit, maximum supply, decimal precision, and whether the inscription was sent to fees.
A transfer inscription is invalid Check available balance at inscription time and validate amt and decimal precision.
A transfer worked once but not again Transfer inscriptions are single-use after their first valid transfer.
Local validation passes but the indexer disagrees Compare the exact on-chain content bytes and indexed state; do not validate a normalized or parsed-and-reserialized payload.

When reporting a problem, collect the following information:

References