API reference¶

This reference is organized by layer: composition and settings first, then the domain-specific models, service adapters, and exposed MCP servers.

Package and composition¶

Polymarket MCP package.

Purpose:

Provide a typed FastMCP integration for Polymarket market discovery, wallet/activity reads, and public CLOB order book and price reads.

Design:

The package is organized around three layers: 1. typed domain and tool I/O models, 2. service adapters that normalize upstream API payloads, and 3. FastMCP server modules that expose those services as tools and resources.

A parent server composes the domain-specific MCP servers into one unified Polymarket MCP surface.

ivar __all__:: Curated public package API.
ivar __version__:: Package version string.

Examples

from polymarket_mcp import create_server

mcp = create_server()

polymarket_mcp.create_server(settings=None)[source]¶

Build the composed Polymarket FastMCP server.

Use this factory when you want a single MCP surface that exposes discovery, wallet analytics, and public order book functionality together.

The returned server mounts: - gamma for market and event discovery, - data for wallet positions, activity, and trades, - clob for public order book, quote, and history reads.

Resources may also be exposed as generated tools when configured, which is especially useful for tool-centric clients that do not use native MCP resource loading directly.

Parameters:: settings (AppSettings | None) – Optional typed application settings. When omitted, default settings are loaded with load_settings().
Returns:: Fully composed parent FastMCP server.
Return type:: FastMCP
Raises:: None. –

Examples

>>> server = create_server()
>>> server.name
'polymarket'

Parent Polymarket FastMCP server.

Purpose:

Compose the Gamma, Data API, and public CLOB FastMCP servers into a single Polymarket MCP entrypoint.

Design:

The parent server is the primary object that MCP clients should connect to. It mounts the child domain servers under stable prefixes so tool names stay organized and collisions are avoided.

Resource-to-tool exposure is optionally enabled so tool-centric clients, including many LangChain and LangGraph workflows, can still access canonical resources through ordinary tool calls.

ivar create_server:: Factory for the parent composed FastMCP server.
ivar mcp:: Module-level default Polymarket FastMCP server instance.

Examples

from polymarket_mcp.server import create_server

mcp = create_server()
mcp.run()

fastmcp run polymarket_mcp/server.py:mcp

polymarket_mcp.server.create_server(settings=None)[source]¶

Build the composed Polymarket FastMCP server.

Use this factory when you want a single MCP surface that exposes discovery, wallet analytics, and public order book functionality together.

The returned server mounts: - gamma for market and event discovery, - data for wallet positions, activity, and trades, - clob for public order book, quote, and history reads.

Resources may also be exposed as generated tools when configured, which is especially useful for tool-centric clients that do not use native MCP resource loading directly.

Parameters:: settings (AppSettings | None) – Optional typed application settings. When omitted, default settings are loaded with load_settings().
Returns:: Fully composed parent FastMCP server.
Return type:: FastMCP
Raises:: None. –

Examples

>>> server = create_server()
>>> server.name
'polymarket'

polymarket_mcp.server.main()[source]¶

Run the default Polymarket MCP server.

Return type:: None

Shared HTTP utilities for Polymarket API access.

Purpose:: Provide a small async HTTP adapter shared by service modules.
Design:: The adapter returns parsed JSON and maps transport and HTTP failures into package-specific exceptions so upstream failures are easier to diagnose and test.

ivar JsonHttpClient:: Shared async JSON HTTP client.

class polymarket_mcp.http.JsonHttpClient(*, base_url, timeout, domain, user_agent)[source]¶

Bases: object

Minimal async JSON client.

Parameters:

base_url (str) – Base URL for requests.
timeout (float) – Request timeout in seconds.
domain (str) – Logical API domain name.
user_agent (str) – Shared outbound user-agent string.

Returns:

Configured HTTP adapter.

Return type:

JsonHttpClient

Raises:

None. –

async get(path, *, params=None)[source]¶

Issue a GET request and parse JSON.

Parameters:

path (str) – Relative API path.
params (dict[str, Any] | None) – Optional query parameters.

Returns:

Parsed JSON body.

Return type:

Any

Raises:

UpstreamRequestError – If the request fails.

async post(path, *, json_body=None)[source]¶

Issue a POST request and parse JSON.

Parameters:

path (str) – Relative API path.
json_body (dict[str, Any] | None) – Optional JSON request body.

Returns:

Parsed JSON body.

Return type:

Any

Raises:

UpstreamRequestError – If the request fails.

Environment-backed application settings for the Polymarket MCP package.

Purpose:: Centralize configuration for the Polymarket MCP package using pydantic-settings so values can be provided through environment variables without custom parsing code.
Design:: Settings are cached through load_settings() and loaded from the POLYMARKET_MCP_ environment namespace.

ivar AppSettings:: Root settings model.
ivar load_settings:: Cached settings loader.

