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.