Сценарии использования

Типичные цепочки запросов для решения реальных задач.

1. Поиск рынка и получение торговых данных

Это базовый сценарий для любого приложения, работающего с Polymarket. Пользователь вводит поисковый запрос (например, «bitcoin» или «выборы»), система находит подходящие рынки, а затем подтягивает актуальные торговые данные — текущую цену и глубину ордербука. Этот сценарий нужен, когда вы строите интерфейс с поиском рынков, виджет котировок или торгового бота, который должен найти рынок по ключевым словам перед совершением сделки. На основе этой цепочки можно создать поисковый движок по рынкам предсказаний, виджет для встраивания на новостные сайты или telegram-бота, который по запросу выдаёт текущие шансы на событие.

Цепочка: Search → Market → Price + Book

# 1. Найти рынок
GET https://gamma-api.polymarket.com/search?query=bitcoin&type=markets

# 2. Получить детали (извлечь clobTokenIds)
GET https://gamma-api.polymarket.com/markets/{id}

# 3. Получить цену и ордербук
GET https://clob.polymarket.com/price?token_id=TOKEN_ID&side=buy
GET https://clob.polymarket.com/book?token_id=TOKEN_ID

2. Мониторинг портфеля с обогащением

Этот сценарий решает задачу отображения портфеля пользователя в понятном виде. Data API возвращает позиции только с техническими идентификаторами, поэтому для каждой позиции нужно подтянуть человекочитаемое название рынка из Gamma API, а затем получить актуальные цены для расчёта прибыли и убытков. Используйте этот сценарий, когда строите личный кабинет трейдера, портфельный трекер или систему уведомлений о состоянии позиций. На его основе можно создать мобильное приложение для отслеживания инвестиций, дашборд с P&L в реальном времени или сервис email-отчётов о состоянии портфеля.

Цепочка: Positions → Markets (enrich) → Current Prices

# 1. Позиции пользователя
GET https://data-api.polymarket.com/positions?user=0x1234...

# 2. Для каждой позиции — детали рынка (название, описание)
GET https://gamma-api.polymarket.com/markets?condition_id={conditionId}

# 3. Актуальные цены для расчёта P&L
GET https://clob.polymarket.com/prices?token_ids=TOKEN_1,TOKEN_2,...&side=sell

3. Дашборд топ-рынков по объёму

Сценарий предназначен для отображения самых популярных и ликвидных рынков платформы. Сначала запрашиваются события, отсортированные по объёму торгов, затем из них извлекаются идентификаторы токенов, и одним batch-запросом получаются актуальные цены. Этот подход оптимален для главных страниц агрегаторов, где нужно показать «что сейчас горячо» без лишних запросов к API. На основе этой цепочки можно построить главную страницу альтернативного интерфейса Polymarket, новостной виджет с трендовыми предсказаниями или аналитический дашборд для обзора рынка.

Цепочка: Events (sorted) → Markets → Prices

# 1. Топ-20 событий по объёму
GET https://gamma-api.polymarket.com/events?active=true&closed=false&order=volume&ascending=false&limit=20

# 2. Из ответа извлечь markets[].clobTokenIds

# 3. Batch-запрос цен
GET https://clob.polymarket.com/prices?token_ids=T1,T2,T3...&side=buy

4. Построение графика цен

Этот сценарий нужен для визуализации исторической динамики вероятности события. Сначала находится рынок по его slug (человекочитаемому URL), из него извлекается token_id, а затем запрашивается история цен с нужным интервалом и количеством точек. Используйте этот подход, когда нужно показать, как менялись шансы события со временем — это ключевая функция для любого аналитического интерфейса. На основе этой цепочки можно создать интерактивные графики на странице рынка, инструмент технического анализа предсказаний или систему для выявления резких движений цены и их корреляции с новостями.

Цепочка: Market → Token ID → Price History

# 1. Найти рынок по slug
GET https://gamma-api.polymarket.com/events/slug/will-bitcoin-reach-100k

# 2. Извлечь clobTokenIds[0] (Yes токен)

# 3. История цен
GET https://clob.polymarket.com/prices-history?market=TOKEN_ID&interval=1h&fidelity=168

5. Анализ топ-трейдеров

Сценарий позволяет изучить поведение самых успешных трейдеров платформы. Сначала получаем рейтинг лучших за период, затем для интересующих адресов подтягиваем публичный профиль, их текущие позиции и историю сделок. Это полезно для copy-trading стратегий, когда хочется понять, на что ставят профессионалы, или для исследования рынка. На основе этой цепочки можно создать сервис отслеживания «умных денег», систему сигналов на основе действий топ-трейдеров или аналитический отчёт о стратегиях лидеров.

Цепочка: Leaderboard → Profile → Positions → Trades

