Руководство по API Полимаркет - соберите первого торгового бота в 2026

Глава 27 из 33

Коротко о главном

Полимаркет предоставляет три публичных API: CLOB (торговля), Gamma (поиск рынков) и Data (аналитика). Официальный Python SDK - py-clob-client 0.34.6. Аутентификация использует API-ключ + подпись ECDSA, ордера подписываются через EIP-712 с помощью proxy-кошелька на Polygon. Лимиты запросов ограничивают вас примерно 60 ордерами в минуту на ключ. Главный подводный камень для новых разработчиков - проблема сопоставления condition_id → token_id между Gamma и CLOB: решите её первой, и всё остальное встанет на места. Каждый месяц на Полимаркет зарабатывается около 40 млн $ на liquidity rewards и спреде, который ловят боты, - почти всё это пользователями API.

Часть 1: Три API

Полимаркет чётко разделяет зоны ответственности между тремя отдельными сервисами. Использование правильного API для каждой задачи сохраняет бота быстрым, простым и в рамках лимитов.

Типичный цикл бота использует Gamma для поиска рынков, CLOB для получения order book и размещения сделок и Data для офлайн-бэктеста стратегии. Думайте о Gamma как о «каталоге», о CLOB как о «бирже», а о Data как о «складе».

Часть 2: Аутентификация и модель proxy-кошелька

Полимаркет не подписывает сделки приватным ключом вашего основного кошелька. Вместо этого используется proxy-кошелёк в стиле Gnosis Safe: ваш основной кошелёк авторизует proxy, а proxy исполняет все сделки на Polygon. Ваш API-бот общается с этим proxy.

Что вам нужно

• API-ключ - создайте в Settings → Developer на Полимаркет
• Приватный ключ - ключ вашего торгового кошелька (НЕ seed-фраза основного MetaMask)
• Адрес funder - адрес вашего proxy-кошелька (показан в Settings → Wallet)
• Chain ID - 137 (Polygon mainnet)
• Тип подписи - 1 (POLY_PROXY, стандарт для розничных пользователей)

Часть 3: Установка py-clob-client

Официальный Python SDK - самый быстрый путь от нуля до первого ордера. Используем версию 0.34.6, актуальную на апрель 2026.

# Create a virtual environment first
python3 -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows

# Install the SDK
pip install py-clob-client==0.34.6 requests websocket-client python-dotenv

Базовая настройка клиента

import os
from dotenv import load_dotenv
from py_clob_client.client import ClobClient
from py_clob_client.constants import POLYGON

load_dotenv()

client = ClobClient(
 host="https://clob.polymarket.com",
 key=os.environ["POLY_PRIVATE_KEY"],
 chain_id=POLYGON, # 137
 signature_type=1, # POLY_PROXY
 funder=os.environ["POLY_FUNDER"],
)

# One-time: derive and cache API credentials
client.set_api_creds(client.create_or_derive_api_creds())

Вызов create_or_derive_api_creds() подписывает сообщение вашим приватным ключом и обменивает его на API-ключ, secret и passphrase. Закэшируйте их в .env после первого запуска, чтобы не обращаться к эндпоинту вывода при каждом старте.

Часть 4: Поиск рынков через Gamma

Прежде чем торговать, нужно найти стоящие рынки. Gamma возвращает JSON со всем, что показывает интерфейс Полимаркет: вопрос, исходы, цены, объём за 24ч, срок, теги и изображения.

import requests

resp = requests.get(
 "https://gamma-api.polymarket.com/markets",
 params={
 "active": "true",
 "closed": "false",
 "tag_slug": "politics",
 "limit": 20,
 "order": "volume24hr",
 "ascending": "false",
 },
 timeout=10,
)
resp.raise_for_status()
markets = resp.json()

for m in markets:
 print(f"{m['slug']:50} Yes ${float(m['outcomePrices'][0]):.3f} Vol24h ${m.get('volume24hr', 0):,.0f}")

Полезные параметры запроса Gamma

Часть 5: Сопоставление condition_id → token_id

Это проблема номер 1 в разработке ботов для Полимаркет. Gamma возвращает condition_id (один на рынок). Сделки CLOB используют token_id (один на исход). Вам всегда нужны оба.

# Each Gamma market object contains 'clobTokenIds' - a JSON string array
import json

market = markets[0]
token_ids = json.loads(market['clobTokenIds']) # ['7410...', '1120...']
yes_token = token_ids[0] # First outcome
no_token = token_ids[1] # Second outcome

# Alternative: ask CLOB directly using condition_id
info = client.get_market(condition_id=market['conditionId'])
yes_token = info['tokens'][0]['token_id']

Подвох с порядком исходов

Массивы outcomes и clobTokenIds в Gamma индексированы совместно. Всегда читайте метку исхода, а не предполагайте, что индекс 0 - это «Yes». На рынках с несколькими исходами (NegRisk, «Оскар», выборы) индекс 0 может быть «Kamala Harris» или «Taylor Swift» - порядок детерминирован, но специфичен для рынка.

Часть 6: Чтение order book

book = client.get_order_book(token_id=yes_token)

best_bid = float(book.bids[0].price) if book.bids else None
best_ask = float(book.asks[0].price) if book.asks else None
mid = (best_bid + best_ask) / 2 if best_bid and best_ask else None
spread = best_ask - best_bid if best_bid and best_ask else None

print(f"Bid {best_bid} Ask {best_ask} Mid {mid:.4f} Spread {spread:.4f}")

Order book возвращается как отсортированные массивы (bids по убыванию, asks по возрастанию). У каждого уровня есть price и size. Чтобы оценить slippage для более крупного ордера, пройдите по стакану и накапливайте объём, пока не наберёте целевой размер.

Часть 7: Размещение ордеров

