Інтеграція з Covalent API
Covalent — це unified API для отримання on-chain даних з 200+ мереж без необхідності утримувати власний архівний вузол. Замість того щоб писати окремі інтеграції для Ethereum, Polygon, Arbitrum та Base, ви робите один запит до Covalent і отримуєте нормалізовану відповідь з декодованими транзакціями, балансами токенів та історією трансферів.
Що реально розв'язує Covalent
Типовий сценарій: вам потрібно показати користувачу портфоліо токенів на 5 мережах, історію транзакцій та NFT. Без Covalent це 5 різних RPC-вузлів, самостійний парсинг ABI, запити до CoinGecko для цін — і пара тижнів роботи. З Covalent:
# Балансі всіх 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 декодовані дані для популярних протоколів.
Аутентифікація та rate limits
API ключ передається через Basic Auth header. Безплатний tier: 4 запити в секунду, 100k запитів на місяць. Для production — платні тарифи від $50/місяць.
const client = new CovalentClient(process.env.COVALENT_API_KEY);
const response = await client.BalanceService.getTokenBalancesForWalletAddress(
"eth-mainnet",
walletAddress,
{ nft: false, noNftFetch: true }
);
GoldRush SDK (офіційний TypeScript клієнт) типізований, автоматично обробляє пагінацію, має retry логіку. Краще використовувати його, ніж raw fetch.
Основні endpoint групи
Balances API — поточні та історичні баланси ERC-20, ERC-721, ERC-1155. Включає USD-стоимість за поточною або історичною ціною. Параметр historic_balance_interval дозволяє отримати часовий ряд баланса без обходу тисяч блоків самостійно.
Transactions API — повна історія транзакцій з декодованими 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-формат — менше плутанини при роботі з тестнетами.
Обмеження, про які варто знати
Covalent індексує історичні дані з затримкою для нових мереж — не розраховуйте на дані з затримкою менше одного блока. Для real-time даних (моніторинг pending транзакцій, поточна ціна на DEX) потрібен прямий RPC.
Decoded data працює лише для white-listed протоколів. Кастомні або малозвісні контракти повертають raw logs — ABI-декодування вам доведеться робити самостійно через ethers.Interface.