Python SDK для Polymarket в 2026 году (и уход с py-clob-client)

Это важнее обычного обновления версии по одной причине: почти все примеры кода для Polymarket в интернете появились раньше. Статьи в блогах, ответы на Stack Overflow, примеры на GitHub и — поскольку модели обучались на этих материалах — код, который пишет ваш ИИ-ассистент, когда вы просите его сделать бота для Polymarket. Если вы ловили себя на отладке импортов, которых не существует, причина в этом.

Что на самом деле изменилось

Старый подход давал по клиенту на каждый сервис Polymarket. Вы импортировали клиент CLOB для стакана, обращались к Gamma по голому HTTP для поиска рынков, отдельно ходили в Data API за позициями и подключали пакет builder-signing, если нужны были транзакции через relayer. Четыре ментальные модели, четыре формата ошибок, четыре стиля пагинации.

Единый SDK сводит всё это в один клиент, покрывающий все части.

Установка

pip install polymarket-client
# uv add polymarket-client
# poetry add polymarket-client

Четыре клиента — выбирайте осознанно

import asyncio
from polymarket import AsyncPublicClient


async def main() -> None:
    async with AsyncPublicClient() as client:
        pages = client.list_markets(closed=False)
        first = await pages.first_page()
        for market in first.items:
            print(market.slug)


asyncio.run(main())

Публичным данным учётные данные не нужны, так что стройте и тестируйте всё, что можно, на AsyncPublicClient, прежде чем добавлять ключ. Поиск рынков, парсинг, пагинацию, генерацию сигналов и отступ можно отработать, ничем не рискуя.

Пагинация

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

pages = client.list_markets(closed=False, page_size=10)

# 1. Page at a time — use this when you need to control pacing
#    against the tight /markets rate limit (300 req / 10s).
async for page in pages:
    for market in page.items:
        ...

# 2. Item at a time, boundaries ignored.
async for market in pages.iter_items():
    ...

# 3. Manual, resumable.
page = await pages.first_page()
if page.next_cursor:
    nxt = await pages.from_cursor(page.next_cursor).first_page()

Типизированные модели

Методы возвращают настоящие типы, а не словари, и они экспортируются из пакета верхнего уровня:

from polymarket import Event, Market, OrderBook, PriceHistoryPoint

Это наименее эффектное улучшение и, вероятно, самое ценное. В старых клиентах переименованное или отсутствующее поле всплывало как KeyError глубоко в цикле стратегии во время выполнения — часто в продакшене, часто с открытой позицией. Типизированные модели переносят эту ошибку туда, где ей место.

Подписки в реальном времени

subscribe() объединяет несколько потоков в единый поток типизированных событий — это настоящее улучшение по сравнению с ручным управлением несколькими соединениями WebSocket.

from polymarket.streams import MarketSpec, SportsSpec

async with await client.subscribe(
    [MarketSpec(token_ids=[token_id]), SportsSpec()],
) as stream:
    async for event in stream:
        # MarketBookEvent | MarketPriceChangeEvent
        # | MarketLastTradePriceEvent | MarketTickSizeChangeEvent
        # | MarketBestBidAskEvent | NewMarketEvent
        # | MarketResolvedEvent | SportsEvent
        handle(event)

SDK берёт на себя heartbeat, кадрирование и переподключения, которые иначе пришлось бы реализовывать самому, — включая требование отправлять PING каждые 10 секунд при прямом соединении. Подробности — в руководстве по WebSocket.

Выставление ордера

market = await client.get_market(slug="<market-slug>")
token_id = market.outcomes.yes.token_id
assert token_id is not None

response = await client.place_market_order(
    token_id=token_id,
    side="BUY",
    amount="10",     # pUSD to spend, not shares to buy
)

if not response.ok:
    raise RuntimeError(response.message)

# Settlement is on-chain and asynchronous.
hashes = await client.wait_for_order_fill_settlement(response)

# Reconcile rather than assuming.
page = await client.list_positions(market=[market.condition_id]).first_page()
position = next((p for p in page.items if p.token_id == token_id), None)

Миграция с py-clob-client

1. Составьте перечень всех вызовов Polymarket, включая прямые вызовы requests к Gamma и Data API. Они тоже входят в задачу — единый SDK их покрывает, и перенос их в SDK даёт основную пользу.
2. Установите polymarket-client и удалите старые пакеты. Если держать оба, чтобы мигрировать постепенно, легко импортировать не тот символ client.
3. Замените создание клиентов. Один AsyncSecureClient.create(...) заменяет старые клиенты для каждого сервиса и их раздельную работу с учётными данными.
4. Замените доступ к словарю доступом к атрибутам. market["condition_id"] становится market.condition_id. Скучно, но именно здесь проверка типов начинает окупаться.
5. Перепишите пагинацию на интерфейс пагинатора вместо ручных циклов по offset или курсору.
6. Замените самописный код WebSocket на subscribe() и удалите свою логику heartbeat и переподключения.
7. Сначала перезапустите пути только для чтения на публичном клиенте и только потом позволяйте чему-либо выставлять ордера.

Почему ваш ИИ-ассистент ошибается

Стоит сказать об этом прямо, потому что многие попадают сюда именно так. Попросите LLM написать код на Python для Polymarket — и очень часто получите импорты py_clob_client, создание ClobClient(...) и объекты OrderArgs. Модель не сломана — она воспроизводит подавляющее большинство кода для Polymarket, который когда-либо видела, а он появился раньше единых SDK.

• Сначала проверьте строку импорта. from polymarket import ... — актуально; from py_clob_client... — нет.
• Вставьте актуальную документацию в контекст. Polymarket публикует машиночитаемый Markdown на docs.polymarket.com/llms.txt, и у каждой страницы есть вариант .md. Дать модели настоящий материал лучше, чем спорить с ней.
• Не доверяйте уверенному коду, который не запускается. Сгенерированный код часто смешивает старые и новые API в то, чего никогда не существовало.

Та же проблема касается поставщиков данных. Мы публикуем llms.txt, llms-full.txt и спецификацию OpenAPI и разрешаем ИИ-краулеры именно для того, чтобы ассистенты могли писать корректные интеграции с PolyTest без догадок. Некоторые поставщики блокируют эти краулеры — это законный выбор, но тогда ваш ассистент будет додумывать их API.

Чего SDK по-прежнему не умеет

Единый SDK — гораздо более удобный интерфейс к API Polymarket. Но он не меняет того, что в этих API есть, — а того, что создателям ботов нужно чаще всего, в них нет.

Исторического стакана нет. client.get_market() вернёт метаданные разрешившегося рынка, но его стакана уже нет: /book возвращает 404, а prices-history хранит лишь около одной точки в минуту. Ни метод SDK, ни тариф, ни учётные данные стакан не вернут.

Для бэктестинга нужны снимки, записанные, пока рынки работали. PolyTest предоставляет их для крипторынков Up/Down — 240M+ снимков на конкретный момент времени, 8 уровней глубины на сторону, метки времени с точностью до долей секунды, разрешившиеся рынки сохраняются. Это обычный REST API с заголовком X-API-Key, так что он встаёт в тот же асинхронный код рядом с SDK. Начните бесплатно или прочитайте, как создать бота, чтобы пройти весь путь.