Decentralized NFT Storage: IPFS & Filecoin Integration

Imagine: you launched an NFT collection of 10,000 tokens, all sold out. A year later, a holder tries to open the metadata—but it won't load because the server hosting the images is down. The tokenURI leads to nothing. Your project's reputation is on the line. This pain is familiar to anyone who stores NFTs on centralized hosting. The solution: decentralized storage on IPFS with Filecoin replication via NFT.Storage. Let's break down the integration from A to Z.

In over 10 years, we have completed 50+ integrations with NFT.Storage, Pinata, and other services, pushing batch uploads to 10,000 files in one round. Below are practical details that saved us hundreds of hours.

Why use NFT.Storage for NFT storage?

NFT.Storage is a service from Protocol Labs that provides free storage of NFT data on IPFS and Filecoin. Technically: you upload a file via the API, get a CID (Content Identifier) — a SHA-256 hash, a unique identifier. Data is replicated onto Filecoin for long-term storage (typical deal is 18 months with cryptographic proof). Unlike centralized servers, content is addressed by content — if the file changes, the CID changes. This is critical for NFTs: a tokenURI like ipfs://Qm.../1.json works even if the project site disappears.

For new projects, we recommend using the modern w3up client (v2) — it handles large collections faster and has a more flexible API. If you already have a legacy integration with the old REST API (v1), it still works, but we recommend migrating for better reliability.

How storage works

IPFS — content addressing

IPFS uses content addressing: the CID is calculated from a hash of the content. ipfs://QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco/image.png is a specific file with a specific hash. It’s impossible to change the content without changing the CID — this guarantees immutability for NFT metadata.

Filecoin for persistence

IPFS alone does not guarantee storage: if no node pins the file, it disappears. NFT.Storage automatically creates Filecoin deals for uploaded data — decentralized long-term storage with cryptographic proof of storage. This sets it apart from simple IPFS pinning services (Pinata, Infura).

Filecoin is a blockchain for verifying data storage. By using it, you get a guarantee that data will be stored for a set period (usually 18 months), even if NFT.Storage goes out of business.

Limits and restrictions

After policy changes, the service stopped accepting new users through its main site, switching to the commercial web3.storage with paid plans. For existing projects, data remains accessible. For new ones, alternatives include Pinata, 4EVERLAND, or self-hosted IPFS nodes.

For production NFT projects, we recommend a hybrid approach: primary storage plus replication on 2-3 pinning services. This minimizes the risk of data loss.

How to integrate NFT.Storage into a project

Uploading a collection

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

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

// Uploading a 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 a 10K collection

For large collections — use storeDirectory to upload an entire directory under one 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 reliable for thousands of files.

How to verify correct upload?

After uploading, it’s important to check CID availability through public gateways: ipfs.io/ipfs/{CID}, cloudflare-ipfs.com/ipfs/{CID}, gateway.pinata.cloud/ipfs/{CID}. If the file is accessible on 2 out of 3 gateways within 30 minutes, the upload is successful. Always verify metadata before setting baseURI in the contract.

Best practices

Separate images and metadata by CID — this simplifies auditing and provides flexibility for reveal strategies. Upload images first, get the directory CID. Then generate JSON metadata with image: ipfs://{imagesCid}/{tokenId}.png and upload them. Changing metadata without changing the CID is impossible — a guarantee for buyers.

Store the CID as a constant in the contract. After the final reveal, the baseURI should be immutable. If setBaseURI is accessible to the owner indefinitely, that’s a trust assumption. Consider renounceOwnership for the URI-changing function after reveal.

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

What’s included in the work

• Analysis of your project and selection of the optimal storage provider (NFT.Storage / Pinata / web3.storage).
• Development of batch upload scripts for images and metadata.
• Setup of API keys and CID verification.
• Smart contract integration: baseURI setup, renounceOwnership.
• Documentation with step-by-step instructions for reuse.
• Technical support during the collection upload period (1-2 days).

