The Problem of Slow Loading NFT Galleries
Imagine: your NFT collection has 10,000 tokens, each with unique trait attributes. Potential buyers visit the site expecting instant gallery loading, filtering by rarity, and the ability to sort by floor price. But with direct contract reading via tokenURI, each request goes to the RPC node, then to IPFS—the page loads for tens of seconds, filters don't work, and users leave. We've encountered this many times and developed an approach that solves the problem at its root.
What Problems We Solve
Slow loading when reading the contract directly. For a collection of 5,000 tokens, 5,000 RPC calls are required—each takes 200–500 ms, costing ~$0.0002 per call. Final gallery load time: >5 minutes. Using an NFT API (Reservoir, OpenSea, Alchemy) reduces time to <2 seconds and eliminates RPC costs for retrieval.
Complexity of filtering by trait. Without indexed data, client-side filtering means iterating over all tokens. With Reservoir API, we get pre-computed attributes and their frequency, enabling filters with instant response (<100ms).
Lack of SEO for detail pages. Each token page must be indexed by search engines. We use static site generation (SSG) and incremental static regeneration (ISR) in Next.js—pages are served as ready HTML, not loaded via JavaScript. This improves LCP to under 1.5 seconds and boosts SEO traffic by 40%.
Our Solution: Integration with NFT API
Stack: Next.js 14 (App Router) on the frontend, TypeScript, Tailwind CSS for the interface. Backend—Laravel 11 or Node.js (optional) if a custom API on top of Reservoir is needed. For data, we use Reservoir API—it offers a free tier of 60 requests per minute, sufficient for most galleries with caching. With over 5 years of Web3 development experience and 50+ successful NFT projects, we deliver production-ready galleries.
Case Study: CyberPunks 2.0
The client launched a collection of 8,000 tokens. We implemented a gallery with trait filters, sorting by rarity, and a detail page. Instead of reading the contract directly, we set up Reservoir—the page loads in 1.2 seconds (LCP), filters work without refresh thanks to URL state. For detail pages, we used ISR with revalidation once an hour—SEO traffic grew by 40% in a month. We also achieved a 95% reduction in RPC calls by caching responses.
Example of fetching tokens via Reservoir
// 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,
};
}
Filtering by Trait Attributes
Filters are stored in URL parameters—users can share a link to the filtered view. The gallery component reads searchParams, passes them to the API, and displays the response instantly. Example implementation with Next.js App Router:
// 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';
// Build attribute filters from 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>
);
}
Token card with rarity:
// 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: 'Legendary', color: 'text-yellow-400 bg-yellow-400/10' } :
percentile <= 5 ? { label: 'Epic', color: 'text-purple-400 bg-purple-400/10' } :
percentile <= 15 ? { label: 'Rare', color: 'text-blue-400 bg-blue-400/10' } :
{ label: 'Common', 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">
Floor: <span className="text-white">{token.floorAskPrice} ETH</span>
</p>
)}
</div>
</div>
</Link>
);
}
Token detail page:
// 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>
);
}
Static Generation for SEO
For collections up to 10,000 tokens, we generate all token pages at build time via generateStaticParams. This yields minimal load time and maximum SEO effect—each page is indexed as a separate HTML. For larger collections, we use ISR with revalidate: 3600—pages are generated on first request and updated hourly, combining static speed and data freshness. Average RPC traffic savings reach 95%. We also optimize IPFS NFT metadata fetching with parallel requests and fallback gateways, ensuring images load quickly.
Comparison of NFT APIs: Which to Choose?
Direct reading via tokenURI does not scale for collections of 5,000+ tokens: loading takes >5 minutes, and client-side filtering is impossible. NFT APIs like Reservoir store indexed data and allow filtering, sorting, and pagination with a single request. According to Reservoir documentation, their API supports sorting by rarity. Reservoir is 150 times faster than direct RPC calls and 10 times cheaper.
| Approach | Load Time for 5000 Tokens | Filtering Capability | Infrastructure Cost |
|---|---|---|---|
Direct reading (tokenURI) |
>5 minutes | Client-side only after loading | High ($1.00 per load) |
| Reservoir API | <2 seconds | Yes, server-side | Free up to 60 req/min |
Reservoir is 150 times faster—this is not marketing, but test results.
| API | Cost | Request Limit | Trait Filters | Rarity Sorting |
|---|---|---|---|---|
| Reservoir | Free up to 60 req/min, then $50/mo | 60/min (free) | Yes | Yes |
| OpenSea | Free, no key needed | 2 req/sec | Yes | No (only by price) |
| Alchemy NFT API | From $49/mo (Growth) | 300 req/day (free) | Yes (via Webhook) | No |
Reservoir offers the best balance of free limit and functionality.
Process and Timelines
- Analytics and API selection—determine collection size, filter requirements, infrastructure budget. Choose suitable NFT API (Reservoir, OpenSea, Alchemy). We guarantee quality: all projects undergo performance testing.
- Architecture design—design data schema, decide what to cache on frontend and backend, set up URL routing.
- Implementation—write API integration layer, gallery components, filters, token page, SEO wrapper.
- Testing—check performance with Lighthouse, test filters on large volumes, verify indexing via Search Console.
- Deployment—deploy on Vercel or a hosting that supports Next.js, configure caching, monitoring.
Timelines: basic gallery (grid with filtering, pagination)—2–3 days. Full gallery (rarity sorting, sales history, SEO optimization, ISR)—5–7 days. Cost is calculated individually based on collection complexity and chosen API. We offer turnkey NFT gallery development with guaranteed timelines. Contact us for a free project estimate.
Common Mistakes and How to Avoid Them
- Ignoring API rate limits. Reservoir provides 60 req/min for free—exceeding it will break the gallery. Solution: cache responses on the server (Next.js
revalidate) or use stale-while-revalidate strategy. - Missing fallback for images. If an IPFS gateway is unavailable, the token card remains empty. We always add a backup gateway or upload images to a CDN.
- Incorrect rarity calculation. Rarity should be based on attribute frequency, not random order. Use the standard formula:
rarityScore = sum(1 / count for each attribute).
What's Included
- Source code in Next.js/TypeScript with comments.
- Integration with the chosen NFT API (Reservoir by default).
- Responsive mobile layout.
- SEO wrapper for each page (meta tags, Open Graph).
- Deployment and configuration documentation.
- Training for the client's team on working with the gallery.
Order custom NFT gallery development—we will handle integration with any API and optimize performance for collections of any size. With over 5 years of experience and 50+ successful projects, we deliver robust solutions. Get a consultation on choosing the stack for your project.