---

name: ipfs description: >- Store and retrieve files on IPFS (InterPlanetary File System). Use when a user asks to store files in a decentralized way, pin content on IPFS, upload NFT metadata, or use content-addressed storage. license: Apache-2.0 compatibility: 'Any platform via HTTP API' metadata: author: terminal-skills version: 1.0.0 category: development tags: - ipfs - decentralized - storage - nft - pinning

IPFS

Overview

IPFS is a decentralized file storage protocol. Files are content-addressed (identified by hash, not location). Used for NFT metadata, dApp assets, and censorship-resistant content. Pinning services (Pinata, web3.storage) ensure files stay available.

Instructions

Step 1: Upload via Pinata

// lib/ipfs.ts — Upload files to IPFS via Pinata
const PINATA_JWT = process.env.PINATA_JWT!

export async function uploadToIPFS(file: Buffer, name: string): Promise<string> {
  const formData = new FormData()
  formData.append('file', new Blob([file]), name)
  formData.append('pinataMetadata', JSON.stringify({ name }))

  const res = await fetch('https://api.pinata.cloud/pinning/pinFileToIPFS', {
    method: 'POST',
    headers: { Authorization: `Bearer ${PINATA_JWT}` },
    body: formData,
  })

  const { IpfsHash } = await res.json()
  return `ipfs://${IpfsHash}`
}

export async function uploadJSON(data: object): Promise<string> {
  const res = await fetch('https://api.pinata.cloud/pinning/pinJSONToIPFS', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${PINATA_JWT}`,
    },
    body: JSON.stringify({ pinataContent: data }),
  })

  const { IpfsHash } = await res.json()
  return `ipfs://${IpfsHash}`
}

Step 2: NFT Metadata

// Upload NFT image and metadata
const imageHash = await uploadToIPFS(imageBuffer, 'nft-image.png')

const metadata = {
  name: 'Cool NFT #1',
  description: 'A very cool NFT',
  image: imageHash,
  attributes: [
    { trait_type: 'Background', value: 'Blue' },
    { trait_type: 'Rarity', value: 'Rare' },
  ],
}

const metadataHash = await uploadJSON(metadata)
// Use metadataHash as tokenURI in your NFT contract

Step 3: Retrieve Content

// Read from IPFS via gateway
const GATEWAY = 'https://gateway.pinata.cloud/ipfs'

async function getFromIPFS(cid: string) {
  const res = await fetch(`${GATEWAY}/${cid}`)
  return res.json()
}

Guidelines

• Content on IPFS is not automatically permanent — it needs to be "pinned" by at least one node.
• Pinata free tier: 500MB storage, 100 pins. web3.storage: 5GB free.
• Use IPFS gateways (ipfs.io, pinata, cloudflare-ipfs) for HTTP access to IPFS content.
• For mutable content, use IPNS (IPFS Name System) or ENS domains.