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

При создании NFT-маркетплейса или портфельного трекера разработчики сталкиваются с необходимостью интеграции с несколькими маркетплейсами. Каждый из них — OpenSea, Blur, X2Y2 — имеет свой API, свои форматы ордеров и rate limits. Поддерживать N интеграций сложно: растёт кодовая база, время на дебаг, затраты на поддержку. Reservoir решает эту проблему единым API. Вместо шести разных API — один протокол с read и write-режимами. Опыт нашей команды — 5+ лет в Web3, более 20 проектов по интеграции DeFi и NFT. Мы гарантируем корректную настройку листингов, cross-marketplace покупок и real-time данных. Reservoir сокращает время интеграции в 3-4 раза по сравнению с прямыми вызовами к API каждого маркетплейса. Свяжитесь с нами, чтобы обсудить ваш проект.

Что реально даёт 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 работает на 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 каждого маркетплейса. Пример из нашей практики: клиент-маркетплейс запустил агрегатор за 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). Это актуально для высоконагруженных проектов.

Что входит в работу

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