Solana Token Metadata on IPFS: Pinata Guide

Your SPL token's name, symbol, and image don't live on Solana itself. They live in a JSON file pointed at by a Metaplex metadata account, and that JSON file usually lives on IPFS. If the JSON disappears, your token shows up everywhere as "Unknown Token" with a placeholder icon — forever. Here's how it actually works and why Pinata is the standard pin.

What metadata actually contains

When you launch an SPL token, Solana stores almost nothing about it onchain — just decimals, mint authority, freeze authority, and total supply. Everything human-readable comes from a separate Metaplex Metadata account, which holds:

• A short name and symbol (32 chars and 10 chars respectively)
• A uri pointing at a JSON file off-chain
• A sellerFeeBasisPoints (mostly used for NFTs)
• A creators array

The actual image, the long-form description, the social links — all of that lives at the URL the uri field points to. That URL is what wallets and explorers fetch to display your token.

Why IPFS instead of a regular web server?

You could put your metadata JSON at https://mybrand.com/token.json and it would work. Until you forget to renew your domain, your hosting bill bounces, your team disbands, or the file gets accidentally deleted. Then every wallet displays your token as "Unknown" forever, with no way to fix it (the metadata account points at a dead URL).

IPFS (the InterPlanetary File System) solves this with content addressing. Instead of asking a server "give me the file at /token.json", you ask the network "give me the file with hash Qm…". As long as anyone in the world is hosting that file, the request resolves. The hash never changes, never expires, and never depends on a single domain.

Where Pinata fits in

IPFS is a network — files don't stay online unless someone "pins" them (commits to keep hosting them). Pinata is the most popular pinning service on the network: you upload a file, they pin it on their gateway and a few others, and it stays available worldwide.

A typical Solana token pin flow:

1. Upload the image (e.g. logo.png) to Pinata → get back a CID like bafkrei…
2. Build the metadata JSON with that CID as the image field
3. Upload the JSON to Pinata → get back another CID
4. Pass the JSON's CID URL into your Metaplex metadata account as uri

SolanaForge handles all four steps for you in a single flow. You upload your logo, fill in the form, and we pin both the image and the JSON before we even build the on-chain transaction. If the on-chain transaction fails (rejected signature, network issue, simulation failure), an HMAC-signed unpin ticket revokes both pins so you don't pay for orphaned files.

What the JSON actually looks like

Here's a typical SolanaForge-generated metadata JSON:

{
  "name": "Mooncoin",
  "symbol": "MOON",
  "description": "Community-launched lunar memecoin on Solana mainnet.",
  "image": "https://gateway.pinata.cloud/ipfs/bafkreig…",
  "external_url": "https://mooncoin.fun",
  "extensions": {
    "twitter": "https://x.com/mooncoin",
    "telegram": "https://t.me/mooncoin",
    "website": "https://mooncoin.fun"
  }
}

The extensions block is what Solscan, Birdeye, and Phantom read to render your social links and verified-badge inputs.

Common pitfalls

• Self-hosting on a single VPS. The day your VPS dies, your token loses its name and image everywhere. Always use a real pinning service or self-host on at least 3 IPFS nodes.
• Using a free pinning service that disappears. Several "free forever" IPFS pinners have shut down over the past 2 years. Pinata has been live since 2018, runs paid plans, and is the safe default.
• Pointing metadata URI at a centralized URL like mybrand.com/token.json. Works until it doesn't. Always use the IPFS gateway URL or — better — an ipfs:// URI directly.

The bottom line

If you want your token to have a name and an image five years from now, the metadata needs to live on IPFS, and IPFS needs a pinning service that won't disappear. SolanaForge bundles Pinata pinning into every launch with rollback safety, so the metadata is always pinned before the transaction lands and unpinned if anything fails. You just upload, fill in the form, and ship.