Work process

1. Analysis (a few hours) — choose service, estimate volumes.
2. Upload script development (1 day) — batch upload, verification, baseURI generation.
3. Contract integration (1 day) — set URI, test on testnet.
4. Testing — check availability on gateways, simulate mint.
5. Deployment — upload to mainnet, reveal.

Time estimates

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

Need reliable integration? Contact us—we’ll set up storage, verify CIDs, and advise on provider selection. Order integration today.

Why does NFT marketplace development require a comprehensive approach?

We see that at first glance, an NFT contract looks simple: ERC-721, mint(), IPFS for metadata — that's it. In practice, it's this 'simplicity' that hides most problems — from bots buying out the entire mint in the first block to broken royalties on the secondary market. We often hear: Make a collection like others in a week — and a month later it turns out gas has tripled due to an unoptimized for loop, or OpenSea cannot see metadata after reveal. We know each of these pitfalls and build processes to avoid them.

Over 5 years of working with blockchains, we have implemented 40+ NFT projects, including marketplaces with dynamic attributes and cross-chain bridges. We have accumulated a library of proven templates — some of which we break down below.

Which standard to choose: ERC-721 or ERC-1155?

ERC-721 — each token is unique, one owner. Suitable for collections where each NFT has individual attributes and a direct owner → tokenId mapping.
ERC-1155 — multi-token standard: one contract holds both fungible and non-fungible tokens. It uses balanceOf(address, tokenId) instead of ownerOf(tokenId). A single transaction can transfer multiple different tokens via safeBatchTransferFrom. This saves gas on bulk operations — important for game items, tickets, edition collections. ERC-1155 is 2–3× more gas-efficient than ERC-721 for batch transfers.

Specific case: a game project with 50 types of items, each with a supply of 10,000. ERC-721 — 500,000 unique tokens, huge overhead on mappings. ERC-1155 — 50 tokenIds, balanceOf per player. Gas per transfer is 2–3 times lower, contract deployment is cheaper. For such tasks, we use OpenZeppelin ERC-1155 with custom modifications.

Metadata: on-chain vs IPFS vs centralized

The standard route is tokenURI() returning a link to a JSON with fields name, description, image, attributes. Three storage options:

• Centralized server — cheapest and most flexible. Risk: server goes down, company closes — NFT loses metadata. Not suitable for collections claiming long-term value.
• IPFS + Pinning — content-addressed storage, the link is bound to the content hash. Pinata or NFT.Storage provide pinning. Important: IPFS does not guarantee availability by itself — an active pinning service is needed. If it shuts down, data may disappear if no one keeps a copy.
• On-chain metadata — base64-encoded SVG or JSON directly in tokenURI. Maximum reliability, but expensive: for a collection of 10,000 tokens, gas costs may exceed $5,000. Suitable for generative art projects where visuals are generated from on-chain attributes (Nouns, Loot).

For most collections, we choose IPFS with Pinata for images + on-chain attributes for traits — a good balance. We validate files against a JSON Schema before upload; a typical mistake is unescaped quotes, causing marketplaces to display a blank screen.

{
  "name": "Token #1",
  "description": "A unique NFT",
  "image": "ipfs://QmHash/image.png",
  "attributes": [{"trait_type": "Background", "value": "Red"}]
}

Dynamic NFT: metadata that changes

Dynamic NFT updates metadata in response to external events — match results, character levels, real-world data via Chainlink. Architecturally, it's a combination: the smart contract stores state → tokenURI() generates metadata from the state on-chain. Caching problem: OpenSea and other marketplaces aggressively cache. The standard invalidation mechanism is a MetadataUpdate(tokenId) event from ERC-4906. OpenSea listens to this event and clears the cache. Without it, updated metadata may not appear for weeks.

Chainlink Automation (formerly Keepers) for automatically updating state on the contract on a schedule or condition — a standard solution for dynamics.

How to protect mint from bots?

