The Cardano Token Registry provides a means to register off-chain token metadata to map to on-chain identifiers (typically hashes representing asset IDs, output locking scripts, or token forging policies).
A server exposes the functionality of a key-value store, allowing users and applications to query registry entries through a RESTful API.
While this registry is limited in scope to handle native tokens only, it will also facilitate a discussion and introduce a standard for a metadata distribution system currently put forward as a draft CIP.
Registration of metadata mappings is optional and is independent of any on-chain activities. However, users may choose to register metadata mappings with a server so that applications (for example, a wallet) can query and display additional human-readable data relevant to the on-chain identifier.
New submissions to this registry will take the form of a GitHub Pull Request with the addition of one JSON file to the mappings/ folder. Submissions will be subject to automated checking for well-formedness and human vetting before being merged into the registry.
Modification of entries in this registry will take the form of a GitHub Pull Request with the modification of one or more JSON files in the mappings/ folder. Submissions will be subject to automated checking for well-formedness and human vetting before being merged into the registry.
Each entry contains the following information:
|Required||The base16-encoded policyId + base16-encoded assetName.|
|Required||The script that hashes to the policyId.|
|Required||A human-readable name for the subject, suitable for use in an interface.|
|Required||A human-readable description for the subject, suitable for use in an interface.|
|Optional||A human-readable ticker name for the subject, suitable for use in an interface.|
|Optional||A HTTPS URL (web page relating to the token).|
|Optional||A PNG image file as a byte string.|
|Optional||The recommended value for decimal places. Native tokens are represented as whole numbers (numbers without decimals) on the blockchain.|
For a comprehensive description of all fields and how to generate them, please see off-chain-metadata-tools.
Submissions to the registry must consist of a single commit directly off the main branch of the cardano-token-registry repository.
Submissions must add or modify files in the mappings/ folder.
The file name must match the encoded
"subject"key of the entry, all lowercase.
The maximum file size of a single metadata entry is 370KB.
Users and applications can query this registry through an API at
The API documentation and source code for the server implementation is available with the off-chain-metadata-tools.
Use of the
To register native token mappings, it is recommended to have pre-existing knowledge about Cardano native assets. Start by reading through the minting a new native asset example.
After creating a Cardano native asset, you will need the following to proceed with the steps to generate a mapping for the registry:
- The monetary policy script for your native asset.
- The assetName associated with the monetary policy script.
- The policyId of the monetary policy script.
- The private key/s used to define your asset policy.
offchain-metadata-tools(see off-chain-metadata tools).
To create a new mapping, you must first obtain your metadata subject. The subject is defined as the concatenation of the base16-encoded policyId and base16-encoded assetName of your asset. In case your assetName is empty, then the policyId is your subject.
For this example, we will consider the following native asset:
- Base16 encode your assetName:
$ echo -n "myassetname" | xxd -ps6d7961737365746e616d65
- Concatenate the policyId with the base16-encoded assetName to obtain the 'subject' for your entry:
- Initialize a new draft entry for the subject using
token-metadata-creator entry --init baa836fef09cb35e180fce4b55ded152907af1e2c840ed5218776f2f6d7961737365746e616d65
This creates a draft JSON file named after your subject.
token-metadata-creator entry baa836fef09cb35e180fce4b55ded152907af1e2c840ed5218776f2f6d7961737365746e616d65 \ --name "My Gaming Token" \ --description "A currency for the Metaverse." \ --policy policy.json
policy.json is the monetary policy script file that hashes to the policyId.
token-metadata-creator entry baa836fef09cb35e180fce4b55ded152907af1e2c840ed5218776f2f6d7961737365746e616d65 \ --ticker "TKN" \ --url "https://finalfantasy.fandom.com/wiki/Gil" \ --logo "icon.png" \ --decimals 4
Each metadata item must be signed with the key/s used to define your asset policy. For this example, we assume only a single signing key is required to validate the monetary policy script and that all metadata fields will be signed at once with the signing key file. Please refer to off-chain-metadata tools for more granular options.
token-metadata-creator entry baa836fef09cb35e180fce4b55ded152907af1e2c840ed5218776f2f6d7961737365746e616d65 -a policy.skey
This will run some additional validations on your submission and check that it is considered valid.
token-metadata-creator entry baa836fef09cb35e180fce4b55ded152907af1e2c840ed5218776f2f6d7961737365746e616d65 --finalize
Your finalized metadata file is now ready to submit to the cardano-token-registry.
To submit a metadata entry for a native asset on Cardano, you must first follow the steps in how to prepare an entry for the token registry and have a finalized metadata file ready for submission.
Then clone a local copy:
$ git clone [email protected]:<your-github-username>/cardano-token-registry$ cd cardano-token-registry
$ cp /path-to-my-file/baa83...d65.json mappings/
$ git add mappings/baa83...d65.json$ git commit -m "Your Token Name"$ git push origin HEAD
Create a pull request from your fork.