Користувач хоче показати свої 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 на місяць на серверах та індексації.