Інтеграція з Flipside Crypto

Інтеграція з Flipside Crypto

Flipside — це аналітична платформа з кюрованими таблицями по блокчейн-даним: декодовані події контрактів, DEX-трейди, NFT-транзакції, bridge активність по 30+ мережам. На відміну від прямого парсингу нод, тут дані вже нормалізовані та доступні через SQL-інтерфейс. Основний сценарій інтеграції — підключення аналітичного шару до продукту без власної індексної інфраструктури.

Моделі доступу до даних

ShroomDK / Flipside API. Основний програмний інтерфейс. Запит пишеться на SQL (діалект Snowflake/Trino), відправляється через REST API, результат повертається як JSON. Ліміти на безплатному плані: 5000 запитів на місяць, 1M рядків на результат, максимальний час виконання запиту ~120 сек.

import requests

API_KEY = "your_api_key"

def query_flipside(sql: str) -> list[dict]:
    response = requests.post(
        "https://api-v2.flipsidecrypto.xyz/json-rpc",
        headers={"x-api-key": API_KEY},
        json={
            "jsonrpc": "2.0",
            "method": "createQueryRun",
            "params": [{"sql": sql, "maxAgeMinutes": 10, "timeoutMinutes": 2}],
            "id": 1
        }
    )
    query_run_id = response.json()["result"]["queryRun"]["id"]
    # polling до завершення
    return poll_results(query_run_id)

Ключові таблиці для EVM-мереж:

Аналогічна структура для Solana (solana.core.*), Polygon, Arbitrum, Base, Avalanche та інших підтримуваних мереж.

Типичний запит — обсяг DEX-торгівлі за протоколами за останні 7 днів:

SELECT 
    platform,
    COUNT(*) as swap_count,
    SUM(amount_in_usd) as volume_usd
FROM ethereum.defi.fact_dex_swaps
WHERE block_timestamp >= DATEADD('day', -7, CURRENT_TIMESTAMP())
    AND amount_in_usd IS NOT NULL
GROUP BY platform
ORDER BY volume_usd DESC
LIMIT 20

Архітектура інтеграції

Кешування — обов'язково. Flipside не призначений для запитів у реальному часі. Архітектурний паттерн: scheduled job підтягує дані кожні N хвилин → зберігає у власну БД → фронтенд читає з кешу. Прямі запити до Flipside API з користувацького інтерфейсу — погана практика: latency 5-30 сек, ліміти швидко закінчуються.

// Cron job кожні 15 хвилин
import { FlipsideClient } from '@flipsidecrypto/sdk';

const flipside = new FlipsideClient({ apiKey: process.env.FLIPSIDE_API_KEY });

async function syncDexVolume() {
  const result = await flipside.query.run({
    sql: `SELECT ... FROM ethereum.defi.fact_dex_swaps WHERE ...`,
    maxAgeMinutes: 15,  // використовуємо кеш Flipside якщо дані свіжі
    timeoutMinutes: 3,
  });
  
  await db.upsert('dex_volume_snapshots', {
    timestamp: new Date(),
    data: result.rows,
  });
}

Офіційний Python SDK:

pip install flipside

from flipside import Flipside

sdk = Flipside(api_key="...", base_url="https://api-v2.flipsidecrypto.xyz")
result = sdk.query("SELECT * FROM ethereum.core.fact_transactions LIMIT 100")
df = result.to_pandas()  # зручно для аналітики

Параметр maxAgeMinutes важливий: якщо запитуєте одні й ті ж дані повторно, Flipside відає кешований результат не розходуючи ліміт запитів.

Обмеження та альтернативи

Flipside оновлює дані з затримкою 30-90 хвилин від поточного блоку — це не інструмент для реалтайм моніторингу. Для даних <1 години потрібні інші джерела: The Graph (субграфи), Dune Analytics (схожий SQL-підхід, але інша модель ліцензування), прямі RPC запити.

Покриття деяких протоколів може бути неповним або застарілим — перед використанням варто верифікувати дані проти on-chain джерела принаймні по кількох транзакціях.