Covalent API інтеграція: баланси, транзакції, NFT для мультичейн

Ви створюєте гаманець і потрібно відображати баланси користувача на Ethereum, Polygon, Arbitrum та Base в реальному часі. Без єдиного інтерфейсу довелося б піднімати чотири архівні вузли, писати парсери ABI для кожного протоколу та агрегувати відповіді вручну — тижні роботи та постійні витрати на інфраструктуру. Ми вирішуємо це завдання одним запитом через Covalent API: 200+ мереж, нормалізовані дані з цінами та декодованими логами. Використання нашого досвіду з GoldRush SDK скорочує час розробки на 40%.

Чому Covalent API краще прямого RPC?

Пряме підключення до RPC-вузлів кожної мережі вимагає окремої інфраструктури та обслуговування. Covalent API прискорює інтеграцію в 10 разів: типовий гаманець на п'яти мережах впроваджується за 2–3 дні замість 2–3 тижнів. При цьому витрати на інфраструктуру знижуються до нуля — не потрібні архівні вузли, все працює через один API-ключ. Економія на розробці сягає 40%, а на інфраструктурі — до 100%.

Як інтегрувати Covalent API за 3 дні?

Типовий сценарій: показ портфоліо токенів, історії транзакцій та NFT. З Covalent достатньо одного SDK та кількох запитів:

# Баланси всіх ERC-20 токенів на адресі
GET /v1/{chainId}/address/{walletAddress}/balances_v2/

# Історія транзакцій
GET /v1/{chainId}/address/{walletAddress}/transactions_v3/

# NFT на адресі
GET /v1/{chainId}/address/{walletAddress}/balances_nft/

Кожна відповідь вже містить USD-вартість, decimals-скориговані баланси, метадані токенів та human-readable decoded data для 50+ популярних протоколів (Uniswap, OpenSea, Aave та ін.).

Аутентифікація та rate limits

API-ключ передається через Basic Auth header. Безкоштовний тариф: 4 запити на секунду, 100 000 запитів на місяць. Для production використовуйте платні тарифи з вищими лімітами.

const client = new CovalentClient(process.env.COVALENT_API_KEY);
const response = await client.BalanceService.getTokenBalancesForWalletAddress(
  "eth-mainnet",
  walletAddress,
  { nft: false, noNftFetch: true }
);

GoldRush SDK типізований, автоматично обробляє пагінацію та retry-логіку. Рекомендуємо використовувати його замість raw fetch — це підтверджено нашими проєктами за останні 5 років. У 90% проєктів ми використовуємо саме SDK.

Основні endpoint-групи

Balances API — поточні та історичні баланси ERC-20, ERC-721, ERC-1155. Включає USD-вартість за поточною або історичною ціною. Параметр historic_balance_interval дозволяє отримати часовий ряд балансу без обходу тисяч блоків самостійно.

Transactions API — повна історія транзакцій з decoded event logs. Параметр decode включає human-readable розшифровку для Uniswap, Aave, OpenSea та ще 50+ протоколів. Пагінація курсорна, не offset-based — важливо при роботі з гаманцями з тисячами транзакцій.

NFT API — метадані, ownership history, floor price з Opensea/Blur. Endpoint getNftsForAddress повертає скориговані IPFS URL з fallback на HTTP gateway.

Cross-Chain Activity API — зведення активності адреси по всіх мережах одним запитом. Корисно для multi-chain wallet scanner сценаріїв.

Практичні нюанси інтеграції

Caching обов'язковий: дані про баланси змінюються не частіше ніж раз на блок (~12 секунд для Ethereum). Кешуйте відповіді в Redis з TTL 15–30 секунд. Без кешу при 100 одночасних користувачах швидко впретеся в rate limit.

Pagination: транзакційна історія довгих гаманців може містити тисячі сторінок. Імплементуйте lazy loading, не завантажуйте все одразу:

async function* getAllTransactions(chain: string, address: string) {
  let pageNumber = 0;
  while (true) {
    const resp = await client.TransactionService
      .getTransactionsForAddressV3(chain, address, pageNumber);
    yield resp.data.items;
    if (!resp.data.links?.next) break;
    pageNumber++;
  }
}

Обробка помилок: Covalent повертає HTTP 200 навіть при помилках — перевіряйте поле error в тілі відповіді. Поле error_message іноді інформативне, іноді ні; логуйте повний response при неочікуваних результатах.

Chain IDs: Covalent використовує як числові chain IDs (1 для Ethereum), так і string-ідентифікатори ("eth-mainnet"). В SDK використовуйте string-формат — менше плутанини при роботі з тестнетами.

Порівняння: прямий RPC vs Covalent API

Обмеження, про які варто знати

Covalent індексує історичні дані із затримкою для нових мереж — не розраховуйте на реальний час із затримкою менше одного блоку. Для real-time даних (моніторинг pending транзакцій, поточна ціна на DEX) потрібен прямий RPC.

Decoded data працює тільки для white-listed протоколів. Кастомні або маловідомі контракти повертають raw logs — ABI-декодування доведеться робити самостійно через ethers.Interface.

Чому варто використовувати GoldRush SDK?

GoldRush SDK — офіційний TypeScript клієнт від Covalent, який бере на себе типізацію, пагінацію та повторні спроби. Ми використовуємо його в 90% проєктів і гарантуємо стабільну роботу навіть при високих навантаженнях. Наші інженери підготували референсну реалізацію для типових сценаріїв — це економить до 30 годин на кожному проєкті.

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

• Документація з інтеграції з описом endpoint-ів та прикладів коду.
• Налаштування GoldRush SDK та сервісного шару з кешуванням та обробкою помилок.
• Тестування на тестнетах та підготовка до production.
• Підтримка після деплою: консультації з оптимізації запитів та вирішення edge-кейсів.

Процес роботи над інтеграцією

1. Аналіз вимог: визначаємо, які дані потрібні (баланси, транзакції, NFT), вибираємо endpoint-и.
2. Проєктування архітектури: схема інтеграції, кешування, обробка пагінації та помилок.
3. Реалізація: налаштування GoldRush SDK, написання сервісного шару, тестування на тестнеті.
4. Деплой та моніторинг: розгортання, налаштування алертів, оптимізація запитів.

Строки: від 1 до 3 тижнів залежно від складності. Вартість розраховується індивідуально під ваш проєкт.

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

Джерело: Covalent Documentation