Search and Discover Prediction Market Instruments API

The client.markets namespace provides a complete set of discovery methods for finding and resolving prediction market instruments across Molecule’s connected venues — Demo, Polymarket, and Kalshi. Use these methods to run filtered keyword searches, resolve tickers and slugs to instrument IDs, fetch individual instruments, and batch-load multiple instruments in a single round trip.

markets.search

Search for instruments using a keyword query, filtered by venue, status, or category. Returns a paginated list of matching instrument objects. The top-level shortcut client.search_markets() calls this same endpoint.

import os
from molecule import Molecule

client = Molecule(
    base_url=os.environ["MOLECULE_BASE_URL"],
    key_id=os.environ["MOLECULE_KEY_ID"],
    private_key=os.environ["MOLECULE_PRIVATE_KEY"],
)

results = client.markets.search(
    q="election",
    venue="Polymarket",
    status="OPEN",
)

for market in results:
    print(market["instrument_id"], market["title"])

Endpoint: GET /v1/markets/search

string

Free-text keyword query. Matches against market title, description, and ticker symbols.

string

Filter results to a specific venue. One of Demo, Polymarket, or Kalshi.

string

Filter by market lifecycle status — for example OPEN or CLOSED. Omit to return all statuses.

string

Filter by category label, such as Politics or Economics.

string

Opaque pagination cursor returned in a previous response. Pass it to fetch the next page of results.

client.search_markets(**params) is a top-level shortcut that delegates directly to client.markets.search(). Use whichever form fits your call site.

markets.list

List instruments on a venue without requiring a keyword query. Use this to enumerate all available markets on a specific venue or to apply a broad filter.

# All active markets on Kalshi
markets = client.markets.list(venue="Kalshi")

# Broad keyword filter with no venue constraint
markets = client.markets.list(q="inflation")

Endpoint: GET /v1/markets

string

Optional free-text filter. When omitted, the endpoint returns all instruments for the specified venue.

string

Filter to a specific venue. One of Demo, Polymarket, or Kalshi.

markets.match

Resolve a market by a known ticker symbol or URL slug to a single instrument object. Use this when you have a human-readable identifier and need the numeric instrument_id required for order submission and order book requests.

# Resolve by ticker
instrument = client.markets.match(ticker="FAKE-HOUSE-DEM")
print(instrument["instrument_id"], instrument["title"])

# Resolve by slug
instrument = client.markets.match(slug="will-the-fed-cut-rates-in-december")
print(instrument["instrument_id"], instrument["title"])

Endpoint: GET /v1/markets/match

string

Venue-native ticker symbol for the instrument. At least one of ticker or slug is required.

string

URL slug for the market. At least one of ticker or slug is required.

Supply at least one of ticker or slug. Calling markets.match() without either parameter will produce a validation error.

markets.get

Fetch a single instrument by its venue-specific integer or string ID. Use this to retrieve the latest snapshot of a known instrument without re-running a search.

instrument = client.markets.get(42)
print(instrument["title"], instrument["status"])

Endpoint: GET /v1/markets/{id}

integer | string

required

The venue-specific instrument ID. Returned as instrument_id in search and match responses.

markets.lookup

Batch-fetch multiple instruments by their IDs in a single request. Use this instead of issuing multiple sequential get() calls when you need to hydrate a list of known instrument IDs.

markets = client.markets.lookup(instrument_ids=[42, 43, 44])

for market in markets:
    print(market["instrument_id"], market["title"], market["status"])

Endpoint: POST /v1/markets/lookup

integer[]

required

List of venue-specific instrument IDs to retrieve. All IDs are fetched in a single round trip.

markets.lookup() issues a POST request to /v1/markets/lookup. Use it to hydrate a set of instrument IDs you already hold — for example, after reading them from your own database or a previous order record.

markets.venues

Retrieve the list of venues known to the Molecule platform, including their names and current status. Live venues are Demo, Polymarket, and Kalshi.

venues = client.markets.venues()

for venue in venues:
    print(venue["name"], venue["status"])

Endpoint: GET /v1/venues

markets.venue_health

Check the health of each connected venue to determine which are currently reachable and responsive before routing orders.

health = client.markets.venue_health()

for entry in health:
    print(entry["venue"], entry["healthy"], entry.get("latency_ms"))

Endpoint: GET /v1/venues/health

Call venue_health() as part of your startup sequence or before activating an automated strategy to confirm that your target venue is live. If a venue is unhealthy, orders routed to it via DIRECT mode may be rejected or delayed.

Python SDK

Markets

Orders

Portfolio

WebSockets

Search and Discover Prediction Market Instruments API

markets.search

markets.list

markets.match

markets.get

markets.lookup

markets.venues

markets.venue_health

​markets.search

​markets.list

​markets.match

​markets.get

​markets.lookup

​markets.venues

​markets.venue_health

markets.search

markets.list

markets.match

markets.get

markets.lookup

markets.venues

markets.venue_health