Посібник з Polymarket API: CLOB, REST і торгові боти (2026)

Розділ 27 з 33

Коротка версія

Polymarket надає доступ до трьох публічних API: CLOB (торгівля), Gamma (пошук ринків) і Data (аналітика). Офіційний Python SDK - py-clob-client 0.34.6. Автентифікація використовує API key + ECDSA signature, а заявки підписуються через EIP-712 за допомогою проксі-гаманця Polygon. Обмеження швидкості встановлюють ліміт приблизно 60 заявок/хвилину на ключ. Найбільша пастка для нових розробників - проблема зіставлення condition_id → token_id між Gamma і CLOB - розв'яжіть її першою, і все інше стане на свої місця. Приблизно $40M/місяць у винагородах за ліквідність і спреді, захопленому ботами, заробляється на Polymarket, майже повністю користувачами API.

Три окремі сервіси: CLOB (9,000/10s auth) для торгівлі, Gamma (4,000/10s public) для пошуку, Data (1,000/10s public) для історичної аналітики.

Частина 1: Три API

Polymarket чітко розділяє функції між трьома окремими сервісами. Використання правильного API для кожного завдання робить ваш бота швидким, простим і в межах лімітів запитів.

Типовий цикл бота використовує Gamma для пошуку ринків, CLOB для отримання книг заявок і розміщення угод, а Data - для офлайн-бектесту продуктивності стратегії. Уявляйте Gamma як "каталог", CLOB як "біржу", а Data як "сховище".

L1 підписує структуру "ClobAuthDomain" EIP-712 з chainId 137, щоб отримати облікові дані. L2 HMAC-SHA256 підписує кожен наступний запит заголовками POLY_SIGNATURE.

Частина 2: Аутентифікація та модель проксі-гаманця

Polymarket не підписує угоди приватним ключем вашого основного гаманця. Натомість він використовує проксі-гаманець у стилі Gnosis Safe: ваш основний гаманець авторизує проксі, а проксі виконує всі угоди на Polygon. Ваш API-бот взаємодіє з цим проксі.

Що вам потрібно

• API key - згенеруйте в Polymarket Settings → Developer
• Private key - ключ вашого trading wallet (НЕ ваша головна seed-фраза MetaMask)
• Funder address - адреса вашого проксі-гаманця (показано в Settings → Wallet)
• Chain ID - 137 (Polygon mainnet)
• Signature type - 1 (POLY_PROXY, standard for retail users)

Тип підпису 1 (POLY_PROXY) для акаунтів Magic-link, тип 2 (GNOSIS_SAFE) для проксі браузерних гаманців, тип 0 (EOA) для прямих ключів. Funder потрібен для типів 1 і 2.

Частина 3: Встановлення py-clob-client

Офіційний Python SDK - це найшвидший шлях від нуля до першої заявки. Ми використаємо версію 0.34.6, яка є актуальною станом на квітень 2026 року.

# Спочатку створіть віртуальне середовище
python3 -m venv venv
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows

# Встановіть 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"],
)

# Одноразово: отримайте та кешуйте API-облікові дані
client.set_api_creds(client.create_or_derive_api_creds())

Виклик create_or_derive_api_creds() підписує повідомлення вашим приватним ключем і обмінює його на API key, secret та passphrase. Після першого запуску збережіть їх у вашому .env, щоб не звертатися до derive endpoint під час кожного старту.

Gamma /markets повертає outcomePrices, clobTokenIds, volume24hr, tags. Використовуйте tag_slug + order=volume24hr як стандартний запит сканера бота.

Частина 4: Відкриття ринків через Gamma

Перш ніж почати торгувати, вам потрібно знайти ринки, якими варто торгувати. Gamma повертає JSON з усім, що показує інтерфейс Polymarket: питання, результати, ціни, обсяг за 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

Gamma надає conditionId (по одному на ринок); CLOB торгує на token_id (по одному на кожен результат). clobTokenIds - це JSON-encoded масив рядків, індекси якого відповідають результатам.

Частина 5: Відображення condition_id → token_id

Це проблема №1 у розробці ботів для Polymarket. Gamma повертає condition_id (по одному на ринок). Угоди в CLOB використовують token_id (по одному на кожен результат). Вам завжди потрібні обидва.

# Кожен об'єкт ринку Gamma містить 'clobTokenIds' - масив JSON-рядків
import json

market = markets[0]
token_ids = json.loads(market['clobTokenIds']) # ['7410...', '1120...']
yes_token = token_ids[0] # Перший результат
no_token = token_ids[1] # Другий результат

# Альтернатива: запитати CLOB напряму за допомогою condition_id
info = client.get_market(condition_id=market['conditionId'])
yes_token = info['tokens'][0]['token_id']

Пастка порядку результатів

Масив outcomes у Gamma і масив clobTokenIds мають однакові індекси. Завжди читайте мітку результату, а не припускайте, що індекс 0 - це "Yes." На ринках із кількома результатами (NegRisk, Oscars, вибори) індекс 0 може бути "Kamala Harris" або "Taylor Swift" - порядок детермінований, але залежить від конкретного ринку.

