SPL Token Metadata Best Practices

What is Token Metadata?

Token metadata is additional information attached to your SPL token that makes it recognizable and usable across the Solana ecosystem. Without proper metadata, your token is just an address—with it, your token has an identity, visual representation, and context.

Why Metadata Matters

Proper metadata ensures your token:

• Displays correctly in wallets like Phantom, Solflare, and Backpack
• Shows up on explorers like Solscan and Solana Explorer with full information
• Gets indexed by DEXs and aggregators like Jupiter and Raydium
• Appears professional and trustworthy to potential holders
• Can be discovered by users searching for tokens in their category

First Impressions Matter: Users often judge a token's legitimacy by how professional its metadata looks. Poor or missing metadata is a red flag that screams "scam" or "unprofessional."

The Metaplex Standard

Metaplex is the de facto standard for NFT and token metadata on Solana. Most wallets, explorers, and platforms follow the Metaplex Token Metadata Standard.

On-Chain vs Off-Chain Metadata

Metaplex uses a hybrid approach:

• On-Chain: Essential data like name, symbol, and URI stored directly on Solana
• Off-Chain: Extended data like images, descriptions, and attributes stored as JSON and referenced by URI

This design keeps blockchain costs low while allowing rich metadata.

Required Fields

At minimum, your token metadata should include:

• name - Full token name (e.g., "My Awesome Token")
• symbol - Ticker symbol (e.g., "MAT")
• uri - URL pointing to your JSON metadata file

Optional But Recommended Fields

• description - Detailed explanation of your token
• image - URL to your token logo
• external_url - Your project website
• attributes - Custom properties and tags
• properties - Extended information including social links

Token Image Specifications

Your token logo is the most visible part of your metadata. Here's how to get it right:

Technical Requirements

• Format: PNG with transparency (preferred) or JPG
• Dimensions: 500x500px minimum, 1000x1000px recommended
• Aspect Ratio: 1:1 (square) is required—circular tokens should be square with transparent corners
• File Size: Under 1MB for fast loading, ideally 100-300KB
• Resolution: 72 DPI minimum, 300 DPI for print-quality

Design Best Practices

• Simple and Recognizable: Should be identifiable even at small sizes (32x32px)
• High Contrast: Works on both light and dark backgrounds
• Professional Quality: No pixelation, blurriness, or amateur design elements
• Unique Identity: Distinctive enough to avoid confusion with other tokens
• Brand Consistent: Matches your project's overall visual identity

Pro Tip: Test your logo at different sizes (16px, 32px, 64px, 128px) to ensure it remains clear and recognizable. Wallets display tokens at various sizes.

Common Image Mistakes to Avoid

• Using non-square images that get distorted
• Low resolution images that look pixelated
• Complex designs with too much detail for small displays
• Copyright infringement—using someone else's art without permission
• Inappropriate or offensive imagery
• White backgrounds that clash with dark mode interfaces

Description Best Practices

Your token description explains what your token is and why it exists. It appears on explorers and some wallets.

Structure Your Description

A good description follows this format:

1. Opening Line: Concise statement of what the token is (1 sentence)
2. Purpose: Explain the token's utility and use cases (2-3 sentences)
3. Key Features: Highlight what makes it unique or valuable
4. Call to Action: Invite users to learn more or get involved

Writing Tips

• Be Concise: 150-300 characters is ideal. People scan, they don't read
• Clear Language: Avoid jargon unless your audience expects it
• Value Proposition: Focus on benefits, not just features
• Professional Tone: Even meme tokens need proper grammar and spelling
• No Hype Language: Avoid "moon," "guaranteed returns," or get-rich-quick promises
• SEO Friendly: Include relevant keywords naturally

Description Example (Good)

"MYTOKEN is the governance token for the MyDAO ecosystem. Token holders can vote on protocol upgrades, treasury management, and community initiatives. With a fixed supply of 100M tokens and no mint authority, MYTOKEN is designed for long-term value accrual through platform fees and staking rewards."

Description Example (Bad)

"MYTOKEN is going to the MOON 🚀🚀🚀 100x GUARANTEED! Buy now before its too late!!! This is the next BIG thing in crypto!!!"

Social Links and External URLs

Connecting your token to your web presence builds trust and community.

Essential Links

Include these in your metadata's properties section:

• Website: Your official project homepage
• Twitter/X: For announcements and community engagement
• Telegram or Discord: For community discussion
• Documentation: Whitepaper or technical docs

Optional But Valuable Links

• Medium or blog for updates
• GitHub for open-source projects
• Reddit community
• YouTube for video content
• CoinGecko or CoinMarketCap listing

Link Best Practices

• Use HTTPS: All URLs should be secure
• Verify Links: Test every link before deploying metadata
• Keep Updated: Dead links damage credibility
• Official Channels Only: Don't link to unofficial fan pages
• Consistent Branding: Social handles should match when possible

