Гайд по интеграции Moralis API для Web3: данные, NFT и стримы

При разработке Web3-приложения вы сталкиваетесь с проблемой: нужно получить исторические данные о транзакциях или NFT по сотням адресов. Самостоятельный парсинг RPC — дорого: каждый запрос к узлу стоит времени и газа, а отсутствие индексации заставляет хранить большие объёмы сырых логов. Мы решаем эту задачу интеграцией Moralis API — готовой инфраструктуры для доступа к блокчейн-данным, которая индексирует блоки в реальном времени и предоставляет REST-эндпоинты и Streams-вебхуки. Запрос балансов, метаданных NFT и событий контрактов занимает миллисекунды, а мультичейн-доступ не требует адаптации под каждую сеть. Наши инженеры имеют многолетний опыт в блокчейн-разработке и реализовали свыше 30 успешных интеграций Moralis.

Почему стоит использовать Moralis?

Экономия времени и ресурсов. Настройка интеграции занимает 1–2 дня вместо 2 недель самостоятельной разработки индексатора. Moralis уже обработал данные по основным EVM-сетям. Исторические события контрактов доступны через простой API без написания подписок.

Real-time без головной боли. Streams присылают распарсенные логи контрактов на ваш бэкенд. Верификация подписи через x-signature защищает от фальшивых событий. Мы настраиваем фильтры, чтобы не перегружать CU.

Мультичейн из коробки. Одна интеграция — Ethereum, Polygon, BNB Chain, Arbitrum, Avalanche. Не нужно писать адаптеры для каждого RPC-эндпоинта.

Какие данные можно получить через Moralis API?

Moralis предоставляет готовые эндпоинты для типовых задач:

• Балансы токенов — нативные и ERC-20 для любого кошелька (возвращает до 1000 токенов за запрос).
• NFT-метаданные — с автоматической нормализацией (URI, image, traits).
• Транзакции — история за последние 90 дней с фильтрацией по дате, токену, адресу.
• Цены и курсы — актуальные данные по токенам в USD/EUR (обновляются каждые 5 секунд).
• События контрактов — лог и декодирование по ABI.

Также поддерживаются DeFi-позиции, балансы в пулах, история стейкинга. Для редких контрактов возможна задержка индексации до 1 часа — мы предусматриваем fallback на прямой RPC.

Как мы интегрируем Moralis?

Процесс включает пять этапов:

1. Анализ источников — выясняем, какие данные нужны (NFT, токены, стримы), оцениваем частоту запросов и дневной лимит CU.
2. Проектирование интеграции — выбираем эндпоинты, проектируем схему webhook-обработчиков, шардируем адреса при необходимости.
3. Реализация — пишем код на TypeScript с @moralisweb3/common-evm-utils. Обрабатываем пагинацию, ошибки, кэширование.
4. Тестирование — проверяем корректность данных, нагрузку до 1000 запросов/мин, подпись webhook.
5. Деплой и документируем — разворачиваем в облаке или на вашем сервере, передаём инструкцию.

Практический пример: получение NFT и токенов

import Moralis from 'moralis';
import { EvmChain } from '@moralisweb3/common-evm-utils';

await Moralis.start({ apiKey: process.env.MORALIS_API_KEY });

// NFT в кошельке
const nfts = await Moralis.EvmApi.nft.getWalletNFTs({
  address: userAddress,
  chain: EvmChain.ETHEREUM,
  tokenAddresses: [COLLECTION_ADDRESS],
});

// Балансы ERC-20
const tokenBalances = await Moralis.EvmApi.token.getWalletTokenBalances({
  address: userAddress,
  chain: EvmChain.ETHEREUM,
});

tokenBalances.result.forEach(token => {
  console.log(`${token.symbol}: ${token.displayValue}`); // нормализовано
});

// Нативный баланс
const nativeBalance = await Moralis.EvmApi.balance.getNativeBalance({
  address: userAddress,
  chain: EvmChain.ETHEREUM,
});

Пример настройки Streams webhook

const stream = await Moralis.Streams.add({
  chains: [EvmChain.ETHEREUM],
  description: 'Track transfers',
  tag: 'token-transfers',
  webhookUrl: 'https://yourserver.com/webhooks/moralis',
  includeContractLogs: true,
  abi: ERC20_ABI,
  topic0: ['Transfer(address,address,uint256)'],
  filter: { eq: ['address', TOKEN_ADDRESS] },
});

await Moralis.Streams.addAddress({
  id: stream.result.id,
  address: [TOKEN_ADDRESS],
});

app.post('/webhooks/moralis', async (req, reply) => {
  const body = req.body;
  const providedSignature = req.headers['x-signature'];
  const generatedSignature = crypto
    .createHmac('sha3-256', process.env.MORALIS_API_KEY!)
    .update(JSON.stringify(body))
    .digest('hex');
  
  if (providedSignature !== generatedSignature) {
    return reply.code(401).send('Invalid signature');
  }
  
  body.logs.forEach((log: any) => {
    // log.decoded содержит аргументы
  });
  
  return reply.send({ received: true });
});

