Market data clients

The Gamma and CLOB clients, their async twins, and the caches in front of them.

GammaClient

GammaClient(
    base_url: str = GAMMA_API_BASE,
    timeout: float = 30.0,
    cache: DiskCache | None = None,
)

Stateful Gamma API client with optional TTL disk cache.

base_url instance-attribute

base_url = base_url

fetch_markets

fetch_markets(
    tag: str | None = None,
    keyword: str | None = None,
    limit: int = 100,
    active: bool = True,
    closed: bool = False,
) -> list[dict[str, Any]]

Fetch markets, using cache if configured.

fetch_markets_all

fetch_markets_all(
    tag: str | None = None,
    keyword: str | None = None,
    page_size: int = 100,
    max_results: int = 1000,
    active: bool = True,
    closed: bool = False,
) -> list[dict[str, Any]]

Fetch all markets using offset-based pagination.

Iterates pages until fewer than page_size results are returned or max_results is reached.

Parameters:

Name	Type	Description	Default
tag	str | None	Filter by tag.	None
keyword	str | None	Client-side keyword filter applied after pagination.	None
page_size	int	Results per page (max 100).	100
max_results	int	Hard cap on total results returned.	1000
active	bool	Include active markets.	True
closed	bool	Include closed markets.	False

Returns:

Type	Description
list[dict[str, Any]]	All matching markets up to max_results.

discover_tmax_markets

discover_tmax_markets(
    page_size: int = 100, active: bool = True
) -> list[TmaxMarketInfo]

Paginate through all active markets and return temperature-max markets.

Paginates using offset-based iteration, stopping when a page has fewer than page_size results. Each page is filtered with the temperature-max heuristic and parsed into TmaxMarketInfo.

Parameters:

Name	Type	Description	Default
page_size	int	Results per API page (max 100).	100
active	bool	If True, only fetch active markets.	True

Returns:

Type	Description
list[TmaxMarketInfo]	List of parsed TmaxMarketInfo for every matching market.

close

close() -> None

ClobClient

ClobClient(
    base_url: str = CLOB_API_BASE, timeout: float = 15.0
)

Stateful CLOB read client with connection reuse.

base_url instance-attribute

base_url = base_url

fetch_prices

fetch_prices(token_ids: list[str]) -> dict[str, float]

close

close() -> None

AsyncGammaClient

AsyncGammaClient(
    base_url: str = GAMMA_API_BASE, timeout: float = 30.0
)

Async client for the Polymarket Gamma API (market discovery), on httpx.AsyncClient.

Use it as an async with block, or call :meth:aclose when done.

Parameters:

Name	Type	Description	Default
base_url	str	The Gamma API root.	GAMMA_API_BASE
timeout	float	Per-request timeout, in seconds.	30.0

base_url instance-attribute

base_url = base_url

fetch_markets async

fetch_markets(
    tag: str | None = None,
    keyword: str | None = None,
    limit: int = 100,
    active: bool = True,
    closed: bool = False,
) -> list[dict[str, Any]]

Fetch one page of markets, optionally filtered by tag and by a keyword in the question.

Parameters:

Name	Type	Description	Default
tag	str | None	Gamma tag to filter by.	None
keyword	str | None	Keep only markets whose question contains this (case-insensitive).	None
limit	int	Page size requested from the API.	100
active	bool	Only active markets.	True
closed	bool	Include closed markets.	False

Returns:

Type	Description
list[dict[str, Any]]	The raw market dicts from the API.

Raises:

Type	Description
HTTPStatusError	The API answered with an error status.

discover_tmax_markets async

discover_tmax_markets(
    page_size: int = 100, active: bool = True
) -> list[TmaxMarketInfo]

Paginate through all active markets and return temperature-max markets.

Paginates using offset-based iteration, stopping when a page has fewer than page_size results. Each page is filtered with the temperature-max heuristic and parsed into TmaxMarketInfo.

Parameters:

Name	Type	Description	Default
page_size	int	Results per API page (max 100).	100
active	bool	If True, only fetch active markets.	True

Returns:

Type	Description
list[TmaxMarketInfo]	List of parsed TmaxMarketInfo for every matching market.

aclose async

aclose() -> None

AsyncClobClient

AsyncClobClient(
    base_url: str = CLOB_API_BASE,
    timeout: float = 15.0,
    concurrency: int = 10,
)

Async client for CLOB midpoint prices, on httpx.AsyncClient.

Use it as an async with block, or call :meth:aclose when done.

Parameters:

Name	Type	Description	Default
base_url	str	The CLOB API root.	CLOB_API_BASE
timeout	float	Per-request timeout, in seconds.	15.0
concurrency	int	The most requests in flight at once.	10

base_url instance-attribute

base_url = base_url

fetch_prices async

fetch_prices(token_ids: list[str]) -> dict[str, float]

Fetch the midpoint price of each token concurrently.

Parameters:

Name	Type	Description	Default
token_ids	list[str]	CLOB token ids.	required

Returns:

Type	Description
dict[str, float]	{token_id: midpoint}. A token whose request failed, or that has no midpoint, is
dict[str, float]	absent from the result rather than raising.

aclose async

aclose() -> None

DiskCache

DiskCache(cache_dir: Path | str, ttl_seconds: int = 3600)

A file-backed key-value cache with a time to live: one JSON file per key.

A value expires ttl_seconds after it was set; reading an expired or unreadable entry returns the default. Values must be JSON-serialisable.

Parameters:

Name	Type	Description	Default
cache_dir	Path | str	Where the entries live (created if missing).	required
ttl_seconds	int	How long a value stays fresh.	3600

cache_dir instance-attribute

cache_dir = Path(cache_dir)

ttl_seconds instance-attribute

ttl_seconds = ttl_seconds

get

get(key: str, default: Any = None) -> Any

set

set(key: str, value: Any) -> None

delete

delete(key: str) -> bool

clear

clear() -> int

purge_expired

purge_expired() -> int

TypedCache

TypedCache(cache_dir: Path | str, ttl_seconds: int = 3600)

Bases: DiskCache

Type-safe TTL disk cache.

Drop-in replacement for DiskCache with typed get/set signatures. No runtime overhead — all typing information is erased at runtime.

Parameters:

Name	Type	Description	Default
cache_dir	Path | str	Directory to store cache files.	required
ttl_seconds	int	Time-to-live in seconds (default: 3600).	3600

get

get(key: str, default: Any = None) -> Any

Return typed cached value or default.

set

set(key: str, value: T) -> None

Store a typed value under key.