Cardano Token Registry

Complete Guide: Registering a Native Token in the Cardano Token Registry

Last updated: February 2026

---

Table of Contents

1. Overview

2. Official Documentation Links

3. Prerequisites

4. Phase 1 - Environment Setup (WSL + Ubuntu)

5. Phase 2 - Install token-metadata-creator

6. Phase 3 - Prepare Your Policy Keys

7. Phase 4 - Prepare Your Logo

8. Phase 5 - Create the Metadata Entry

9. Phase 6 - Sign and Finalize

10. Phase 7 - Verify the JSON

11. Phase 8 - Submit the Pull Request

12. Registry Field Reference

13. Common Mistakes & How to Avoid Them

14. Best Practices Checklist

---

Overview

The Cardano Token Registry is an off-chain metadata repository maintained by the Cardano Foundation. It maps native token subjects (policy ID + asset name hex) to human-readable metadata like names, tickers, descriptions, and logos.

Key facts:

• Entirely off-chain — no ADA or blockchain transaction required

• Metadata is submitted via GitHub Pull Request

• Signatures prove policy ownership cryptographically

• The process works on Windows via WSL (Windows Subsystem for Linux)

---

Official Documentation Links

Resource	URL
Cardano Token Registry (GitHub)	https://github.com/cardano-foundation/cardano-token-registry
token-metadata-creator tool	https://github.com/input-output-hk/offchain-metadata-tools
Tool manual	https://input-output-hk.github.io/offchain-metadata-tools/
Registry submission guide	https://github.com/cardano-foundation/cardano-token-registry/wiki/How-to-prepare-an-entry-for-the-registry
CIP-26 (off-chain metadata)	https://github.com/cardano-foundation/CIPs/tree/master/CIP-0026

---

Prerequisites

Before starting, you need:

• Policy ID of your native token

• Policy signing key (.skey file, used during minting)

• Policy script file (.script or .json)

• Asset name in hex (e.g. fSLVR → 66534c5652)

• Logo image (see Phase 4 for format requirements)

• GitHub account

• Windows PC with WSL, or a Linux machine

💡 Finding your asset name in hex: You can convert ASCII to hex online at https://string-functions.com/string-hex.aspx or in Linux: echo -n "YOURTOKEN" | xxd -p

💡 Your subject is always: {policyID}{assetNameHex} — concatenated with no separator.

---

Phase 1 - Environment Setup (WSL + Ubuntu)

Skip this phase if you already have Linux.

Install WSL on Windows

Open PowerShell as Administrator and run:

wsl --install

Restart your computer when prompted.

After restart, Ubuntu will open and ask you to create a UNIX user.

⚠️ Your UNIX username must be lowercase. Ubuntu will reject uppercase usernames.

Verify WSL is working

Open the Ubuntu terminal and run:

whoami

You should see your lowercase username.

💡 Accessing Windows files from Ubuntu: Your Windows drives are mounted at /mnt/c/, /mnt/d/ etc. Example: C:\Users\YourUsername\Desktop\ → /mnt/c/Users/YourUsername/Desktop/

---

Phase 2 - Install token-metadata-creator

In your Ubuntu terminal:

# Update package list and install dependencies
sudo apt update && sudo apt install git wget -y

# Create working directory
mkdir ~/tokenreg && cd ~/tokenreg

# Download the tool (check for latest release at https://github.com/input-output-hk/offchain-metadata-tools/releases)
wget https://github.com/input-output-hk/offchain-metadata-tools/releases/download/v0.4.0.0/token-metadata-creator.tar.gz

# Extract
tar -xzf token-metadata-creator.tar.gz

# Move to system path
sudo mv token-metadata-creator /usr/local/bin/

# Verify installation
token-metadata-creator --help

If you see the help output, the tool is installed correctly.

---

Phase 3 - Prepare Your Policy Keys

You need two files in your working directory:

policy.script

Create this file with your policy script. Example for a simple signature policy:

cat > ~/tokenreg/policy.script << 'EOF'
{
  "type": "all",
  "scripts": [
    {
      "type": "sig",
      "keyHash": "YOUR_KEY_HASH_HERE"
    }
  ]
}
EOF

policy.skey

