Карта API Polymarket: Gamma, CLOB и Data API
Новички теряют день на одной и той же проблеме: у Polymarket не один API, а четыре, и нужный эндпоинт редко оказывается в том, который вы попробовали первым. Вот полная карта.
Первое, что нужно понять об API Polymarket: такой вещи не существует. Есть четыре REST API и четыре потока WebSocket, каждый обслуживает отдельную часть интеграции, у каждого свой хост, свои лимиты запросов и свои требования к аутентификации.
Почти любой вопрос «в API Polymarket нет X» оказывается вопросом «X находится на другом хосте». Вот вся поверхность в одном месте.
Четыре REST API
| API | Базовый URL | Для чего | Аутентификация |
|---|---|---|---|
| Gamma | gamma-api.polymarket.com | Поиск событий и рынков; метаданные | Не нужна |
| CLOB | clob.polymarket.com | Цены, стаканы, выставление ордеров и управление ими | Не нужна для чтения, L1/L2 для торговли |
| Data | data-api.polymarket.com | Позиции, активность, участие в рынках | Не нужна |
| Relayer | relayer-v2.polymarket.com | Отправка транзакций кошелька без необходимости держать POL на газ | Подпись |
Правило маршрутизации за 30 секунд
Какие рынки существуют? → Gamma. Какая цена / хочу торговать → CLOB. Что лежит на этом кошельке? → Data API. Нужно переместить средства без газа → Relayer. Если вы ищете эндпоинт событий в CLOB или стакан в Gamma — в этом и ошибка.
Gamma API — поиск и метаданные
Начинают с Gamma. Он отвечает на вопрос, что существует: события, рынки внутри них, теги, поиск и метаданные, которые нужны для работы со всем остальным, — и, что критично, ID токенов, которые требует каждый эндпоинт CLOB.
/events— список событий, доступна пагинация по ключам/markets— список рынков; а такжеby id,by slug,by token/public-search— поиск по событиям и рынкам/tags,/comments— таксономия и обсуждения- Открытый интерес, текущий объём, крупнейшие держатели
У /markets самый жёсткий лимит на платформе
300 запросов / 10 с — в 13 раз жёстче общего лимита самого Gamma в 4,000 запросов / 10 с. Если вы в цикле листаете полный список рынков, сломается именно это. Кешируйте метаданные рынков — за время жизни рынка они почти не меняются. Все цифры — в справочнике по лимитам запросов.
CLOB API — цены, стаканы и ордера
Сам стакан и единственное место, где можно торговать. Чтение публичное; для торговли нужны учётные данные.
| Группа | Эндпоинты | Аутентификация |
|---|---|---|
| Стакан | /book, /books, /midpoint, /midpoints, /spread, /spreads | Публично |
| Цены | /price, /prices, /prices-history, цена последней сделки, /tick-size, ставка комиссии | Публично |
| Ордера | POST /order, POST /orders, DELETE /order, /orders, /cancel-all, /cancel-market-orders | L2 + подпись кошелька |
| Журнал | /trades, /data/orders, /data/trades, /notifications | L2 |
| Аутентификация | /auth/api-key, /auth/api-keys, /auth/derive-api-key | L1 |
| Аккаунт | баланс и разрешения (получение / обновление) | L2 |
Единственное и множественное число — реальная разница
Почти у каждого эндпоинта рыночных данных CLOB есть пакетный двойник: /book и /books, /price и /prices. Эндпоинты в единственном числе получают 1,500 запросов / 10 с, а во множественном — 500 запросов / 10 с, но один вызов во множественном числе охватывает много токенов, так что пакетные запросы дают гораздо больше данных на единицу бюджета лимита. Практически всегда выбирайте /books, а не цикл по /book.
Data API — позиции и активность
Вопросы о портфеле: /positions, /closed-positions, /trades, а также API пользовательского PNL. Учтите, что это самый жёсткий из трёх основных API — общий лимит 1,000 запросов / 10 с, а у /positions и /closed-positions всего по 150 запросов / 10 с. Он рассчитан на дашборды, а не на циклы опроса.
Четыре потока WebSocket
Если вы опрашиваете /book по таймеру, остановитесь — для этого и существуют потоки. Опрос — самый частый способ впустую сжечь бюджет лимита запросов.
| Поток | URL | Что передаёт |
|---|---|---|
| CLOB Market | wss://ws-subscriptions-clob.polymarket.com/ws/market | Публичные обновления стакана, цен и жизненного цикла рынков |
| CLOB User | wss://ws-subscriptions-clob.polymarket.com/ws/user | Аутентифицированные обновления ордеров и сделок вашего аккаунта |
| RTDS | wss://ws-live-data.polymarket.com | Публичные референсные цены, комментарии, торговая активность |
| Sports | wss://sports-api.polymarket.com/ws | Текущий статус и счёт матчей |
Канал User — тот, о котором забывают. Если ваш бот опрашивает /data/orders, чтобы узнать, исполнился ли ордер, вы тратите бюджет лимита на информацию, которую канал User прислал бы вам в момент события — и с меньшей задержкой.
Аутентификация: L1 и L2
Для публичных рыночных данных учётные данные вообще не нужны — к Gamma, эндпоинтам чтения CLOB и Data API можно обращаться голым curl. Для торговли нужны два уровня, и понимание того, какой есть какой, решает большинство ошибок аутентификации.
| Уровень | Как работает | Назначение |
|---|---|---|
| L1 | Кошелёк подписывает сообщение EIP-712 | Доказать контроль над кошельком; создать или получить учётные данные API |
| L2 | Запросы подписываются учётными данными API с помощью HMAC-SHA256 | Аутентификация приватных запросов к CLOB |
При выставлении ордеров используются оба: L2 аутентифицирует запрос, а подпись кошелька авторизует ордер. Типизированные данные L1 — это полезная нагрузка ClobAuth в chainId: 137 (Polygon) с адресом вашего подписанта, Unix-меткой времени в секундах, nonce (используйте 0, если только вы не управляете несколькими наборами учётных данных) и фиксированной строкой сообщения.
Получение API-ключа
- Подпишите полезную нагрузку EIP-712
ClobAuthсвоим приватным ключом Polygon. - Вызовите
POST /auth/api-keyс заголовками L1, чтобы создать учётные данные. Вы получите ключ, секрет и passphrase — для L2 нужны все три. - При последующих запусках вызывайте
GET /auth/derive-api-key, чтобы получить существующие учётные данные, а не создавать новые.
Две ошибки аутентификации, на которые приходится большинство вопросов в поддержку
Неполные учётные данные — L2 нужны ключ, секрет и passphrase; с двумя из трёх получается корректно сформированный запрос с непроверяемой подписью. Рассинхронизация часов — подпись включает метку времени, поэтому контейнер, у которого часы отстают на несколько секунд, создаёт подписи, которые сервер отклоняет как недействительные. Обе проявляются как Unauthorized/Invalid api key — вот почему это сообщение так часто ищут. См. справочник по ошибкам.
SDK
Polymarket поддерживает единые SDK для TypeScript и Python, которые оборачивают всё перечисленное в типизированный интерфейс и берут на себя пагинацию, форматы ошибок и настройку кошелька. Если вы начинаете с нуля на одном из этих языков, используйте их — вручную реализовывать подпись EIP-712 и HMAC-подпись запросов — верный способ потратить выходные с массой ошибок.
Работайте с REST напрямую, если ваша среда выполнения не покрыта SDK, если нужен точный контроль над подписью, заголовками, повторами или транспортом, или если нужен эндпоинт, который SDK ещё не открыл. Учтите, что речь о единых SDK — если вы на старом клиенте, есть задокументированный путь миграции, и именно старые клиенты порождают многие ошибки с устаревшими учётными данными.
Сколько стоит API Polymarket?
Нисколько. Нет платного тарифа, страницы с ценами на API и подписки — API Polymarket бесплатны, а доступ регулируется лимитами запросов, а не оплатой. Для публичных рыночных данных даже ключ не нужен.
Единственное, что зависит от денег, — это торговые лимиты на подписанта, которые распределяются по уровням в зависимости от 30-дневного объёма вашего кошелька-мейкера — от Standard с 40 токенами ордеров/с до Elite с 600, — но это выделение пропускной способности, а не плата.
Единственное, чего не даст ни один из этих API
Нанеся на карту всю поверхность, полезно знать, чего на ней нет: исторической глубины стакана.
Каждый эндпоинт выше отдаёт текущее состояние. /book возвращает стакан сейчас. /prices-history даёт цены, но не глубину, поэтому не скажет, каким было бы ваше исполнение. А когда рынок разрешается, /book возвращает 404. Остаётся редкий ценовой ряд, примерно одна точка в минуту, который можно получить, указав явно начало и конец. Ни тариф, ни уровень лимитов этого не меняют.
| Вопрос | Можно ли ответить через API Polymarket? |
|---|---|
| Какой стакан прямо сейчас? | Да — /book |
| Какой была цена вчера? | Да, примерно одна точка в минуту, из /prices-history с указанием начала и конца |
| Какой была глубина вчера в 14:03:17? | Нет |
| По какой цене исполнился бы мой ордер на 500 акций? | Нет |
| Покажите рынок, который разрешился на прошлой неделе | Его запись и исход — да (closed=true). Его стакан — нет. |
Из-за этого пробела для бэктестинга стратегии на Polymarket нужен отдельный источник данных, который записывал стакан, пока рынки работали. PolyTest делает именно это для крипторынков Up/Down — 240M+ снимков на конкретный момент времени с 8 уровнями глубины на сторону, метками времени с точностью до долей секунды и сохранёнными, а не удалёнными разрешившимися рынками. Один заголовок, чистый JSON и 3-дневный бесплатный пробный период:
curl -H "X-API-Key: $POLYTEST_KEY" \
"https://api.polytest.io/api/v1/markets?coin=btc&market_type=5m&limit=20"Полный справочник эндпоинтов — в документации PolyTest, или начните бесплатный пробный период.
Часто задаваемые вопросы
- Какие эндпоинты есть у API Polymarket?
- У Polymarket четыре REST API: Gamma (gamma-api.polymarket.com) для событий, рынков и метаданных; CLOB (clob.polymarket.com) для цен, стаканов и торговли; Data API (data-api.polymarket.com) для позиций и активности; и Relayer (relayer-v2.polymarket.com) для транзакций без газа. Также есть четыре потока WebSocket: публичный рыночный канал, аутентифицированный пользовательский канал, данные в реальном времени и спорт.
- API Polymarket бесплатный?
- Да. Нет платного тарифа, подписки или страницы с ценами на API — доступ регулируется лимитами запросов, а не оплатой, и для публичных рыночных данных API-ключ вообще не нужен. Единственное, что масштабируется, — уровень торговой пропускной способности на подписанта, который зависит от 30-дневного торгового объёма вашего кошелька, а не от оплаты.
- Как получить API-ключ Polymarket?
- Подпишите типизированные данные EIP-712 ClobAuth своим приватным ключом Polygon, затем вызовите POST /auth/api-key с заголовками L1, чтобы создать учётные данные. Вы получите ключ, секрет и passphrase — все три нужны для подписи запросов L2. При последующих запусках используйте GET /auth/derive-api-key, чтобы получить существующие учётные данные, а не создавать новые. Для публичных рыночных данных ключ не нужен.
- Чем Gamma API отличается от CLOB API?
- Gamma — для поиска: какие события и рынки существуют, их метаданные и ID токенов, нужные другим эндпоинтам. CLOB — для стакана: текущие цены, глубина стакана, выставление и отмена ордеров. Если нужно найти рынок, используйте Gamma; если нужно узнать цену или торговать, используйте CLOB.
- Есть ли у Polymarket SDK для Python?
- Да. Polymarket поддерживает единые SDK для TypeScript и Python, которые покрывают все четыре REST API типизированным интерфейсом и берут на себя пагинацию, форматы ошибок и настройку кошелька. Для старых клиентов есть задокументированный путь миграции. Работать с REST напрямую имеет смысл, если ваша среда выполнения не поддерживается, нужен точный контроль над подписью и повторами или нужен эндпоинт, который SDK ещё не открыл.
- Можно ли получить историческую глубину стакана через API Polymarket?
- Нет. Каждый эндпоинт Polymarket отдаёт текущее состояние. Эндпоинт /prices-history возвращает ценовой ряд примерно с одной точкой в минуту без стоящей за ним глубины, поэтому не скажет, по какой цене исполнился бы ордер заданного размера, а стакан разрешившегося рынка возвращает 404. Для бэктестинга нужны снимки на конкретный момент времени, записанные, пока рынки работали, — например, архив PolyTest из 240M+ снимков крипторынков Up/Down.
Получите исторические данные, которые Polymarket не хранит
PolyTest записывает крипторынки Polymarket Up/Down в процессе их работы — 240M+ снимков с 8 уровнями глубины стакана, метками времени с точностью до долей секунды и сохранёнными разрешившимися рынками. Начните с 3-дневного бесплатного пробного периода.
Читать дальше
Python SDK для Polymarket в 2026 году (и уход с py-clob-client)
Если ваш код всё ещё импортирует ClobClient из py_clob_client, он построен на устаревшем пакете — как и большая часть кода для Polymarket, который напишет вам ИИ-ассистент. Вот актуальный SDK и как на него перейти.
WebSocket в Polymarket: данные в реальном времени без обрывов
Опрос стакана — самый частый способ впустую сжечь бюджет лимита запросов. Вот четыре потока, параметры подписки, которые никто не документирует, и сбой, при котором ваш бот получает тишину и принимает её за затишье.
Лимиты запросов API Polymarket: полный справочник
Polymarket публикует свои лимиты запросов на нескольких страницах, в двух совершенно разных системах и с 10-секундным окном, которого почти никто не ожидает. Здесь всё это собрано в одном наборе таблиц — плюс что на самом деле происходит, когда вы превышаете лимит.