Security Note: Never link to suspicious or phishing sites. Malicious links in metadata can get your token flagged or delisted.

Metadata JSON Structure

Here's a complete example of properly structured token metadata:

{
  "name": "My Awesome Token",
  "symbol": "MAT",
  "description": "MAT is the governance token for the MyDAO ecosystem, enabling community-driven decision making and value distribution.",
  "image": "https://arweave.net/your-image-hash",
  "external_url": "https://myawesometoken.com",
  "attributes": [
    {
      "trait_type": "Type",
      "value": "Governance"
    },
    {
      "trait_type": "Supply",
      "value": "Fixed"
    }
  ],
  "properties": {
    "files": [
      {
        "uri": "https://arweave.net/your-image-hash",
        "type": "image/png"
      }
    ],
    "category": "currency",
    "creators": [],
    "links": {
      "website": "https://myawesometoken.com",
      "twitter": "https://twitter.com/MyAwesomeToken",
      "telegram": "https://t.me/myawesometoken",
      "discord": "https://discord.gg/myawesometoken",
      "medium": "https://medium.com/@myawesometoken"
    }
  }
}

Field Explanations

• name: Full token name, displayed in wallets
• symbol: 2-5 character ticker
• description: Detailed explanation (150-500 characters)
• image: Direct URL to your token logo
• external_url: Your project's main website
• attributes: Key-value pairs for categorization and filtering
• properties.files: Array of associated files (usually just the image)
• properties.category: Token type (usually "currency" for fungible tokens)
• properties.links: All your social and web presence

Hosting Your Metadata

Where you host your metadata matters for permanence and accessibility.

Hosting Options

1. Arweave (Recommended)

• Permanent storage: Pay once, stored forever
• Decentralized: No single point of failure
• Industry standard: Preferred by Solana ecosystem
• Cost: ~$0.10-0.20 per metadata upload

2. IPFS

• Decentralized: Content-addressed storage
• Widely supported: Most platforms accept IPFS URIs
• Cost: Variable, depends on pinning service
• Consideration: Requires pinning to ensure availability

3. Traditional Web Hosting (Not Recommended)

• Flexible: Easy to update metadata
• Cheap: Can use existing web hosting
• Risks: Can go down, domain can expire, company can shut down
• Use case: Only during development/testing

Best Practice: Use Arweave for production tokens. The permanence and decentralization align with crypto principles and prevent future issues.

Uploading to Arweave

Most token creation platforms (like CreateMyCoin) handle Arweave uploads automatically. If you're doing it manually:

1. Upload your token image to Arweave (gets a permanent URL)
2. Create your JSON metadata file with the image URL
3. Upload the JSON file to Arweave (gets another permanent URL)
4. Use the JSON URL as your token's URI when minting

Updating and Maintaining Metadata

Sometimes you need to update your token's metadata after creation.

What Can Be Updated

If you maintained update authority during token creation:

• The URI pointing to your metadata
• Off-chain metadata (description, links, images) by uploading new JSON
• Token name and symbol (though this can cause confusion)

What Cannot Be Changed

• Token mint address (this is your token's permanent identity)
• Decimals (set forever at creation)
• Initial supply (though more can be minted if you kept mint authority)

When to Update Metadata

Valid reasons to update:

• Fixing typos or errors in description
• Updating social links when URLs change
• Improving token logo with higher quality version
• Adding new features or use cases to description
• Rebranding (with clear communication to community)

Best Practices for Updates

• Announce changes: Tell your community before updating
• Preserve history: Keep old metadata accessible for transparency
• Don't abuse it: Frequent changes damage trust
• Test first: Verify new metadata works before deploying

Metadata Checklist

Before deploying your token, verify:

• ✅ Logo is 1000x1000px PNG with transparency
• ✅ Logo looks good at 32px, 64px, and 128px sizes
• ✅ Description is clear, professional, and under 300 characters
• ✅ All social links are working and use HTTPS
• ✅ JSON metadata is valid and properly formatted
• ✅ Metadata is hosted on permanent storage (Arweave recommended)
• ✅ No typos in name, symbol, or description
• ✅ External URL points to your official website
• ✅ Image URL is accessible and loads quickly
• ✅ Metadata has been tested in at least one wallet

Conclusion

Quality metadata is the difference between a professional token and an amateur project. It's your token's first impression, its identity across the ecosystem, and a key factor in building trust with potential holders.

By following these best practices—using proper image specifications, writing clear descriptions, providing complete social links, and hosting on permanent storage—you ensure your token puts its best foot forward from day one.

Remember: you can have the best tokenomics and utility in the world, but if your metadata looks unprofessional or is missing, users will never stick around long enough to discover your value proposition.