# Polymarket MCP Server - Tools Reference
This document reflects the current toolset defined in `src/tools/`. All tools return JSON (stringified). On failure, tools return:
```json
{ "error": "message" }
```
General dependency notes:
- `clobTokenIds` come from `list_active_markets`, `list_markets`, or `get_market_details`.
- `conditionId` comes from market objects in Gamma API responses and is used by Data API and realtime subscriptions.
- `event id` comes from `list_events`/`get_event_by_id`.
- `series id` comes from `list_series`/`get_series_by_id`.
---
## Guide
### `get_tool_guide`
- Purpose: Return workflows, dependencies, and examples.
- Parameters: none.
- Returns: Guide object with workflows and notes.
---
## Market Discovery & Search
### `search_markets`
- Purpose: Search markets, events, and profiles by text; limit applies per type.
- Parameters:
- `query` (string, required) — Search query text.
- `limit` (number, optional, default 20, max 100) — Max results per type.
- Returns: Search response with `events`, `markets`, `profiles` arrays.
### `list_active_markets`
- Purpose: List active markets sorted by volume.
- Parameters:
- `limit` (number, optional, default 20, max 100)
- `offset` (number, optional, default 0)
- `order` (string, optional, default `volume24hr`; options: volume24hr, liquidity, startDate, endDate)
- Returns: Array of market objects (includes `clobTokenIds`, `conditionId`).
### `get_trending_markets`
- Purpose: Top-volume markets for a timeframe.
- Parameters:
- `timeframe` (enum: `24h`/`7d`/`30d`, optional, default `24h`)
- `limit` (number, optional, default 10)
- Returns: Array of market objects.
### `get_closing_soon_markets`
- Purpose: Markets closing within N hours.
- Parameters:
- `hours` (number, optional, default 24)
- `limit` (number, optional, default 20)
- Returns: Array of market objects sorted by end date.
### `get_featured_markets`
- Purpose: Featured/promoted markets (fallback to top-volume).
- Parameters:
- `limit` (number, optional, default 10)
- Returns: Array of market objects.
### `filter_markets_by_category`
- Purpose: Filter by tag/category slug.
- Parameters:
- `category` (string, required) — Tag slug (e.g., `politics`).
- `limit` (number, optional, default 20)
- `active_only` (boolean, optional, default true)
- Returns: Array of market objects.
### `get_all_tags`
- Purpose: List all tags.
- Parameters: none.
- Returns: Array of tags (use `id` or `slug`).
### `get_markets_by_tag`
- Purpose: Filter markets by tag id.
- Parameters:
- `tag_id` (string, required) — Must be numeric.
- `limit` (number, optional, default 20, max 100)
- `closed` (boolean, optional, default false)
- Returns: Array of market objects.
### `get_event_markets`
- Purpose: Get markets for an event.
- Parameters:
- `event_slug` (string, optional)
- `event_id` (string, optional)
- Returns: Array of event objects (includes `markets`).
- Notes: Either `event_slug` or `event_id` is required.
### `compare_markets`
- Purpose: Compare multiple markets by slug.
- Parameters:
- `market_slugs` (string[], required, min 2, max 10)
- Returns: Array of market objects or per-slug error entries.
---
## Market Details & Analysis
### `get_market_by_slug`
- Purpose: Market details by slug.
- Parameters:
- `slug` (string, required)
- Returns: Market object (includes `clobTokenIds`, `conditionId`).
### `get_market_by_id`
- Purpose: Market details by numeric id.
- Parameters:
- `id` (string, required)
- Returns: Market object (includes `clobTokenIds`, `conditionId`).
### `list_markets`
- Purpose: List markets with filters.
- Parameters:
- `limit` (number, optional, default 20)
- `offset` (number, optional, default 0)
- `order` (string, optional) — e.g., `volume24hr`, `liquidity`, `startDate`, `endDate`, `createdAt`
- `ascending` (boolean, optional)
- `active` (boolean, optional)
- `closed` (boolean, optional)
- `tag_slug` (string, optional)
- `featured` (boolean, optional)
- `end_date_min` (string, optional, ISO 8601)
- `end_date_max` (string, optional, ISO 8601)
- Returns: Array of market objects.
### `get_market_details`
- Purpose: Market info plus `livePrice` by token id.
- Parameters:
- `slug` (string, required)
- Returns: Market object with `livePrice` map.
- Notes: `livePrice` can be null if tokens are closed or no active CLOB.
### `get_market_volume`
- Purpose: Volume and liquidity by slug.
- Parameters:
- `slug` (string, required)
- Returns: Object with `slug`, `question`, `volume`, `volume24hr`, `liquidity`.
### `analyze_market_opportunity`
- Purpose: Heuristic analysis using volume, liquidity, spread, time-to-close.
- Parameters:
- `slug` (string, required)
- Returns: Analysis object with score, recommendation, and metrics.
- Notes: Uses first `clobTokenIds` entry when available.
---
## Events & Series
### `get_event_by_slug`
- Purpose: Event details by slug.
- Parameters:
- `slug` (string, required)
- Returns: Event object with associated markets.
### `get_event_by_id`
- Purpose: Event details by id.
- Parameters:
- `id` (string, required)
- Returns: Event object with associated markets.
### `list_events`
- Purpose: List events with filters.
- Parameters:
- `limit` (number, optional, default 20)
- `offset` (number, optional, default 0)
- `order` (string, optional)
- `ascending` (boolean, optional)
- `active` (boolean, optional)
- `closed` (boolean, optional)
- `tag` (string, optional)
- Returns: Array of event objects.
### `list_series`
- Purpose: List series with pagination.
- Parameters:
- `limit` (number, optional, default 20)
- `offset` (number, optional, default 0)
- Returns: Array of series objects.
- Notes: Each series can include a large `events` array.
### `get_series_by_id`
- Purpose: Series details by id.
- Parameters:
- `id` (string, required)
- Returns: Series object (includes `events`).
### `get_sports_metadata`
- Purpose: Sports metadata (leagues, seasons, etc.).
- Parameters: none.
- Returns: Sports metadata object.
### `list_teams`
- Purpose: List teams for sports markets.
- Parameters:
- `limit` (number, optional, default 20)
- `offset` (number, optional, default 0)
- Returns: Array of teams.
### `get_valid_sports_market_types`
- Purpose: Valid sports market types.
- Parameters: none.
- Returns: `{ marketTypes: [...] }`.
---
## CLOB Pricing & Orderbook
### `get_current_price`
- Purpose: Bid/ask/mid price for a token.
- Parameters:
- `token_id` (string, required)
- `side` (enum `BUY`/`SELL`/`BOTH`, optional, default `BOTH`)
- Returns: Object with `bid`, `ask`, `mid`.
- Notes: 404 if no active order book.
### `get_midpoint`
- Purpose: Midpoint price for a token.
- Parameters:
- `token_id` (string, required)
- Returns: Object with `mid`.
- Notes: 404 if no active order book.
### `get_spread`
- Purpose: Spread for a token.
- Parameters:
- `token_id` (string, required)
- Returns: Object with `spread`, `bid`, `ask`.
- Notes: 404 if no active order book.
### `get_order_book`
- Purpose: Order book for a token.
- Parameters:
- `token_id` (string, required)
- Returns: Order book object with bids/asks.
- Notes: 404 if no active order book.
### `get_liquidity`
- Purpose: Liquidity metrics for a token.
- Parameters:
- `token_id` (string, required)
- Returns: `{ token_id, bid_liquidity_usd, ask_liquidity_usd, total_liquidity_usd, bid_levels, ask_levels }`
- Notes: 404 if no active order book.
### `get_price_history`
- Purpose: Historical price series.
- Parameters:
- `token_id` (string, required)
- `interval` (string, optional; e.g. `1h`)
- `fidelity` (number, optional)
- `startTs` (number, optional; unix seconds)
- `endTs` (number, optional; unix seconds)
- Returns: `{ history: [{ t, p }, ...] }`
- Notes: `history` can be empty.
### `get_batch_prices`
- Purpose: Batch price lookup for tokens.
- Parameters:
- `token_ids` (string[], required)
- Returns: Object keyed by token id.
- Notes: Empty `{}` if none found.
### `get_batch_spreads`
- Purpose: Batch spread lookup.
- Parameters:
- `token_ids` (string[], required)
- Returns: Object keyed by token id.
- Notes: Empty `{}` if none found.
### `get_batch_order_books`
- Purpose: Batch order books.
- Parameters:
- `token_ids` (string[], required)
- Returns: Array of order book objects.
- Notes: Empty `[]` if none found.
---
## Comments & Profiles
### `list_comments`
- Purpose: List comments for an event/series/market.
- Parameters:
- `limit` (number, optional, default 20)
- `offset` (number, optional, default 0)
- `user` (string, optional)
- `market` (string, optional)
- `order` (string, optional)
- `ascending` (boolean, optional)
- `parent_entity_type` (enum `Event`/`Series`/`market`, optional)
- `parent_entity_id` (number, optional)
- `get_positions` (boolean, optional)
- `holders_only` (boolean, optional)
- Returns: Array of comments.
- Notes: `parent_entity_type` + `parent_entity_id` is required in practice; otherwise Gamma often returns 422.
### `get_comment_by_id`
- Purpose: Get a comment by id.
- Parameters:
- `id` (string, required)
- Returns: Comment object.
### `get_public_profile`
- Purpose: Public user profile by address.
- Parameters:
- `address` (string, required)
- Returns: Profile object.
- Notes: Unknown address may return 404.
---
## Data API (Public Wallet Data)
### `get_positions`
- Purpose: Open positions for a user.
- Parameters:
- `user` (string, required)
- `market` (string, optional; conditionId)
- `limit` (number, optional)
- `offset` (number, optional)
- Returns: Array of positions.
### `get_closed_positions`
- Purpose: Closed/settled positions for a user.
- Parameters: same as `get_positions`.
- Returns: Array of closed positions.
### `get_positions_value`
- Purpose: Total value of user positions.
- Parameters:
- `user` (string, required)
- Returns: Value summary object.
### `get_trades`
- Purpose: Trade history (public).
- Parameters:
- `user` (string, optional)
- `market` (string, optional; conditionId)
- `limit` (number, optional)
- `offset` (number, optional)
- Returns: Array of trades.
### `get_user_activity`
- Purpose: User activity feed.
- Parameters:
- `user` (string, required)
- `limit` (number, optional)
- `offset` (number, optional)
- Returns: Array of activity items.
### `get_top_holders`
- Purpose: Top holders for a market.
- Parameters:
- `market` (string, required; conditionId)
- `limit` (number, optional)
- Returns: Array of holders.
### `get_open_interest`
- Purpose: Open interest for a market.
- Parameters:
- `market` (string, required; conditionId)
- Returns: Open interest object.
### `get_live_volume`
- Purpose: Live volume for an event.
- Parameters:
- `id` (string, required; event id)
- Returns: Live volume object.
### `get_total_traded`
- Purpose: Total number of markets traded by a user.
- Parameters:
- `user` (string, required)
- Returns: Summary object.
### `get_trader_leaderboard`
- Purpose: Trader leaderboard.
- Parameters:
- `limit` (number, optional)
- `offset` (number, optional)
- Returns: Leaderboard array.
### `get_builder_leaderboard`
- Purpose: Builder leaderboard.
- Parameters:
- `limit` (number, optional)
- `offset` (number, optional)
- Returns: Leaderboard array.
### `get_builder_volume_timeseries`
- Purpose: Builder volume timeseries.
- Parameters:
- `limit` (number, optional)
- Returns: Timeseries array.
### `check_health_data_api`
- Purpose: Data API health check.
- Parameters: none.
- Returns: `{ data: "OK" }` on success.
---
## Realtime WebSocket
### `subscribe_market_prices`
- Purpose: Subscribe to price changes by conditionId.
- Parameters:
- `market_ids` (string[], required, min 1)
- `callback_type` (enum `notification`/`log`, optional, default `notification`)
- Returns: `{ subscription_id, status, markets }`
### `subscribe_orderbook_updates`
- Purpose: Subscribe to orderbook updates by `token_ids` (clobTokenIds).
- Parameters:
- `token_ids` (string[], required, min 1)
- `depth` (number, optional, default 10, min 1, max 100)
- `callback_type` (enum `notification`/`log`, optional, default `notification`)
- Returns: `{ subscription_id, status, tokens }`
### `subscribe_market_resolution`
- Purpose: Subscribe to resolution alerts by conditionId.
- Parameters:
- `market_ids` (string[], required, min 1)
- `callback_type` (enum `notification`/`log`, optional, default `notification`)
- Returns: `{ subscription_id, status, markets }`
### `get_realtime_status`
- Purpose: Inspect subscriptions, connection state, stats, and recent messages.
- Parameters: none.
- Returns: Status object (includes `connected`, subscriptions, `recentMessages`).
- Notes: `connected=false` means offline; subscriptions may exist but will not receive events.
### `unsubscribe_realtime`
- Purpose: Unsubscribe from a feed.
- Parameters:
- `subscription_id` (string, required)
- Returns: `{ subscription_id, removed, status }`
---
## Bridge
### `get_supported_assets`
- Purpose: Bridge-supported assets and chains.
- Parameters: none.
- Returns: Asset list.
### `get_bridge_quote`
- Purpose: Bridge quote.
- Parameters:
- `fromAmountBaseUnit` (string, required)
- `fromChainId` (string, required)
- `fromTokenAddress` (string, required)
- `recipientAddress` (string, required)
- `toChainId` (string, required)
- `toTokenAddress` (string, required)
- Returns: Quote object with fee breakdowns.
### `get_bridge_transaction_status`
- Purpose: Bridge status by address.
- Parameters:
- `address` (string, required)
- Returns: `{ transactions: [...] }`
- Notes: Unknown addresses may return 500.
---
## Health
### `check_health_gamma`
- Purpose: Gamma API health check.
- Parameters: none.
- Returns: `"OK"` (plain text).
