Интеграция с 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). Это актуально для высоконагруженных проектов.

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

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

Почему разработка NFT маркетплейсов требует комплексного подхода?

Мы видим, что на первый взгляд NFT-контракт выглядит просто: ERC-721, mint(), IPFS для метаданных, всё. На практике именно в этой «простоте» прячется большинство проблем — от ботов, скупающих весь mint в первый блок, до сломанных royalties на вторичном рынке. Типовой запрос: «Сделайте коллекцию как у других за неделю», а через месяц выясняется, что газ вырос втрое из-за неоптимизированного for-цикла, а OpenSea не видит метаданные после reveal. Мы знаем каждый из этих граблей и строим процессы так, чтобы их избежать.

За 5 лет работы с блокчейнами мы реализовали 40+ NFT-проектов, включая маркетплейсы с динамическими атрибутами и cross-chain мостами. Накопили библиотеку проверенных шаблонов — часть из них разберём ниже.

Какой стандарт выбрать: ERC-721 или ERC-1155?

ERC-721 — каждый токен уникален, один owner. Подходит для коллекций, где каждый NFT имеет индивидуальные атрибуты и прямую привязку owner → tokenId.
ERC-1155 — multi-token стандарт: один контракт хранит и fungible, и non-fungible токены. Использует balanceOf(address, tokenId) вместо ownerOf(tokenId). Одна транзакция может передать несколько разных токенов через safeBatchTransferFrom. Это экономит газ при массовых операциях — важно для игровых айтемов, тикетов, edition-коллекций.

Конкретный кейс: игровой проект с 50 видами айтемов, каждый в тираже 10 000. ERC-721 — 500 000 уникальных токенов, огромный overhead на маппинги. ERC-1155 — 50 tokenId, balanceOf на каждого игрока. Газ на transfer ниже в 2–3 раза, деплой контракта дешевле. Для таких задач мы используем OpenZeppelin ERC-1155 с кастомными модификациями.

Метаданные: on-chain vs IPFS vs centralized

Стандартный путь — tokenURI() возвращает ссылку на JSON с полями name, description, image, attributes. Три варианта хранения:

• Centralized server — самый дешёвый и гибкий. Риск: сервер падает, компания закрывается — NFT теряет метаданные. Не подходит для коллекций с претензией на долгосрочную ценность.
• IPFS + Pinning — контентно-адресуемое хранилище, ссылка привязана к хешу содержимого. Pinata или NFT.Storage обеспечивают pinning. Важно: IPFS не гарантирует доступность сам по себе — нужен активный pinning service. Если он закроется, данные могут исчезнуть, если никто не хранит копию.
• On-chain metadata — base64-encoded SVG или JSON прямо в tokenURI. Максимальная надёжность, но дорого: для коллекции из 10 000 токенов затраты на газ могут превысить $5000. Подходит для generative art проектов, где визуал генерируется из on-chain атрибутов (Nouns, Loot).

Для большинства коллекций мы выбираем IPFS с Pinata для images + on-chain атрибуты для трейтов — хороший баланс. Файлы перед загрузкой проверяем через валидатор JSON Schema; типичная ошибка — неэкранированные кавычки, из-за чего маркетплейсы показывают пустой экран.

Dynamic NFT: метаданные, которые меняются

Dynamic NFT обновляет метаданные в ответ на внешние события — результаты матчей, уровень персонажа, реальные данные через Chainlink. Архитектурно это связка: смарт-контракт хранит state → tokenURI() генерирует метаданные из state on-chain. Проблема с кешированием: OpenSea и другие маркетплейсы агрессивно кешируют. Стандартный механизм инвалидации — MetadataUpdate(tokenId) event из ERC-4906. OpenSea слушает этот event и сбрасывает кеш. Без него обновлённые метаданные могут не отображаться неделями.

Chainlink Automation (бывший Keepers) для автоматического обновления state на контракте по расписанию или по условию — стандартное решение для динамики.

Как защитить mint от ботов?

Allowlist через merkle tree — стандарт. Список адресов хешируется в merkle root, хранится в контракте. При mint пользователь предоставляет merkle proof — контракт проверяет без хранения полного списка. Используем OpenZeppelin MerkleProof library.

