Пользователь хочет показать свои NFT на сайте, но прямое чтение из блокчейна — это медленно и больно. ERC-721 не имеет метода tokensOfOwner, приходится перебирать события или полагаться на ERC721Enumerable, который есть не у всех. Мы используем специализированные NFT API, которые индексируют события и возвращают готовые списки. Например, для коллекции BAYC вы получаете все токены по адресу владельца за один запрос, без перебора миллионов событий. Но есть подводные камни: IPFS-шлюзы, медленная загрузка, обработка ошибок. Наша реализация учитывает всё это.
Почему не читать NFT напрямую из контракта?
ERC-721 контракт хранит ownerOf(tokenId) и tokenURI(tokenId), но не предоставляет обратный маппинг. Без ERC721Enumerable найти все токены пользователя через RPC — значит перебрать все события Transfer за всю историю, или держать собственную базу. NFT API (Alchemy, Moralis, OpenSea) делают индексацию за нас — это быстрее и надёжнее. Альтернативный подход с собственным индексером потребует инфраструктуры и времени на разработку, что неоправданно для большинства проектов.
Как получать NFT через Alchemy API?
Мы используем alchemy.nft.getNftsForOwner с конфигурацией SDK.
// lib/nft.ts import { Alchemy, Network, OwnedNft } from 'alchemy-sdk'; const alchemy = new Alchemy({ apiKey: process.env.ALCHEMY_API_KEY, network: Network.ETH_MAINNET, }); export interface NftItem { tokenId: string; contractAddress: string; name: string; description: string; imageUrl: string; collectionName: string; attributes: Array<{ trait_type: string; value: string | number }>; } export async function getWalletNfts( ownerAddress: string, opts?: { contractAddresses?: string[]; pageSize?: number }, ): Promise<NftItem[]> { const response = await alchemy.nft.getNftsForOwner(ownerAddress, { contractAddresses: opts?.contractAddresses, pageSize: opts?.pageSize ?? 100, omitMetadata: false, }); return response.ownedNfts.map(mapNft); } function mapNft(nft: OwnedNft): NftItem { const imageUrl = resolveIpfsUrl( nft.image?.cachedUrl ?? nft.image?.originalUrl ?? '', ); return { tokenId: nft.tokenId, contractAddress: nft.contract.address, name: nft.name ?? `#${nft.tokenId}`, description: nft.description ?? '', imageUrl, collectionName: nft.contract.name ?? 'Unknown Collection', attributes: (nft.raw?.metadata?.attributes ?? []) as NftItem['attributes'], }; } function resolveIpfsUrl(url: string): string { if (url.startsWith('ipfs://')) { return url.replace('ipfs://', 'https://cloudflare-ipfs.com/ipfs/'); } return url; } Пример ответа Alchemy API (сокращён)
{ "ownedNfts": [ { "contract": { "address": "0x..." }, "tokenId": "1", "tokenType": "ERC721", "title": "My NFT", "description": "...", "metadata": { "image": "ipfs://..." } } ], "pageKey": "...", "totalCount": 42 } Alchemy NFT API Documentation
Для реального времени можно подключить WebSocket-уведомления о новых токенах, что полезно для динамических коллекций.
Компонент галереи и карточки
Компонент галереи
Используем React Query для загрузки и кэширования данных.
// components/NftGallery.tsx import { useQuery } from '@tanstack/react-query'; import { getWalletNfts, NftItem } from '@/lib/nft'; interface NftGalleryProps { address: string; contractFilter?: string[]; } export function NftGallery({ address, contractFilter }: NftGalleryProps) { const { data, isLoading, error } = useQuery({ queryKey: ['nfts', address, contractFilter], queryFn: () => getWalletNfts(address, { contractAddresses: contractFilter }), staleTime: 60_000, // NFT меняются редко — кэшируем на минуту enabled: !!address, }); if (isLoading) return <NftGridSkeleton count={12} />; if (error) return <ErrorState message="Не удалось загрузить NFT" />; if (!data?.length) return <EmptyState />; return ( <div className="grid grid-cols-2 gap-4 sm:grid-cols-3 lg:grid-cols-4"> {data.map(nft => ( <NftCard key={`${nft.contractAddress}-${nft.tokenId}`} nft={nft} /> ))} </div> ); } Карточка и детальный просмотр
// components/NftCard.tsx import { useState } from 'react'; import { NftItem } from '@/lib/nft'; export function NftCard({ nft }: { nft: NftItem }) { const [imgError, setImgError] = useState(false); return ( <div className="group relative overflow-hidden rounded-xl border border-white/10 bg-neutral-900"> <div className="aspect-square overflow-hidden bg-neutral-800"> {imgError ? ( <div className="flex h-full items-center justify-center text-neutral-500"> <ImageIcon className="h-12 w-12" /> </div> ) : ( <img src={nft.imageUrl} alt={nft.name} loading="lazy" decoding="async" className="h-full w-full object-cover transition-transform group-hover:scale-105" onError={() => setImgError(true)} /> )} </div> <div className="p-3"> <p className="truncate text-xs text-neutral-400">{nft.collectionName}</p> <p className="mt-0.5 truncate font-medium text-white">{nft.name}</p> </div> </div> ); } // components/NftDetail.tsx export function NftDetail({ nft }: { nft: NftItem }) { return ( <div className="space-y-6"> <img src={nft.imageUrl} alt={nft.name} className="w-full rounded-2xl" /> <div> <h2 className="text-2xl font-bold">{nft.name}</h2> <p className="mt-1 text-sm text-neutral-400"> {nft.collectionName} · #{nft.tokenId} </p> </div> {nft.description && ( <p className="text-sm leading-relaxed text-neutral-300">{nft.description}</p> )} {nft.attributes.length > 0 && ( <div> <h3 className="mb-3 text-sm font-semibold uppercase tracking-wider text-neutral-500"> Атрибуты </h3> <div className="grid grid-cols-3 gap-2"> {nft.attributes.map((attr, i) => ( <div key={i} className="rounded-lg border border-blue-500/20 bg-blue-500/5 p-2 text-center"> <p className="text-xs text-blue-400">{attr.trait_type}</p> <p className="mt-0.5 text-sm font-medium">{attr.value}</p> </div> ))} </div> </div> )} </div> ); } Такая структура позволяет легко встраивать компоненты в любой React-проект.
Поддержка ERC-1155 и пагинация
Для ERC-1155 токенов Alchemy возвращает balance. Мы проверяем tokenType и добавляем поле quantity. Для больших коллекций реализуем пагинацию через pageKey.
// utils/nft-extras.ts export function filterErc1155WithBalance( nfts: OwnedNft[], mapNft: (nft: OwnedNft) => NftItem, ) { return nfts .filter(nft => nft.tokenType === 'ERC1155') .map(nft => ({ ...mapNft(nft), quantity: nft.balance, })); } export async function getAllWalletNfts( ownerAddress: string, ): Promise<NftItem[]> { const all: NftItem[] = []; let pageKey: string | undefined; do { const response = await alchemy.nft.getNftsForOwner(ownerAddress, { pageKey, pageSize: 100, }); all.push(...response.ownedNfts.map(mapNft)); pageKey = response.pageKey; } while (pageKey); return all; } Сравнение решений
Сравнение NFT API
| Критерий | Alchemy | Moralis | OpenSea |
|---|---|---|---|
| Мультичейн | Ethereum, Polygon, Optimism, Arbitrum | 20+ сетей | Ethereum, Polygon, Klaytn |
| Бесплатный лимит | 100k/мес | 40k/мес | 10k/мес |
| Тип токенов | ERC-721, ERC-1155 | ERC-721, ERC-1155 | ERC-721, ERC-1155 |
| Метаданные | Автоматически | Частично | Требуется own |
| Пагинация | pageKey | cursor | next |
RPC vs NFT API
| Аспект | Чтение через RPC | NFT API |
|---|---|---|
| Скорость | Медленно (перебор событий) | Быстро (индексированные данные) |
| Простота | Сложно (нужна свою база) | Просто (один endpoint) |
| Поддержка ERC-1155 | Нужно обрабатывать отдельно | Встроена |
| IPFS изображения | Нужно кешировать | Автоматически проксируются |
Этапы работы
- Анализ — определяем, какие сети и контракты нужны, согласовываем API.
- Интеграция — подключаем SDK, реализуем загрузку и отображение.
- Оптимизация — lazy-загрузка, кэширование, обработка ошибок.
- Тестирование — проверяем на реальных кошельках с большими коллекциями.
- Деплой — разворачиваем на продакшн, настраиваем мониторинг.
Что входит в работу
- Документация по интеграции и настройке API-ключей.
- Исходный код компонентов на React/TypeScript.
- Инструкция по деплою и обновлению.
- Тестовый доступ к работающему прототипу.
- Поддержка в течение 2 недель после сдачи.
Сроки и стоимость
Базовая галерея с Alchemy API, lazy-загрузкой и детальным просмотром — 1–2 дня. Расширенная версия с фильтрацией по коллекциям, пагинацией, поддержкой ERC-1155 и мультичейн — 3–4 дня. Стоимость рассчитывается индивидуально в зависимости от сложности и стека. Для примера: при самостоятельной разработке инфраструктура и время могут стоить более $5000, наше решение обходится в разы дешевле. Свяжитесь с нами для оценки вашего проекта — мы подберём оптимальное решение.
Частые ошибки при интеграции
-
Необработанный IPFS — изображения не загружаются, если не использовать шлюз. Всегда заменяйте
ipfs://наhttps://cloudflare-ipfs.com/ipfs/. - Игнорирование balance у ERC-1155 — может привести к некорректному отображению количества. Всегда проверяйте
tokenType. - Слишком короткий staleTime — NFT меняются редко, кэширование на 1–5 минут существенно снижает нагрузку на API.
- Отсутствие fallback для изображений — при ошибке загрузки показывайте заглушку, иначе пользователь видит битую иконку.
Для добавления поиска по NFT и фильтрации по коллекциям мы интегрируем стейт на фронтенде или используем серверный поиск через API Alchemy. Это позволяет быстро находить нужные токены и сортировать по коллекциям.
Гарантируем совместимость с ведущими коллекциями и многолетний опыт интеграции NFT API. Мы разрабатываем с 2018 года и реализовали более 10 проектов с NFT-отображением для маркетплейсов и крипто-портфолио. Получите консультацию — закажите интеграцию под ваш проект. Использование Alchemy API позволяет сэкономить до $1000 в месяц на серверах и индексации.