Reservoir NFT Aggregator Integration

Reservoir NFT Aggregator Integration

Reservoir is not just an API for getting NFT data. It's a protocol with its own order books that aggregates liquidity from OpenSea, Blur, X2Y2, LooksRare, Coinbase NFT and allows placing cross-marketplace listings through a single interface. If you're building an NFT project and don't want to integrate 6 marketplaces separately — Reservoir solves the problem.

What Reservoir Really Provides

Two usage modes: read-only (data about collections, prices, activity) and write (creating orders, executing trades). Most projects start with read, but true value — in write integration.

Read API covers:

• Floor prices, bid/ask depth by collection
• Ownership data (who owns each token)
• Sales history, transfers, mints
• Attribute-level stats (rare trait prices)
• Real-time events via WebSocket

Write (via SDK):

• List tokens simultaneously on multiple marketplaces
• Cross-marketplace fills (buy token wherever it's listed)
• Collection bids, attribute bids
• Sweep (buy multiple NFTs in one transaction)

Quick Start with Reservoir SDK

import { createClient } from "@reservoir0x/reservoir-sdk";
import { createWalletClient, http } from "viem";
import { mainnet } from "viem/chains";

const client = createClient({
  chains: [{ id: 1, baseApiUrl: "https://api.reservoir.tools", active: true }],
  apiKey: process.env.RESERVOIR_API_KEY,
});

// Get collection floor price
const { data } = await fetch(
  `https://api.reservoir.tools/collections/v7?id=${collectionAddress}`,
  { headers: { "x-api-key": process.env.RESERVOIR_API_KEY } }
).then(r => r.json());

const floorPrice = data.collections[0].floorAsk.price.amount.native;

// Execute purchase via SDK (finds best market automatically)
await client.actions.buyToken({
  items: [{ token: `${contractAddress}:${tokenId}`, quantity: 1 }],
  wallet: walletClient,
  onProgress: (steps) => console.log(steps),
});

API Keys Setup and Rate Limits

Free tier provides 50 requests/second — enough for most projects at start. Production loads require paid plan. Important note: for write operations (placing orders) you need API key with appropriate permissions, and Reservoir should verify the account.

Self-hosted node — Reservoir is open-source protocol, you can deploy your own node for full control and unlimited requests. Requires syncing with on-chain data via Ethereum node (Erigon recommended for performance). Relevant for high-load projects.

WebSocket for Real-Time Data

import { WebSocket } from "ws";

const ws = new WebSocket("wss://ws.reservoir.tools?api_key=YOUR_KEY");

ws.on("open", () => {
  // Subscribe to sales of specific collection
  ws.send(JSON.stringify({
    type: "subscribe",
    event: "sale.created",
    filters: { contract: collectionAddress }
  }));
});

ws.on("message", (data) => {
  const event = JSON.parse(data.toString());
  // sale.created, token.floor-ask.changed, collection.floor-ask.changed
  handleRealtimeEvent(event);
});

Typical Integration Use Cases

NFT marketplace with aggregation — show listings from all platforms, user buys via our UI. Revenue model: protocol fee on top of Reservoir fee. Technically: Reservoir SDK + custom smart contract with fee hook.

Portfolio tracker — use Reservoir Ownership API to get user's NFTs with current prices. Significantly simpler than direct calls to OpenSea/Blur APIs separately.

Rarity + price correlation — combine Reservoir attribute stats with rarity data (from Rarity.tools or own calculation) to estimate fair value of specific token.

Automated market making — bots placing collection bids by algorithmic strategies. Reservoir SDK simplifies order management.

Integration with Specific Marketplaces

Reservoir supports different marketplace protocols via orderbook parameter. When creating a listing specify where order goes:

await client.actions.listToken({
  listings: [{
    token: `${contract}:${tokenId}`,
    weiPrice: parseEther("0.5").toString(),
    orderbook: "reservoir", // or "opensea", "blur", "looks-rare"
    orderKind: "seaport-v1.5",
    expirationTime: Math.floor(Date.now() / 1000) + 86400 * 7,
  }],
  wallet: walletClient,
});

Blur requires separate authentication via their API — Reservoir abstracts this, but auth token still needs to be obtained once.

Multi-Chain

Reservoir supports Ethereum, Polygon, Arbitrum, Optimism, Base, Zora and others. Configure multiple chain endpoints in SDK client and switch by chainId from wallet provider.