Інтеграція з Reservoir NFT-агрегатором: API, SDK, кейси

При створенні NFT-маркетплейсу або портфельного трекера розробники стикаються з необхідністю інтеграції з кількома маркетплейсами. Кожен з них — OpenSea, Blur, X2Y2 — має свій API, свої формати ордерів і rate limits. Підтримувати N інтеграцій складно: зростає кодова база, час на дебаг, витрати на підтримку. Reservoir — провідний NFT агрегатор, що об'єднує ліквідність з 6+ маркетплейсів, та вирішує цю проблему єдиним API. Замість шести різних API — один протокол з read і write-режимами. Досвід нашої команди — 5+ років у Web3, понад 20 проєктів з інтеграції DeFi та NFT. Ми гарантуємо коректне налаштування лістингів, cross-marketplace покупок і real-time даних. Reservoir скорочує час інтеграції в 3-4 рази порівняно з прямими викликами до API кожного маркетплейсу. Вартість типової інтеграції — від $2,000 до $10,000 залежно від складності, з економією до $2,000 на місяць на інфраструктурі. Зв'яжіться з нами, щоб обговорити ваш проєкт.

Що реально дає Reservoir

Два режими: read-only (дані про колекції, ціни, активність) і write (створення ордерів, виконання trades). Більшість проєктів починають з read, але справжня цінність — у write-інтеграції.

Read-режим покриває:

• Floor prices, bid/ask depth
• Ownership data по кожному токену
• Sales history, transfers, mints
• Attribute-level статистика (ціни рідкісних властивостей)
• Real-time події через WebSocket (обробляє понад 1000 подій на секунду)

Write-режим (через SDK):

• Лістинги одночасно на кількох маркетплейсах
• Cross-marketplace покупки (автоматичний пошук найкращої ціни)
• Collection bids та attribute bids
• Sweep — покупка кількох NFT в одній транзакції

Як інтегрувати 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, }); // отримати 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; // виконати покупку через SDK await client.actions.buyToken({ items: [{ token: `${contractAddress}:${tokenId}`, quantity: 1 }], wallet: walletClient, onProgress: (steps) => console.log(steps), }); 

Підтримувані маркетплейси та мережі

Reservoir забезпечує агрегацію OpenSea, Blur та інших маркетплейсів. Reservoir працює на Ethereum, Polygon, Arbitrum, Optimism, Base, Zora (всього 10+ блокчейнів), забезпечуючи мультичейн-середовище. При створенні лістингу вказуємо параметр orderbook:

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

Покрокова інтеграція SDK за 5 кроків

1. Встановіть пакет: npm install @reservoir0x/reservoir-sdk
2. Отримайте API-ключ у Reservoir Dashboard
3. Створіть клієнт з ключем і вкажіть ланцюжок (наприклад, Ethereum mainnet)
4. Використовуйте методи read: getCollections, getTokens, getSales
5. Для write-операцій підключіть гаманець через viem або wagmi і викличте buyToken або listToken

Чому write-режим — ключова перевага?

Write-режим дозволяє створювати крос-маркетплейс лістинги, виконувати покупки та керувати ордерами через єдиний SDK. Це скорочує код у 5 разів порівняно з прямими викликами до API кожного маркетплейсу. Reservoir у 5 разів швидше інтегрується, ніж пряма робота з кожним маркетплейсом окремо. Приклад з нашої практики: наш клієнт-маркетплейс запустив агрегатор за 3 тижні замість 2 місяців. Економія часу склала 60%. Економія на інфраструктурі при переході з self-hosted ноди на хмарний API становить $500–$2000 на місяць.

Типові кейси інтеграції

• NFT marketplace з агрегацією — показуємо лістинги з усіх платформ, користувач купує через наш UI. Revenue model: комісія поверх Reservoir fee. Використовуємо Reservoir SDK + власний смарт-контракт з fee hook.
• Portfolio tracker — використовуємо Ownership API для отримання NFT користувача з актуальними цінами замість прямих викликів до окремих API.
• Rarity + price correlation — комбінуємо attribute stats з даними rarity для оцінки fair value токена.
• Automated market making — боти з collection bids за алгоритмічними стратегіями через SDK.

WebSocket для real-time даних

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 ключів та rate limits

Безкоштовний тариф дає 50 запитів/секунду — достатньо для старту. Production-навантаження вимагають платного плану. Для write-операцій потрібен API-ключ з правами, обліковий запис має бути підтверджений. Reservoir документація рекомендує використовувати платні плани для високонавантажених проєктів.

Self-hosted нода — Reservoir open-source, можна розгорнути власний інстанс для повного контролю та безлімітних запитів. Потрібна синхронізація через Ethereum-ноду (рекомендується Erigon). Це актуально для високонавантажених проєктів.

Що входить в роботу

Оцінимо ваш проєкт — зв'яжіться з нами для консультації. Замовте інтеграцію під ключ та отримайте гарантію якості.