Allowlist via Merkle tree — standard. The list of addresses is hashed into a Merkle root, stored in the contract. During mint, the user provides a Merkle proof — the contract verifies without storing the full list. We use OpenZeppelin MerkleProof library.

Reveal mechanism — on mint, a placeholder is issued; real traits are revealed after the sale ends. Otherwise, bots can scan pending transactions and snipe rare traits via frontrunning. But reveal requires a commitment scheme — the random seed must be fixed before mint or use Chainlink VRF.

Chainlink VRF for fair randomization of traits. VRF request at mint → callback with verifiable random number → assign traits. This adds ~2 transactions and latency but guarantees fairness. Chainlink VRF v2.5.

Rate limiting — require(mintedPerWallet[msg.sender] < maxPerWallet). Does not protect against multi-wallets but raises attack cost. For premium projects, we often add proof-of-work directly in the contract (via EIP-2612 signatures).

Royalties: the real market state

ERC-2981 — on-chain royalty standard. The contract returns (recipient, amount) for any sale price via royaltyInfo(tokenId, salePrice). Marketplaces query this on each sale. Problem: adherence to royalties is voluntary for marketplaces. Blur launched with zero royalties, triggering a wave of other platforms. The situation has partially stabilized: OpenSea supports ERC-2981, Blur added optional ones. Royalty payments can represent 5–10% of secondary sale volume, so getting them right matters.

Attempts to enforce royalties on-chain by restricting transfers only to approved marketplaces (operator filtering) were proposed by OpenSea via OperatorFilterRegistry. This breaks composability — you cannot transfer an NFT through a custom contract. Most serious projects have abandoned this approach. For projects where royalties are critical, we build a custom marketplace within the ecosystem plus an incentive structure for users to trade there.

Lazy minting and gas-free mint

Gas-free mint via signature: the creator signs a voucher (tokenId, tokenURI, price, signature), the buyer provides the voucher in mint() — the contract verifies the signature via ECDSA.recover() and mints. Works on OpenSea via their Seaport protocol. Seaport is an optimized contract with minimal gas usage. Understanding its mechanics is important when integrating custom marketplace logic.

Stack for NFT projects

• Contracts: Solidity 0.8.x, OpenZeppelin ERC721Enumerable or ERC721A (Azuki) for gas-optimized batch mint, ERC1155 from OpenZeppelin
• VRF and automation: Chainlink VRF v2.5, Chainlink Automation
• Storage: Pinata (IPFS pinning), NFT.Storage, Arweave for permanent storage
• Marketplace: OpenSea Seaport protocol, custom integration
• Frontend: wagmi v2 + viem, RainbowKit for wallet connection, React + TypeScript

Development process

1. Mint mechanics design — allowlist, public sale, price curve (Dutch auction or fixed), limits per wallet
2. Contracts — with Foundry fuzz tests on mint limits, Merkle proof verification, royalty calculations
3. IPFS deployment — upload metadata and images before reveal, pin on at least two services
4. Reveal — if using Chainlink VRF, test on testnet mandatory: VRF subscription must be funded with LINK tokens
5. Marketplace integration — verify collection on OpenSea, configure royalties, test MetadataUpdate events
6. Deployment and monitoring — Tenderly for reentrancy detection, Etherscan API for contract verification, set up event alerts

Deliverables

• Source code of smart contracts (Solidity, Rust for Solana) with comments
• Test suite (Foundry/Hardhat) with ≥90% coverage
• Deployment documentation and integration instructions
• Access to pinning services (Pinata/Pinfluence)
• Metadata generation scripts (Python/JS)
• Support during marketplace verification
• 30 days of technical support after deployment

Timeline

Cost is calculated individually after auditing your task. Send a brief with your project description — we will provide a transparent estimate within 3 business days. For regular clients, there is a flexible discount system on batch orders. If you need a gas-optimized contract, order a free gas analysis. Get a consultation on marketplace architecture — leave a request, and we will evaluate your project in three days.