class polymarket_mcp.settings.AppSettings(_case_sensitive=None, _nested_model_default_partial_update=None, _env_prefix=None, _env_prefix_target=None, _env_file=PosixPath('.'), _env_file_encoding=None, _env_ignore_empty=None, _env_nested_delimiter=None, _env_nested_max_split=None, _env_parse_none_str=None, _env_parse_enums=None, _cli_prog_name=None, _cli_parse_args=None, _cli_settings_source=None, _cli_parse_none_str=None, _cli_hide_none_type=None, _cli_avoid_json=None, _cli_enforce_required=None, _cli_use_class_docs_for_groups=None, _cli_exit_on_error=None, _cli_prefix=None, _cli_flag_prefix_char=None, _cli_implicit_flags=None, _cli_ignore_unknown_args=None, _cli_kebab_case=None, _cli_shortcuts=None, _secrets_dir=None, _build_sources=None, **values)[source]¶

Bases: BaseSettings

Typed application settings.

Parameters:

gamma_base_url (str) – Base URL for the Gamma API.
data_base_url (str) – Base URL for the Data API.
clob_base_url (str) – Base URL for the CLOB API.
request_timeout_seconds (float) – Per-request timeout.
enable_resources_as_tools (bool) – Whether to expose resources as generated tools.
user_agent (str) – Optional shared user-agent string for outbound requests.
_case_sensitive (bool | None)
_nested_model_default_partial_update (bool | None)
_env_prefix (str | None)
_env_prefix_target (EnvPrefixTarget | None)
_env_file (DotenvType | None)
_env_file_encoding (str | None)
_env_ignore_empty (bool | None)
_env_nested_delimiter (str | None)
_env_nested_max_split (int | None)
_env_parse_none_str (str | None)
_env_parse_enums (bool | None)
_cli_prog_name (str | None)
_cli_parse_args (bool | list[str] | tuple[str, ...] | None)
_cli_settings_source (CliSettingsSource[Any] | None)
_cli_parse_none_str (str | None)
_cli_hide_none_type (bool | None)
_cli_avoid_json (bool | None)
_cli_enforce_required (bool | None)
_cli_use_class_docs_for_groups (bool | None)
_cli_exit_on_error (bool | None)
_cli_prefix (str | None)
_cli_flag_prefix_char (str | None)
_cli_implicit_flags (bool | Literal['dual', 'toggle'] | None)
_cli_ignore_unknown_args (bool | None)
_cli_kebab_case (bool | Literal['all', 'no_enums'] | None)
_cli_shortcuts (Mapping[str, str | list[str]] | None)
_secrets_dir (PathType | None)
_build_sources (tuple[tuple[PydanticBaseSettingsSource, ...], dict[str, Any]] | None)

Returns:

Validated settings object.

Return type:

AppSettings

Raises:

ValueError – If any field fails validation.

Examples

>>> settings = AppSettings()
>>> settings.gamma_base_url
'https://gamma-api.polymarket.com'

model_config = {'arbitrary_types_allowed': True, 'case_sensitive': False, 'cli_avoid_json': False, 'cli_enforce_required': False, 'cli_exit_on_error': True, 'cli_flag_prefix_char': '-', 'cli_hide_none_type': False, 'cli_ignore_unknown_args': False, 'cli_implicit_flags': False, 'cli_kebab_case': False, 'cli_parse_args': None, 'cli_parse_none_str': None, 'cli_prefix': '', 'cli_prog_name': None, 'cli_shortcuts': None, 'cli_use_class_docs_for_groups': False, 'enable_decoding': True, 'env_file': '.env', 'env_file_encoding': 'utf-8', 'env_ignore_empty': False, 'env_nested_delimiter': None, 'env_nested_max_split': None, 'env_parse_enums': None, 'env_parse_none_str': None, 'env_prefix': 'POLYMARKET_MCP_', 'env_prefix_target': 'variable', 'extra': 'forbid', 'json_file': None, 'json_file_encoding': None, 'nested_model_default_partial_update': False, 'protected_namespaces': ('model_validate', 'model_dump', 'settings_customise_sources'), 'secrets_dir': None, 'toml_file': None, 'validate_default': True, 'yaml_config_section': None, 'yaml_file': None, 'yaml_file_encoding': None}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

polymarket_mcp.settings.load_settings()[source]¶

Load and cache application settings.

Parameters:: None.
Returns:: Cached settings object.
Return type:: AppSettings
Raises:: None. –

Examples

>>> settings = load_settings()
>>> settings.enable_resources_as_tools in {True, False}
True

Structured error types for the Polymarket MCP package.

Purpose:: Provide domain-specific exceptions and helpers for surfacing upstream API failures with clear, typed context.
Design:: Errors are separated from transport and service code so upstream HTTP issues can be normalized once and handled consistently across the package.

ivar PolymarketError:: Base package exception.
ivar UpstreamRequestError:: Raised when a request to a Polymarket upstream service fails.
ivar UpstreamResponseError:: Raised when a Polymarket upstream service returns malformed data.

exception polymarket_mcp.errors.PolymarketError[source]¶

Bases: Exception

Base package exception.

Parameters:: message – Human-readable error description.
Returns:: None.
Raises:: None. –

exception polymarket_mcp.errors.UpstreamRequestError(*, domain, path, message, status_code=None)[source]¶

