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

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

Transpose — це SQL-інтерфейс поверх даних блокчейну. Замість того, щоб писати та підтримувати власний індексер, ви пишете звичайний SQL-запрос та отримуєте історичні дані по транзакціях, токенах, NFT, DeFi протоколах. Підтримуються Ethereum, Polygon, Optimism, Arbitrum, Base, BSC.

Коли це має сенс: аналітичні задачі, MVP, внутрішні дашборди, дослідження. Коли не має: real-time события з latency < 1 секунди, кастомні контракти з нестандартними событіями, обсяги запитів, які роблять Transpose економічно невигідним.

Робота з API

Transpose надає два інтерфейси: SQL API (довільні запити) та REST API (попередньо визначені endpoints для типових запитів).

SQL API — основний інструмент для нетривіальних задач:

const TRANSPOSE_KEY = process.env.TRANSPOSE_API_KEY

async function queryTranspose<T>(sql: string): Promise<T[]> {
    const response = await fetch('https://api.transpose.io/sql', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-KEY': TRANSPOSE_KEY,
        },
        body: JSON.stringify({ sql }),
    })

    if (!response.ok) {
        const error = await response.json()
        throw new Error(`Transpose error: ${error.message}`)
    }

    const data = await response.json()
    return data.results as T[]
}

// Приклад: топ-10 холдерів токена
const topHolders = await queryTranspose<{ address: string; balance: string }>(`
    SELECT owner_address AS address, balance
    FROM ethereum.token_owners
    WHERE contract_address = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
    ORDER BY balance DESC
    LIMIT 10
`)

Основні таблиці

Transpose організує дані у схеми по блокчейну (ethereum, polygon тощо). Ключові таблиці:

Типові паттерни запитів

Активність гаманця за період:

SELECT
    DATE_TRUNC('day', timestamp) AS day,
    COUNT(*) AS tx_count,
    SUM(value::numeric / 1e18) AS eth_sent
FROM ethereum.transactions
WHERE from_address = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
  AND timestamp >= NOW() - INTERVAL '30 days'
GROUP BY 1
ORDER BY 1

Історія трансфери конкретного токена на адресу:

SELECT
    t.timestamp,
    t.transaction_hash,
    t.from_address,
    t.to_address,
    (t.quantity::numeric / POW(10, tk.decimals)) AS amount,
    tk.symbol
FROM ethereum.token_transfers t
JOIN ethereum.tokens tk ON t.contract_address = tk.contract_address
WHERE t.to_address = '0xYourAddress'
  AND t.contract_address IN (
      '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', -- USDC
      '0xdAC17F958D2ee523a2206206994597C13D831ec7'  -- USDT
  )
ORDER BY t.timestamp DESC
LIMIT 100

Обмеження та rate limits

Бесплатний план: 1 запрос/секунду, 10 000 рядків/запрос, 100 запитів/день. Платні плани знімають більшість обмежень, але вартість зростає з обсягом.

Практичні обмеження, які потрібно враховувати:

• Дані з затримкою ~2 хвилини від реального часу (не для real-time систем)
• Максимальний розмір результату — 10 000 рядків; для більших виборок потрібна пагінація через OFFSET/LIMIT
• Складні JOIN між схемами (cross-chain) не підтримуються

Для інтеграції у production API рекомендується кешування результатів — більшість аналітичних запитів не вимагає даних свіжіше 5-10 хвилин:

import { createClient } from 'redis'

const redis = createClient({ url: process.env.REDIS_URL })

async function cachedTransposeQuery<T>(sql: string, ttlSeconds = 300): Promise<T[]> {
    const key = `transpose:${Buffer.from(sql).toString('base64').slice(0, 64)}`
    const cached = await redis.get(key)

    if (cached) return JSON.parse(cached)

    const results = await queryTranspose<T>(sql)
    await redis.setEx(key, ttlSeconds, JSON.stringify(results))
    return results
}

Інтеграція займає 1-2 дні: налаштування API-клієнта, визначення потрібних запитів, кешування, error handling з retry для 429 відповідей.