# Polymarket Watchlist & Movement Alerts (`fetchfinch/polymarket-watchlist-alerts`) Actor

Monitor topics, people, companies, and exact Polymarket markets for new listings and material odds, volume, liquidity, or status changes.

- **URL**: https://apify.com/fetchfinch/polymarket-watchlist-alerts.md
- **Developed by:** [Fetch Finch](https://apify.com/fetchfinch) (community)
- **Categories:** Automation, Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$0.003 / actor start

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

Monitor the prediction markets that matter to you without manually searching Polymarket or comparing numbers between visits. **Polymarket Alerts & Market Watchlist API** discovers relevant markets from topics, people, companies, and exact market links, then alerts you when listings, odds, volume, liquidity, or market status change.

The Actor uses Polymarket's public data APIs. You do not need a Polymarket account, wallet, trading credentials, or Polymarket API key.

### What can Polymarket Alerts & Market Watchlist API do?

- Discover active markets related to a topic such as artificial intelligence, elections, Bitcoin, or interest rates.
- Follow people, companies, products, and organizations.
- Track exact markets or multi-market events using a Polymarket URL, slug, market ID, or condition ID.
- Detect newly listed matching markets.
- Alert when outcome probabilities move by a configurable number of percentage points.
- Alert when cumulative volume or available liquidity changes beyond your USD and percentage thresholds.
- Detect market activation and closure.
- Deliver alert batches to HTTPS webhooks, including Make, Zapier, custom endpoints, and Discord-compatible webhooks.
- Export results from Apify as JSON, CSV, Excel, XML, RSS, or HTML.

This Actor is useful for traders, researchers, journalists, analysts, investors, risk teams, and automation builders who need structured Polymarket monitoring instead of a one-time market search.

### How to monitor Polymarket markets

1. Add at least one topic, person, company, or exact market to your watchlist.
2. Choose the movement thresholds that should create an alert.
3. Run the Actor once to establish the initial baseline.
4. Create an Apify schedule using the same input—for example, every 15 minutes or every hour.
5. Read alert records from the dataset or send them directly to your webhook workflow.

The first run is quiet by default. It saves current values as a baseline so old markets are not incorrectly reported as new. Enable **Alert for every match on the first run** only when you deliberately want immediate test alerts.

### Polymarket watchlist input

| Input | What it controls |
| --- | --- |
| `topics` | Subjects and themes to discover |
| `people` | People mentioned in relevant markets |
| `companies` | Companies, products, and organizations |
| `markets` | Exact Polymarket URLs, event slugs, market IDs, or condition IDs |
| `priceChangePercentPoints` | Minimum odds movement in probability percentage points |
| `volumeChangePercent` and `volumeChangeUsd` | Relative and absolute cumulative-volume thresholds |
| `liquidityChangePercent` and `liquidityChangeUsd` | Relative and absolute liquidity thresholds |
| `minimumMarketVolumeUsd` | Filters low-volume search discoveries; exact markets bypass it |
| `includeSnapshots` | Adds current market snapshots alongside alerts |
| `webhookUrls` | Optional HTTPS destinations for alert batches |

#### Example input

```json
{
  "topics": ["Artificial intelligence", "US interest rates"],
  "people": ["Sam Altman"],
  "companies": ["OpenAI", "Nvidia"],
  "markets": [],
  "priceChangePercentPoints": 3,
  "volumeChangePercent": 25,
  "volumeChangeUsd": 1000,
  "liquidityChangePercent": 25,
  "liquidityChangeUsd": 1000,
  "minimumMarketVolumeUsd": 1000,
  "includeSnapshots": false,
  "alertOnFirstRun": false,
  "resetState": false
}
```

Search terms can return several markets from the same event. Use `minimumMarketVolumeUsd` and `maxTrackedMarkets` to keep broad watchlists focused. For the most precise monitoring, provide exact market or event URLs.

### Polymarket alert output

The dataset can contain two record types:

- `alert` — a threshold was crossed or the market status changed.
- `snapshot` — the market's current state, included only when `includeSnapshots` is enabled.

Each alert includes its trigger, matching watchlist term, current and previous outcome probabilities, volume, liquidity, order-book summary, market status, and direct Polymarket URL.

```json
{
  "recordType": "alert",
  "detectedAt": "2026-08-20T10:58:23.655Z",
  "alertTypes": ["liquidity_change"],
  "question": "Will example outcome happen?",
  "outcomes": [
    {
      "name": "Yes",
      "probabilityPercent": 61.5,
      "changePercentPoints": 2.5
    }
  ],
  "volume": {
    "currentUsd": 125000,
    "changeUsd": 4200,
    "changePercent": 3.48
  },
  "liquidity": {
    "currentUsd": 18200,
    "changeUsd": 2200,
    "changePercent": 13.75
  },
  "url": "https://polymarket.com/event/example-market"
}
```

Movement thresholds are measured from the last alert baseline for that metric. Smaller changes therefore accumulate until they become large enough to trigger an alert.

### Scheduled Polymarket alerts

This Actor performs one market check per run. Use an Apify schedule to turn it into continuous monitoring.

For scheduled runs:

- Keep the watchlist and `stateStoreName` unchanged so the saved baseline is reused.
- Keep `resetState` set to `false`.
- Keep `alertOnFirstRun` set to `false` after testing.
- Set `includeSnapshots` to `false` if you want datasets and webhooks to contain actionable alerts only.
- Avoid overlapping runs of the same watchlist.

Different watchlists are automatically isolated inside the state store. Changing the topics, people, companies, or exact markets creates a separate baseline.

### Send Polymarket alerts to webhooks

When a run detects alerts, the Actor can send one JSON batch to each configured HTTPS webhook. The payload includes a human-readable `text` field and the complete `alerts` array.

Webhook URLs and custom headers are encrypted secret inputs. This makes it possible to connect authenticated APIs without exposing credentials in the dataset or run logs.

If delivery is critical, enable `failOnWebhookError`. An unsuccessful webhook will then fail the run so your schedule or external automation can retry it.

### Polymarket monitoring API and integrations

Run the Actor manually, on a schedule, through the Apify API, or from integrations such as Make, Zapier, n8n, and other automation platforms. Results are stored in a structured Apify dataset and can be downloaded or consumed programmatically.

No browser or proxy is used. The Actor queries Polymarket's public Gamma API and maintains its own persistent comparison layer across runs.

### How much does Polymarket monitoring cost?

The exact price and platform usage estimate are displayed in Apify before you start a run. This Actor does not require paid proxies or third-party API subscriptions. Cost mainly depends on how often it runs and how many search terms and retained markets it checks.

For an efficient production setup, begin with a 15- or 60-minute schedule, use focused search terms, set a minimum market-volume filter, and disable snapshots when you only need alerts.

### Limitations

- This is scheduled monitoring, not a real-time streaming trading feed. Detection speed depends on your schedule frequency.
- Topic, person, and company discovery uses Polymarket search relevance and may return broadly related markets. Exact URLs provide the highest precision.
- A first run cannot identify historical changes because no previous baseline exists.
- Availability and field accuracy depend on Polymarket's public APIs.
- The Actor monitors public market data; it does not place trades or access user portfolios.

### Frequently asked questions

#### Does this Actor scrape Polymarket?

No. It uses Polymarket's public APIs and adds discovery, persistent baselines, threshold evaluation, structured output, scheduling, and webhook delivery.

#### Do I need a Polymarket account or wallet?

No. Public market monitoring does not require authentication, a wallet, or trading credentials.

#### Why did my first run produce no alerts?

That is the expected default. The first run creates the comparison baseline. Enable snapshots to inspect matches immediately, or temporarily enable first-run alerts for testing.

#### Why do I see both an alert and a snapshot for the same market?

`includeSnapshots` was enabled. Disable it when you want only actionable alert records.

#### How do I start over with a fresh baseline?

Enable `resetState` for one manual run, then turn it off again. Do not leave it enabled in a schedule.

#### Can I monitor one exact market?

Yes. Add its Polymarket URL, slug, numeric market ID, or condition ID to `markets` and leave the broader search lists empty.

### Support and disclaimer

If you find an issue or need a new alert type, open an issue from the Actor's **Issues** tab with a sample input and run ID.

Prediction-market probabilities are not financial advice. Polymarket controls market data and resolution rules. Review each market's resolution criteria before making decisions based on an alert.

# Actor input Schema

## `topics` (type: `array`):

Themes or subjects to discover, for example AI, Bitcoin, Federal Reserve, or elections.

## `people` (type: `array`):

People whose related Polymarket events should be monitored.

## `companies` (type: `array`):

Companies, products, or organizations to monitor.

## `markets` (type: `array`):

Polymarket market/event URLs, numeric market IDs, condition IDs, or slugs. Exact entries remain tracked even when search rankings change.

## `priceChangePercentPoints` (type: `number`):

Alert when any outcome moves by at least this many probability percentage points since its last odds alert.

## `volumeChangePercent` (type: `number`):

Minimum relative cumulative-volume increase. Both this and the USD minimum must be met when a prior volume exists.

## `volumeChangeUsd` (type: `number`):

Minimum absolute cumulative-volume increase required for a volume alert.

## `liquidityChangePercent` (type: `number`):

Minimum relative liquidity increase or decrease. Both this and the USD minimum must be met when prior liquidity is non-zero.

## `liquidityChangeUsd` (type: `number`):

Minimum absolute liquidity change required for a liquidity alert.

## `minimumMarketVolumeUsd` (type: `number`):

Ignore low-volume search discoveries. Exact market entries bypass this filter.

## `searchResultsPerTerm` (type: `integer`):

Higher values improve recall but can add loosely related results and API work.

## `maxTrackedMarkets` (type: `integer`):

Safety cap for persistent state and per-run API requests. Existing and exact markets are prioritized.

## `alertOnFirstRun` (type: `boolean`):

Normally the first run creates a quiet baseline. Enable this to treat every initial match as a new-market alert.

## `includeSnapshots` (type: `boolean`):

Store a current snapshot for each matched market in addition to alert records.

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

Named key-value store used across scheduled runs. A configuration fingerprint isolates different watchlists in the same store.

## `resetState` (type: `boolean`):

Delete the saved baseline for this watchlist before processing this run.

## `webhookUrls` (type: `array`):

Optional HTTPS endpoints for alert batches (works with custom endpoints, Make, Zapier, and Discord-compatible webhooks).

## `webhookHeaders` (type: `object`):

Optional secret headers such as Authorization. Values must be strings.

## `failOnWebhookError` (type: `boolean`):

When enabled, any unsuccessful notification delivery fails the Actor run so scheduling or external automation can retry it.

## Actor input object example

```json
{
  "topics": [
    "Artificial intelligence"
  ],
  "people": [],
  "companies": [],
  "markets": [],
  "priceChangePercentPoints": 3,
  "volumeChangePercent": 25,
  "volumeChangeUsd": 1000,
  "liquidityChangePercent": 25,
  "liquidityChangeUsd": 1000,
  "minimumMarketVolumeUsd": 0,
  "searchResultsPerTerm": 25,
  "maxTrackedMarkets": 500,
  "alertOnFirstRun": false,
  "includeSnapshots": true,
  "stateStoreName": "polymarket-watchlist-alerts-state",
  "resetState": false,
  "failOnWebhookError": false
}
```

# Actor output Schema

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

No description

## `summary` (type: `string`):

No description

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("fetchfinch/polymarket-watchlist-alerts").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("fetchfinch/polymarket-watchlist-alerts").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 '{}' |
apify call fetchfinch/polymarket-watchlist-alerts --silent --output-dataset

```

## MCP server setup

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

```

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/mxxbVQHjmj3hIpiaY/builds/m869t9FgSm03FwGk6/openapi.json