Bases: PolymarketError

Raised when a Polymarket upstream request fails.

Parameters:

domain (str) – Upstream API domain such as gamma or clob.
path (str) – Relative request path.
message (str) – Human-readable error description.
status_code (int | None) – Optional upstream HTTP status code.

Returns:

None.

Raises:

None. –

Return type:

None

property status_name: str | None¶

Return a symbolic HTTP status name when available.

Parameters:: None.
Returns:: Symbolic status name such as NOT_FOUND.
Return type:: str | None
Raises:: ValueError – If the status code is invalid.

exception polymarket_mcp.errors.UpstreamResponseError(*, domain, path, message)[source]¶

Bases: PolymarketError

Raised when an upstream response cannot be normalized safely.

Parameters:

domain (str) – Upstream API domain such as gamma or data.
path (str) – Relative request path.
message (str) – Human-readable error description.

Returns:

None.

Raises:

None. –

Return type:

None

Gamma discovery¶

Typed Gamma domain and tool I/O models.

Purpose:

Define normalized market-discovery models for the Polymarket Gamma API and the MCP tool input and output contracts built on top of them.

Design:

The models in this module separate: 1. tool inputs, 2. normalized domain objects, and 3. MCP-friendly output envelopes.

This keeps the service layer stable and avoids leaking arbitrary upstream JSON across the package.

ivar SearchPublicArgs:: Input model for free-text public search.
ivar ListMarketsArgs:: Input model for market listing and filtering.
ivar ListEventsArgs:: Input model for event listing and filtering.
ivar Market:: Normalized Polymarket market model.
ivar Event:: Normalized Polymarket event model.
ivar SearchMarketsOutput:: MCP output envelope for market search.
ivar ListEventsOutput:: MCP output envelope for event listing.
ivar MarketDetailOutput:: MCP output envelope for a single market.
ivar EventDetailOutput:: MCP output envelope for a single event.

class polymarket_mcp.models.gamma.SearchPublicArgs(**data)[source]¶

Bases: BaseModel

Arguments for Gamma public search.

Parameters:

query (str) – Free-text query used to search markets, events, and related public entities.
limit (int) – Maximum number of results to request.

Returns:

Validated search arguments.

Return type:

SearchPublicArgs

Raises:

ValueError – If validation fails.

Examples

>>> args = SearchPublicArgs(query="fed decision", limit=5)
>>> args.limit
5

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.gamma.ListMarketsArgs(**data)[source]¶

Bases: BaseModel

Arguments for listing or filtering Gamma markets.

Parameters:

limit (int) – Maximum number of markets to return.
active (bool) – Whether to prefer active markets.
closed (bool) – Whether to include closed markets.
slug (str | None) – Optional exact market slug filter.
tag_id (int | None) – Optional tag identifier filter.
series_slug (str | None) – Optional series slug filter.

Returns:

Validated market filter arguments.

Return type:

ListMarketsArgs

Raises:

ValueError – If validation fails.

Examples

>>> args = ListMarketsArgs(limit=10, active=True, closed=False)
>>> args.active
True

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.gamma.ListEventsArgs(**data)[source]¶

Bases: BaseModel

Arguments for listing or filtering Gamma events.

Parameters:

limit (int) – Maximum number of events to return.
active (bool) – Whether to prefer active events.
closed (bool) – Whether to include closed events.
slug (str | None) – Optional exact event slug filter.

Returns:

Validated event filter arguments.

Return type:

ListEventsArgs

Raises:

ValueError – If validation fails.

Examples

>>> args = ListEventsArgs(limit=10, active=True, closed=False)
>>> args.closed
False

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.gamma.Market(**data)[source]¶

Bases: BaseModel

Normalized Polymarket market model.

Parameters:

id (str | None) – Optional upstream market identifier.
slug (str) – Canonical market slug from Polymarket URLs.
question (str | None) – Human-readable market question text.
active (bool | None) – Whether the market is currently active.
closed (bool | None) – Whether the market is closed.
liquidity (float | None) – Reported liquidity value when present.
volume (float | None) – Reported volume value when present.
event_slug (str | None) – Parent event slug when known.
clob_token_ids (list[str]) – Associated CLOB token identifiers, if available.
extra_data (Any)

Returns:

Normalized market model.

Return type:

Market

Raises:

ValueError – If validation fails.

Examples

>>> market = Market(slug="fed-decision", question="Will the Fed cut?")
>>> market.slug
'fed-decision'

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.gamma.Event(**data)[source]¶

Bases: BaseModel

Normalized Polymarket event model.

Parameters:

id (str | None) – Optional upstream event identifier.
slug (str) – Canonical event slug from Polymarket URLs.
title (str | None) – Human-readable event title.
active (bool | None) – Whether the event is currently active.
closed (bool | None) – Whether the event is closed.
markets (list[Market]) – Nested normalized markets associated with the event.
extra_data (Any)

Returns:

Normalized event model.

Return type:

Event

Raises:

ValueError – If validation fails.

Examples

