Уявіть: ви випускаєте колекцію з 10 000 NFT. Метадані — JSON із зображеннями — лежать на сервері, але при піку трафіку сайт падає, IPFS-шлюзи перевантажені. Ви переходите на IPFS, але без піннінгу файли зникають. Pinata — managed pinning service, який гарантує доступність. Однак інтеграція потребує розуміння API, керування CID та резервування. Ми підключаємо Pinata за 2-3 дні, забезпечуючи uptime 99.9% для ваших метаданих.
IPFS використовує контентну адресацію: хеш файлу — його адреса. Але якщо жоден вузол не зберігає файл, він недоступний. Pinata вирішує цю проблему, підтримуючи файли на своїх серверах і надаючи API для завантаження, керування та видалення. Ми реалізували понад 20 таких інтеграцій для NFT-проектів, DeFi-додатків та децентралізованих сховищ, обробляючи до 100 000 файлів на проект.
Референс: IPFS — протокол, що лежить в основі.
Основні проблеми, які вирішує інтеграція
Доступність метаданих — ключова проблема. Без піннінгу NFT-метадані можуть зникнути, що порушує стандарти ERC-721/1155. Pinata гарантує uptime 99.9% для запіннених файлів. Швидкість завантаження через dedicated gateway у 3-5 разів вища за публічний gateway.pinata.cloud. Керування колекціями: за допомогою pinataMetadata.keyvalues легко знаходити файли за проектом або типом — це спрощує обслуговування кількох колекцій одночасно.
Як завантажувати файли на IPFS через Pinata?
Завантаження файлів через Pinata API
const PINATA_JWT = process.env.PINATA_JWT!; // из dashboard.pinata.cloud // Загрузка файла 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 хеш } // Загрузка JSON (для 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
Стандартний ERC-721/ERC-1155 workflow:
// 1. Загружаем изображение const imageCid = await uploadFile(imageBuffer, 'nft-image.png'); // 2. Формируем metadata по ERC-721 Metadata Standard const metadata = { name: 'My NFT #1', description: 'Description here', image: `ipfs://${imageCid}`, // ipfs:// URI, не https:// attributes: [ { trait_type: 'Background', value: 'Blue' }, { trait_type: 'Rarity', value: 'Rare' }, ], }; // 3. Загружаем metadata const metadataCid = await uploadJson(metadata, 'nft-1-metadata.json'); // 4. tokenURI = ipfs://{metadataCid} // В контракте: tokenURI(tokenId) возвращает ipfs://{metadataCid} Використовуйте ipfs:// URI в контракті, не https://gateway.pinata.cloud/ipfs/. Gateway може змінюватися або бути недоступним — ipfs:// URI працює з будь-яким gateway.
Чому варто використовувати dedicated gateway?
Dedicated gateway (платна опція) значно швидший за публічний: він використовує кешування та білі списки. Для NFT маркетплейсів, де користувачі завантажують зображення, це критично — знижує навантаження та прискорює відображення. Офіційна документація Pinata рекомендує dedicated gateway для production-проектів.
Як тегувати файли для керування?
При завантаженні передавайте pinataMetadata.keyvalues. Наприклад: { project: 'my-nft-collection', type: 'image' }. Потім через API pinList можна фільтрувати за цими ключами. Це зручно при роботі з кількома проектами. Ми використовуємо такий підхід для проектів з десятками тисяч файлів — мітки дозволяють швидко знайти та оновити потрібні елементи.
| Метод | Тип даних | Швидкість | Приклад використання |
|---|---|---|---|
| pinFileToIPFS | Бінарні файли (зображення, відео) | Середня | Завантаження NFT-зображень |
| pinJSONToIPFS | JSON-об'єкти | Висока | Метадані NFT |
| pinByHash | Існуючий CID | Миттєво | Перенесення даних з інших сервісів |
Чому важливо дублювати CID?
Pinata — централізований сервіс. Для довготривалої надійності дублюйте критичні CID у Filecoin через NFT.Storage або web3.storage, або тримайте власну IPFS ноду з ipfs pin add {cid}.
# Власна IPFS нода як додаткове сховище ipfs pin add bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi CID однаковий скрізь — якщо файл є хоча б у однієї ноди в мережі, він досяжний. Два pinning-провайдери = подвійна надійність. Ми рекомендуємо таку схему для проектів з високими вимогами до доступності.
| Провайдер | Тип | Доступність | Особливості |
|---|---|---|---|
| Pinata | Managed pinning service | Висока | Швидкий dedicated gateway, API, груповий пін |
| NFT.Storage | Filecoin | Децентралізована | Безкоштовно (обмеження за об'ємом) |
| Власна нода | IPFS node | Повний контроль | Потребує адміністрування |
Процес роботи
- Аналіз вимог: визначаємо об'єм файлів, структуру метаданих, необхідні функції (груповий пін, резервування).
- Проектування: обираємо тариф Pinata, налаштовуємо JWT та dedicated gateway.
- Інтеграція API: пишемо скрипти завантаження, пакетної обробки, керування ключами.
- Тестування: симулюємо завантаження 100+ файлів, перевіряємо доступність та швидкість.
- Деплой та документація: передаємо код, навчаємо команду.
Строки: від 2 до 5 робочих днів залежно від складності. Вартість розраховується індивідуально. Отримайте консультацію — оцінимо об'єм вашого проекту.
Що входить у роботу
- Налаштування Pinata JWT та dedicated gateway
- Інтеграція API завантаження файлів (pinFileToIPFS, pinJSONToIPFS)
- Скрипти для пакетного завантаження та керування метаданими
- Реалізація ERC-721/1155 з ipfs:// URI
- Документація коду, навчання команди по роботі з Pinata
- Гарантія підтримки протягом місяця після здачі
Замовте інтеграцію під ключ з резервуванням — ми допоможемо обрати оптимальну схему піннінгу.
Pinata SDK (v2)
import { PinataSDK } from 'pinata'; const pinata = new PinataSDK({ pinataJwt: process.env.PINATA_JWT!, pinataGateway: process.env.PINATA_GATEWAY!, // yourname.mypinata.cloud }); // Загрузка из URL const upload = await pinata.upload.url('https://example.com/image.png'); console.log(upload.cid); // Получение файла через dedicated gateway const url = await pinata.gateways.convert(`ipfs://${cid}`); // → https://yourname.mypinata.cloud/ipfs/{cid} Dedicated gateway (платна опція) значно швидший за публічний gateway.pinata.cloud — важливо для NFT маркетплейсів, де зображення завантажуються користувачами.
Груповий пін та керування колекціями
// Список запіннених файлів з фільтрацією 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(); } // Анпін файлу (звільняє сховище) async function unpinFile(cid: string) { await fetch(`https://api.pinata.cloud/pinning/unpin/${cid}`, { method: 'DELETE', headers: { Authorization: `Bearer ${PINATA_JWT}` }, }); } Використовуйте pinataMetadata.keyvalues для тегування файлів за проектом або колекцією — потім зручно фільтрувати та керувати зберіганням.
Локальне резервування
Для довготривалої надійності дублюйте критичні CID в інші сервіси. Це гарантує доступність навіть при недоступності Pinata. Замовте інтеграцію під ключ з резервуванням — забезпечте збереження ваших даних.