Интеграция с 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 поддерживает разные маркетплейс-протоколы через 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 провайдера.