>>> event = Event(slug="fed-event", title="Fed Event")
>>> event.title
'Fed Event'

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.gamma.SearchMarketsOutput(**data)[source]¶

Bases: BaseModel

Tool output for public Gamma search.

Parameters:

query (str) – Original search query.
markets (list[Market]) – Matching normalized markets.

Returns:

Search result envelope.

Return type:

SearchMarketsOutput

Raises:

ValueError – If validation fails.

Examples

>>> output = SearchMarketsOutput(query="fed", markets=[])
>>> output.count
0

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property count: int¶

Return the number of matching markets.

Returns:: Number of returned markets.
Return type:: int
Raises:: None. –

Examples

>>> SearchMarketsOutput(query="x", markets=[]).count
0

class polymarket_mcp.models.gamma.ListEventsOutput(**data)[source]¶

Bases: BaseModel

Tool output for Gamma event listing.

Parameters:: events (list[Event]) – Matching normalized events.
Returns:: Event listing envelope.
Return type:: ListEventsOutput
Raises:: ValueError – If validation fails.

Examples

>>> output = ListEventsOutput(events=[])
>>> output.count
0

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property count: int¶

Return the number of returned events.

Returns:: Number of returned events.
Return type:: int
Raises:: None. –

Examples

>>> ListEventsOutput(events=[]).count
0

class polymarket_mcp.models.gamma.MarketDetailOutput(**data)[source]¶

Bases: BaseModel

Tool output for a single market lookup.

Parameters:: market (Market) – The normalized market payload.
Returns:: Single-market envelope.
Return type:: MarketDetailOutput
Raises:: ValueError – If validation fails.

Examples

>>> output = MarketDetailOutput(market=Market(slug="x"))
>>> output.market.slug
'x'

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.gamma.EventDetailOutput(**data)[source]¶

Bases: BaseModel

Tool output for a single event lookup.

Parameters:: event (Event) – The normalized event payload.
Returns:: Single-event envelope.
Return type:: EventDetailOutput
Raises:: ValueError – If validation fails.

Examples

>>> output = EventDetailOutput(event=Event(slug="x"))
>>> output.event.slug
'x'

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Typed Gamma API service adapter.

Purpose:: Fetch Polymarket Gamma data and normalize it into stable domain models.
Design:: This module is the normalization boundary between raw upstream payloads and the rest of the package. MCP-facing code should depend on these typed models rather than raw JSON dictionaries.

ivar GammaService:: Service wrapper for Gamma market-discovery endpoints.

class polymarket_mcp.services.gamma.GammaService(settings)[source]¶

Bases: object

Service wrapper for Polymarket Gamma.

Parameters:: settings (AppSettings) – Application settings.
Returns:: Configured service adapter.
Return type:: GammaService
Raises:: None. –

Examples

>>> from polymarket_mcp.settings import load_settings
>>> service = GammaService(load_settings())
>>> service.__class__.__name__
'GammaService'

async search_public(args)[source]¶

Search Gamma public entities and return normalized markets.

Parameters:: args (SearchPublicArgs) – Structured free-text search arguments.
Returns:: Matching normalized markets.
Return type:: list[Market]
Raises:: httpx.HTTPError – If the upstream request fails.

Examples

service = GammaService(settings)
markets = await service.search_public(
    SearchPublicArgs(query="fed decision", limit=5),
)

async list_markets(args)[source]¶

List Gamma markets as normalized models.

Parameters:: args (ListMarketsArgs) – Structured market filter arguments.
Returns:: Matching normalized markets.
Return type:: list[Market]
Raises:: httpx.HTTPError – If the upstream request fails.

Examples

markets = await service.list_markets(
    ListMarketsArgs(limit=5, active=True),
)

async get_market_by_slug(slug)[source]¶

Get one market by slug.

Parameters:

slug (str) – Canonical market slug from the Polymarket URL.

Returns:

Matching normalized market.

Return type:

Market

Raises:

httpx.HTTPError – If the upstream request fails.
KeyError – If the upstream payload is missing required fields.

Examples

market = await service.get_market_by_slug("fed-decision")

async list_events(args)[source]¶

List Gamma events as normalized models.

Parameters:: args (ListEventsArgs) – Structured event filter arguments.
Returns:: Matching normalized events.
Return type:: list[Event]
Raises:: httpx.HTTPError – If the upstream request fails.

Examples

events = await service.list_events(
    ListEventsArgs(limit=5, active=True),
)

async get_event_by_slug(slug)[source]¶

Get one event by slug.

Parameters:

slug (str) – Canonical event slug from the Polymarket URL.

Returns:

Matching normalized event.

Return type:

Event

Raises:

httpx.HTTPError – If the upstream request fails.
KeyError – If the upstream payload is missing required fields.

Examples

event = await service.get_event_by_slug("fed-event")

async list_tags()[source]¶

List raw Gamma tags.

Parameters:: None.
Returns:: Tag payloads.
Return type:: list[dict[str, Any]]
Raises:: httpx.HTTPError – If the upstream request fails.

async list_series()[source]¶

List raw Gamma series.

