# Polymarket Markets API: Prices, Volume, New Market Monitor (`ailu_studio/polymarket-markets`) Actor

Polymarket prediction markets from the public Gamma API: question, outcome prices (probabilities), best bid/ask, 24h volume, liquidity, start and end dates, event slug and URL. Keyword search, sorting, and a new-market monitor mode. No API key.

- **URL**: https://apify.com/ailu_studio/polymarket-markets.md
- **Developed by:** [Ailu Studio](https://apify.com/ailu_studio) (community)
- **Categories:** News, Agents, Other
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 result rows

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Polymarket Markets API: Prices, Volume, Liquidity, New Market Monitor

Returns Polymarket prediction markets as flat JSON rows from Polymarket's public Gamma API: the question, outcome labels and current prices (probabilities between 0 and 1), best bid and ask, last trade, 24-hour and lifetime volume, liquidity, start and end dates, parent event, resolution source, condition id, CLOB token ids and the market URL. List the most traded markets, search by keyword, filter by status, liquidity and end date, or run it as a monitor that returns only markets your watchlist has not seen before. No API key, no browser, no proxy.

### Use cases

- Pull the top markets by 24-hour volume into a dashboard, spreadsheet or LLM prompt on a schedule.
- Search markets about a topic (`query: "bitcoin"`, `"fed"`, `"election"`) and read their current odds.
- Monitor newly created markets: `outputMode: "new"` with `sortBy: "startDate"` returns only markets that appeared since the last run.
- Find markets resolving soon (`sortBy: "endDate"` or `endsBefore`) for event-driven strategies.
- Get `conditionId` and `clobTokenIds` to connect rows to the CLOB API or on-chain data.

### Input

| Field | Default | Meaning |
|---|---|---|
| `query` | `""` | Keyword. Uses Polymarket's search endpoint, then keeps markets whose question, event title or outcome label contains the keyword (case-insensitive). Empty = list mode. |
| `status` | `active` | `active` (open for trading), `closed` (resolved or ended) or `all`. |
| `sortBy` | `volume24hr` | `volume24hr`, `volume`, `liquidity` (highest first), `endDate` (soonest first) or `startDate` (newest first). |
| `minLiquidityUsd` | `0` | Drop markets with less order-book liquidity (USD). Closed markets report no liquidity. |
| `endsBefore` | `""` | ISO date or date-time; keep only markets ending on or before it. |
| `outputMode` | `all` | `all` returns every matching market. `new` returns only markets not seen before by the watchlist in `stateStoreName`. |
| `stateStoreName` | `polymarket-markets-state` | Key-value store that remembers seen market ids for `outputMode: "new"`. One per watchlist. |
| `maxItems` | `100` | Maximum rows returned. |

Running with the defaults returns the 100 active markets with the highest 24-hour volume.

### Output

| Field | Type | Meaning |
|---|---|---|
| `id` | string | Polymarket market id. |
| `question`, `slug`, `eventSlug`, `eventTitle`, `groupItemTitle` | string | Question text, URL slugs, parent event title, short label inside multi-outcome events. |
| `url` | string | `https://polymarket.com/event/<eventSlug>/<slug>` |
| `outcomes`, `outcomePrices` | string\[], number\[] | Outcome labels and their prices (probabilities 0-1), same order. |
| `yesPrice`, `noPrice` | number | Price of the Yes / No outcome. |
| `bestBid`, `bestAsk`, `lastTradePrice`, `spread` | number | Yes order-book quotes. |
| `priceChange24h`, `priceChange1w` | number or null | Yes price change over 24 h / 7 d. |
| `volumeUsd`, `volume24hUsd`, `volume1wkUsd`, `liquidityUsd` | number or null | Volume and liquidity in USD. |
| `startDate`, `endDate`, `createdAt` | string | ISO 8601 UTC. |
| `active`, `closed`, `acceptingOrders`, `negRisk` | boolean | Status flags. |
| `resolutionSource`, `conditionId`, `clobTokenIds`, `image` | | Resolution note, on-chain condition id, CLOB token ids per outcome, image URL. |
| `changeType`, `firstSeenAt` | string | Only in `outputMode: "new"`: always `new`, plus when the watchlist first saw the market. |
| `fetchedAt` | string | ISO 8601 UTC fetch time. |

Sample row (trimmed):

```json
{
  "id": "562831",
  "question": "2026 Balance of Power: R Senate, R House",
  "slug": "2026-balance-of-power-r-senate-r-house-537",
  "eventSlug": "balance-of-power-2026-midterms",
  "eventTitle": "Balance of Power: 2026 Midterms",
  "groupItemTitle": "Republicans Sweep",
  "url": "https://polymarket.com/event/balance-of-power-2026-midterms/2026-balance-of-power-r-senate-r-house-537",
  "outcomes": ["Yes", "No"],
  "outcomePrices": [0.045, 0.955],
  "yesPrice": 0.045,
  "noPrice": 0.955,
  "bestBid": 0.04,
  "bestAsk": 0.05,
  "lastTradePrice": 0.05,
  "priceChange24h": null,
  "volumeUsd": 22055475.37,
  "volume24hUsd": 5690029.61,
  "liquidityUsd": 2081675.25,
  "startDate": "2025-07-11T21:05:25.044Z",
  "endDate": "2026-11-04T04:59:00.000Z",
  "active": true,
  "closed": false,
  "negRisk": true,
  "resolutionSource": null,
  "conditionId": "0xc5eae79d1ffe716572353962eb926b1e3964c500a4880a7a94f58408218ee76b",
  "clobTokenIds": ["1037041417739476789318234100309561819185620627884860347857826416031498288933", "2586929638691165404971548906882475774517468128839723852178011894955376048852"],
  "fetchedAt": "2026-11-03T15:00:00.000Z"
}
```

The `OUTPUT` record of the run's key-value store holds a summary (`mode`, `pages`, `fetched`, `matched`, change counts, errors).

### How it works and limits

- List mode reads `GET https://gamma-api.polymarket.com/markets?limit=100&offset=N` with the status, order, `liquidity_num_min` and `end_date_max` parameters applied server-side, one request per 100 markets, until `maxItems` is reached or the pages run out (cap: 50 pages).
- Keyword mode reads `GET /public-search?q=<query>&limit_per_type=50&page=N` (up to 20 pages), flattens the markets of each matching event, and then applies the keyword to question, event title and outcome label. A market whose only match is in its long description is therefore not returned.
- `outputMode: "new"` stores the ids of all matching markets in the named key-value store and returns only ids that were absent on the previous run; the first run returns everything up to `maxItems` and still records every matching id as seen. Markets that drop out of the scanned window are forgotten, so with a volume sort a market can be reported as new again if it re-enters the window; use `sortBy: "startDate"` for a stable new-market feed. Nothing is reported as removed or updated.
- Requests are spaced 250 ms apart and retried with back-off on 429 and 5xx responses. Prices are a snapshot from the Gamma index, usually a few seconds behind the order book. Nothing is cached between runs.
- Not covered: order-book depth, trade history, positions, comments, and user profiles.

### Pricing

Pay per result: **$1.00 per 1,000 rows** (`result` event). Platform usage is billed separately by Apify. Removed/free rows are not charged.

### Legal

Not affiliated with Polymarket. Uses the public Polymarket Gamma API only. Data licence/terms: https://docs.polymarket.com/ and https://polymarket.com/tos. Prices are market probabilities, not advice; prediction markets may be restricted in your jurisdiction.

### FAQ

**What do the prices mean?** `yesPrice: 0.045` means the market prices a 4.5% chance of Yes. Prices of all outcomes in a market sum to roughly 1.

**How do I get only brand-new markets every hour?** Set `outputMode: "new"`, `sortBy: "startDate"`, a dedicated `stateStoreName`, and schedule the Actor hourly. The first run returns the current newest markets; later runs return only markets created since.

**Why does a keyword search return a market whose question does not contain the word?** It matches the event title or the outcome label instead (for example the candidate name in a multi-outcome event).

**Can I get closed or resolved markets?** Yes, `status: "closed"`. Their `outcomePrices` show the resolved outcome as 1 and 0; liquidity is null.

**Is there a rate limit?** Polymarket does not publish one for the Gamma API. The Actor keeps one request in flight with 250 ms spacing, which has not triggered throttling in testing.

# Actor input Schema

## `query` (type: `string`):

Optional keyword such as "bitcoin", "fed" or "election". Markets are searched with Polymarket's search endpoint and then kept only when the question, event title or outcome label contains the keyword (case-insensitive). Leave empty to list markets by the sort order instead.

## `status` (type: `string`):

Which markets to return. "active" (default) means active and not closed; "closed" means resolved or ended markets; "all" returns both.

## `sortBy` (type: `string`):

Order of the rows and, without a keyword, the order in which Polymarket pages are read. Use "startDate" with outputMode "new" to monitor newly created markets. Default volume24hr.

## `minLiquidityUsd` (type: `integer`):

Drop markets whose order-book liquidity in USD is below this value. Default 0 (no filter). Closed markets usually report no liquidity, so keep 0 when status is closed or all.

## `endsBefore` (type: `string`):

Optional ISO 8601 date or date-time such as "2026-12-31" or "2026-12-31T23:59:00Z". Only markets whose end date is on or before this moment are returned. Leave empty for no end-date filter.

## `outputMode` (type: `string`):

"all" (default) returns every matching market each run. "new" remembers the market ids seen by the watchlist named in stateStoreName and returns only markets that were not in it on the previous run (changeType "new"); on the first run every matching market is new.

## `stateStoreName` (type: `string`):

Name of the key-value store that remembers which market ids were already seen in outputMode "new". Use a different name per watchlist, e.g. "polymarket-crypto-new". Default polymarket-markets-state.

## `maxItems` (type: `integer`):

Maximum number of market rows to return. Default 100. Each 100 markets costs one request to Polymarket; a keyword search reads up to 50 events per request.

## Actor input object example

```json
{
  "query": "",
  "status": "active",
  "sortBy": "volume24hr",
  "minLiquidityUsd": 0,
  "endsBefore": "",
  "outputMode": "all",
  "stateStoreName": "polymarket-markets-state",
  "maxItems": 100
}
```

# Actor output Schema

## `results` (type: `string`):

All rows in the default dataset.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": ""
};

// Run the Actor and wait for it to finish
const run = await client.actor("ailu_studio/polymarket-markets").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "query": "" }

# Run the Actor and wait for it to finish
run = client.actor("ailu_studio/polymarket-markets").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "query": ""
}' |
apify call ailu_studio/polymarket-markets --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ailu_studio/polymarket-markets"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/5dzpazxbQMkKSgqiq/builds/H2N2YECUsxyeYNY6a/openapi.json