How to pin NFT metadata and images to IPFS, step by step

Every NFT has two parts that live off-chain: the media (an image, video or 3D file) and a small JSON metadata file that describes it. Your contract only stores a pointer to the metadata. This guide shows how to pin both to IPFS so the pointer keeps working for as long as the content is pinned, no matter which marketplace or wallet reads it.

What you need

• A folder with your media files, named by token ID (1.png, 2.png, ...).
• An IPFS pinning service account. We use Octopin below, but the steps are the same on any provider.
• A script or spreadsheet to generate the metadata JSON files.

Step 1: pin the media folder

Upload the whole media folder in one go instead of file by file. A folder upload gives you a single directory CID, and every file is reachable under it:

ipfs://<MEDIA_CID>/1.png
ipfs://<MEDIA_CID>/2.png

In Octopin, open the upload page, choose folder, and select the directory. When it finishes you get the directory CID. Open one file through a public gateway such as https://ipfs.io/ipfs/<MEDIA_CID>/1.png to confirm it resolves outside our own gateway too.

Step 2: write the metadata JSON

Each token gets one JSON file following the ERC-721 metadata standard (ERC-1155 uses the same shape). The image field must point at the media using the ipfs:// scheme:

{
  "name": "Octo #1",
  "description": "One of 4,848 OctoPeeps.",
  "image": "ipfs://<MEDIA_CID>/1.png",
  "attributes": [
    { "trait_type": "Background", "value": "Teal" },
    { "trait_type": "Eyes", "value": "Sleepy" }
  ]
}

Name the files by token ID. Many projects drop the .json extension (1, 2, ...) so the contract can build the URI as baseURI + tokenId. If you keep the extension, make sure your contract appends it.

Step 3: pin the metadata folder

Upload the metadata directory the same way. You get a second CID, and each token's metadata is at ipfs://<METADATA_CID>/1. Spot-check a few files through a public gateway and confirm the image links open.

Step 4: set the base URI in your contract

Set baseURI (or return it from tokenURI) as:

ipfs://<METADATA_CID>/

Use ipfs://, not an https gateway URL. A gateway hostname ties your collection to one company's server forever. The ipfs:// form lets every marketplace and wallet pick its own gateway, and lets you switch pinning providers without touching the contract. Full explanation here.

Step 5: check it on a marketplace

After minting a test token, open it on OpenSea or Magic Eden and use "refresh metadata". Marketplaces cache aggressively, so the first fetch can take a few minutes. How marketplaces resolve ipfs:// URIs.

Common mistakes

• Pinning files one by one. You end up with thousands of unrelated CIDs and no clean base URI.
• Gateway URLs in metadata. An https://some-gateway/ipfs/... image link breaks when that gateway goes away, as Storacha users found out in 2026.
• Editing after the reveal. Any change to a file changes its CID. Fix mistakes before you set the base URI, or plan a contract method to update it.
• Choosing a host by storage price only. A mint or a viral moment can push a lot of traffic. Check bandwidth pricing. On Octopin bandwidth is unlimited on every plan, including free.
• No backup. Keep the original folders or a CAR export. With them you can re-pin the exact same CIDs anywhere.

How much space does a collection need?

Metadata is tiny, usually under 1 KB per token. Media is what counts: a 10,000-piece PFP collection at around 100 KB per image needs about 1 GB. That fits the Octopin free plan's storage, though its 2,000 file limit means a collection that size needs the $5/mo Hobby plan.