Parameters:: None.
Returns:: Series payloads.
Return type:: list[dict[str, Any]]
Raises:: httpx.HTTPError – If the upstream request fails.

async list_sports()[source]¶

List raw Gamma sports metadata.

Parameters:: None.
Returns:: Sports payloads.
Return type:: list[dict[str, Any]]
Raises:: httpx.HTTPError – If the upstream request fails.

async list_teams()[source]¶

List raw Gamma teams metadata.

Parameters:: None.
Returns:: Team payloads.
Return type:: list[dict[str, Any]]
Raises:: httpx.HTTPError – If the upstream request fails.

FastMCP Gamma server for Polymarket market discovery.

Purpose:: Expose Polymarket Gamma discovery capabilities as MCP tools and resources.
Design:: This module is intentionally read-only. Tool docstrings are written for LLM-facing tool selection and explain when each tool should be used, how identifiers should be supplied, and which follow-up tools are likely helpful.

ivar mcp:: FastMCP server instance for Gamma discovery.

async polymarket_mcp.servers.gamma_server.search_public(args)[source]¶

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.

Parameters:: args (SearchPublicArgs) – Structured free-text search arguments.
Returns:: Matching normalized markets and a count field.
Return type:: SearchMarketsOutput
Raises:: httpx.HTTPError – If the upstream Gamma request fails.

Examples

result = await search_public(
    SearchPublicArgs(query="fed decision", limit=5),
)

async polymarket_mcp.servers.gamma_server.list_markets(args)[source]¶

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.

Parameters:: args (ListMarketsArgs) – Structured market filter arguments.
Returns:: Matching normalized markets and a count field.
Return type:: SearchMarketsOutput
Raises:: httpx.HTTPError – If the upstream Gamma request fails.

Examples

result = await list_markets(
    ListMarketsArgs(limit=10, active=True, closed=False),
)

async polymarket_mcp.servers.gamma_server.get_market_by_slug(slug)[source]¶

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.

Parameters:: slug (str) – Canonical market slug from a Polymarket market URL.
Returns:: Single normalized market payload.
Return type:: MarketDetailOutput
Raises:: httpx.HTTPError – If the upstream Gamma request fails.

Examples

result = await get_market_by_slug("fed-decision-in-june")

async polymarket_mcp.servers.gamma_server.list_events(args)[source]¶

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.

Parameters:: args (ListEventsArgs) – Structured event filter arguments.
Returns:: Matching normalized events and a count field.
Return type:: ListEventsOutput
Raises:: httpx.HTTPError – If the upstream Gamma request fails.

Examples

result = await list_events(
    ListEventsArgs(limit=5, active=True, closed=False),
)

async polymarket_mcp.servers.gamma_server.get_event_by_slug(slug)[source]¶

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.

Parameters:: slug (str) – Canonical event slug from a Polymarket event URL.
Returns:: Single normalized event payload.
Return type:: EventDetailOutput
Raises:: httpx.HTTPError – If the upstream Gamma request fails.

Examples

result = await get_event_by_slug("fed-rate-decision")

async polymarket_mcp.servers.gamma_server.list_tags()[source]¶

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.

Parameters:: None.
Returns:: Raw tag payloads from Gamma.
Return type:: list[dict[str, object]]
Raises:: httpx.HTTPError – If the upstream Gamma request fails.

Examples

tags = await list_tags()

async polymarket_mcp.servers.gamma_server.list_series()[source]¶

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.

Parameters:: None.
Returns:: Raw series payloads from Gamma.
Return type:: list[dict[str, object]]
Raises:: httpx.HTTPError – If the upstream Gamma request fails.

Examples

series = await list_series()

async polymarket_mcp.servers.gamma_server.list_sports()[source]¶

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.

Parameters:: None.
Returns:: Raw sports payloads from Gamma.
Return type:: list[dict[str, object]]
Raises:: httpx.HTTPError – If the upstream Gamma request fails.

Examples

sports = await list_sports()

async polymarket_mcp.servers.gamma_server.list_teams()[source]¶

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.

Parameters:: None.
Returns:: Raw team payloads from Gamma.
Return type:: list[dict[str, object]]
Raises:: httpx.HTTPError – If the upstream Gamma request fails.

Examples

teams = await list_teams()

async polymarket_mcp.servers.gamma_server.market_resource(slug)[source]¶

Read a canonical market resource by slug.

Parameters:: slug (str) – Canonical market slug.
Returns:: JSON-encoded normalized market payload.
Return type:: str
Raises:: httpx.HTTPError – If the upstream Gamma request fails.

Examples

text = await market_resource("fed-decision-in-june")

async polymarket_mcp.servers.gamma_server.event_resource(slug)[source]¶

Read a canonical event resource by slug.

Parameters:: slug (str) – Canonical event slug.
Returns:: JSON-encoded normalized event payload.
Return type:: str
Raises:: httpx.HTTPError – If the upstream Gamma request fails.

Examples

text = await event_resource("fed-rate-decision")

Data API¶

Typed Data API domain and tool I/O models.

