Представьте: вы выпускаете коллекцию из 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. Закажите интеграцию под ключ с резервированием — обеспечьте сохранность ваших данных.