Інтеграція з Bitquery API

Інтеграція з Bitquery API

Bitquery — GraphQL API над індексованими даними більше 40 блокчейнів. Привертає розробників тим, що знімає необхідність розворачувати власні ноди та писати indexer для кожної мережі. На практиці інтеграція виходить складніше, ніж обіцяє документація: rate limits, різниці в схемах між V1 та V2 (EAP), особливості запитів до DEX-даних — все це вимагає розуміння нюансів перед тим, як будувати production-систему.

V1 vs V2 (EAP): принципіальні відмінності

Bitquery розвиває дві паралельні версії API. V1 (api.bitquery.io) — стара, з широкою підтримкою мереж. V2 (streaming.bitquery.io, EAP — Early Access Program) — нова архітектура з підтримкою WebSocket-підписок для real-time даних.

Для нових проектів варто одразу орієнтуватися на V2, якщо потрібні мережі підтримуються. V1 переходить у режим підтримки без активної розробки.

# V2: підписка на нові свапи Uniswap V3 в реальному часі
subscription {
  EVM(network: eth) {
    DEXTrades(
      where: {
        Trade: { Dex: { ProtocolName: { is: "uniswap_v3" } } }
      }
    ) {
      Block { Time Number }
      Trade {
        Buy { Amount Currency { Symbol Address } }
        Sell { Amount Currency { Symbol Address } }
        Dex { PoolAddress }
      }
    }
  }
}

Типові задачі та запити

Моніторинг DEX-торговлі

Задача отримати історію торгів по конкретній парі на Uniswap V3 з OHLCV агрегацією:

query DEXOHLCVQuery($since: ISO8601DateTime!, $poolAddress: String!) {
  EVM(network: eth, dataset: archive) {
    DEXTradeByTokens(
      where: {
        Trade: { 
          Dex: { SmartContract: { is: $poolAddress } }
        }
        Block: { Time: { since: $since } }
      }
      orderBy: { ascendingByField: "Block_Time" }
      limit: { count: 1000 }
    ) {
      Block { Time(interval: { in: minutes, count: 5 }) }
      Trade {
        open: PriceInUSD(minimum: Block_Time)
        high: PriceInUSD(maximum: Trade_PriceInUSD)
        low: PriceInUSD(minimum: Trade_PriceInUSD)
        close: PriceInUSD(maximum: Block_Time)
        volume: sum(of: Trade_Side_AmountInUSD)
      }
    }
  }
}

Відстеження крупних переводів (whale monitoring)

query WhaleTransfers($minAmount: String!) {
  EVM(network: eth) {
    Transfers(
      where: {
        Transfer: {
          Currency: { SmartContract: { is: "0xdac17f958d2ee523a2206206994597c13d831ec7" } }
          Amount: { ge: $minAmount }
        }
      }
      limit: { count: 50 }
      orderBy: { descendingByField: "Block_Time" }
    ) {
      Block { Time Number }
      Transfer {
        From To
        Amount
        Currency { Symbol }
      }
      Transaction { Hash }
    }
  }
}

Rate limits та стратегії роботи з ними

Bitquery тарифікує запити в "points" — кожен запит коштує певну кількість очків залежно від обсягу повернених даних. Основні обмеження на платних планах: кількість запитів на хвилину та місячний ліміт points.

Стратегія управління rate limits:

Кешування на рівні додатку — історичні дані (торги за попередні дні) не змінюються, можуть бути закешовані в Redis або PostgreSQL на 24+ години. Звертатися до Bitquery тільки за свіжими даними.

Пагінація через cursor — запити з limit повертають максимум 1000–25000 записів. Для отримання повного набору використовується offset або cursor-based пагінація:

async function fetchAllTrades(poolAddress: string, since: string) {
  const allTrades = [];
  let offset = 0;
  const limit = 1000;
  
  while (true) {
    const data = await bitquery.request(TRADES_QUERY, { 
      poolAddress, since, limit, offset 
    });
    const trades = data.EVM.DEXTradeByTokens;
    allTrades.push(...trades);
    
    if (trades.length < limit) break;
    offset += limit;
    
    // Поважаємо rate limit
    await delay(200);
  }
  
  return allTrades;
}

Батчинг запитів — GraphQL дозволяє об'єднувати кілька операцій в один HTTP-запит, що економить round-trip time, хоча points розходуються по-прежньому за кожну операцію.

WebSocket для real-time: особливості V2

V2 підтримує підписки через graphql-ws протокол. Стандартна реалізація на Node.js:

import { createClient } from "graphql-ws";
import WebSocket from "ws";

const client = createClient({
  url: "wss://streaming.bitquery.io/eap",
  webSocketImpl: WebSocket,
  connectionParams: {
    headers: { "X-API-KEY": process.env.BITQUERY_API_KEY }
  },
  retryAttempts: Infinity,
  shouldRetry: () => true,
});

const unsubscribe = client.subscribe(
  { query: SWAP_SUBSCRIPTION },
  {
    next: (data) => processSwap(data.data.EVM.DEXTrades),
    error: (err) => logger.error("subscription error", err),
    complete: () => logger.info("subscription completed"),
  }
);

Важливо: V2 WebSocket вимагає окремого API ключа (EAP access), який видається за запитом окремо від основного ключа V1.

Обмеження та коли Bitquery не підходить

Bitquery — managed сервіс, це означає залежність: індексування може відставати від chain tip на 1–3 блока, історичні дані іноді містять gaps, підтримка нестандартних або нових мереж додається з затримкою.

Сценарії, де краще власний indexer або альтернативи:

• SLA < 1 секунди на дані (Bitquery не гарантує затримку)
• Кастомні подій від непопулярних контрактів без верифікованого ABI
• Обсяги даних, які упруться в monthly limits при розумному бюджеті
• Compliance-вимоги до зберігання даних на своїй інфраструктурі

Альтернативи по задачам: Dune Analytics — для ad-hoc SQL аналітики; The Graph — для проектно-специфичних subgraph з гарантованою доступністю; Goldsky/Envio — для high-performance індексації з низькою затримкою.

Інтеграція Bitquery як data source для дашборда або alert-системи займає 1–2 тижні з урахуванням нормалізації даних, кешування та обробки помилок.