How to Add Token Metadata with Metaplex

By default, an SPL token has no name or image — wallets show it as "Unknown Token." The Metaplex Token Metadata program fixes this by attaching a metadata account to your mint.

How Metadata Works

The metadata account stores an on-chain name, symbol, and a URI pointing to a JSON file. That JSON contains the description and an image URL. Wallets read the on-chain name/symbol and fetch the JSON for the logo.

The Metadata JSON

{
  "name": "My Token",
  "symbol": "MTK",
  "description": "My awesome token",
  "image": "https://yoursite.com/logo.png",
  "properties": { "files": [{ "uri": "...png", "type": "image/png" }], "category": "image" }
}

Creating the Metadata Account

Use the CreateMetadataAccountV3 instruction. The data is Borsh-encoded: a 1-byte discriminator, length-prefixed strings for name/symbol/uri, seller fee basis points, optional creators/collection/uses, an is_mutable flag, and optional collection details.

Best Practices

• Include the metadata instruction in the same transaction as the mint so name/logo are set atomically.
• Host the image and JSON on reliable storage and serve JSON with proper CORS and application/json.
• Keep name ≤ 32 chars, symbol ≤ 10, uri ≤ 200.
• Add properties.files for maximum wallet/explorer compatibility.

FAQ

Why does my logo show in Phantom but not Solscan?

Explorers like Solscan cache and gate logos for new, unverified tokens. The metadata is correct; Solscan may need time or manual verification.