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

# Polymarket Search Markets

Search and browse Polymarket prediction markets. Use orderBy 'trending'/'volume'/'newest'/'liquidity' to browse all active markets without any filters. 'trending' ranks by 24-hour volume, one market per event — the same feed as polymarket.com's Trending page; use it for 'what's trending / hot / popular today'. 'volume' is ALL-TIME volume, which surfaces long-dated mega-markets that may barely trade today — use it for 'biggest markets ever', not for trending. Add a query for keyword search, or date filters (endDateMin/Max) for time-bounded browsing. Returns markets with question, outcomes, prices, volume, liquidity, and parent eventSlug/eventTitle. Search ranking: keyword queries match against EVENT titles, then surface that event's markets — so per-game markets (e.g. 'Belgium vs. Egypt') only appear when the query matches the event title. Results are volume-ranked by default so the liquid flagship market (e.g. 'World Cup Winner') surfaces first ahead of low-volume novelty markets (e.g. 'World Cup: Glove Brand'); for specific matchups, search by team/entity names alone (e.g. 'Belgium Egypt'). Absence from one query does not mean absence from Polymarket. Query vs tag: use `query` for keyword/entity search (e.g. 'bitcoin', 'Belgium Egypt'); use `tag` to BROWSE a whole category by its Polymarket slug (e.g. tag: 'weather' | 'sports' | 'politics' | 'fifa-world-cup'), which returns the same live markets as polymarket.com/<slug>. Prefer `tag` for topic/category requests — keyword search misses category markets whose text omits the word (e.g. query 'weather' finds nothing, but tag 'weather' surfaces the live 'Highest temperature in <city>' markets). A bare `tag` browses by volume. Ideal for: market discovery, automated market selection, finding short-duration markets, dashboards.