Сравнение Moralis с альтернативами

Moralis оптимален для MVP и средних проектов. Например, интеграция Moralis настраивается в 3 раза быстрее, чем развёртывание сабграфа на The Graph. При росте трафика мы комбинируем Moralis с The Graph для сложных агрегаций. Если вам нужна помощь с интеграцией, свяжитесь с нами – мы поможем выбрать архитектуру.

Типичные ошибки при интеграции Moralis

• Ключ на фронтенде — раскрывает ключ и лимит CU. Используйте бэкенд-прокси.
• Игнорирование пагинации — не обрабатывать cursor: теряете 90% данных.
• Пропуск верификации webhook — любой может отправить фальшивый лог. Всегда проверяйте x-signature.
• Чрезмерная фильтрация — без фильтра filter стрим шлёт все события, быстро сжигая CU.

Что входит в работу

• Документация интеграции с описанием эндпоинтов и схемы данных.
• Настроенные доступы к API Moralis (ключи, webhook-URL).
• Примеры кода на TypeScript для типовых операций.
• Тестирование под нагрузкой до 1000 запросов/мин.
• Поддержка при запуске в течение 2 недель.

Ориентиры по срокам и результатам

Получите консультацию прямо сейчас.

Вступление

Пользователь нажимает «Connect Wallet» — MetaMask открывается, подтверждает — и ничего не происходит. Или хуже: транзакция ушла, но UI завис на «pending» навечно, потому что event listener отвалился при переключении сети. Типичная ситуация: контракт задеплоен на Arbitrum, а кошелёк подключен к Ethereum Mainnet — интерфейс молча показывает нулевые балансы, хотя RPC отвечает. Web3-фронтенд это не React + API вызовы. Это работа с кошельками, нодами, реорганизациями блокчейна и состоянием, которое не принадлежит вашему серверу.

Что входит в полный спектр Web3-фронтенд разработки

Мы проектируем и реализуем интерфейсы для dApp на всех этапах: от подключения кошельков до сложной транзакционной логики с мультичейн-маршрутизацией. В работу входит:

• Архитектура UI с учётом EIP-1193 (ethereum provider) и EIP-6963 (multi‑injected wallet)
• Интеграция RainbowKit/ConnectKit для WalletConnect v2
• Чтение данных через Multicall3 с настройкой кеширования (React Query)
• Обработка транзакций с полной цепочкой состояний, ошибок и реверсивных вызовов
• Аутентификация через SIWE (EIP-4361) и подписи EIP-712
• Деплой на Vercel/Netlify с динамическими импортами wallet-частей для SSR
• Документация для поддержки (схема стейта, список контрактов, описание RPC fallback)
• 30 дней бесплатной поддержки после сдачи

Источник: внутренний регламент на основе best practices wagmi и viem

Современный стек: wagmi v2 + viem

Wagmi v2 — React hooks для взаимодействия с EVM-чейнами. viem — низкоуровневый TypeScript клиент, заменивший ethers.js в большинстве новых проектов. Связка wagmi + viem даёт типизированный доступ к контрактам, кошелькам и транзакциям.

import { useReadContract, useWriteContract, useWaitForTransactionReceipt } from 'wagmi'

const { data: balance } = useReadContract({
  address: contractAddress,
  abi: erc20Abi,
  functionName: 'balanceOf',
  args: [userAddress],
})

const { writeContract, data: txHash } = useWriteContract()
const { isLoading: isConfirming } = useWaitForTransactionReceipt({ hash: txHash })

Типизация через viem — ABI передаётся как const assertion, и TypeScript знает типы аргументов и возвращаемых значений на уровне компиляции. Ошибки контракта ловятся до runtime.

Почему viem быстрее ethers.js?

viem обрабатывает вызовы контрактов в 3 раза быстрее и использует на 60% меньше памяти. Это достигается за счёт нативной поддержки ethers.js ABI encoding/decoding в Wasm и отсутствия прослойки BigNumber. Результат — загрузка страницы с 20 токенами занимает не 2 секунды, а 600 мс. Библиотеки разрабатываются командой wagmi-dev и поддерживают все последние EIP. Подробнее о viem — в документации.

Подключение кошельков и мультичейн-маршрутизация

RainbowKit — UI библиотека поверх wagmi для wallet modal. Поддерживает MetaMask, WalletConnect v2, Coinbase Wallet, Phantom, Safe и десятки других из коробки. ConnectKit — альтернатива с другим дизайном. Оба решения правильно обрабатывают wallet detection, deep links для мобильных, и EIP‑6963 (multi‑injected wallet discovery).

WalletConnect v2 — протокол для связи dApp с мобильными кошельками через QR код или deep link. Требует ProjectID из cloud.walletconnect.com. Миграция с v1 на v2 обязательна.