# 1. Топ трейдеры за неделю
GET https://data-api.polymarket.com/leaderboard?window=week&limit=10

# 2. Профиль трейдера
GET https://gamma-api.polymarket.com/profiles/{address}

# 3. Его позиции
GET https://data-api.polymarket.com/positions?user={address}

# 4. История сделок
GET https://data-api.polymarket.com/trades?user={address}&limit=100

6. Real-time маркет-мейкинг

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

Цепочка: Markets → Books → WebSocket → Orders

# 1. Рынки с наградами для MM
GET https://clob.polymarket.com/rewards/markets

# 2. Текущие ордербуки
GET https://clob.polymarket.com/books?token_ids=T1,T2

# 3. Подписка на обновления
WS: {"type":"subscribe","channel":"market","assets_ids":["T1","T2"]}

# 4. При изменении — выставить ордера
POST https://clob.polymarket.com/order (L2 auth)

7. Анализ ликвидности и спредов

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

Цепочка: Events → Markets → Spread + Midpoint + Book

# 1. Активные события
GET https://gamma-api.polymarket.com/events?active=true&closed=false&limit=50

# 2. Для каждого токена:
GET https://clob.polymarket.com/spread?token_id=TOKEN_ID
GET https://clob.polymarket.com/midpoint?token_id=TOKEN_ID
GET https://clob.polymarket.com/book?token_id=TOKEN_ID

# 3. Агрегировать: глубина книги, спред, ликвидность

8. Категорийный анализ

Этот сценарий позволяет анализировать рынки в разрезе тематических категорий. Сначала получаем идентификатор нужного тега (криптовалюты, политика, спорт), затем запрашиваем все события с этим тегом и агрегируем статистику: суммарный объём, среднюю ликвидность, количество активных рынков. Это полезно для понимания, какие темы сейчас привлекают больше внимания и денег. На основе этой цепочки можно создать аналитику популярности категорий, тематические дайджесты или фильтр рынков по интересам пользователя.

Цепочка: Tags → Events → Markets → Aggregate Volume

# 1. Получить ID тега
GET https://gamma-api.polymarket.com/tags/slug/crypto
# → id: 21

# 2. События по тегу
GET https://gamma-api.polymarket.com/events?tag_id=21&active=true&limit=100

# 3. Агрегировать volume, liquidity, посчитать статистику

# 4. Детали по топ-рынкам
GET https://clob.polymarket.com/books?token_ids=...

9. Спортивные события (серии)

Сценарий специфичен для спортивных рынков, которые организованы в серии (лиги, турниры). Сначала получаем список доступных лиг, затем запрашиваем все активные события конкретной лиги (например, NBA), извлекаем токены всех матчей и подписываемся на live-обновления. Спортивные события требуют особого подхода, потому что шансы меняются очень быстро по ходу матча. На основе этой цепочки можно создать спортивный раздел с live-котировками, приложение для ставок на спорт или систему отслеживания шансов во время трансляции.

Цепочка: Sports → Series → Events → Markets → WebSocket

# 1. Список спортивных лиг
GET https://gamma-api.polymarket.com/sports

# 2. События лиги NBA
GET https://gamma-api.polymarket.com/events?series_id=10345&active=true

# 3. Извлечь token_ids всех матчей

# 4. Подписка на live-обновления
WS: {"type":"subscribe","channel":"market","assets_ids":["T1","T2",...]}

10. Анализ китов

Этот сценарий позволяет отслеживать поведение крупных игроков на конкретном рынке. Сначала получаем список топ-держателей токена (например, Yes), затем для каждого кита подтягиваем профиль, смотрим все его позиции на других рынках и анализируем историю сделок. Это помогает понять, кто стоит за крупными ставками и какова их общая стратегия. На основе этой цепочки можно создать whale-alert систему, инструмент для анализа концентрации позиций или исследование информированности крупных игроков.

Цепочка: Market → Holders → Profiles → Their Positions

# 1. Топ держатели Yes-токена
GET https://data-api.polymarket.com/holders?market=CONDITION_ID&outcome=Yes

# 2. Профили крупнейших
GET https://gamma-api.polymarket.com/profiles/{address}

# 3. Все позиции кита (на каких ещё рынках он)
GET https://data-api.polymarket.com/positions?user={address}

# 4. Его последние сделки
GET https://data-api.polymarket.com/trades?user={address}&limit=50

Общие паттерны

Паттерн	Описание
Gamma → CLOB	Получить метаданные → извлечь token_id → торговые данные
Data + Gamma	Позиции/сделки → обогатить названиями рынков
REST → WebSocket	Начальный snapshot → подписка на обновления
Batch-запросы	/prices, /books с несколькими token_ids