Purpose:: Define normalized wallet, activity, and trade models for the Polymarket Data API along with MCP input and output contracts.
Design:: These models separate raw upstream payloads from normalized internal models and MCP-facing tool outputs.

ivar WalletArgs:: Input model for wallet-scoped queries.
ivar TradesArgs:: Input model for trade queries.
ivar Position:: Normalized wallet position model.
ivar ActivityItem:: Normalized wallet activity model.
ivar Trade:: Normalized trade model.
ivar WalletPositionsOutput:: MCP output envelope for current positions.
ivar WalletActivityOutput:: MCP output envelope for activity.
ivar TradesOutput:: MCP output envelope for trades.

class polymarket_mcp.models.data.WalletArgs(**data)[source]¶

Bases: BaseModel

Arguments for wallet-scoped Data API queries.

Parameters:: user (str) – Wallet address, usually in 0x... format.
Returns:: Validated wallet arguments.
Return type:: WalletArgs
Raises:: ValueError – If validation fails.

Examples

>>> args = WalletArgs(user="0xabc")
>>> args.user
'0xabc'

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.data.TradesArgs(**data)[source]¶

Bases: BaseModel

Arguments for Data API trade queries.

Parameters:

market (str | None) – Optional market identifier or slug when supported upstream.
user (str | None) – Optional wallet address to scope trades.
limit (int) – Maximum number of trades to return.

Returns:

Validated trade query arguments.

Return type:

TradesArgs

Raises:

ValueError – If validation fails.

Examples

>>> args = TradesArgs(user="0xabc", limit=10)
>>> args.limit
10

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.data.Position(**data)[source]¶

Bases: BaseModel

Normalized wallet position model.

Parameters:

market_slug (str | None)
title (str | None)
outcome (str | None)
size (float | None)
avg_price (float | None)
current_value (float | None)
realized_pnl (float | None)
unrealized_pnl (float | None)
extra_data (Any)

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.data.ActivityItem(**data)[source]¶

Bases: BaseModel

Normalized wallet activity model.

Parameters:

activity_type (str | None)
market_slug (str | None)
title (str | None)
outcome (str | None)
price (float | None)
size (float | None)
timestamp (int | None)
extra_data (Any)

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.data.Trade(**data)[source]¶

Bases: BaseModel

Normalized trade model.

Parameters:

market_slug (str | None)
outcome (str | None)
price (float | None)
size (float | None)
side (str | None)
user (str | None)
timestamp (int | None)
extra_data (Any)

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.data.WalletPositionsOutput(**data)[source]¶

Bases: BaseModel

Tool output for current or closed wallet positions.

Parameters:

user (str)
positions (list[Position])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property count: int¶

Return the number of positions.

Returns:: Number of returned positions.
Return type:: int

class polymarket_mcp.models.data.WalletActivityOutput(**data)[source]¶

Bases: BaseModel

Tool output for wallet activity.

Parameters:

user (str)
activity (list[ActivityItem])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property count: int¶

Return the number of activity rows.

Returns:: Number of returned rows.
Return type:: int

class polymarket_mcp.models.data.TradesOutput(**data)[source]¶

Bases: BaseModel

Tool output for trade queries.

Parameters:: trades (list[Trade])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property count: int¶

Return the number of trades.

Returns:: Number of returned trades.
Return type:: int

Typed Data API service adapter.

Purpose:: Fetch Polymarket Data API payloads and normalize them into stable wallet and trade models.
Design:: This module is the normalization boundary between raw Data API responses and MCP-facing code.

class polymarket_mcp.services.data.DataApiService(settings)[source]¶

Bases: object

Service wrapper for Polymarket Data API.

Parameters:: settings (AppSettings) – Application settings.
Returns:: Configured service adapter.
Return type:: DataApiService

async get_positions(args)[source]¶

Get normalized current positions for a wallet.

Parameters:: args (WalletArgs) – Wallet query arguments.
Returns:: Current wallet positions.
Return type:: list[Position]

async get_closed_positions(args)[source]¶

Get normalized closed positions for a wallet.

Parameters:: args (WalletArgs) – Wallet query arguments.
Returns:: Closed wallet positions.
Return type:: list[Position]

async get_activity(args)[source]¶

Get normalized wallet activity.

Parameters:: args (WalletArgs) – Wallet query arguments.
Returns:: Wallet activity rows.
Return type:: list[ActivityItem]

async get_trades(args)[source]¶

Get normalized trades.

Parameters:: args (TradesArgs) – Trade query arguments.
Returns:: Matching trade rows.
Return type:: list[Trade]

FastMCP Data API server for Polymarket wallet and trade reads.

Purpose:: Expose Polymarket wallet, activity, and trade reads as MCP tools and resources.
Design:: This module is read-only. Tool docstrings are written to help an LLM choose the correct wallet or trade tool and understand the expected identifiers and likely next steps.

async polymarket_mcp.servers.data_server.get_positions(args)[source]¶

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.

Parameters:: args (WalletArgs) – Wallet query arguments.
Returns:: Current normalized positions for the wallet.
Return type:: WalletPositionsOutput
Raises:: httpx.HTTPError – If the upstream Data API request fails.