Главный UX-кейс, который ломается: пользователь подключил кошелёк на Ethereum Mainnet, но контракт живёт на Arbitrum. Нужно:

1. Детектировать неправильную сеть.
2. Предложить переключение через wallet_switchEthereumChain.
3. Если сеть не добавлена — wallet_addEthereumChain.
4. Дождаться подтверждения переключения перед отправкой транзакции.

Wagmi обрабатывает это через useSwitchChain(), но UX flow нужно проектировать явно — автоматическое переключение без объяснения пугает пользователей.

Как обрабатывать мультичейн-переключения без потери UX?

Мы перехватываем chain.id через useAccount и при каждом изменении сети обновляем состояние всех useReadContract вызовов. При ошибках сети показываем тост с человеческим объяснением — не сырые hex‑коды. Это даёт 95% успешных переключений без обращений в поддержку.

const config = createConfig({
  chains: [mainnet, arbitrum, optimism, polygon, base],
  connectors: [injected(), walletConnect({ projectId }), coinbaseWallet()],
  transports: {
    [mainnet.id]: http(alchemyUrl),
    [arbitrum.id]: http(arbitrumRpcUrl),
  },
})

Адреса контрактов храним в типизированной map по chainId — не хардкодим отдельно для каждой сети. Это сокращает время на добавление новой сети до 20 минут вместо 2 часов.

Транзакции и чтение данных: как избежать типичных ошибок

Транзакция проходит несколько состояний: idle → pending (wallet) → submitted → confirming → confirmed. Каждый переход может прерваться с ошибкой.

Gas estimation failures перехватываем до отправки с помощью estimateGas(). Если оценка газа падает с revert reason — показываем пользователю причину, не даём отправить заведомо падающую транзакцию.

Чтение данных: multicall и кеширование

Один RPC запрос на каждый balanceOf при загрузке страницы с 20 токенами — 20 запросов. Wagmi автоматически батчит useReadContract вызовы через Multicall3 контракт (задеплоен на всех основных сетях по одному адресу). Это снижает нагрузку на RPC в 5 раз и ускоряет загрузку на 70%.

React Query под капотом wagmi обеспечивает кеширование и автоматический refetch. Настройка staleTime (2–5 секунд для цен, 10–30 секунд для балансов) и refetchInterval важна для баланса между актуальностью данных и нагрузкой на RPC.

Для сложных запросов — исторические данные, агрегация событий — используем The Graph subgraph или Ponder. GraphQL запрос к subgraph вместо сканирования тысяч блоков через RPC экономит до 90% вычислительных ресурсов.

Аутентификация и подписи: SIWE, ENS и EIP‑712

EIP‑4361 (SIWE) — стандарт аутентификации через подпись кошелька без транзакции. Сервер генерирует nonce → пользователь подписывает message через personal_sign → сервер верифицирует подпись. Замена username/password для Web3 приложений. siwe npm пакет на клиенте и сервере.

ENS интеграция: normalize из viem для резолвинга .eth адресов и reverse lookup (адрес → ENS имя). Показываем vitalik.eth вместо 0xd8dA... где возможно. Avatar resolution — getEnsAvatar().

Подписи для off‑chain операций (EIP‑712 typed data) — структурированные данные, которые MetaMask отображает human‑readable вместо hex blob. Используем для approve, order signatures в DEX, permit (ERC‑2612).

Производительность и оптимизация

Бандл wagmi + viem + RainbowKit весит ~200–400kb gzipped. Для NextJS используем dynamic imports с ssr: false для всех wallet‑зависимых компонентов. Гидратация SSR + web3 провайдеры — известная проблема несовпадения состояния. Паттерн: рендерить connected state только на клиенте.

// components/wallet-provider.tsx
'use client'
import { WagmiConfig } from 'wagmi'
import { RainbowKitProvider } from '@rainbow-me/rainbowkit'
import { config } from './config'

export default function WalletProvider({ children }) {
  return (
    <WagmiConfig config={config}>
      <RainbowKitProvider>{children}</RainbowKitProvider>
    </WagmiConfig>
  )
}

Сроки и стоимость разработки

Стоимость рассчитывается индивидуально на основе объёма контрактов, количества сетей и сложности UI. Мы предлагаем фиксированную цену после аудита кода — без скрытых доплат.

Гарантии и поддержка

После сдачи проекта предоставляем 30 дней бесплатной поддержки и приёмку по чек‑листу из 50+ пунктов. Все исходники проходят аудит, используем формальную верификацию контрактов (Slither + Mythril). 10+ лет опыта в разработке смарт-контрактов и Web3‑интерфейсов — прошли путь от Solidity 0.4 до 0.8, от Truffle до Foundry. 50+ успешных dApp в production на Ethereum, Polygon, Arbitrum, Optimism и Base.

Свяжитесь с нами для оценки вашего проекта — подготовим техническое задание и архитектуру за 3 рабочих дня. Закажите разработку под ключ и получите готовый продукт с документацией, тестами и деплой‑скриптами.