![Polymarket Search Markets logo](https://cdn.b3.fun/b3os-icons/polymarket-icon.png)
Catalog action Utility

Search and browse Polymarket prediction markets. Use orderBy 'trending'/'volume'/'newest'/'liquidity' to browse all active markets without any filters. 'trending' ranks by 24-hour volume, one market per event — the same feed as polymarket.com's Trending page; use it for 'what's trending / hot / popular today'. 'volume' is ALL-TIME volume, which surfaces long-dated mega-markets that may barely trade today — use it for 'biggest markets ever', not for trending. Add a query for keyword search, or date filters (endDateMin/Max) for time-bounded browsing. Returns markets with question, outcomes, prices, volume, liquidity, and parent eventSlug/eventTitle. Search ranking: keyword queries match against EVENT titles, then surface that event's markets — so per-game markets (e.g. 'Belgium vs. Egypt') only appear when the query matches the event title. Results are volume-ranked by default so the liquid flagship market (e.g. 'World Cup Winner') surfaces first ahead of low-volume novelty markets (e.g. 'World Cup: Glove Brand'); for specific matchups, search by team/entity names alone (e.g. 'Belgium Egypt'). Absence from one query does not mean absence from Polymarket. Query vs tag: use `query` for keyword/entity search (e.g. 'bitcoin', 'Belgium Egypt'); use `tag` to BROWSE a whole category by its Polymarket slug (e.g. tag: 'weather' | 'sports' | 'politics' | 'fifa-world-cup'), which returns the same live markets as polymarket.com/&lt;slug&gt;. Prefer `tag` for topic/category requests — keyword search misses category markets whose text omits the word (e.g. query 'weather' finds nothing, but tag 'weather' surfaces the live 'Highest temperature in &lt;city&gt;' markets). A bare `tag` browses by volume. Ideal for: market discovery, automated market selection, finding short-duration markets, dashboards.


## At a Glance

| Field | Value |
| --- | --- |
| Action ID | `polymarket-search-markets` |
| Category | Utility |
| Connector | Not required |
| Requires gas | No |
| Funds movement | None declared |
| Tags | `polymarket`, `search`, `market-data`, `read` |

## Payload Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | `string` | No | Keyword/entity search \(e.g., 'bitcoin', 'Belgium Egypt'\). Matches a market's text. When used alone, searches via keyword matching; when combined with date filters, filters results by question text client-side. For a whole topic/category \(weather, sports, politics, …\), use 'tag' instead — keyword search misses category markets whose text omits the word \(e.g. query 'weather' returns nothing\). |
| `startDateMin` | `string` | No | ISO 8601 date-time. Only return markets starting AFTER this time. Only works in browse mode \(with date filters\). Example: '2026-03-17T05:00:00Z' |
| `startDateMax` | `string` | No | ISO 8601 date-time. Only return markets starting BEFORE this time. Only works in browse mode \(with date filters\). Example: '2026-03-17T06:00:00Z' |
| `endDateMin` | `string` | No | ISO 8601 date-time. Only return markets ending AFTER this time. Enables browse mode using the /markets endpoint with server-side date filtering. Example: '2026-03-17T05:00:00Z' |
| `endDateMax` | `string` | No | ISO 8601 date-time. Only return markets ending BEFORE this time. Use with endDateMin to find markets ending within a specific window. Example: '2026-03-17T06:00:00Z' |
| `volumeNumMin` | `number` | No | Minimum ALL-TIME trading volume in USDC \(not 24h volume, in every mode\). Filters out low-volume markets. Works in browse mode \(with date filters\) and in trending mode; not applied to keyword searches. In trending mode the filter runs client-side after fetching 'limit' events, so a page can come back shorter than 'limit' while nextCursor still advances by the full page size. |
| `liquidityNumMin` | `number` | No | Minimum liquidity in USDC. Filters out illiquid markets. Works in browse mode \(with date filters\) and in trending mode; not applied to keyword searches. Same short-page caveat as volumeNumMin in trending mode. |
| `includeInactive` | `boolean` | No | Also show inactive markets that aren't currently trading. |
| `includeClosed` | `boolean` | No | Also show closed/resolved markets, plus markets whose end date has already passed. By default, browsing without a date filter only returns markets that haven't ended yet. |
| `tag` | `string` | No | Browse a whole Polymarket category by its slug \(e.g., 'weather', 'politics', 'crypto', 'sports', 'fifa-world-cup'\) — returns the same live markets as polymarket.com/&lt;slug&gt;. Prefer this over 'query' for topic/category requests. Can be used alone \(browses the category by volume\) or alongside 'query'/date filters to scope a keyword search to that category. |
| `orderBy` | `string` | No | Order results by the specified criteria. 'relevance' \(default\) volume-ranks keyword results so the liquid flagship market surfaces first \(a low-volume novelty market can otherwise outrank it in the raw API order\), 'trending' sorts by 24-hour volume with one market per event — matches polymarket.com's Trending feed, use it for 'what's hot today' — 'volume' sorts by ALL-TIME trading volume \(long-dated mega-markets, not necessarily active today\), 'newest' sorts by end date, 'liquidity' sorts by current liquidity. |
| `ascending` | `boolean` | No | Sort in ascending order instead of descending. Only applies when orderBy is set. |
| `limit` | `number` | No | Maximum number of results to return \(default: 10, max: 100\) |
| `cursor` | `string` | No | Opaque cursor for pagination. Pass the nextCursor value from a previous response to fetch the next page. Works in browse mode \(keyset cursor\) and in trending mode \(stringified page offset\). The two formats are NOT interchangeable — only pass a nextCursor back to a request with the same mode and orderBy that produced it. Not supported in keyword-search mode. |
| `fetchAllPages` | `boolean` | No | When true, automatically paginates through all available pages and returns the combined result set. Only works in browse mode \(with date filters\); rejected in trending mode \(use limit, max 100, instead\). The limit param is ignored when this is enabled. Capped at 10,000 markets for safety. |

## Result Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `markets` | `array` | Yes | Array of matching markets |
| `count` | `number` | Yes | Number of results returned |
| `query` | `string` | No | The search query used |
| `orderBy` | `string` | No | The ordering criteria used |
| `nextCursor` | `string` | No | Opaque cursor for fetching the next page. Present only when more results are available. Pass as the cursor input to get the next page. |

## Examples

**Workflow node**

```json
{
  "type": "polymarket-search-markets",
  "payload": {
    "query": "status:open",
    "startDateMin": "2026-04-25T12:00:00Z",
    "startDateMax": "2026-04-25T12:00:00Z",
    "endDateMin": "2026-04-25T12:00:00Z",
    "endDateMax": "2026-04-25T12:00:00Z"
  },
  "children": []
}
```
  **Test with API**

```bash
curl -X POST "https://api.b3os.org/v1/actions/polymarket-search-markets/test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "inputs": {
    "query": "status:open",
    "startDateMin": "2026-04-25T12:00:00Z",
    "startDateMax": "2026-04-25T12:00:00Z",
    "endDateMin": "2026-04-25T12:00:00Z",
    "endDateMax": "2026-04-25T12:00:00Z"
  }
}'
```

**Use expressions for dynamic values**

Payload fields can use workflow expressions such as `{{$trigger.body.amount}}`, `{{$nodes.fetch.result.price}}`, and `{{$props.asset}}` when the value should come from a trigger, prior node, or reusable workflow prop.