Реалізація NFT-галереї на сайті

Реалізація NFT-галереї на веб-сайті

NFT-галерея — сторінка або секція сайту, яка показує токени коллекції: сітка карточок, фільтрація за trait-атрибутами, сортування за рідкістю, детальна сторінка токена з історією. Це не те саме, що галерея гаманця користувача — тут відображається контент коллекції цілком, зазвичай доступний без підключення гаманця.

Джерело даних

Два підходи: читати метадані напрямо з контракту через tokenURI або використовувати NFT API.

Прямо читання через tokenURI — повільно для колекцій 5000+ токенів. На кожен токен — один RPC-запит, потім запит до IPFS за JSON. Для галереї з фільтрацією за trait це неприйнятно.

OpenSea API, Alchemy NFT API та Reservoir API індексують метадані й надають їх з фільтрацією. Reservoir — найкращий вибір для галереї без платежу: безплатний рівень 60 запитів/хв, підтримка trait-фільтрів та редкості.

Завантаження коллекції через Reservoir API

// lib/collection.ts
const RESERVOIR_BASE = 'https://api.reservoir.tools';

export interface CollectionToken {
  tokenId: string;
  name: string;
  image: string;
  rarityScore: number;
  rarityRank: number;
  attributes: Array<{ key: string; value: string; tokenCount: number }>;
  lastSalePrice: string | null;
  floorAskPrice: string | null;
}

export async function getCollectionTokens(
  contractAddress: string,
  opts: {
    limit?: number;
    offset?: number;
    sortBy?: 'floorAskPrice' | 'rarity' | 'tokenId';
    attributes?: Record<string, string>;
  } = {},
): Promise<{ tokens: CollectionToken[]; total: number }> {
  const params = new URLSearchParams({
    collection: contractAddress,
    limit: String(opts.limit ?? 20),
    offset: String(opts.offset ?? 0),
    sortBy: opts.sortBy ?? 'tokenId',
    includeAttributes: 'true',
    includeLastSale: 'true',
  });

  if (opts.attributes) {
    for (const [key, value] of Object.entries(opts.attributes)) {
      params.append('attributes[' + key + ']', value);
    }
  }

  const res = await fetch(`${RESERVOIR_BASE}/tokens/v7?${params}`, {
    headers: { 'x-api-key': process.env.RESERVOIR_API_KEY ?? '' },
    next: { revalidate: 60 },
  });

  const data = await res.json();

  return {
    tokens: data.tokens.map(mapToken),
    total: data.totalTokens ?? 0,
  };
}

Фільтри за атрибутами

// Отримати всі trait-типи та значення коллекції
export async function getCollectionAttributes(contractAddress: string) {
  const res = await fetch(
    `${RESERVOIR_BASE}/collections/${contractAddress}/attributes/all/v4`,
    { headers: { 'x-api-key': process.env.RESERVOIR_API_KEY ?? '' } },
  );
  const data = await res.json();

  // Структура: { attributes: [{ key, kind, values: [{ value, count }] }] }
  return data.attributes as Array<{
    key: string;
    kind: 'string' | 'number' | 'range';
    values: Array<{ value: string; count: number }>;
  }>;
}

Компонент галереї з URL-фільтрами

Фільтри зберігаються в URL — користувач може поділитись посиланням на відфільтрований вигляд:

// app/gallery/page.tsx (Next.js App Router)
import { useSearchParams, useRouter } from 'next/navigation';
import { getCollectionTokens, getCollectionAttributes } from '@/lib/collection';

const CONTRACT = process.env.NEXT_PUBLIC_CONTRACT_ADDRESS!;

export default async function GalleryPage({
  searchParams,
}: {
  searchParams: Record<string, string>;
}) {
  const page = parseInt(searchParams.page ?? '1');
  const sortBy = (searchParams.sort ?? 'tokenId') as 'floorAskPrice' | 'rarity' | 'tokenId';

  // Збираємо attribute-фільтри з search params
  const attributes: Record<string, string> = {};
  for (const [key, value] of Object.entries(searchParams)) {
    if (!['page', 'sort'].includes(key)) {
      attributes[key] = value;
    }
  }

  const [{ tokens, total }, attrs] = await Promise.all([
    getCollectionTokens(CONTRACT, {
      limit: 24,
      offset: (page - 1) * 24,
      sortBy,
      attributes: Object.keys(attributes).length ? attributes : undefined,
    }),
    getCollectionAttributes(CONTRACT),
  ]);

  return (
    <div className="flex gap-8">
      <TraitFilters attributes={attrs} activeFilters={attributes} />
      <div className="flex-1">
        <SortControl currentSort={sortBy} />
        <TokenGrid tokens={tokens} />
        <Pagination total={total} page={page} perPage={24} />
      </div>
    </div>
  );
}

Карточка токена з редкістю

// components/TokenCard.tsx
import Link from 'next/link';
import { CollectionToken } from '@/lib/collection';

function RarityBadge({ rank, total }: { rank: number; total: number }) {
  const percentile = (rank / total) * 100;
  const tier =
    percentile <= 1 ? { label: 'Легендарний', color: 'text-yellow-400 bg-yellow-400/10' } :
    percentile <= 5 ? { label: 'Епічний', color: 'text-purple-400 bg-purple-400/10' } :
    percentile <= 15 ? { label: 'Рідкісний', color: 'text-blue-400 bg-blue-400/10' } :
    { label: 'Звичайний', color: 'text-neutral-400 bg-neutral-400/10' };

  return (
    <span className={`rounded-md px-2 py-0.5 text-xs font-medium ${tier.color}`}>
      #{rank} · {tier.label}
    </span>
  );
}

export function TokenCard({ token, totalSupply }: { token: CollectionToken; totalSupply: number }) {
  return (
    <Link href={`/gallery/${token.tokenId}`} className="group block">
      <div className="overflow-hidden rounded-xl border border-white/5 bg-neutral-900 transition hover:border-white/20">
        <div className="relative aspect-square overflow-hidden bg-neutral-800">
          <img
            src={token.image}
            alt={token.name}
            loading="lazy"
            className="h-full w-full object-cover transition-transform group-hover:scale-105"
          />
        </div>
        <div className="p-3 space-y-2">
          <div className="flex items-start justify-between gap-2">
            <span className="font-medium truncate">{token.name}</span>
            <RarityBadge rank={token.rarityRank} total={totalSupply} />
          </div>
          {token.floorAskPrice && (
            <p className="text-sm text-neutral-400">
              Мінімум: <span className="text-white">{token.floorAskPrice} ETH</span>
            </p>
          )}
        </div>
      </div>
    </Link>
  );
}

Детальна сторінка токена

// app/gallery/[tokenId]/page.tsx
export default async function TokenPage({ params }: { params: { tokenId: string } }) {
  const token = await getToken(CONTRACT, params.tokenId);

  return (
    <div className="grid grid-cols-1 gap-12 lg:grid-cols-2">
      <TokenImage src={token.image} name={token.name} />
      <div className="space-y-6">
        <TokenHeader token={token} />
        <AttributeGrid attributes={token.attributes} />
        <TradeActions token={token} />
        <SaleHistory contractAddress={CONTRACT} tokenId={params.tokenId} />
      </div>
    </div>
  );
}

SEO та статична генерація

Для колекцій до 10000 токенів — статична генерація generateStaticParams у Next.js. Для більших колекцій — ISR з revalidate: 3600.

Часова шкала: сітка з базовими фільтрами та детальною сторінкою — 2–3 дні. Повна галерея з сортуванням за редкістю, багаторівневими фільтрами, історією продаж та SEO-оптимізацією — 5–7 днів.