Examples

result = await get_positions(WalletArgs(user="0xabc"))

async polymarket_mcp.servers.data_server.get_closed_positions(args)[source]¶

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.

Parameters:: args (WalletArgs) – Wallet query arguments.
Returns:: Closed normalized positions for the wallet.
Return type:: WalletPositionsOutput
Raises:: httpx.HTTPError – If the upstream Data API request fails.

Examples

result = await get_closed_positions(WalletArgs(user="0xabc"))

async polymarket_mcp.servers.data_server.get_activity(args)[source]¶

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.

Parameters:: args (WalletArgs) – Wallet query arguments.
Returns:: Normalized activity rows for the wallet.
Return type:: WalletActivityOutput
Raises:: httpx.HTTPError – If the upstream Data API request fails.

Examples

result = await get_activity(WalletArgs(user="0xabc"))

async polymarket_mcp.servers.data_server.get_trades(args)[source]¶

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.

Parameters:: args (TradesArgs) – Trade query arguments.
Returns:: Normalized trade rows.
Return type:: TradesOutput
Raises:: httpx.HTTPError – If the upstream Data API request fails.

Examples

result = await get_trades(TradesArgs(user="0xabc", limit=20))

async polymarket_mcp.servers.data_server.positions_resource(address)[source]¶

Read canonical current positions for a wallet.

Parameters:: address (str) – Wallet address, usually in 0x... format.
Returns:: JSON-encoded current positions payload.
Return type:: str
Raises:: httpx.HTTPError – If the upstream Data API request fails.

Examples

text = await positions_resource("0xabc")

async polymarket_mcp.servers.data_server.activity_resource(address)[source]¶

Read canonical recent activity for a wallet.

Parameters:: address (str) – Wallet address, usually in 0x... format.
Returns:: JSON-encoded wallet activity payload.
Return type:: str
Raises:: httpx.HTTPError – If the upstream Data API request fails.

Examples

text = await activity_resource("0xabc")

Public CLOB¶

Typed CLOB public domain and tool I/O models.

Purpose:: Define normalized public order book, pricing, and history models for the Polymarket CLOB API along with MCP inputs and outputs.

class polymarket_mcp.models.clob.TokenArgs(**data)[source]¶

Bases: BaseModel

Arguments for single-token CLOB reads.

Parameters:: token_id (str)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.clob.TokensArgs(**data)[source]¶

Bases: BaseModel

Arguments for multi-token CLOB reads.

Parameters:: token_ids (list[str])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.clob.PriceHistoryArgs(**data)[source]¶

Bases: BaseModel

Arguments for price history reads.

Parameters:

token_id (str)
interval (str)
start_ts (int | None)
end_ts (int | None)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.clob.OrderBookLevel(**data)[source]¶

Bases: BaseModel

Single normalized order book level.

Parameters:

price (float)
size (float)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.clob.OrderBook(**data)[source]¶

Bases: BaseModel

Normalized public order book.

Parameters:

token_id (str)
bids (list[OrderBookLevel])
asks (list[OrderBookLevel])
midpoint (float | None)
spread (float | None)
timestamp (int | None)
extra_data (Any)

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.clob.PriceQuote(**data)[source]¶

Bases: BaseModel

Normalized price quote.

Parameters:

token_id (str)
price (float | None)
midpoint (float | None)
spread (float | None)
extra_data (Any)

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.clob.PriceHistoryPoint(**data)[source]¶

Bases: BaseModel

Normalized historical price point.

Parameters:

timestamp (int)
price (float)
extra_data (Any)

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.clob.OrderBookOutput(**data)[source]¶

Bases: BaseModel

Tool output for one order book.

Parameters:: book (OrderBook)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.clob.PriceQuoteOutput(**data)[source]¶

Bases: BaseModel

Tool output for one price quote.

Parameters:: quote (PriceQuote)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class polymarket_mcp.models.clob.PriceQuotesOutput(**data)[source]¶

Bases: BaseModel

Tool output for multiple price quotes.

Parameters:: quotes (list[PriceQuote])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property count: int¶

Return the number of quotes.

Returns:: Number of returned quotes.
Return type:: int

class polymarket_mcp.models.clob.PriceHistoryOutput(**data)[source]¶

Bases: BaseModel

Tool output for historical prices.

Parameters:

token_id (str)
interval (str)
points (list[PriceHistoryPoint])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property count: int¶

Return the number of history points.

Returns:: Number of returned points.
Return type:: int

Typed public CLOB service adapter.

Purpose:: Fetch Polymarket public order book and pricing payloads and normalize them into stable models.

class polymarket_mcp.services.clob_public.ClobPublicService(settings)[source]¶

Bases: object

Service wrapper for public CLOB endpoints.

Parameters:: settings (AppSettings) – Application settings.
Returns:: Configured service adapter.
Return type:: ClobPublicService

async get_book(args)[source]¶

Get one normalized order book.

Parameters:: args (TokenArgs) – Single-token lookup arguments.
Returns:: Normalized order book.
Return type:: OrderBook