Книга повертається як bids у порядку спадання, asks - у порядку зростання. Пройдіть рівні, щоб оцінити ціну виконання для будь-якого цільового номіналу перед надсиланням market-like FAK.

Частина 6: Читання книги заявок

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}")

Книги заявок повертаються як відсортовані масиви (bids за спаданням, asks за зростанням). Кожен рівень має price і size. Щоб оцінити прослизання для більшого ордера, проходьтеся по книзі та накопичуйте номінал, доки не буде виконано ваш цільовий розмір.

GTC залишається в книзі, GTD автоматично скасовується у timestamp, FOK вимагає повного виконання на весь розмір або скасування, FAK бере все, що може, за лімітом і скасовує решту.

Частина 7: Розміщення заявок

Лімітна заявка (GTC - за замовчуванням)

from py_clob_client.clob_types import OrderArgs, OrderType

args = OrderArgs(
 token_id=yes_token,
 price=0.45,
 size=100, # Акції, а не долари. 100 акцій @ $0.45 = $45 максимальна вартість.
 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. Ви ніколи не надсилаєте необроблені приватні ключі через мережу - лише підписані заявки.

Типи заявок

Скасування

# Одна заявка
client.cancel(order_id="0xabc...")

# Скасувати всі заявки на конкретному ринку
client.cancel_market_orders(market=market['conditionId'])

# Ядерний варіант: скасувати все
client.cancel_all()

Частина 8: Потокова передача WebSocket

Опитування Gamma щосекунди є марнотратним, і ви швидко натрапите на обмеження швидкості. Стрічка WebSocket передає оновлення книги заявок і угод у реальному часі, із затримкою менше секунди.

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 (публічна книга заявок + угоди) та /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: Еталонна архітектура бота

Кожен надійний бот Polymarket має ті самі шість компонентів. Створіть кожен як окремий модуль; тримайте їх слабко зв'язаними.

Частина 11: Поширені режими відмов

• Застарілі дані WebSocket - відстежуйте час останнього повідомлення для кожного активу; якщо для активного ринку немає оновлень понад 30 с, примусово оновіть через REST.
• Конфлікти nonce - py-clob-client обробляє order nonce за вас, але якщо ви пишете власний signer, збільшуйте nonce на кожен ордер.
• Недостатній баланс - завжди перевіряйте баланс USDC перед виставленням; книга може показувати ваш ордер, але matching його відхилить.
• Ринок призупинено або завершується - перевіряйте market.active && !market.closed перед торгівлею. Оновлення Gamma відстають від CLOB на кілька секунд під час завершення.
• Невідповідність адаптера NegRisk - ринки з кількома результатами маршрутизуються через окремий адаптер NegRisk. SDK це обробляє, але підтвердьте, що ваш ордер потрапив у правильний venue.

Частина 12: Винагороди за ліквідність через API

Polymarket виплачує ~$5M/місяць у загальних винагородах за ліквідність плюс $5M+/місяць у винагородах для спортивних ринків (див. Винагороди за ліквідність). Переважна більшість іде API-орієнтованим маркетмейкерам, які можуть підтримувати вузькі двосторонні котирування на тисячах ринків.

Формула винагороди заохочує ордери поблизу середньої точки, розмір і час перебування в книзі. Мінімальний цикл маркетмейкінгу:

1. Зчитати книгу заявок для цільового ринку
2. Обчислити справедливу середню точку (наприклад, VWAP топ-3 рівнів з кожного боку)
3. Поставити bid на mid - spread_target/2 і ask на mid + spread_target/2
4. На кожному оновленні WebSocket переновлювати ціну, якщо ваша котирування відхилилася від цілі більш ніж на tick
5. Скасувати й вийти, якщо книга розріджується або з'являються новини

Частина 13: Перехід у production

• Хостинг: VPS за $6/місяць (Hetzner, DigitalOcean) у Європі або US-East достатньо для більшості ботів. Розміщуйте поруч із Polygon RPC, якщо вам потрібна затримка менше 10 мс.
• RPC: використовуйте Alchemy, Infura або QuickNode для надійного Polygon RPC. Безкоштовних тарифів достатньо, доки ви не почнете виставляти сотні ордерів на хвилину.
• Моніторинг: Prometheus + Grafana для метрик; бот Telegram для сповіщень. Логуйте кожен order ID, який ви надсилаєте, і кожне виконання, яке отримуєте.
• Резервні копії: зберігайте стан щохвилини. Якщо VPS помре посеред виконання, ви захочете відновитися за секунди, а не звіряти вручну.
• Податки: ваш logger також є вашим audit trail - див. Податковий гайд.

Частина 14 - Перевірені поради для Polymarket API

Шпаргалка: ситуація -> дія

Що далі?

• Інструменти й ресурси - сторонні панелі, аналітика та джерела даних, які доповнюють API
• Просунуті стратегії - багатоланковий арбітраж і конструкції на кшталт опціонів, придатні для ботів
• Нагороди за ліквідність - точні формули для заробітку на знижках для мейкерів
• Посібник з книги заявок - глибше розуміння того, як читати книгу, перш ніж писати код для роботи з нею
• Глосарій - прості визначення кожного терміна в цьому посібнику