Cardano Transaction Metadata: What Are the Limits, Encoding Rules, and How Long Does It Stay On-Chain?

04 November 2026

Cardano transaction metadata is limited to 64 bytes per entry when using the standard transaction format, supports CBOR encoding for structured data, and is stored permanently on the blockchain as part of the ledger history. Every full node retains the metadata indefinitely, and it is never pruned or deleted.

Metadata Size Limits

A single Cardano transaction can include up to 64 bytes of metadata when submitted as a plain text field. However, this limit applies per metadata entry, not per transaction. If you need to attach more data, you can include multiple metadata entries within one transaction, but each entry must stay under 64 bytes.

The practical limit for a single transaction's total metadata payload depends on the number of entries and the transaction's overall size. Cardano transactions have a maximum size of 16 KB (16,384 bytes) as of the current protocol parameters. Metadata is one component of this limit, alongside inputs, outputs, and any script data. If your metadata entries plus the rest of the transaction exceed 16 KB, the transaction will be rejected.

For structured data, the 64-byte limit applies to the encoded CBOR representation, not the raw human-readable data. A simple key-value pair like {"note": "hello"} might take 15-20 bytes in CBOR, leaving room for additional fields. Complex nested structures will consume the limit quickly.

Encoding Requirements

Metadata on Cardano must be encoded in CBOR (Concise Binary Object Representation). This is a binary format, not JSON or plain text, though many wallets and SDKs handle the conversion automatically.

The CBOR metadata must conform to the Cardano metadata specification, which restricts the allowed CBOR data types. You can use:

• Unsigned integers (0 to 2^64 - 1)
• Byte strings (up to 64 bytes)
• Text strings (up to 64 bytes)
• Arrays (lists) of these types
• Maps (dictionaries) with keys and values of these types

Nested structures are allowed, but each level adds to the encoded size. The total encoded CBOR must not exceed 64 bytes per metadata entry.

Most wallet interfaces and development libraries (such as the Cardano CLI, cardano-serialization-lib, or Blockfrost) accept metadata as JSON and convert it to CBOR automatically. If you are building a transaction manually, you must encode the metadata yourself using a CBOR library.

Permanent storage and retrieval

Once a transaction with metadata is included in a block and that block is confirmed, the metadata is part of the permanent blockchain history. Every full node that has synced the chain from genesis retains the metadata in its local database. There is no mechanism to delete or redact metadata from a confirmed transaction.

This permanence has practical consequences:

• Metadata cannot be edited or removed after submission. Double-check the content before broadcasting.
• Metadata is public. Anyone can read it by querying a full node or an API provider like Blockfrost or Koios. Do not include private keys, passwords, or personal data.
• The metadata remains accessible for as long as the chain exists. Even if a wallet or explorer stops supporting metadata display, the data persists in the node database.

How to Add Metadata to a Transaction

The process depends on your wallet or development tool. General steps:

1. Prepare your data in the format you want to attach. Ensure it fits within the 64-byte CBOR limit per entry. If your data is larger, split it across multiple metadata entries or multiple transactions.

2. Encode the data as CBOR. If using a wallet like Daedalus or Eternl, the wallet handles this. If using the Cardano CLI, you provide a JSON file, and the CLI converts it to CBOR.

3. Add metadata to the transaction during construction. In the Cardano CLI, use the --metadata-json-file or --metadata-cbor-file flags. In a library like cardano-serialization-lib, call the appropriate method on the transaction builder.

4. Submit the transaction normally. The metadata is included in the transaction body and recorded on-chain.

Practical Considerations

• Many wallets do not display metadata in their user interface. You may need to check a block explorer or use an API to confirm the metadata was attached correctly.
• If you are attaching metadata to a transaction that also sends ADA or native assets, the metadata does not affect the transaction's core function. It is purely an attachment.
• Metadata is not encrypted by default. If you need confidentiality, encrypt the data yourself before encoding it as CBOR.
• Some applications use metadata for timestamping documents, tracking supply chains, or recording provenance. The 64-byte limit means these use cases typically rely on storing a hash or reference, not the full document.

Checking your metadata after submission

To verify your metadata is on-chain:

• Use a block explorer that supports metadata display. Enter the transaction hash and look for a "metadata" section.
• Query the transaction via an API. For example, with Blockfrost, the /txs/{hash}/metadata endpoint returns the metadata as JSON (converted from CBOR).
• Run a local node and use the cardano-cli query transaction command with the --tx-in flag (though this requires the transaction to be in the local node's UTXO set, which may not persist indefinitely for spent outputs). The most reliable method is to query the node's tx table directly or use a chain-indexing service.

Metadata remains readable for the lifetime of the chain. There is no expiration or automatic deletion. If you need data removed, you cannot - plan accordingly.

Back to cardano