Polygon Blockchain API: платежи стейблкоинами с низким gas

Совпадение названий заслуживает ещё двух абзацев, потому что половина результатов поиска по «polygon api» указывает на неправильный продукт. Polygon.io — американская компания, продающая потоки рыночных данных: котировки акций, цепочки опционов, свечи форекс. Её API отвечает на вопросы вроде «по какой цене торговалась AAPL вчера». У неё нет блокчейна, токенов и связи с сетью, которую покрывает эта страница.

Polygon-блокчейн, управляемый Polygon Labs, — это совместимая с EVM proof-of-stake сеть, расчитывающая транзакции токенов. Её поверхность API, будь то сырой JSON-RPC или платёжный слой вроде Chaingateway, отвечает на вопросы вроде «пришёл ли USDC клиента» и выполняет инструкции вроде «выплатить 50 USDT». Если вам нужны тикеры и свечи OHLC, закройте эту вкладку и ищите Polygon.io. Если вам нужно перемещать стейблкоины с комиссиями в долях цента, читайте дальше.

Самое частое, что строится на эндпоинтах Polygon от Chaingateway, — это обработка платежей стейблкоинами, и экономика объясняет почему. Каждому переводу ERC-20 нужен gas. В mainnet Ethereum gas за перевод USDT может стоить больше самого небольшого платежа; в Polygon тот же перевод стоит максимум копейки. Взимать с кого-то 2 USDC за цифровой продукт здесь жизнеспособно. В L1 — нет.

Цифры это подтверждают. По состоянию на середину 2026 года трекеры комиссий оценивают типичный перевод USDT в Polygon PoS между десятой долей цента и двумя центами, и он редко превышает несколько центов даже когда сеть загружена. Тот же перевод в mainnet Ethereum варьировался от заметно меньше доллара в спокойные недели до нескольких долларов во время всплесков перегрузки. Разрыв движется вместе с рынками gas, но годами держался на два-три порядка, и для бизнес-модели, построенной на небольших платежах, этот разрыв — вся бизнес-модель.

Типичная касса выглядит так: ваш бэкенд назначает клиенту депозитный адрес и показывает QR-код, а клиент отправляет USDC или USDT с любого кошелька или биржи. Примерно через две секунды перевод в блоке. Срабатывает вебхук, ваш сервер проверяет HMAC-подпись, и заказ переключается на оплаченный. Никаких карточных сетей, никаких chargeback, никакого ожидания банковских часов.

Факты о сети дрейфуют, поэтому вот актуальные с датами. По состоянию на начало июля 2026 года:

Блоки приходят каждые 2–2,3 секунды в среднем, согласно данным о времени блока PolygonScan, а финальность транзакций составляет около 5 секунд. Для депозитов это означает, что разрыв между «клиент нажал отправить» и «безопасно зачислить» измеряется однозначными секундами.

Токен газа — POL. Миграция с MATIC произошла 4 сентября 2024 года по курсу 1:1, с автоматической конвертацией балансов в сети PoS; Polygon сообщила о завершении миграции на 99% примерно через год. Каждая транзакция в Polygon PoS с тех пор платит gas в POL.

Тестовая сеть — Amoy, привязанная к Sepolia Ethereum. Она заменила старую testnet Mumbai, выведенную из эксплуатации 13 апреля 2024 года вместе с сетью Goerli, от которой она зависела. Туториалы, всё ещё упоминающие Mumbai, устарели; поток, который они описывают, обычно работает в Amoy без изменений.

Каждая транзакция Polygon платит gas в POL, токене, заменившем MATIC в сентябре 2024 года по курсу 1:1. Отправляющему адресу нужен небольшой баланс POL для этого; получение токенов ничего не стоит получателю. Цена gas устанавливается автоматически API, поэтому интеграции редко настраивают её вручную.

Балансы в сети PoS автоматически мигрировали с MATIC на POL, так что старая документация, всё ещё говорящая о MATIC, сегодня означает POL. Обычный паттерн — пополненный горячий кошелёк для выплат плюс консолидирующие переводы с депозитных адресов, которые вы пополняете POL по мере необходимости. Поскольку один перевод сжигает лишь крошечную долю одного POL, скромный резерв покрывает большой трафик.

Работает каждый стандартный контракт ERC-20 в Polygon. USDT, USDC и DAI поддерживаются из коробки, включая десятичные знаки. Если вы запустили собственный токен, передайте адрес его контракта тому же эндпоинту, и он будет вести себя как любой другой. NFT и DeFi-токены следуют тому же правилу. Поскольку API идентичен для всех сетей, код, написанный для Polygon, также работает против Ethereum, BSC или Arbitrum, как только вы поменяете сегмент сети в URL.

