Search Polymarket discovery data by free-text topic.

Use this tool when you know a topic or phrase but do not yet know the exact market slug. This is the best first step for queries like "Fed decision", "NBA finals", or "election odds".

Prefer this tool over get_market_by_slug when you only have a natural language description. Prefer list_markets when you already have a more structured filter such as a known tag or exact slug.

The query should be plain human text, not a full URL. The result returns normalized markets that can be followed up with get_market_by_slug for a more precise single-market lookup. If you need live pricing or the order book next, use the CLOB public server after you obtain the market's token IDs.

List or filter markets when you already have structured constraints.

Use this tool when you want market discovery with explicit filters such as active-only results, a tag ID, a series slug, or an exact slug. This is more structured than free-text search.

Prefer this tool over search_public when you already know the filtering dimension. Prefer get_market_by_slug when you already know the exact market slug and want a single canonical result.

A slug should be the Polymarket slug string from the URL, not the full URL itself. This tool returns normalized market objects that may include clob_token_ids for later live-price lookups in the CLOB server.

Fetch one canonical market by its slug.

Use this tool when you already know the exact market slug and want the clearest single-market lookup. This is the preferred tool after a search step has identified the correct market.

Do not use this tool for broad discovery across a topic; use search_public or list_markets first in that case. The slug should be the market slug string from the Polymarket URL path, not the full URL.

This tool is often followed by CLOB book or price lookups if you want live market state, or by event lookup if you want the parent event context.

List or filter event groups that contain one or more markets.

Use this tool when you want broader event-level discovery rather than individual market-level discovery. Events often provide better context for finding clusters of related markets under one theme.

Prefer this tool over list_markets when the user asks about a broader topic and you want grouped context first. Prefer get_event_by_slug when you already know the exact event slug.

Event results may include nested market objects, which makes this tool a good starting point for collecting related market slugs and token IDs.

Fetch one canonical event by its slug.

Use this tool when you already know the event slug and want the full event-level context, including any nested markets returned by Gamma.

Prefer this tool when the question is about an event grouping rather than a single market. If you only know the topic in natural language, use search_public or list_events first.

The slug should be the event slug string from the Polymarket URL path, not the full URL. This tool is especially helpful for finding all related markets under one event before selecting a specific market for deeper analysis.

List available discovery tags for category-based exploration.

Use this tool when you need category metadata such as politics, crypto, or sports-style groupings and want to drive a later structured market query.

Prefer this tool before list_markets when the user wants markets from a category but you do not yet know the numeric tag identifier. Once the tag is known, switch to a structured market listing tool.

Args: None.

Returns: list[dict[str, object]]: Raw tag payloads from Gamma.

Raises: httpx.HTTPError: If the upstream Gamma request fails.

Examples: .. code-block:: python

    tags = await list_tags()

List available series metadata for structured discovery.

Use this tool when the user refers to a known series or recurring grouping and you need series metadata before filtering markets with a series slug.

Prefer this tool when discovery is series-oriented rather than free-text topic-oriented. For general search, use search_public instead.

Args: None.

Returns: list[dict[str, object]]: Raw series payloads from Gamma.

Raises: httpx.HTTPError: If the upstream Gamma request fails.

Examples: .. code-block:: python

    series = await list_series()

List sports metadata for sports-related discovery flows.

Use this tool when the user is exploring sports markets and you need sport metadata before narrowing to teams, events, or markets.

Prefer this tool when the question is explicitly sports-oriented. For a direct market/topic search, search_public is usually a faster first step.

Args: None.

Returns: list[dict[str, object]]: Raw sports payloads from Gamma.

Raises: httpx.HTTPError: If the upstream Gamma request fails.

Examples: .. code-block:: python

    sports = await list_sports()

List team metadata for sports-market exploration.

Use this tool when a sports workflow needs team-level metadata before finding related events or markets.

Prefer this tool after identifying a sport or when the user explicitly asks about teams. For non-sports discovery, use other Gamma tools instead.

Args: None.

Returns: list[dict[str, object]]: Raw team payloads from Gamma.

Raises: httpx.HTTPError: If the upstream Gamma request fails.

Examples: .. code-block:: python

    teams = await list_teams()

Fetch current positions for one wallet.