async get_books(args)[source]¶

Get multiple normalized order books.

Parameters:: args (TokensArgs) – Multi-token lookup arguments.
Returns:: Normalized order books.
Return type:: list[OrderBook]

async get_price(args)[source]¶

Get one normalized price quote.

Parameters:: args (TokenArgs) – Single-token lookup arguments.
Returns:: Normalized price quote.
Return type:: PriceQuote

async get_prices(args)[source]¶

Get multiple normalized price quotes.

Parameters:: args (TokensArgs) – Multi-token lookup arguments.
Returns:: Normalized price quotes.
Return type:: list[PriceQuote]

async get_midpoint(args)[source]¶

Get midpoint data for one token.

Parameters:: args (TokenArgs) – Single-token lookup arguments.
Returns:: Quote with midpoint populated when available.
Return type:: PriceQuote

async get_spread(args)[source]¶

Get spread data for one token.

Parameters:: args (TokenArgs) – Single-token lookup arguments.
Returns:: Quote with spread populated when available.
Return type:: PriceQuote

async get_price_history(args)[source]¶

Get normalized historical prices.

Parameters:: args (PriceHistoryArgs) – History query arguments.
Returns:: Historical price points.
Return type:: list[PriceHistoryPoint]

FastMCP public CLOB server for Polymarket order books and pricing.

Purpose:: Expose read-only order book, quote, and history tools for the Polymarket CLOB API.
Design:: This module is for live market-state reads only. Tool docstrings help an LLM choose the correct tool for books, spot quotes, midpoint/spread, and historical price queries.

async polymarket_mcp.servers.clob_public_server.get_book(args)[source]¶

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.

Parameters:: args (TokenArgs) – Single-token lookup arguments.
Returns:: One normalized order book.
Return type:: OrderBookOutput
Raises:: httpx.HTTPError – If the upstream CLOB request fails.

Examples

result = await get_book(TokenArgs(token_id="123"))

async polymarket_mcp.servers.clob_public_server.get_books(args)[source]¶

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.

Parameters:: args (TokensArgs) – Multi-token lookup arguments.
Returns:: Normalized order books in bulk.
Return type:: list[OrderBookOutput]
Raises:: httpx.HTTPError – If the upstream CLOB request fails.

Examples

result = await get_books(TokensArgs(token_ids=["1", "2"]))

async polymarket_mcp.servers.clob_public_server.get_price(args)[source]¶

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.

Parameters:: args (TokenArgs) – Single-token lookup arguments.
Returns:: One normalized price quote.
Return type:: PriceQuoteOutput
Raises:: httpx.HTTPError – If the upstream CLOB request fails.

Examples

result = await get_price(TokenArgs(token_id="123"))

async polymarket_mcp.servers.clob_public_server.get_prices(args)[source]¶

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.

Parameters:: args (TokensArgs) – Multi-token lookup arguments.
Returns:: Multiple normalized price quotes.
Return type:: PriceQuotesOutput
Raises:: httpx.HTTPError – If the upstream CLOB request fails.

Examples

result = await get_prices(TokensArgs(token_ids=["1", "2"]))

async polymarket_mcp.servers.clob_public_server.get_midpoint(args)[source]¶

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.

Parameters:: args (TokenArgs) – Single-token lookup arguments.
Returns:: Quote object with midpoint populated when available.
Return type:: PriceQuoteOutput
Raises:: httpx.HTTPError – If the upstream CLOB request fails.

Examples

result = await get_midpoint(TokenArgs(token_id="123"))

async polymarket_mcp.servers.clob_public_server.get_spread(args)[source]¶

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.

Parameters:: args (TokenArgs) – Single-token lookup arguments.
Returns:: Quote object with spread populated when available.
Return type:: PriceQuoteOutput
Raises:: httpx.HTTPError – If the upstream CLOB request fails.

Examples

result = await get_spread(TokenArgs(token_id="123"))

async polymarket_mcp.servers.clob_public_server.get_price_history(args)[source]¶

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.

Parameters:: args (PriceHistoryArgs) – Historical price query arguments.
Returns:: Normalized historical price points.
Return type:: PriceHistoryOutput
Raises:: httpx.HTTPError – If the upstream CLOB request fails.

Examples

result = await get_price_history(
    PriceHistoryArgs(token_id="123", interval="1h"),
)

async polymarket_mcp.servers.clob_public_server.book_resource(token_id)[source]¶

Read the canonical order book resource for one token.

Parameters:: token_id (str) – Single CLOB token ID.
Returns:: JSON-encoded order book payload.
Return type:: str
Raises:: httpx.HTTPError – If the upstream CLOB request fails.

Examples

text = await book_resource("123")

async polymarket_mcp.servers.clob_public_server.price_resource(token_id)[source]¶

Read the canonical price resource for one token.

Parameters:: token_id (str) – Single CLOB token ID.
Returns:: JSON-encoded price quote payload.
Return type:: str
Raises:: httpx.HTTPError – If the upstream CLOB request fails.

Examples

text = await price_resource("123")