Сбор данных Polymarket через API для рынков и истории

Сбор данных Polymarket означает получение публичных рыночных записей через API для создания воспроизводимого набора данных для анализа.

В этой задаче важно сразу отделить исследовательский сбор данных от торговли, автоматического размещения ордеров и любых попыток обойти правила платформы. Надежный процесс использует открытые API-эндпоинты рыночных данных, сохраняет необработанные ответы, фиксирует время получения и позволяет повторить выборку без ручных догадок.

Polymarket интересен не только ценами. Для аналитики обычно нужны события, рынки, варианты исхода, идентификаторы токенов или позиций, статусы, ликвидность, объем, best bid, best ask, spread, последняя цена сделки и момент закрытия. Именно здесь начинается дисциплина данных: обнаружение автоматизированного сбора не должно становиться поводом для агрессивного парсинга, если те же данные можно получить через публичный API.

Браузер в таком процессе нужен не как основной источник, а как контрольный слой. Например, когда цена в API отстает от интерфейса, страница уже показывает новое состояние рынка или требуется проверить, как пользователь видит вопрос, варианты исхода и связанные события. Для этого полезно понимать обнаружение headless browser, но еще важнее проектировать сбор так, чтобы обращений к браузеру было как можно меньше.

Какие данные Polymarket стоит собирать через API

Начинать стоит не с кода, а с ответа на вопрос, какую таблицу должен получить аналитик. Если цель заключается в изучении динамики рынков, нужны не все поля подряд, а стабильная схема, где каждая запись имеет понятный источник, время и ключи для присоединения к другим таблицам.

Типичная модель содержит несколько уровней. Event описывает общую тему или группу связанных рынков. Market описывает отдельный рынок с определенными вариантами исхода, часто Yes и No. Outcome описывает сторону рынка, а asset ID используется для запросов цен, книги ордеров или торговых полей в зависимости от версии рынка.

Для большинства исследовательских задач достаточно собирать следующие группы полей:

Такое ядро позволяет сравнивать рынки, строить историю изменения состояний и проверять, не исчезли ли важные рынки из-за фильтров. Если цель похожа на мониторинг цен в масштабе, лучше сразу отделить статическую метаинформацию от частых снимков цены. Вопросы, slug и дата закрытия меняются редко, а bid, ask и last trade могут требовать более частого обновления.

Важное правило: не смешивайте необработанный ответ API и нормализованную таблицу в одном слое. Они выполняют разные функции:

• необработанный ответ нужен для аудита и повторной обработки
• нормализованная таблица нужна для анализа

Если API изменит формат, сохраненные необработанные ответы позволят пересчитать набор данных без повторного запуска полного сбора.

Отдельно стоит зафиксировать границу между данными для исследования и данными для действий:

• исследовательскому сценарию нужны полнота, стабильные ключи и объяснимость для контентного анализа, SEO-исследования, академической работы или внутренней панели мониторинга рисков
• торговый сценарий предъявляет дополнительные требования к задержке, порядку обновлений, доступности книги ордеров, минимальному размеру ордера и соблюдению правил платформы

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

Как работают вместе market data API, CLOB и исторические снимки

В Polymarket есть несколько логических источников. Их стоит разделять в соответствии с ролью в процессе сбора:

• market data endpoints помогают находить события и рынки, читать структуру market object и извлекать поля для аналитики
• CLOB нужен для работы с order book, текущей ликвидностью и торговыми идентификаторами
• повторяющиеся снимки или отдельный источник исторических цен нужны для анализа изменений во времени, если они доступны для конкретного сценария

Такое разделение помогает не смешивать поиск рынков, текущие торговые данные и историю в одном процессе.

Практическая разница такова: market data отвечает на вопрос «что это за рынок», а CLOB отвечает на вопрос «что сейчас происходит с ценами и заявками». Если собирать только market data, можно пропустить небольшие изменения ликвидности. Если собирать только CLOB, без метаданных будет сложно объяснить, к какому событию относится token ID и какой outcome он представляет.

Сбор данных стоит организовать как последовательный процесс, а не как отдельный скрипт. Сначала каталог собирает список релевантных событий и рынков. Затем слой обогащения данных добавляет варианты исхода и asset ID. Далее слой снимков регулярно сохраняет динамические поля. В конце слой контроля качества проверяет пропуски, дубликаты, аномальные цены и неожиданные изменения статусов.

В небольшом проекте весь процесс может работать как задание cron или простая очередь задач. В крупном проекте лучше разделить discovery, обновление и validation, чтобы сбой в одном слое не портил другие данные. Например, если CLOB временно не отвечает, каталог рынков все равно может обновиться, а пропущенные снимки книги ордеров получат отдельный статус.

