Pinata IPFS Pinning Integration

Pinata IPFS Pinning Integration

IPFS is content-addressable filesystem: file hash is its address. But if no one "pins" (stores) a file — it disappears from network. Pinata is a managed pinning service: you upload files, they guarantee availability. Used in NFT projects, dApps with on-chain metadata, decentralized storage.

File Upload via Pinata API

const PINATA_JWT = process.env.PINATA_JWT!;  // from dashboard.pinata.cloud

// Upload file
async function uploadFile(fileBuffer: Buffer, filename: string): Promise<string> {
  const formData = new FormData();
  formData.append('file', new Blob([fileBuffer]), filename);
  formData.append('pinataMetadata', JSON.stringify({ name: filename }));
  formData.append('pinataOptions', JSON.stringify({ cidVersion: 1 }));

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

  const data = await response.json();
  return data.IpfsHash;  // CIDv1 hash
}

// Upload JSON (for NFT metadata)
async function uploadJson(metadata: object, name: string): Promise<string> {
  const response = await fetch('https://api.pinata.cloud/pinning/pinJSONToIPFS', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${PINATA_JWT}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      pinataContent: metadata,
      pinataMetadata: { name },
      pinataOptions: { cidVersion: 1 },
    }),
  });

  const data = await response.json();
  return data.IpfsHash;
}

NFT Metadata Workflow

Standard ERC-721/ERC-1155 workflow:

// 1. Upload image
const imageCid = await uploadFile(imageBuffer, 'nft-image.png');

// 2. Form metadata per ERC-721 Metadata Standard
const metadata = {
  name: 'My NFT #1',
  description: 'Description here',
  image: `ipfs://${imageCid}`,  // ipfs:// URI, not https://
  attributes: [
    { trait_type: 'Background', value: 'Blue' },
    { trait_type: 'Rarity', value: 'Rare' },
  ],
};

// 3. Upload metadata
const metadataCid = await uploadJson(metadata, 'nft-1-metadata.json');

// 4. tokenURI = ipfs://{metadataCid}
// In contract: tokenURI(tokenId) returns ipfs://{metadataCid}

Use ipfs:// URI in contract, not https://gateway.pinata.cloud/ipfs/. Gateway may change or be unavailable — ipfs:// URI works with any gateway.

Pinata SDK (v2)

import { PinataSDK } from 'pinata';

const pinata = new PinataSDK({
  pinataJwt: process.env.PINATA_JWT!,
  pinataGateway: process.env.PINATA_GATEWAY!,  // yourname.mypinata.cloud
});

// Upload from URL
const upload = await pinata.upload.url('https://example.com/image.png');
console.log(upload.cid);

// Get file via dedicated gateway
const url = await pinata.gateways.convert(`ipfs://${cid}`);
// → https://yourname.mypinata.cloud/ipfs/{cid}

Dedicated gateway (paid option) is significantly faster than public gateway.pinata.cloud — important for NFT marketplaces where images are loaded by users.

Batch Pin and Collection Management

// List pinned files with filtering
async function listPins(keyValues?: Record<string, string>) {
  const params = new URLSearchParams({
    status: 'pinned',
    pageLimit: '100',
    ...(keyValues ? { 'metadata[keyvalues]': JSON.stringify(keyValues) } : {}),
  });

  const response = await fetch(
    `https://api.pinata.cloud/data/pinList?${params}`,
    { headers: { Authorization: `Bearer ${PINATA_JWT}` } }
  );

  return response.json();
}

// Unpin file (free storage)
async function unpinFile(cid: string) {
  await fetch(`https://api.pinata.cloud/pinning/unpin/${cid}`, {
    method: 'DELETE',
    headers: { Authorization: `Bearer ${PINATA_JWT}` },
  });
}

Use pinataMetadata.keyvalues to tag files by project or collection — later convenient to filter and manage storage.

Local Backup

Pinata is centralized service. For long-term reliability: duplicate critical CIDs to Filecoin via NFT.Storage or web3.storage, or run your own IPFS node with ipfs pin add {cid}.

# Own IPFS node as additional storage
ipfs pin add bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

CID is identical everywhere — if file exists at any one node in network, it's reachable. Two pinning providers = double reliability.