Інтеграція з Reservoir (NFT-агрегатор)

Інтеграція з Reservoir (NFT-агрегатор)

Reservoir це не просто API для отримання NFT даних. Це протокол з власними order books, який агрегує ліквідність з OpenSea, Blur, X2Y2, LooksRare, Coinbase NFT та дозволяє розміщувати cross-marketplace листинги через єдиний інтерфейс. Якщо ви будуєте NFT-проект та не хочете інтегрувати 6 маркетплейсів окремо — Reservoir розв'язує задачу.

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

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

Read API покриває:

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

Write (через SDK):

• Розміщення листингів одночасно на кількох маркетплейсах
• Cross-marketplace fills (покупка токена де б він ні був виставлен)
• 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),
});

Налаштування API ключів та rate limits

Бесплатний tier дає 50 запитів/секунду — достатньо для більшості проектів на старте. Production навантаження потребують платного плану. Важливий нюанс: для write операцій (розміщення ордерів) потрібен API ключ з відповідними правами, та Reservoir повинен підтвердити аккаунт.

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

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

import { WebSocket } from "ws";

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

ws.on("open", () => {
  // Підписка на sales конкретної колекції
  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);
});

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

NFT marketplace з агрегацією — показуємо листинги з усіх платформ, користувач купує через наш UI. Revenue model: protocol fee поверх Reservoir fee. Технічно: Reservoir SDK + власний смарт-контракт з fee hook.

Portfolio tracker — використовуємо Reservoir Ownership API для отримання NFTs користувача з актуальними цінами. Значно простіше, ніж прямі виклики до OpenSea/Blur API окремо.

Rarity + price correlation — комбінуємо Reservoir attribute stats з rarity даними (від Rarity.tools або власний розрахунок) для оцінки fair value конкретного токена.

Automated market making — боти, які виставляють collection bids за алгоритмічними стратегіями. Reservoir SDK спрощує управління ордерами.

Інтеграція з конкретними маркетплейсами

Reservoir підтримує різні marketplace-протоколи через 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,
});

Blur потребує окремої аутентифікації через їх API — Reservoir абстрагує це, але токен авторизації все одно потрібно отримати один раз.

Мультичейн

Reservoir підтримує Ethereum, Polygon, Arbitrum, Optimism, Base, Zora та інші. Конфігуруємо кілька chain endpoints в SDK клієнті та переключаємось по chainId з wallet провайдера.