Документация Polymarket API: Полное руководство по CLOB, WebSocket и Python для трейдеров

В 2025 году Polymarket окончательно утвердился в роли ликвидного и технологичного рынка предсказаний. Для профессиональных трейдеров и разработчиков использование веб-интерфейса становится "узким горлышком": ручной ввод ордеров не позволяет реализовать сложные стратегии или мгновенно реагировать на волатильность. Выход один — интеграция через API.

В этом руководстве мы детально разберем техническую документацию Polymarket, архитектуру CLOB и способы взаимодействия с платформой на языке Python.

---

1. Экосистема API Polymarket: Gamma vs CLOB

Первое, что нужно усвоить: Polymarket использует две независимые системы API. Они решают разные задачи и имеют разные эндпоинты.

• Gamma API: Это информационный слой. Он отвечает за поиск рынков, получение их названий, категорий, описаний и изображений. Gamma API работает как классический REST сервис и не требует сложной аутентификации для чтения данных.
• CLOB API (Central Limit Order Book): Это торговое ядро. Именно здесь происходит работа с ордерами, стаканами (L2 data) и совершаются сделки. CLOB API требует обязательной аутентификации через подпись сообщений (EIP-712).

Для трейдера наиболее критичен CLOB API, так как он обеспечивает доступ к ликвидности в реальном времени.

2. Gamma API: Исследование рынков

Прежде чем торговать, нужно найти, на что ставить. Gamma API позволяет фильтровать рынки по статусу (активные, закрытые), популярности и тематике (Политика, Спорт, Крипто).

Основные возможности:

• Поиск рынков по ключевым словам.
• Получение правил разрешения споров (Resolution source).
• Просмотр исторических данных о ценах.

Важно помнить: Gamma API имеет строгие лимиты на частоту запросов (Rate Limits). Если вы планируете сканировать тысячи рынков, делайте это через кеширование или с задержками.

3. CLOB API: Архитектура и принципы работы

Polymarket использует гибридную модель децентрализованной биржи. Это означает, что:

1. Матчинг (сопоставление ордеров) происходит оффчейн на серверах Polymarket. Это обеспечивает мгновенное исполнение без ожидания блока в Polygon.
2. Сеттлмент (исполнение сделки) происходит ончейн через смарт-контракты.

Базовый URL для работы с CLOB: https://clob.polymarket.com. Все запросы, связанные с торговлей, направляются именно сюда.

4. Аутентификация и безопасность (L2 Authentication)

Безопасность в Polymarket API построена на криптографических подписях. Вам не нужно передавать пароль или секретный токен в открытом виде.

Как это работает:

1. Бот генерирует специальное сообщение с меткой времени.
2. Вы подписываете это сообщение своим приватным ключом.
3. Сервер проверяет подпись и выдает временный доступ к торговым функциям.

Для работы через Python используются API Credentials: Key, Secret и Passphrase. Эти данные генерируются один раз при инициализации клиента и должны храниться в строгом секрете.

5. Работа с ордербуком (Order Book)

Ордербук (стакан) — это список всех лимитных ордеров на покупку (Bids) и продажу (Asks) для конкретного исхода.

Эндпоинт: GET /book?token_id=... В ответе вы получите массив цен и объемов. Для алгоритмических трейдеров ключевым показателем является Midpoint price — среднее арифметическое между лучшим бидом и лучшим аском. Это наиболее справедливая цена актива в данный момент.

6. WebSocket API: Стрим данных в реальном времени

Для стратегий, где важна скорость, REST API (запросы по расписанию) не подходит из-за задержек. Polymarket предоставляет WebSocket для получения данных "пушем".

URL: wss://ws-subscriptions-clob.polymarket.com/ws/

Типы каналов:

• market: Публичные данные. Обновления стакана, последние сделки. Доступен без авторизации.
• user: Приватные данные. Уведомления об исполнении ваших ордеров, изменении баланса. Требует авторизационного сообщения.

Использование WebSocket позволяет сократить время реакции бота до 20-50 мс.

7. Размещение ордеров: Глубокое погружение

На Polymarket каждый ордер — это сложный объект, который должен быть подписан перед отправкой.

Обязательные поля:

• token_id: Уникальный ID исхода.
• price: Цена (от 0.001 до 0.999).
• size: Количество акций.
• side: BUY или SELL.

После отправки ордер получает статус LIVE. Если цена в стакане совпадает с вашей, ордер переходит в статус FILLED (исполнен).

8. Типы ордеров и параметры исполнения

В 2025 году Polymarket поддерживает только лимитные ордера. Рыночных ордеров в чистом виде нет, но их можно имитировать.

Параметры Time-in-Force:

• GTC (Good Til Cancelled): Ордер висит до исполнения или отмены.
• FOK (Fill or Kill): Требует немедленного исполнения всего объема или отменяется.
• GTD (Good Til Date): Автоматическое удаление после указанного времени.

9. Управление позициями и балансом

API позволяет отслеживать состояние вашего портфеля:

• GET /orders: Список всех активных ордеров.
• GET /balance/allowance: Проверка разрешений для USDC.e.
• GET /trades: История ваших совершенных сделок.

Для расчета текущей прибыли (PnL) обычно используется разница между средней ценой покупки и текущим Midpoint.

10. Технические нюансы: Token ID и Condition ID

Одна из самых частых ошибок новичков — путаница между ID.

• Condition ID относится ко всему рынку (событию).
• Token ID относится к конкретному токену (например, "Да").

В сложных рынках (Multiple Choice) у каждого варианта ответа будет свой Token ID. Получить их список можно через Gamma API.

11. Ошибки и отладка (Error Handling)

• 400 Bad Request: Ошибка в параметрах запроса.
• 401 Unauthorized: Проблема с подписью или ключами.
• 429 Too Many Requests: Превышение лимитов запросов.

Рекомендуется внедрять в код бота экспоненциальную задержку (exponential backoff) при получении 429 ошибки.

12. Библиотеки и инструменты

Лучше использовать готовые SDK:

• Python: py-clob-client — самая стабильная библиотека.
• JavaScript: clob-client-js — для Node.js и фронтенда.

13. Лимиты (Rate Limits) и оптимизация

• Используйте WebSocket вместо бесконечных GET запросов.
• Объединяйте отмену ордеров в один запрос (batch cancel).
• Не сканируйте рынки с нулевой ликвидностью.

14. FAQ по API

"Можно ли торговать без KYC?" — Если аккаунт требует KYC в интерфейсе, API также будет ограничено. "Поддерживается ли Testnet?" — Да, используйте Sandbox Polymarket для тестов. "Где взять исторические данные?" — Через WebSocket или сторонние дата-провайдеры.

15. Заключение

Интеграция с Polymarket API — обязательный шаг для профессионального трейдинга. Система требует понимания криптографических подписей, но обеспечивает высочайшую скорость и безопасность. Начните с установки py-clob-client и получения данных стакана в реальном времени.