This is your signing key — the private key used to prove ownership of the policy. It should be in the Cardano key envelope format:

{
  "type": "PaymentSigningKeyShelley_ed25519",
  "description": "Payment Signing Key",
  "cborHex": "5820YOUR_CBOR_HEX_HERE"
}

💡 Finding your keyHashes: Go to your NFT Project - click "Project Info" in the side bar - open "Cardano Policy" and press "Export Policy Keys".

⚠️ Security: Never share your .skey file. It proves ownership of your policy and could be used to sign transactions.

Create the policy skripts and copy both files to your working directory:

cp /path/to/policy.script ~/tokenreg/
cp /path/to/policy.skey ~/tokenreg/

---

Phase 4 - Prepare Your Logo

This phase is the most error-prone. Follow carefully.

Requirements

Property	Requirement
Format	PNG only (not JPEG, WebP, SVG)
Dimensions	Maximum 200×200 pixels (recommended)
Base64 size	Must be under 65,536 characters when base64-encoded
Color mode	RGBA recommended (supports transparency)

⚠️ Common mistake: Many token logos exist online as JPEG or WebP. Even if the file is named .png, it might be a JPEG. Always verify and convert if needed.

Step 1 - Check your image format

python3 -c "
with open('your_logo.png', 'rb') as f:
    header = f.read(8)
print('Format:', 'PNG' if header[:8] == b'\\x89PNG\\r\\n\\x1a\\n' else 'NOT PNG - header: ' + header[:4].hex())
"

Step 2 - Convert and resize to 200×200 PNG

Install Pillow if needed:

pip install Pillow --break-system-packages

Run the conversion:

python3 << 'EOF'
from PIL import Image
import io, base64

# Open your image (works with JPEG, WebP, PNG, etc.)
img = Image.open('your_logo_original.png')
print(f"Original: {img.format}, {img.size}, mode={img.mode}")

# Convert to RGBA (supports transparency)
img = img.convert('RGBA')

# Resize to 200x200
img = img.resize((200, 200), Image.LANCZOS)

# Save as PNG
buf = io.BytesIO()
img.save(buf, format='PNG', optimize=True)
png_data = buf.getvalue()

# Check base64 size
b64 = base64.b64encode(png_data).decode('ascii')
print(f"PNG size: {len(png_data):,} bytes")
print(f"Base64 length: {len(b64):,} chars (limit: 65,536)")
print(f"Within limit: {len(b64) <= 65536}")

# Save
with open('logo.png', 'wb') as f:
    f.write(png_data)
print("Saved as logo.png")
EOF

Step 3 - Verify the logo

python3 << 'EOF'
import base64, struct

with open('logo.png', 'rb') as f:
    data = f.read()

b64 = base64.b64encode(data).decode('ascii')
print(f"Valid PNG: {data[:8].hex() == '89504e470d0a1a0a'}")
w = struct.unpack('>I', data[16:20])[0]
h = struct.unpack('>I', data[20:24])[0]
print(f"Dimensions: {w}x{h}")
print(f"Base64 length: {len(b64)} chars")
print(f"PNG size: {len(data):,} bytes")
EOF

All checks should pass before proceeding.

💡 If you exceed 65,536 base64 chars: Try reducing to 150×150 or increase PNG compression. The base64 length is roughly 1.37× the PNG byte size.

---

Phase 5 - Create the Metadata Entry

Set your subject as an environment variable (saves typing):

export SUBJECT="YOUR_POLICY_ID_HEX_YOUR_ASSET_NAME_HEX"
# Example:
# export SUBJECT="1674af42f614956176bab5d8ac573afb42c13ad89fc8dd0651f5cb8b66534c5652"

Navigate to your working directory:

cd ~/tokenreg

Initialize the draft:

token-metadata-creator entry --init $SUBJECT

This creates a .json.draft file.

Add all metadata fields in one command:

token-metadata-creator entry $SUBJECT \
  --name "YourTokenName" \
  --description "Your token description here. Be precise and informative." \
  --ticker "TICKER" \
  --url "https://yourwebsite.com" \
  --logo logo.png \
  --decimals 6 \
  --policy policy.script

⚠️ Critical field notes:

