Інтеграція з 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). Це актуально для високонавантажених проєктів.

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

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

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

Ми бачимо, що на перший погляд NFT-контракт виглядає просто: ERC-721, mint(), IPFS для метаданих, і все. На практиці саме в цій «простоті» ховається більшість проблем — від ботів, які скуповують весь mint у першому блоці, до зламаних роялті на вторинному ринку. Типовий запит: «Зробіть колекцію як у інших за тиждень», а через місяць з'ясовується, що газ виріс втричі через неоптимізований 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 забезпечують pіннінг. Важно: 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 стандарт роялті. Контракт повертає (recipient, amount) для будь-якої sale price через royaltyInfo(tokenId, salePrice). Маркетплейси опитують це при кожному продажу. Проблема: дотримання роялті — добровільне рішення маркетплейсу. Blur запустився з нульовими роялті, що викликало хвилю інших платформ. Зараз ситуація частково стабілізувалася: OpenSea підтримує ERC-2981, Blur додав опціональні.

Спроби enforce роялті on-chain через обмеження transfers тільки на approved маркетплейси (operator filtering) OpenSea пропонував через OperatorFilterRegistry. Це ламає composability — не можна передати NFT через кастомний контракт. Більшість серйозних проектів відмовилися від цього підходу. Для проектів, де роялті критичні, ми будуємо кастомний маркетплейс всередині екосистеми + 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, піннінг на мінімум двох сервісах
4. Reveal — якщо використовується Chainlink VRF, тест на testnet обов'язковий: VRF subscription має бути funded LINK токенами
5. Маркетплейс-інтеграція — верифікація колекції на OpenSea, налаштування роялті, тест MetadataUpdate events
6. Деплой та моніторинг — Tenderly для відлову reentrancy, Etherscan API для верифікації контракту, налаштування оповіщень за подіями

Що входить в роботу (deliverables)

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

Строки

Вартість розраховується індивідуально після аудиту вашого завдання. Надішліть brief з описом проекту — оцінимо прозоро протягом 3 робочих днів. Для постійних клієнтів діє гнучка система знижок на пакетні замовлення. Зв'яжіться з нами для детального обговорення вашого NFT-проекту. Отримайте консультацію з архітектури маркетплейсу — залиште заявку, і ми оцінимо проект за три дні.