Реалізація відображення NFT-колекції користувача на сайті

Реалізація відображення NFT-коллекції користувача на сайті

Показати NFT користувача — не те саме, що показати список ERC-20 токенів. NFT — це метадані на IPFS, зображення в IPFS або Arweave, JSON-схема OpenSea Metadata Standard та ще ERC-721 vs ERC-1155. Вирішувати самостійно через виклики on-chain — повільно та болісно. Використовувати спеціалізований NFT API — правильний підхід.

Чому не читати NFT безпосередньо з контракту

Контракт ERC-721 не зберігає список токенів за адресою. Є ownerOf(tokenId) та tokenURI(tokenId), але немає tokensOfOwner(address). Щоб знайти всі NFT користувача через RPC, потрібно або перебирати события Transfer за всю історію блокчейну, або використовувати ERC721Enumerable — розширення, яке має далеко не всі коллекції.

NFT API (Alchemy, Moralis, OpenSea, QuickNode) індексує события Transfer та надає готовий endpoint.

Отримання NFT через Alchemy NFT API

// 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;
}

Компонент галереї

// 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>
  );
}

Картка NFT з ледачим завантаженням зображень

// 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>
  );
}

Підтримка ERC-1155

Токени ERC-1155 — напіврлидерні: один tokenId може належати кільком адресам із різною кількістю. Alchemy API повертає balance для таких токенів:

// Для ERC-1155 перевіряємо кількість
const nft1155Items = response.ownedNfts.filter(
  nft => nft.tokenType === 'ERC1155',
).map(nft => ({
  ...mapNft(nft),
  quantity: nft.balance, // "5" — власник тримає 5 копій
}));

Пагінація для великих колекцій

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;
}

Часова шкала: базова галерея з Alchemy API, ледачим завантаженням та детальним переглядом — 1–2 дні. Розширена версія з фільтрацією за колекціями, пагінацією, підтримкою ERC-1155 та мультичейну — 3–4 дні.