Reveal механика — при mint выдаётся placeholder, реальные трейты reveal-ятся после окончания продажи. Иначе боты могут сканировать pending транзакции и снайперить редкие трейты через frontrunning. Но reveal требует commitment scheme — случайный seed должен быть зафиксирован до mint или использовать Chainlink VRF.

Chainlink VRF для честной рандомизации трейтов. VRF request в момент mint → callback с verifiable random number → assign traits. Это добавляет ~2 транзакции и latency, но гарантирует честность. Ссылка на Chainlink VRF v2.5.

Rate limiting — require(mintedPerWallet[msg.sender] < maxPerWallet). Не защищает от мульти-кошельков, но поднимает стоимость атаки. Для премиум-проектов часто добавляем proof-of-work прямо в контракт (через EIP-2612 signatures).

Royalties: реальное состояние рынка

ERC-2981 — on-chain стандарт royalties. Контракт возвращает (recipient, amount) для любой sale price через royaltyInfo(tokenId, salePrice). Маркетплейсы опрашивают это при каждой продаже. Проблема: соблюдение royalties — добровольное решение маркетплейса. Blur запустился с нулевыми royalties, что вызвало волну других платформ. Сейчас ситуация частично стабилизировалась: OpenSea поддерживает ERC-2981, Blur добавил опциональные.

Попытки enforce royalties on-chain через ограничение transfers только на approved маркетплейсы (operator filtering) OpenSea предлагал через OperatorFilterRegistry. Это ломает composability — нельзя передать NFT через кастомный контракт. Большинство серьёзных проектов отказались от этого подхода. Для проектов, где royalties критичны, мы строим кастомный маркетплейс внутри экосистемы + incentive structure для пользователей торговать именно там.

Lazy minting и gas-free mint

Gas-free mint через подпись: создатель подписывает voucher (tokenId, tokenURI, price, signature), покупатель предоставляет voucher в mint() — контракт верифицирует подпись через ECDSA.recover() и минтит. Работает на OpenSea через их Seaport протокол. Seaport — оптимизированный контракт с минимальным gas usage. Понимание его механики важно при интеграции custom marketplace логики.

Стек для NFT-проектов

• Контракты: Solidity 0.8.x, OpenZeppelin ERC721Enumerable или ERC721A (Azuki) для gas-оптимизированного batch mint, ERC1155 от OpenZeppelin
• VRF и автоматизация: Chainlink VRF v2.5, Chainlink Automation
• Хранение: Pinata (IPFS pinning), NFT.Storage, Arweave для постоянного хранения
• Маркетплейс: OpenSea Seaport protocol, кастомная интеграция
• Фронтенд: wagmi v2 + viem, RainbowKit для wallet connection, React + TypeScript

Процесс разработки

1. Проектирование mint-механики — allowlist, public sale, price curve (Dutch auction или фиксированная), limits per wallet
2. Контракты — с Foundry fuzz-тестами на mint limits, merkle proof-верификацию, royalty calculations
3. IPFS деплой — загрузка метаданных и images до reveal, pinning на минимум двух сервисах
4. Reveal — если используется Chainlink VRF, тест на testnet обязателен: VRF subscription должен быть funded LINK токенами
5. Маркетплейс-интеграция — верификация коллекции на OpenSea, настройка royalties, тест MetadataUpdate events
6. Деплой и мониторинг — Tenderly для отлова reentrancy, Etherscan API для верификации контракта, настройка оповещений по событиям

Что входит в работу (deliverables)

• Исходный код смарт-контрактов (Solidity, Rust для Solana) с комментариями
• Тест-сьют (Foundry/Hardhat) с покрытием ≥90%
• Документация развёртывания и инструкции по интеграции
• Доступы к pinning-сервисам (Pinata/Pinfluence)
• Скрипты для генерации метаданных (Python/JS)
• Поддержка при верификации на маркетплейсах
• 30 дней технической поддержки после деплоя

Сроки

Стоимость рассчитывается индивидуально после аудита вашей задачи. Пришлите brief с описанием проекта — оценим прозрачно в течение 3 рабочих дней. Для постоянных клиентов действует гибкая система скидок на пакетные заказы. Свяжитесь с нами для детального обсуждения вашего NFT-проекта. Получите консультацию по архитектуре маркетплейса — оставьте заявку, и мы оценим проект за три дня.