Еще один полезный прием заключается в том, чтобы не перезаписывать текущее состояние без сохранения истории. Если таблица markets_current всегда содержит только последнюю запись, она удобна для быстрого чтения, но не объясняет, когда именно изменились статус, цена или дата завершения. Поэтому рядом стоит хранить market_snapshots, где каждый запуск оставляет отдельную строку или отдельный необработанный ответ. Текущее состояние можно строить как view поверх истории, а не использовать как единственный источник истины.

Как сопоставлять рынки, outcomes и token ID без разрывов

Самая частая ошибка при сборе данных Polymarket заключается в том, что разработчик берет видимый slug или текст вопроса и использует его как главный ключ. Это удобно для чтения, но ненадежно для объединения таблиц. Slug может быть человекочитаемым, формулировки question могут быть похожими, а одно событие может содержать несколько рынков.

Более стабильная схема сохраняет сразу несколько ключей:

• market_id: для поиска конкретного рынка
• condition_id: для связей с аналитикой, позициями и жизненным циклом рынка
• slug: для ссылки на страницу и ручной проверки
• Asset ID: для конкретного outcome

В ответе API могут встречаться разные поля идентификаторов, включая clobTokenIds, а в отдельных схемах могут присутствовать и другие идентификаторы. Их назначение и пригодность для конкретных запросов следует проверять по документации соответствующего API и фактической структуре ответа. Не стоит выбирать поле только потому, что оно присутствует в ответе API. Правильный выбор зависит от типа рынка и схемы конкретного API, а одна запись может содержать несколько идентификаторов одновременно.

В нормализованной таблице вариантов исхода желательно хранить одну строку на outcome, а не одну строку на рынок. Так проще сохранять цены Yes и No, строить историю и избегать путаницы, когда событие содержит много похожих рынков. Для бинарных рынков сумму цен Yes и No можно использовать как дополнительный диагностический показатель, но она не обязательно равна точно 1, особенно если сравниваются разные типы цен или значения, полученные в разное время.

Минимальный процесс сопоставления выглядит так:

1. Выберите event или список рынков через API рыночных данных.
2. Сохраните event_id, market_id, slug, question и condition_id.
3. Разберите outcomes и outcomePrices, если они пришли как JSON-строки.
4. Проверьте тип рынка и схему соответствующего API, после чего выберите asset ID, соответствующий нужному outcome.
5. Сопоставьте outcome label, price и asset ID по одинаковому индексу.
6. Запишите отдельную строку для каждого outcome.
7. Добавьте время получения ответа и хеш необработанного payload.

Если этот слой реализован аккуратно, дальнейшие задачи упрощаются. Можно рассчитывать изменения для каждого outcome, отслеживать появление новых рынков, находить закрытые рынки и строить собственную историю без ручного разбора страниц.

Для контроля качества полезно хранить небольшую справочную таблицу market_identity. Она содержит не все снимки, а только стабильные поля: ID, slug, condition ID, версию рынка, первое и последнее время наблюдения, а также признак того, были ли найдены outcome asset IDs. Такая таблица помогает быстро увидеть, какие рынки еще не готовы к ценовым запросам, какие изменили статус и какие требуют ручной или браузерной проверки.

Как обрабатывать пагинацию, обновления и временные метки

Публичные списки рынков могут возвращаться частями. Механизм пагинации зависит от конкретного эндпоинта и версии API. Одни интерфейсы используют курсоры, другие могут поддерживать параметры вроде limit и offset. Перед реализацией проверьте документацию выбранного эндпоинта и не предполагайте, что next_cursor и after_cursor работают везде.

Во время каждого прохода стоит сохранять не только записи, но и контекст запроса: endpoint, параметры, cursor, HTTP status, время начала, время завершения, количество записей и признак завершения пагинации. Тогда можно отличить «рынков больше нет» от «запрос завершился ошибкой на третьей странице».

Для обновлений есть два базовых режима. Первый режим ищет новые и измененные рынки с определенным интервалом. Второй делает частые снимки для выбранного набора asset ID. В реальных проектах эти режимы лучше разделять, поскольку поиск новых рынков может выполняться реже, а цены обновляться чаще.

Необходимые временные метки:

• source_created_at для времени создания рынка в источнике
• source_updated_at для времени обновления рынка в источнике
• source_end_date для запланированного завершения
• source_closed_time для фактического закрытия, если поле доступно
• collected_at для времени получения ответа вашим процессом
• normalized_at для времени преобразования необработанного ответа в таблицу

