> ## Documentation Index
> Fetch the complete documentation index at: https://molelcule.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```python theme={"dark"}
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`

<ParamField query="q" type="string">
  Free-text keyword query. Matches against market title, description, and ticker symbols.
</ParamField>

<ParamField query="venue" type="string">
  Filter results to a specific venue. One of `Demo`, `Polymarket`, or `Kalshi`.
</ParamField>

<ParamField query="status" type="string">
  Filter by market lifecycle status — for example `OPEN` or `CLOSED`. Omit to return all statuses.
</ParamField>

<ParamField query="category" type="string">
  Filter by category label, such as `Politics` or `Economics`.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque pagination cursor returned in a previous response. Pass it to fetch the next page of results.
</ParamField>

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

***

## 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.

```python theme={"dark"}
# 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`

<ParamField query="q" type="string">
  Optional free-text filter. When omitted, the endpoint returns all instruments for the specified venue.
</ParamField>

<ParamField query="venue" type="string">
  Filter to a specific venue. One of `Demo`, `Polymarket`, or `Kalshi`.
</ParamField>

***

## 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.

```python theme={"dark"}
# 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`

<ParamField query="ticker" type="string">
  Venue-native ticker symbol for the instrument. At least one of `ticker` or `slug` is required.
</ParamField>

<ParamField query="slug" type="string">
  URL slug for the market. At least one of `ticker` or `slug` is required.
</ParamField>

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

***

## 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.

```python theme={"dark"}
instrument = client.markets.get(42)
print(instrument["title"], instrument["status"])
```

**Endpoint:** `GET /v1/markets/{id}`

<ParamField path="instrument_id" type="integer | string" required>
  The venue-specific instrument ID. Returned as `instrument_id` in search and match responses.
</ParamField>

***

## 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.

```python theme={"dark"}
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`

<ParamField body="instrument_ids" type="integer[]" required>
  List of venue-specific instrument IDs to retrieve. All IDs are fetched in a single round trip.
</ParamField>

<Note>
  `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.
</Note>

***

## 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`.

```python theme={"dark"}
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.

```python theme={"dark"}
health = client.markets.venue_health()

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

**Endpoint:** `GET /v1/venues/health`

<Tip>
  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.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.