Пропускная способность достаточно высока для игр и других высокочастотных нагрузок, а затраты достаточно низки, чтобы сценарии использования, вытесненные из Ethereum L1, стали практичными. Крупные потребительские бренды запустили программы лояльности и коллекционные предметы в Polygon, что привлекло массовых пользователей в сеть, а институциональные проекты продолжают выбирать её для расчётов. Для вашей команды порог входа низкий: сеть совместима с EVM, так что всё, что вы знаете об Ethereum, переносится без изменений.

Три запроса покрывают весь платёжный цикл. Точные схемы запроса — в справочнике API; для тестовых прогонов против testnet Polygon (Amoy) добавьте заголовок X-Network: testnet.

Импортируйте существующий кошелёк:

curl -X POST https://app.chaingateway.io/api/v2/polygon/addresses/import \
  -H "Authorization: Bearer $CHAINGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xYourAddress",
    "privatekey": "0xYourPrivateKey",
    "password": "YourWalletPassword"
  }'

Пароль защищает импортированный ключ на платформе; последующие отправки с этого адреса передают пароль вместо сырого ключа.

Отправьте USDT в Polygon (контракт 0xc2132D05D31c914a87C6611C10748AEb04B58e8F):

curl -X POST https://app.chaingateway.io/api/v2/polygon/transactions/erc20 \
  -H "Authorization: Bearer $CHAINGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contractaddress": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
    "from": "0xYourSenderAddress",
    "to": "0xRecipientAddress",
    "amount": 5,
    "password": "YourWalletPassword"
  }'

Получите список прошлых уведомлений вебхука, самый быстрый способ сверить депозиты с вашей базой данных:

curl https://app.chaingateway.io/api/v2/polygon/webhooks/notifications \
  -H "Authorization: Bearer $CHAINGATEWAY_API_KEY"

Те же три вызова напрямую переводятся на PHP, Python или Node с любым стандартным HTTP-клиентом; здесь нет специфичной для Polygon библиотеки для установки.

Вот полный поток приёма, так, как он работает в продакшене, а не в демо.

Сопоставление адресов и атрибуция

Каждый клиент или заказ получает собственный депозитный адрес, хранящийся в одной таблице: ваш внутренний ID, адрес, метка времени. Адрес во входящем payload вебхука — это ключ поиска, привязывающий перевод к заказу, а уникальный индекс на этом столбце гарантирует, что депозит никогда не сможет совпасть с двумя заказами. Если ваша платформа уже управляет ключами, зарегистрируйте их один раз через POST /api/v2/polygon/addresses/import и прикрепите вебхуки, как описано в руководстве по вебхукам.

Проверка и зачисление депозита

Когда клиент платит, перевод оказывается в блоке примерно за две секунды, а уведомление приходит на вашу конечную точку мгновение спустя. Ваш обработчик сначала проверяет HMAC-подпись, находит заказ по адресу, а затем проверяет ещё одну вещь перед зачислением: видел ли он этот хэш транзакции раньше. Храните каждый обработанный хэш с уникальным ограничением и позволяйте базе данных отклонять дубликаты. Доставка, которую пропустил ваш сервер, не пропала: она появляется под GET /api/v2/polygon/webhooks/notifications/failed, а POST /api/v2/polygon/webhooks/notifications/{id}/retry отправляет её снова, так что таймаут на вашей стороне никогда не теряет депозит; идемпотентная обработка — вот что не позволяет воспроизведённому уведомлению зачислить дважды.

Сколько ждать перед отпуском товара

Это бизнес-решение, а не техническое. Финальность в Polygon наступает примерно через 5 секунд после включения, так что даже осторожная политика стоит мало: зачисляйте покупку на 3 USDC по первому уведомлению, удерживайте четырёхзначный депозит, пока ваша проверка сверки против GET /api/v2/polygon/webhooks/notifications не подтвердит его. Этот эндпоинт также служит вашим аудиторским следом; ночная сверка с вашим реестром ловит всё, что мог скрыть двухчасовой сбой.

Выборка депозитных адресов

Депозитные адреса со временем заполняются, поэтому запланируйте выборку: задачу, консолидирующую балансы в ваш казначейский кошелёк тем же вызовом POST /api/v2/polygon/transactions/erc20, с from, установленным в депозитный адрес. Каждому выбираемому адресу нужна крупица POL на gas, что при ценах Polygon достаточно мала, чтобы предзаполнять оптом.

Выводы — поток, где ошибки стоят денег напрямую, и две привычки убирают большую часть риска.

Валидируйте перед постановкой в очередь. Адрес назначения должен декодироваться как 20-байтовое значение 0x, а когда он содержит буквы смешанного регистра, должна совпадать контрольная сумма EIP-55. Отклоняйте сбои на форме, где пользователь может исправить опечатку; API валидирует снова перед трансляцией, но чем раньше поймана ошибка, тем дешевле.