Все временные поля лучше приводить к UTC и сохранять исходное значение рядом. Это особенно важно для рынков, связанных со спортивными событиями, выборами, релизами или короткими временными интервалами крипторынков. Ошибка в часовом поясе может создать ложное впечатление, что API опоздал или рынок закрылся раньше, чем это произошло на самом деле.

Для хранения достаточно начать с PostgreSQL, SQLite или другого понятного хранилища. Если команда работает в Afina, удобно связать контрольные таблицы, необработанные ответы и промежуточные результаты с API и автоматизацией Afina, чтобы браузерная проверка и API-сбор не расходились по разным файлам.

Надежный сбор не должен останавливаться из-за одного неудачного запроса. Для временных ошибок нужны retry с backoff, для постоянных ошибок нужен статус в журнале, а при ограничениях необходимо снижать частоту. Если endpoint начинает возвращать 429 или нестабильные ошибки, правильная реакция состоит не в агрессивном увеличении параллельности, а в снижении нагрузки и переносе части задач.

Планировщик также должен учитывать жизненный цикл рынка. Новые или активные рынки можно проверять чаще, чем давно закрытые. Рынки с близким endDate требуют более внимательного обновления, поскольку именно в этот период меняются ликвидность, статус и итоговые поля. Закрытые записи можно переводить в более холодный режим, но не удалять: они нужны для истории, сравнения и проверки прежних выводов.

Когда нужна браузерная проверка отображаемых данных

Браузерная проверка помогает выяснить, соответствуют ли нормализованные данные тому, что пользователь видит на странице.

Она особенно полезна в следующих нетипичных ситуациях:

• новый рынок только что появился
• книга ордеров еще недоступна
• страница уже показывает обновленный текст
• поля статуса в API выглядят противоречиво

Для выборочного аудита достаточно отобрать небольшое количество рынков, открыть их страницы, прочитать видимые поля и сравнить их с ответами API. Это снижает расходы на браузерные запросы.

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

Во время такого аудита проверяют не только расхождения в статусах и вариантах исхода, но и отображение question и description, особенно после изменений интерфейса, которые могли повлиять на собственный парсер.

Здесь важно не превращать QA в скрытый scraping UI. Если каждый рынок полностью открывается в браузере с высокой частотой, система становится дороже и менее стабильной. Рациональнее проверять выборку, рискованные категории и записи с аномалиями.

Результат браузерной проверки тоже должен быть структурированным. Недостаточно просто сохранить скриншот или отметить запись как проверенную. Лучше записать ui_question, ui_outcomes, ui_price_seen, ui_status_seen, время открытия страницы, URL и версию собственного сценария. Если позже возникнет расхождение, будет понятно, находится ли проблема в API, UI, парсере или моменте создания снимка данных.

Как контролировать полноту, повторы и воспроизводимость сбора

Качество набора данных Polymarket зависит не только от того, ответил ли API. Необходимо уметь объяснить каждую строку, повторить сбор, найти пропущенную страницу и доказать, что цена относится именно к тому outcome, который указан в таблице.

Начните с простых инвариантов. Для рынков с бинарной структурой Yes/No ожидаются два варианта исхода, но эту проверку не следует применять ко всем типам рынков. Если outcome labels и asset IDs сопоставляются по индексу, длины массивов должны совпадать. Для закрытого рынка доступность актуальной книги ордеров нужно проверять отдельно, а не предполагать ее наличие. Для активного рынка отсутствующий asset ID следует отмечать как отдельное состояние, а не молча пропускать.

Полезный контрольный список проверки качества:

• у каждой записи есть market_id, condition_id или явная причина их отсутствия
• у каждого outcome есть label и asset ID, если рынок уже готов к чтению цен
• collected_at не может быть пустым
• endDate не должна быть раньше createdAt
• дубликаты по market_id, outcome_label, collected_at объединяются или помечаются
• хеш ответа сохраняется для аудита повторной обработки
• у пропущенных страниц пагинации есть статус повторной попытки
• выборочная браузерная проверка имеет отдельный результат и время проверки

Для воспроизводимости полезно сохранять версию кода, параметры запуска, список endpoint-ов и настройки частоты. Если через месяц потребуется объяснить резкий скачок volume, команда должна видеть, вызван ли он реальным изменением рынка, изменением фильтра, ошибкой cursor-пагинации или новой схемой API.

Afina подходит как рабочая среда для команд, которые объединяют API-сбор, браузерную проверку и операционные профили. Например, API-скрипт собирает рынки, а контрольный браузерный сценарий открывает только подозрительные записи: новые рынки, рынки без asset ID, резкие изменения bid/ask или записи, где updatedAt изменился без очевидного обновления ценовых полей.

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

Скачать