Парсинг даних NFT-колекцій: floor price, volume, holders та аналітика

Парсинг даних NFT-колекцій (floor price, volume, holders)

OpenSea API повертає floor price із затримкою 5-15 хвилин та агрегує дані за своєю методологією. Для торгових ботів, аналітичних платформ та minting dApps, яким потрібен реальний floor — це неприйнятно. Ми розробляємо парсери, які читають події прямо з блокчейну, забезпечуючи точність до секунди. Це єдиний спосіб отримати актуальний floor без затримок.

Наш досвід — 5+ років у блокчейн-розробці та десятки проєктів з парсингу NFT-даних. Ми знаємо всі тонкощі: реорганізації ланцюжків, rate limits валідаторів, wash trading та як їх обробляти. Гарантуємо стабільну роботу парсера навіть на високонавантажених колекціях.

У цій статті розберемо повну архітектуру парсера NFT-даних: вибір стеку, індексування подій, обчислення floor price, зберігання в ClickHouse та типові проблеми. Також покажемо, що входить у наше рішення під ключ.

Джерела даних: що звідки брати

On-chain події

Для ERC-721/ERC-1155 колекцій всі продажі видно через події маркетплейсів. Кожен маркетплейс емітує власну подію:

• OpenSea Seaport: OrderFulfilled(...) — контракт 0x00000000000000ADc04C56Bf30aC9d3c0aAF14dC
• Blur: TakerAsk / TakerBid на 0x000000000000Ad05Ccc4F10045630fb830B95127
• LooksRare v2: TakerAsk / TakerBid
• X2Y2: EvInventory

Floor price не можна отримати з подій напряму — події показують виконані ордери, а не активні лістинги. Для актуального floor потрібно або індексувати active listings через маркетплейс API, або використовувати агрегатори.

Holders та transfers

Transfer(address indexed from, address indexed to, uint256 indexed tokenId) — стандарт ERC-721. Повний граф володіння будується через replay всіх Transfer подій від блоку деплою. Unique holders = унікальні адреси to за вирахуванням адрес, які потім перевели токени на іншу адресу.

Для ERC-1155: TransferSingle та TransferBatch. Тут володіння — це баланс, не бінарний стан: balanceOf(address, tokenId).

Як ми обчислюємо floor price?

Два підходи:

1. Маркетплейс API агрегація — запитуємо floor у OpenSea, Blur, LooksRare, беремо мінімум. Проблема: rate limits та кешування на стороні API. Ми використовуємо кеш на 60 секунд і fallback при перевищенні лімітів.

2. Orderbook індексування — підписуємося на події створення/скасування ордерів. Seaport: OrderValidated (створення), OrderCancelled, OrderFulfilled (виконання). Будуємо локальний orderbook, обчислюємо floor самостійно. Точніше, але складніше в підтримці при оновленнях контрактів маркетплейса. Ми рекомендуємо перший підхід для більшості проєктів, другий — для торгових ботів із субсекундним відгуком.

Архітектура парсера

Стек

ethereum-node (Alchemy/Infura/Quicknode) 
  → ethers.js / viem (event filtering)
    → message queue (Redis Streams / BullMQ)
      → PostgreSQL / ClickHouse (storage)
        → REST/WebSocket API (видача даних)

Для історичних даних — getLogs з фільтром по address та topics[0]. Блоки батчимо по 2000 (обмеження більшості RPC провайдерів на eth_getLogs):

async function fetchTransferEvents(
  contract: string,
  fromBlock: number,
  toBlock: number,
  provider: JsonRpcProvider
) {
  const iface = new Interface(['event Transfer(address indexed from, address indexed to, uint256 indexed tokenId)']);
  const filter = {
    address: contract,
    topics: [iface.getEventTopic('Transfer')],
    fromBlock,
    toBlock,
  };
  const logs = await provider.getLogs(filter);
  return logs.map(log => iface.parseLog(log));
}

Для real-time: WebSocket підписка через provider.on(filter, callback) або Alchemy eth_subscribe newLogs.

Зберігання та запити

ClickHouse ефективніший за PostgreSQL для time-series NFT даних — аналітичні запити на мільйонах рядків у 10-50x швидші. Схема:

Партиціонування по місяцях (toYYYYMM(timestamp)), сортувальний ключ (contract, timestamp).

Чому on-chain дані точніші за OpenSea API?

OpenSea API використовує власний пул ордерів і кешує floor price із затримкою до 15 хвилин. Це критично для арбітражних ботів та аналітики в реальному часі. On-chain дані — єдине джерело істини. Ми гарантуємо точність до останнього підтвердженого блоку (фіналізація за 2 епохи — 64 блоки на Ethereum PoS).

Вирішення типових проблем

Rate limits

Alchemy Free — 330 CUPS, Growth — 660 CUPS. При історичному парсингу великої колекції (BAYC: 500k+ Transfer подій) без throttling отримаємо 429. Реалізуємо exponential backoff + queue з concurrency control.

Реорганізації блокчейну

Події з останніх 12 блоків потрібно позначати як «pending» і підтверджувати тільки після finality. Для Ethereum PoS — 2 епохи (64 блоки) для економічного finality.

Wash trading

Обсяг за адресами з циклічними переказами спотворює статистику. Базова евристика: угоди де from і to — пов'язані адреси (отримували ETH з одного джерела) позначаються прапорцем.

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

• Архітектура парсера під ваше завдання
• Код на TypeScript з використанням ethers.js/viem
• Налаштування ClickHouse для зберігання та аналітики
• Дашборд у Grafana з ключовими метриками (floor price, volume, holders)
• REST/WebSocket API для інтеграції з вашим додатком
• Повна документація та навчання команди
• Підтримка після запуску

Ми надаємо рішення під ключ. Оцінимо ваш проєкт за 1 день.

Орієнтири за термінами

Парсер Transfer подій + holders tracker — 1 день. Додавання floor price через маркетплейс API + кеш — ще півдня. Історичний бекфіл для великої колекції + дашборд — 2-3 дні сумарно.

Зв'яжіться з нами, щоб отримати консультацію та точну оцінку для вашого проєкту.

Чому розробка 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-проекту. Отримайте консультацію з архітектури маркетплейсу — залиште заявку, і ми оцінимо проект за три дні.