Лимитный ордер (GTC - по умолчанию)

from py_clob_client.clob_types import OrderArgs, OrderType

args = OrderArgs(
 token_id=yes_token,
 price=0.45,
 size=100, # Shares, not dollars. 100 shares @ $0.45 = $45 max cost.
 side="BUY",
)
signed_order = client.create_order(args)
response = client.post_order(signed_order, OrderType.GTC)
print(response)

Вызов create_order подписывает структурированное сообщение EIP-712 вашим приватным ключом. post_order отправляет его в CLOB. Вы никогда не передаёте сырые приватные ключи по сети - только подписанные ордера.

Типы ордеров

Отмена

# Single order
client.cancel(order_id="0xabc...")

# Cancel all orders on a specific market
client.cancel_market_orders(market=market['conditionId'])

# Nuclear option: cancel everything
client.cancel_all()

Часть 8: Стриминг по WebSocket

Опрашивать Gamma каждую секунду расточительно, и вы быстро упрётесь в лимиты. Фид WebSocket стримит обновления order book и сделок в реальном времени с задержкой меньше секунды.

import json, websocket

WS_URL = "wss://ws-subscriptions-clob.polymarket.com/ws/market"

def on_open(ws):
 ws.send(json.dumps({
 "type": "market",
 "assets_ids": [yes_token, no_token],
 }))

def on_message(ws, message):
 event = json.loads(message)
 if event.get("event_type") == "price_change":
 print(f"{event['market']} {event['side']} {event['price']} size={event['size']}")

ws = websocket.WebSocketApp(
 WS_URL,
 on_open=on_open,
 on_message=on_message,
)
ws.run_forever(ping_interval=20)

Существует два фида: /market (публичный order book и сделки) и /user (ваши собственные события ордеров и исполнений, с аутентификацией). Продакшен-боты обычно подключаются к обоим, автоматически переподключаются при разрыве и считают WebSocket источником истины о текущем состоянии стакана.

Часть 9: Лимиты запросов и backoff

При получении HTTP 429 сервер возвращает заголовок Retry-After. Реализуйте экспоненциальный backoff с jitter:

import random, time

def post_with_backoff(fn, *args, max_retries=6):
 for attempt in range(max_retries):
 try:
 return fn(*args)
 except Exception as e:
 if "429" in str(e):
 sleep = (2 ** attempt) + random.random()
 time.sleep(min(sleep, 30))
 continue
 raise
 raise RuntimeError("Too many retries")

Часть 10: Эталонная архитектура бота

У любого надёжного бота Полимаркет одни и те же шесть компонентов. Стройте каждый как отдельный модуль; держите их слабо связанными.

Часть 11: Частые режимы отказа

• Устаревшие данные WebSocket - отслеживайте время последнего сообщения по каждому активу; если нет обновлений >30с на активном рынке, форсируйте обновление через REST.
• Коллизии nonce - py-clob-client управляет nonce ордеров за вас, но если пишете свой подписчик, инкрементируйте nonce на каждом ордере.
• Недостаточный баланс - всегда проверяйте баланс pUSD перед отправкой; стакан может показывать ваш ордер, но матчинг его отклонит.
• Рынок на паузе или разрешается - проверяйте market.active && !market.closed перед торговлей. Обновления Gamma отстают от CLOB на несколько секунд у момента разрешения.
• Несоответствие адаптера NegRisk - рынки с несколькими исходами идут через отдельный адаптер NegRisk. SDK с этим справляется, но убедитесь, что ваш ордер ушёл в нужный venue.

Часть 12: Liquidity rewards через API

Полимаркет распределяет около 5 млн $/мес на общие liquidity rewards плюс 5 млн $+/мес на награды специально для спорта (см. Liquidity rewards). Подавляющая часть идёт API-маркет-мейкерам, которые держат узкие двусторонние котировки на тысячах рынков.

Формула наград поощряет ордера у середины, размер и время в стакане. Минимальный цикл маркет-мейкинга:

1. Прочитайте order book целевого рынка
2. Вычислите справедливую середину (например, VWAP трёх верхних уровней с каждой стороны)
3. Выставьте bid на mid − spread_target/2 и ask на mid + spread_target/2
4. На каждом обновлении WebSocket переоценивайте цену, если котировка ушла больше чем на тик от цели
5. Отменяйте и выходите, если стакан истончается или выходят новости

Часть 13: Выход в продакшен

• Хостинг: VPS за 6 $/мес (Hetzner, DigitalOcean) в Европе или US-East хватит большинству ботов. Размещайте рядом с Polygon RPC, если нужна задержка меньше 10мс.
• RPC: используйте Alchemy, Infura или QuickNode для надёжного Polygon RPC. Бесплатных тарифов хватает, пока не отправляете сотни ордеров в минуту.
• Мониторинг: Prometheus + Grafana для метрик; Telegram-бот для оповещений. Логируйте каждый отправленный order ID и каждое полученное исполнение.
• Бэкапы: сохраняйте состояние каждую минуту. Если VPS умрёт посреди исполнения, вы захотите продолжить за секунды, а не сверять вручную.
• Налоги: ваш логгер - это и есть аудиторский след (см. Налоговое руководство).

Часть 14 - Проверенные профессиональные советы по API Полимаркет

Шпаргалка: ситуация → действие

Что дальше?

• Инструменты и ресурсы - сторонние дашборды, аналитика и фиды данных, дополняющие API
• Продвинутые стратегии - многоногий арбитраж и опционоподобные конструкции для ботов
• Liquidity rewards - точные формулы для заработка на маркет-мейкерских rebate
• Руководство по order book - более глубокая интуиция для чтения стакана перед написанием кода
• Глоссарий - простые определения каждого термина из этого руководства