Reservoir NFT Aggregator Integration: API, SDK, Use Cases

Developers building NFT marketplaces or portfolio trackers must integrate with multiple platforms. Each — OpenSea, Blur, X2Y2 — has its own API, order formats, and rate limits. Maintaining N integrations is complex: the codebase grows, debugging time increases, and support costs rise. Reservoir solves this with a single API. Instead of six different APIs, you get one protocol with read and write modes. With over 5 years of experience and more than 20 successful NFT and DeFi projects, we are an expert in Reservoir integration. We ensure correct listing setup, cross-marketplace purchases, and real-time data. Reservoir reduces integration time by 3-4x compared to direct calls to each marketplace API. Contact us to discuss your project. Typical custom integration costs $30,000–$60,000; Reservoir-based integration costs $5,000–$15,000 — a 75% budget saving. Our client marketplace launched an aggregator in 3 weeks instead of 2 months, saving 60% time. Infrastructure savings when switching from a self-hosted node to cloud API amount to $500–$2,000 per month.

What Reservoir Actually Delivers

Two modes: read-only (collection data, prices, activity) and write (order creation, trade execution). Most projects start with read, but the real value lies in write integration.

Read mode covers:

• Floor prices, bid/ask depth
• Ownership data per token
• Sales history, transfers, mints
• Attribute-level statistics (rare trait prices)
• Real-time events via WebSocket (processes 1000+ events/second)

Write mode (via SDK):

• Listings simultaneously on multiple marketplaces
• Cross-marketplace purchases (automatic best price search)
• Collection bids and attribute bids
• Sweep — buying multiple NFTs in one transaction

Integrating 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
await client.actions.buyToken({
  items: [
    {
      token: `${contractAddress}:${tokenId}`,
      quantity: 1,
    },
  ],
  wallet: walletClient,
  onProgress: (steps) => console.log(steps),
});

Supported Marketplaces and Networks

Reservoir works on Ethereum, Polygon, Arbitrum, Optimism, Base, Zora (10+ blockchains total). When creating a listing, specify the orderbook parameter:

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

Step-by-Step SDK Integration in 5 Steps

1. Install the package: npm install @reservoir0x/reservoir-sdk
2. Get an API key from the Reservoir Dashboard
3. Create a client with the key and specify the chain (e.g., Ethereum mainnet)
4. Use read methods: getCollections, getTokens, getSales
5. For write operations, connect a wallet via viem or wagmi and call buyToken or listToken

The Key Advantage of Write Mode

Write mode allows creating cross-marketplace listings, executing purchases, and managing orders through a single SDK. This reduces code by 5x compared to direct calls to each marketplace API. For example, a typical custom integration costs $30,000–$60,000, while Reservoir-based integration costs $5,000–$15,000, saving 75% of the budget. Our practice: a client marketplace launched an aggregator in 3 weeks instead of 2 months, saving 60% time. Infrastructure savings when switching from a self-hosted node to cloud API amount to $500–$2,000 per month. Reservoir SDK is 5x more efficient than managing multiple APIs separately.

Typical Integration Use Cases

• NFT marketplace with aggregation — show listings from all platforms; users buy through our UI. Revenue model: commission on top of Reservoir fee. We use Reservoir SDK + custom smart contract with fee hook.
• Portfolio tracker — use Ownership API to fetch user NFTs with current prices instead of direct calls to individual APIs.
• Rarity + price correlation — combine attribute stats with rarity data to estimate fair token value.
• Automated market making — bots with collection bids based on algorithmic strategies via SDK.

WebSocket for Real-Time Data

import { WebSocket } from "ws";
const ws = new WebSocket("wss://ws.reservoir.tools?api_key=YOUR_KEY");
ws.on("open", () => {
  ws.send(
    JSON.stringify({
      type: "subscribe",
      event: "sale.created",
      filters: { contract: collectionAddress },
    })
  );
});
ws.on("message", (data) => {
  const event = JSON.parse(data.toString());
  handleRealtimeEvent(event);
});

API Key Configuration and Rate Limits

The free tier provides 50 requests/second — enough for startup. Production loads require a paid plan. Write operations need an API key with appropriate permissions; the account must be verified. Reservoir documentation recommends paid plans for high-traffic projects.

Self-hosted node: Reservoir is open-source; you can deploy your own instance for full control and unlimited requests. Requires syncing via an Ethereum node (Erigon recommended). This is relevant for high-load projects.

What's Included in the Work

We'll assess your project — contact us for a consultation. Order turnkey integration and get quality assurance.