NFT.Storage Integration

NFT.Storage Integration

NFT.Storage is a service from Protocol Labs providing free NFT data storage on IPFS and Filecoin. Technically: you upload file via API, get CID (Content Identifier), data replicates on Filecoin for long-term storage. Unlike centralized servers, content is addressed by hash of its contents — if file changes, CID changes too.

For NFT projects it solves specific problem: tokenURI shouldn't point to https://myproject.com/metadata/1.json — this server can shut down, NFT becomes empty. IPFS URI like ipfs://Qm.../1.json works regardless if project website exists.

How Storage Works

IPFS — Content Addressing

IPFS uses content addressing: CID computed from file content hash. ipfs://QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco/image.png — specific file with specific hash. Impossible to change content without changing CID — this guarantees immutability for NFT metadata.

NFT.Storage implements two APIs: old REST API (v1) and new w3up client (v2). For new projects we recommend w3up — better performance on large collections.

Filecoin for Persistence

IPFS itself doesn't guarantee storage: if no node pins file, it disappears. NFT.Storage automatically creates Filecoin deals for uploaded data — decentralized long-term storage with cryptographic proof of storage. This differs from simple IPFS pinning service (Pinata, Infura).

Limits and Restrictions

NFT.Storage introduced restrictions in 2024: free tier no longer available for new registrations via main site. Protocol Labs shifted focus to web3.storage with paid plans. For existing projects — data remains accessible. For new ones — alternatives: Pinata (paid), 4EVERLAND, or self-hosted IPFS nodes.

For production NFT projects we recommend hybrid approach: primary storage + replication on 2-3 pinning services.

Integration via JavaScript SDK

Collection Upload

import { NFTStorage, File } from 'nft.storage'

const client = new NFTStorage({ token: process.env.NFT_STORAGE_KEY })

// Upload single NFT with image and metadata
const metadata = await client.store({
  name: 'Collection #1234',
  description: 'Description here',
  image: new File([imageBuffer], 'image.png', { type: 'image/png' }),
  attributes: [
    { trait_type: 'Background', value: 'Blue' }
  ]
})

console.log(metadata.url) // ipfs://Qm.../metadata.json
console.log(metadata.data.image.href) // ipfs://Qm.../image.png

Batch Upload for 10K Collection

For large collections — storeDirectory for uploading entire directory as single CID:

const files = images.map((buffer, i) => 
  new File([buffer], `${i}.png`, { type: 'image/png' })
)
const imagesCid = await client.storeBlob(new Blob([/* directory */]))

In practice, using Pinata pinFileToIPFS with batch upload is more convenient — more reliable API for thousands of files.

Upload Verification

After upload, important to verify accessibility via public gateway before setting baseURI in contract. Use multiple gateways: ipfs.io/ipfs/{CID}, cloudflare-ipfs.com/ipfs/{CID}, gateway.pinata.cloud/ipfs/{CID}. If file accessible through 2 of 3 gateways within 30 minutes — upload successful.

Best Practices

Separate images and metadata by CID. Upload images separately, get directory CID. Then generate JSON metadata with image: ipfs://{imagesCid}/{tokenId}.png and upload it. Can't change metadata without changing CID — this guarantees for buyers.

Store CID in contract as constant. After final reveal baseURI should be immutable. If setBaseURI available to owner forever — this is trust assumption. Consider renounceOwnership for URI change function after reveal.

IPFS gateway in tokenURI. Wallets and marketplaces expect ipfs:// scheme, not https://gateway.ipfs.io/. Return ipfs://{CID}/{tokenId}.json — each client uses their own gateway.

Workflow

Setup (few hours). Account registration, get API key, test uploading one file.

Develop upload script (1 day). Batch upload images and metadata, CID verification, generate final baseURI.

Contract integration. Set baseURI after verifying accessibility on gateway.

Timeline Estimates

Integration as part of NFT collection development — 1-2 days. Separately — few hours for experienced team.