• --logo expects a PNG file path, not a base64 string. The tool encodes it internally.

• --decimals must match exactly what was set during minting. Double-check this value!

• --ticker maximum 9 characters.

• --url must be a valid HTTPS URL.

---

Phase 6 - Sign and Finalize

Sign the entry with your policy signing key:

token-metadata-creator entry $SUBJECT -a policy.skey

This adds cryptographic signatures to all attestable fields.

Finalize (produces the final JSON):

token-metadata-creator entry $SUBJECT --finalize

This outputs: {SUBJECT}.json

---

Phase 7 - Verify the JSON

Never skip this step. Run this verification before submitting:

cat ${SUBJECT}.json | python3 -c "
import json, sys, base64, struct

d = json.load(sys.stdin)

# Check all required fields
print('subject:', d.get('subject', 'MISSING'))
print('name:', d['name']['value'])
print('ticker:', d['ticker']['value'])
print('decimals:', d['decimals']['value'])
print('url:', d['url']['value'])
print('policy:', d.get('policy', 'MISSING'))

# Check logo
b64 = d['logo']['value']
png = base64.b64decode(b64)
valid_png = png[:8].hex() == '89504e470d0a1a0a'
w = struct.unpack('>I', png[16:20])[0]
h = struct.unpack('>I', png[20:24])[0]
print(f'Logo b64 length: {len(b64)} chars (limit: 65,536)')
print(f'Logo valid PNG: {valid_png}')
print(f'Logo dimensions: {w}x{h}')
print(f'Logo PNG size: {len(png):,} bytes')

# Check signatures exist
for field in ['name', 'ticker', 'decimals', 'url', 'logo', 'description']:
    sigs = len(d.get(field, {}).get('signatures', []))
    print(f'  {field}: {sigs} signature(s)')

# File size
import os
size = os.path.getsize(f'{d[\"subject\"]}.json')
print(f'File size: {size:,} bytes (limit: 370,000)')
"

Expected output:

• Valid PNG: True

• Dimensions: 200x200

• Base64 length under 65,536

• All fields have 1+ signatures

• File size under 370,000 bytes

💡 Visually inspect the logo too! Decode it and open it:

python3 -c "
import json, base64
with open('${SUBJECT}.json') as f:
    d = json.load(f)
with open('/tmp/preview_logo.png', 'wb') as f:
    f.write(base64.b64decode(d['logo']['value']))
print('Saved to /tmp/preview_logo.png')
"
# Copy to Windows Desktop to view
cp /tmp/preview_logo.png /mnt/c/Users/YOURNAME/Desktop/

---

Phase 8 - Submit the Pull Request

Step 1 - Fork the registry

Go to https://github.com/cardano-foundation/cardano-token-registry and click Fork → Create fork.

Settings:

• Owner: your GitHub account

• Repository name: cardano-token-registry (keep default)

• Copy master branch only: checked

• Description: leave empty

Step 2 - Create a GitHub Personal Access Token

Go to https://github.com/settings/tokens → Generate new token (classic)

Settings:

• Note: Cardano Token Registry

• Expiration: 30 days (sufficient)

• Scope: tick repo only

Click Generate token and copy it immediately — GitHub shows it only once.

Step 3 - Clone your fork

git config --global user.email "[email protected]"
git config --global user.name "YourGitHubUsername"

git clone https://github.com/YOURUSERNAME/cardano-token-registry.git
cd cardano-token-registry

When prompted for password, paste your Personal Access Token (not your GitHub password).

Step 4 - Create a branch, add file, commit, push

# Create branch
git checkout -b add-YOURTOKEN-token

# Copy your finalized JSON
cp ~/tokenreg/${SUBJECT}.json mappings/

# Verify it's there
ls mappings/${SUBJECT}.json

# Stage, commit, push
git add mappings/${SUBJECT}.json
git commit -m "Add YOURTOKEN token metadata"
git push origin add-YOURTOKEN-token

Step 5 - Open the Pull Request

Go to the URL shown in the terminal output (or navigate to your fork on GitHub).

PR description template:

Adding metadata for the YOURTOKEN token.

Policy ID: YOUR_POLICY_ID
Ticker: YOURTICKER
Decimals: X
URL: https://yourwebsite.com

