This ERC defines a format for identifying tokens in onchain registries using optional human readable aliases. A Token Identifier combines an optional human readable alias, a unique token ID from an onchain registry, and the registry location encoded as an ERC-7930 interoperable address. This format is useful for NFTs, real-world assets (RWAs), agents, and other tokenized assets. For example, agent registries like ERC-8004 can use this format to identify agents with human readable names.
As tokenized assets become more prevalent in blockchain ecosystems, including NFTs, RWAs, and autonomous agents, there is a need for a consistent way to identify and reference them. Currently no format exists for identifying tokens with optional human readable aliases across different registries. Systems need to support multiple tokens with human readable aliases, while at the same time providing globally unique identifiers tied to onchain registration. This ERC addresses these needs by combining optional human readable aliases with onchain token IDs and registry locations in a single, parseable format. For example, agent registries like ERC-8004 can use this format to provide human readable names for agents while maintaining globally unique identifiers.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.
A Token Identifier is a string with the following structure:
token-identifier = [<alias>.]<token-id>@<registry>
The <token-id> and <registry> components are REQUIRED for a fully specified identifier. The <alias> is an optional human readable identifier for the token, treated as case-insensitive. The alias SHOULD be included to improve usability. When present, the alias must be a valid label, which means:
- Must use only lowercase letters (a-z), digits (0-9), and hyphens (-)
- Must not start or end with a hyphen
Aliases may be duplicated across different tokens since uniqueness comes from the token ID. The entire Token Identifier must form a valid URI when combined with the token ID and registry components.
The alias MAY be taken from metadata fields in the registry. For example, agent registries like ERC-8004 may provide a "name" field that can be used as the alias. Since the alias is not needed to identify the token, it can also be self-assigned by clients.
The token-id is the numeric token ID from the onchain registry, such as an ERC-721 or ERC-6909 token. It is the primary identifier for the token and MUST be a non-negative integer corresponding to a valid token in the specified registry, represented as a decimal string.
The registry is an ERC-7930 interoperable address of the token registry contract, which includes both the chain ID and contract address. The registry MUST be represented as a hexadecimal string in lowercase (e.g., 0x00010000010114d8da6bf26964af9d7eed9e03e53415d37aa96045).
This format is especially useful for multi token registries such as ERC-1155 and ERC-6909, where a single registry contract issues many token IDs and clients can present per token aliases (e.g., neo.145@...) for usability.
Systems can use various methods to make it easier for human users to specify a token. With a list of tokens that have unique aliases, the alias alone may be sufficient. As the number of tokens grows, systems may require both the alias and token ID to uniquely identify a token. When tokens exist across multiple registries, the full identifier including the registry address provides complete specification of a unique token. The token ID alone with the registry address is sufficient to uniquely identify a token.
Examples (using agents and RWAs):
- webdev - Alias only, sufficient when the alias is unique
- punk.2344 - Alias with token ID
- agent.235234 - Alias with token ID
- neo.145@0x00010000010114d8da6bf26964af9d7eed9e03e53415d37aa96045 - Multi token registry style alias and token ID with registry
- silver-bullion-bar.58348729@0x00010000010114d8da6bf26964af9d7eed9e03e53415d37aa96045 - RWA style alias and token ID with registry
- coder.35523423 - Alias with specific token ID
- 35523423@0x00010000010114d8da6bf26964af9d7eed9e03e53415d37aa96045 - Token ID with registry (no alias)
The canonical form of a Token Identifier is [<alias>.]<token-id>@<registry> with token-id and registry always present and alias present when available, and lowercase. Implementations should use canonical form for display and transmission.
Examples (using agents):
- webdev.42@0x00010000010114d8da6bf26964af9d7eed9e03e53415d37aa96045 (with alias)
- 42@0x00010000010114d8da6bf26964af9d7eed9e03e53415d37aa96045 (without alias)
The Token Identifier format combines several design elements to balance usability, uniqueness, and interoperability. Each component serves a specific purpose in creating a format that is partly human readable (alias and token ID) and partly opaque (registry), while remaining machine parseable and supporting the diverse needs of token registry systems including NFTs, RWAs, and agent registries.
This format intentionally separates the identifier into two parts: a fully human readable portion (<alias>.<token-id>) and an opaque location portion (@<registry>). In many registries (including typical NFT, RWA, and agent registries), token IDs are simple decimal numbers rather than hashes, so both the alias and token ID can remain fully human readable (e.g., punk.2344, agent.235234, silver-bullion-bar.58348729).
By contrast, CAIP-19 style asset identifiers combine chain and contract information into an opaque prefix, and place the asset ID at the end. For example, a CryptoKitties token might be described as:
eip155:1/erc721:0x06012c8cf97bead5deae237070f9587f8e7a266d/771769In this structure, the information a user may care about most (the asset ID) is pushed to the end of a mostly opaque locator string. This ERC keeps the alias and token ID upfront, and moves the chain and contract addressing details into the registry component (an ERC-7930 interoperable address), making identifiers easier to read, speak, and copy while still remaining globally unique when combined with the registry. In RWA systems, the registry portion can be validated against a known list of RWA registries, while the alias and token ID (e.g., silver-bullion-bar.58348729) can remain something an owner is expected to recognize and care about.
Including an optional human readable alias alongside the token ID improves usability. While the token ID provides uniqueness and is the primary identifier, aliases provide meaning and make tokens easier to reference. For example, agent registries can use aliases to provide human readable names for agents.
Aliases are also portable: one system can share its alias for an asset with another system as a semantic hint about the asset, which can be used in useful semantic ways (e.g., support-agent.3453).
ERC-7930 provides chain-agnostic address encoding with future compatibility for non-EVM chains. It is a self-describing format that includes the chain ID, allowing a single field instead of separate chain ID and address fields.
The @ symbol semantically means "at" (token at registry), is familiar from email addresses, is valid in URLs, and clearly separates the token identifier from the location.
This ERC is backward compatible with systems using alias-only token identification. An identifier with just an alias and no . or @ matches tokens by alias. Implementations should warn when alias-only matches are ambiguous. Existing systems can gradually adopt full identifiers with token IDs and registry addresses.
<token-id>@<registry> when making security-relevant decisions.registry component is an ERC-7930 interoperable address and may point to any contract. Clients SHOULD validate the registry against an allowlist or other trust mechanism before treating an identifier as trusted.. and @ only where specified) and treat aliases as case-insensitive. Incorrect parsing or normalization could cause identifiers to resolve to the wrong token.Copyright and related rights waived via CC0.