Интеграция с 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 decoded data для популярных протоколов.
Аутентификация и 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 клиент) типизирован, handles pagination автоматически, есть retry логика. Лучше использовать его, чем raw fetch.
Основные 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-формат — меньше путаницы при работе с тестнетами.
Ограничения, о которых стоит знать
Covalent индексирует исторические данные с задержкой для новых сетей — не рассчитывайте на данные с задержкой меньше одного блока. Для real-time данных (мониторинг pending транзакций, текущая цена на DEX) нужен прямой RPC.
Decoded data работает только для white-listed протоколов. Кастомные или малоизвестные контракты возвращают raw logs — ABI-декодирование придётся делать самостоятельно через ethers.Interface.