Search and Discover Prediction Market Instruments API

Search prediction market instruments by keyword, venue, status, or category. Covers markets.search, markets.list, markets.match, markets.get, and lookup.

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

q · string

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

venue · string

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

status · string

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

category · string

Filter by category label, such as Politics or Economics.

cursor · 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

q · string

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

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

ticker · string

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

slug · 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}

instrument_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

instrument_ids · 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.