Збір даних Polymarket через API для ринків та історії

Збір даних Polymarket означає отримання публічних ринкових записів через API, що дає відтворюваний набір для аналізу.

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

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

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

Які дані Polymarket варто збирати через API

Починати варто не з коду, а з відповіді на питання, яку таблицю має отримати аналітик. Якщо ціль полягає у вивченні динаміки ринків, потрібні не всі поля поспіль, а стабільна схема, де кожен запис має зрозуміле джерело, час і ключі для приєднання до інших таблиць.

Типова модель містить кілька рівнів. Event описує загальну тему або групу пов'язаних ринків. Market описує окремий ринок із визначеними варіантами результату, часто Yes і No. Outcome описує сторону ринку, зазвичай Yes або No, а 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, команда повинна бачити, чи це реальна зміна ринку, чи наслідок зміни фільтра, помилки курсорної пагінації або нової схеми API.

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

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

Скачати