Use this tool when the user wants to know what a wallet currently holds, which markets it is exposed to, or its current directional footprint.

Prefer this tool over get_activity when the question is about present state rather than historical actions. Do not use this tool if you still need to discover which market exists; that belongs to Gamma tools.

The input should be a wallet address, typically in 0x... format. A common next step is get_activity for recent changes or CLOB/Gamma tools for deeper inspection of the markets referenced by the positions.

Fetch closed positions for one wallet.

Use this tool when the user wants completed or no-longer-open positions, such as reviewing realized exposure or prior bets.

Prefer this tool over get_positions when historical closed exposure is specifically requested. A common next step is get_activity or get_trades to explain how the wallet entered and exited those markets.

The input should be a wallet address, typically in 0x... format.

Fetch recent activity for one wallet.

Use this tool when the user wants to know what a wallet has been doing recently, including buying, selling, or other account-level actions.

Prefer this tool over get_positions when the question is about recent behavior rather than current holdings. Prefer get_trades when the user specifically wants trade rows rather than broader account activity.

The input should be a wallet address, typically in 0x... format. A common next step is to inspect affected markets through Gamma or CLOB tools.

Fetch trade rows for a wallet or market filter.

Use this tool when the user wants trade-level records rather than current holdings or general wallet activity. This is useful for detailed flow analysis and execution history.

Prefer this tool over get_activity when exact trade rows matter. Prefer Gamma tools when you still need to discover the right market first.

The input can include a wallet address, a market filter, or both, depending on what the user already knows. A common next step is to summarize the trade flow or compare it with current positions.

Fetch the current order book for one token.

Use this tool when the user wants live market microstructure such as bids, asks, depth, spread, or liquidity around the current price.

Prefer this tool over get_price when depth matters, not just the current quote. Do not use this tool for market discovery; Gamma tools are better for finding the right market or token first.

The input should be a single CLOB token ID, not a market slug or wallet address. A common next step is to summarize book depth or compare books across multiple tokens.

Fetch current order books for multiple tokens.

Use this tool when the user wants to compare liquidity or depth across several known tokens at once.

Prefer this tool over repeated single-token lookups when you already know multiple token IDs. Do not use this tool if you still need to identify which market or token is relevant.

The input should be a list of CLOB token IDs. A common next step is to rank the returned books by spread, depth, or visible liquidity.

Fetch a current price quote for one token.

Use this tool when the user wants the current quoted price or implied level for a known token but does not need the full order book.

Prefer this tool over get_book when a lightweight spot quote is enough. Prefer get_midpoint or get_spread when the question is specifically about those metrics.

The input should be a single CLOB token ID. A common next step is to compare the quote with historical prices or fetch the full book.

Fetch current price quotes for multiple tokens.

Use this tool when the user wants a quick multi-token quote snapshot without needing full order books for each token.

Prefer this tool over repeated single-token quote calls when several token IDs are already known. Do not use this tool for discovery or wallet-level analysis.

The input should be a list of CLOB token IDs. A common next step is to rank tokens by price or follow up with get_book on the most interesting ones.

Fetch the midpoint for one token.

Use this tool when the user specifically wants the midpoint rather than a full order book or generic quote.

Prefer this tool when reasoning about fair value between best bid and best ask. If depth matters too, use get_book instead.

The input should be a single CLOB token ID.

Fetch the spread for one token.

Use this tool when the user specifically wants transaction tightness, execution quality hints, or a quick liquidity proxy.

Prefer this tool over get_book when only the spread is needed. If the user wants depth and book shape too, use get_book.

The input should be a single CLOB token ID.

Fetch historical price points for one token.

Use this tool when the user wants trend, momentum, or time-series context for a known token.

Prefer this tool over get_price when the question is about change over time rather than the current quote. Do not use this tool if the token ID is not yet known; use Gamma discovery first.

The input should be a single CLOB token ID plus an interval and optional time bounds. A common next step is to summarize the trend or compare recent history with the current quote or spread.

List all available resources and resource templates.

Returns JSON with resource metadata. Static resources have a 'uri' field, while templates have a 'uri_template' field with placeholders like {name}.

Read a resource by its URI.

For static resources, provide the exact URI. For templated resources, provide the URI with template parameters filled in.

Returns the resource content as a string. Binary content is base64-encoded.