Сначала запись, потом отправка. Создайте одну строку базы данных на выплату с конечным автоматом (queued, sent, confirmed), позвольте воркеру делать ровно один вызов POST /api/v2/polygon/transactions/erc20 на строку и немедленно сохраняйте возвращённый хэш транзакции. Дайте пользователю этот хэш как ссылку на PolygonScan, и он сможет отслеживать собственный вывод вместо обращения в поддержку. Если вызов API истёк по таймауту, не стреляйте снова на автомате: проверьте список уведомлений и ваши собственные записи, чтобы подтвердить, что ничего не ушло, затем повторите обдуманно. Горячему кошельку нужен резерв POL на gas; в Polygon небольшой баланс покрывает тысячи переводов, так что месячного пополнения достаточно.

Amoy — тестовая сеть Polygon, привязанная к Sepolia, работающая с начала 2024 года как замена Mumbai, и каждый эндпоинт на этой странице работает против неё, если добавить один заголовок:

X-Network: testnet

Никакого отдельного аккаунта, второго ключа, других изменений. Тестовый POL приходит из публичных краников Amoy, а адреса и механика точно совпадают с mainnet.

Потратьте тестовый прогон на пути сбоя, а не на счастливый путь. Отключите вашу конечную точку вебхука, отправьте депозит, верните конечную точку, затем прочитайте список неудачных уведомлений и воспроизведите доставку через эндпоинт повтора. Воспроизведите уже обработанное уведомление и убедитесь, что ваша проверка идемпотентности его отклоняет. Отправьте одну и ту же выплату дважды и убедитесь, что ушла только одна. Каждая репетиция занимает минуты в Amoy и предотвращает реальный инцидент позже; когда все три держатся, уберите заголовок, и идентичный код окажется в продакшене.

Ваша конечная точка вебхука питает ваш реестр, так что укрепляйте её как любой другой ввод, связанный с деньгами.

Сначала подпись. Задайте личный секрет в настройках профиля, и каждое уведомление будет нести заголовок X-Signature: base64-кодированный HMAC-SHA256 от txid payload, с ключом из этого секрета. Пересчитайте его и сравните с постоянным временем, прежде чем трогать остальной payload. Всё, что не проходит проверку, получает ответ 4xx без обработки. Примеры проверки на Python, Java, PHP и JavaScript — в руководстве по вебхукам.

Белый список IP от Chaingateway охраняет другое направление: в панели аккаунта вы можете ограничить доступ к API списком IP ваших собственных серверов, так что утёкший API-ключ бесполезен откуда-либо ещё. Он защищает ваш ключ, а не ваш приёмник вебхука — для приёмника проверка подлинности — это подпись. От повторно воспроизведённых уведомлений, которые по определению несут валидные подписи, защищает ваше ограничение по хэшу транзакции; дубликат подтверждается и отбрасывается. Обслуживайте конечную точку только по HTTPS и держите секреты вне URL, потому что URL просачиваются в логи инфраструктуры, которую вы не эксплуатируете.

Ошибки возвращаются как стандартные HTTP-коды статуса с телами JSON, так что ваши обычные паттерны применяются без изменений.

401 — проблема аутентификации: Bearer-токен отсутствует, отозван или введён с опечаткой. Другие ответы 4xx — сбои валидации, неверная контрольная сумма или неизвестное поле, и тело называет виновника; повтор идентичного запроса не может увенчаться успехом. 429 означает, что достигнут лимит запросов тарифа; замедлитесь с увеличивающимися задержками, и посмотрите на страницу тарифов, если вы упираетесь в него при обычной работе, а не всплесками.

Для ответов 5xx повторяйте чтения свободно. Повторяйте отправки только после того, как подтвердили через список уведомлений и ваши собственные строки выплат, что первая попытка не была транслирована. Держите полное тело ответа в логах рядом с запросом, вызвавшим его; эта пара сокращает каждую сессию отладки и обращение в поддержку. Коды статуса и схемы ошибок по эндпоинту — в справочнике API.

Основной паттерн — приём платежей: депозитный адрес на заказ, вебхук на входящий перевод, расчёт за секунды. Продавцы используют это для кассы, а платформы — для пользовательских балансов, отслеживая депозиты и обрабатывая выводы на тысячах адресов через те же эндпоинты.

Низкая стоимость gas открывает паттерны, мёртвые по прибытии где-либо ещё: микровыплаты создателям контента, airdrop и графики вестинга, выполняемые как обычные переводы ERC-20, регулярный биллинг подписки в стейблкоинах и трансграничные платежи, где комиссия — центы вместо процента.