ERC-8127 Human-readable token identifier (Human Readable Token Identifiers)

Draft · Names & metadata · created 2026-01-14

Defines a format for identifying tokens with a single string of the form alias.token-id@registry. It attaches a human-readable alias while still allowing a token to be uniquely identified worldwide via its token ID and registry address.

Why it is needed

As more assets are issued as tokens, such as NFTs, real-world assets (RWAs), and autonomous agents, a consistent way to refer to and reference them is needed. Until now, however, there has been no common format for identifying tokens across multiple registries using a human-readable alias. A purely numeric token ID is hard for people to recognize as a specific asset. Existing asset identification schemes place chain and contract information at the front of the string, pushing the asset ID that users care about most to the hard-to-read end. Systems also need to handle multiple aliased tokens while still providing a globally unique identifier tied to on-chain registration. This standard solves this by combining an optional alias, an on-chain token ID, and a registry location into a single resolvable string.

In depth

Token identifier format

A token identifier is a string of the form [<alias>.]<token-id>@<registry>. token-id and registry are REQUIRED for a complete identifier, while alias is optional. Aliases are treated case-insensitively and must be a valid label, meaning only lowercase letters (a-z), digits (0-9), and hyphens (-) are allowed, and the label must not start or end with a hyphen. Including an alias is RECOMMENDED for usability, but since uniqueness is guaranteed by the token ID, different tokens may share the same alias. The complete token identifier must form a valid URI when combined with the token ID and registry. The alias may be taken from a metadata field in the registry, for example the name field of an agent registry such as ERC-8004. Since the alias is not required for identification, clients may also assign it themselves.

Rules for token-id and registry

token-id is the numeric token ID in an on-chain registry such as ERC-721 or ERC-6909. It is the token's primary identifier and must be a non-negative integer corresponding to a token that actually exists in the specified registry, expressed as a decimal string. registry is the ERC-7930 interoperable address of the token registry contract, encoding both the chain ID and contract address. It must be expressed as a lowercase hex string, for example 0x00010000010114d8da6bf26964af9d7eed9e03e53415d37aa96045. This format is especially useful for multi-token registries where a single registry contract issues multiple token IDs, as with ERC-1155 or ERC-6909, and clients can display per-token aliases such as neo.145@....

Resolution rules

Depending on the context, a system may be able to locate a token using only part of the identifier. If aliases form a fully unique list of tokens, the alias alone, such as webdev, is sufficient. As the number of tokens grows, an alias combined with a token ID, such as punk.2344 or agent.235234, may be required. When tokens span multiple registries, the full identifier including the registry address fully and uniquely specifies the token. Even without an alias, a combination of token ID and registry address alone, such as 35523423@0x0001..., is sufficient to uniquely identify the token.

Canonical form

The canonical form is [<alias>.]<token-id>@<registry>, where token-id and registry are always present, the alias is included when available, and the whole string is lowercase. Implementations should use the canonical form for display and transmission. The source text gives webdev.42@0x00010000010114d8da6bf26964af9d7eed9e03e53415d37aa96045 as an example with an alias, and 42@0x00010000010114d8da6bf26964af9d7eed9e03e53415d37aa96045 as an example without one.

Comparison with CAIP-19

This format deliberately splits the identifier into a fully human-readable part (<alias>.<token-id>) and an opaque location part (@<registry>). In typical NFT, RWA, and agent registries, the token ID is a simple decimal number rather than a hash, so both the alias and token ID remain readable. CAIP-19, by contrast, puts chain and contract information in an opaque prefix and the asset ID at the end. For example, a CryptoKitties token is written as eip155:1/erc721:0x06012c8cf97bead5deae237070f9587f8e7a266d/771769, pushing the asset ID that users care about most to the end of a mostly opaque location string. This ERC puts the alias and token ID first and moves chain and contract information into the registry element, making it easy to read, say, and copy while still forming a globally unique identifier once combined with the registry. In RWA systems, the registry part can be validated against a list of known RWA registries, while a part like silver-bullion-bar.58348729 can remain a name the owner recognizes and cares about.

Why alias, ERC-7930, and @ were chosen

The alias adds meaning on top of the uniqueness guaranteed by the token ID, making tokens easier to reference. Aliases are also portable: an alias one system attaches to an asset can be passed to another system as a useful semantic hint about that asset (for example, support-agent.3453). ERC-7930 is used for the registry notation because it provides chain-agnostic address encoding and future compatibility with non-EVM chains. Since it is a self-describing format that includes the chain ID, the chain ID and address can be handled as a single field rather than separately. The @ delimiter conveys the meaning of 'at' (a token at a registry), is familiar from email addresses, is valid in URLs, and clearly separates the token-identifying part from the location.

Backward compatibility and proposal status

This ERC is backwards compatible with existing systems that identify tokens by alias alone. An identifier consisting only of an alias, without a . or @, is resolved by alias. If resolving by alias alone yields multiple overlapping matches, implementations must warn. Existing systems can gradually adopt the full identifier including the token ID and registry address. This proposal is in Draft status, created on January 14, 2026, so its contents may still change.

Things to watch out for

Original ERC · ← ERCs