Step 6 - Wait for CI and review

After submitting, two automated checks will run:

• CI / approve — checks PR format

• CI / Validate-Metadata — validates your JSON structure and signatures

Both must pass. The "Merging is blocked" message is normal — a Cardano Foundation maintainer must approve and merge. This typically takes a few days to a week.

---

Registry Field Reference

Field	Required	Max Length	Notes
subject	✅	—	policyID + assetNameHex
name	✅	50 chars	Human-readable token name
description	✅	500 chars	What the token represents
ticker	Optional	9 chars	Trading ticker symbol
url	Optional	250 chars	Must be HTTPS
logo	Optional	65,536 base64 chars	PNG only, max 200×200px
decimals	6 is standard	—	Integer, must match minting
policy	Auto-generated	—	CBOR-encoded policy script

---

Common Mistakes & How to Avoid Them

Wrong decimals value

Problem: Setting decimals to 0 when the token was minted with 6 decimals (or any other value).

Fix: Always verify your decimals before creating the metadata. Check your minting transaction or NMKR/minting platform settings. Decimals must match exactly what was encoded at mint time.

---

Logo not a valid PNG

Problem: Logo file is actually a JPEG or WebP even though it has a .png extension. This produces a broken or corrupted logo in the registry.

Fix: Always check the file header bytes. If the first 8 bytes are not 89 50 4E 47 0D 0A 1A 0A, it is not a PNG. Convert explicitly with Pillow as shown in Phase 4.

---

Logo base64 too large

Problem: A 256×256 PNG may exceed the 65,536 base64 character limit.

Fix: Use 200×200 maximum. Check the base64 length before proceeding. Reduce to 150×150 if still too large.

---

Logo path vs base64 confusion

Problem: Passing a pre-encoded base64 file to --logo instead of the PNG file path.

Fix: The --logo flag expects a PNG file path. The tool encodes it to base64 internally. Example: --logo logo.png ✅ not --logo logo.b64 ❌

---

WSL username with uppercase

Problem: Trying to create a UNIX user like Flo — Ubuntu rejects it.

Fix: Always use lowercase for UNIX usernames: flo, john, tokenadmin.

---

Using GitHub password instead of Personal Access Token

Problem: git push fails with authentication error.

Fix: GitHub no longer accepts passwords for CLI operations. Generate a Personal Access Token with repo scope and use that as the password.

---

Not visually verifying the logo

Problem: The JSON passes all automated checks (valid PNG bytes, correct dimensions) but the actual image is broken or wrong.

Fix: Always decode the base64 logo from your final JSON and visually inspect it before submitting the PR. Open it in an image viewer to confirm it looks correct.

---

Subject lowercase requirement

Problem: The filename must be {subject}.json where subject is all lowercase hex.

Fix: Policy IDs and asset name hex are always lowercase. The token-metadata-creator tool handles this automatically.

---

Best Practices Checklist

Before submitting your PR, confirm all of the following:

Metadata correctness:

• Subject is correct: policyID + assetNameHex (no separator)

• Decimals match exactly what was set at minting time

• Description is accurate and informative (max 500 chars)

• URL is live and HTTPS

• Ticker is correct (max 9 chars)

Logo:

• File is a true PNG (verified by header bytes)

• Dimensions are 200×200 or smaller

• Base64 length is under 65,536 characters

• Visually inspected and looks correct

• RGBA mode for transparency support

Signatures:

• Signed with the correct policy.skey

• All fields have signatures

• Policy field is present

File:

• JSON filename matches subject exactly

• File is in the mappings/ directory

• File size is under 370KB

• JSON is valid (no syntax errors)

GitHub:

• Forked from cardano-foundation/cardano-token-registry

• PR targets master branch

• Both CI checks pass

• PR description includes policy ID, ticker, decimals

---

Cleanup After Submission

Once your PR is submitted, you can safely clean up your local files:

# Remove working files
rm -rf ~/tokenreg
rm -rf ~/cardano-token-registry

# Remove downloaded tool archive
rm -f ~/token-metadata-creator.tar.gz*

# Return to home directory
cd ~

The token-metadata-creator binary remains installed at /usr/local/bin/ — useful if you register more tokens in the future.