# Polymarket Prediction Market & Wallet Monitor (`barefoot_grade/polymarket-clob-monitor`) Actor

Track live Polymarket prediction markets and the recent trades of wallets you choose. Each run returns a market board with outcome prices, end dates and tags, plus one record per wallet fill with side, shares, price, USDC value and timestamp.

- **URL**: https://apify.com/barefoot_grade/polymarket-clob-monitor.md
- **Developed by:** [Philip Kirkbride](https://apify.com/barefoot_grade) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 market or wallet trades

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?

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 Prediction Market & Wallet Monitor

Track live Polymarket prediction markets and the recent trading activity of wallets you choose. Every run returns a current market board — question, outcome prices, end dates, lifecycle flags and tags — and, when you add wallet addresses, their recent fills with buy/sell side, shares, price, USDC value, market context and timestamp.

Use it for prediction-market research, odds dashboards, event monitoring and wallet-activity feeds. Results arrive as a dataset with one record per market or per wallet fill, plus a run summary. The data is public market information, so no sign-in is required.

### Quick start

Collect the current market board and the last 24 hours of fills for one wallet:

```json
{"wallets":["0xd9c9651bfd445b2cddf750662ee79a755f216686"],"lookbackHours":24,"maxMarkets":200,"maxPages":6}
```

Leave `wallets` empty for a market-only run.

### Input

| Name | Type | Default | What it does |
| --- | --- | --- | --- |
| `wallets` | array | `[]` | Wallet addresses whose recent fills to collect. |
| `lookbackHours` | integer | `24` | How far back to keep wallet trades (1–336 hours). |
| `maxWalletTrades` | integer | `100` | Most recent trades fetched per wallet (1–500). |
| `activeOnly` | boolean | `true` | Keep only markets that are active and not closed. |
| `acceptingOrdersOnly` | boolean | `false` | Keep only markets that are accepting orders. |
| `tag` | string | empty | Keep only markets carrying this tag, such as `sports`. |
| `maxMarkets` | integer | `200` | Maximum market records returned (1–2000). |
| `maxPages` | integer | `6` | Maximum market pages fetched (1–30). |
| `telegramChatId` | string | empty | Optional chat for a large-trade digest. Requires the `TELEGRAM_BOT_TOKEN` environment variable. |
| `alertMinUsd` | number | `100` | Trades at or above this USDC value go into the digest. |
| `requestDelaySecs` | number | `0.25` | Pause between wallet requests, in seconds. |

Very restrictive filters can return fewer records or none; the run summary explains why (for example, the page budget was reached).

### Output

Every row is either a market or a wallet trade. Market rows carry the question, market slug, lifecycle flags, end date, tags, trading rules and outcome tokens with their prices. Wallet rows carry the wallet, side, shares, price, USDC value, outcome and trade timestamp.

One market row — selected fields from a real 2026-09-06 snapshot; prices are historical, not current quotes:

```json
{
  "kind": "market",
  "conditionId": "0x6133ff58978f713ff58cfa4a3db6c522bbf9c4baaf580ce99688133a8c6539af",
  "question": "Manchester City FC vs. Norwich City FC: O/U 7.5 Total Corners",
  "marketSlug": "efl-mnc-nor-2026-09-17-corners-total-7pt5",
  "active": true,
  "closed": false,
  "acceptingOrders": true,
  "endDate": "2026-09-17T00:00:00Z",
  "tags": ["Sports", "Soccer", "Games", "Carabao Cup", "EFL Cup"],
  "tokens": [
    {"outcome": "Over", "price": 0.51},
    {"outcome": "Under", "price": 0.49}
  ]
}
```

One wallet-trade row:

```json
{
  "kind": "wallet_trade",
  "wallet": "0xd9c9651bfd445b2cddf750662ee79a755f216686",
  "side": "BUY",
  "size": 2.5,
  "price": 0.4,
  "usdcSize": 1.0,
  "outcome": "Yes",
  "title": "Will Málaga CF win on 2026-09-06?",
  "tradedAt": "2026-09-06T15:14:58+00:00"
}
```

Unpublished values are returned as `null` rather than guessed. A run summary in the key-value store reports the status, record counts, coverage and any warnings.

### FAQ

**How fresh is the data?** Each run reads the current market board and the newest available wallet fills.

**What limits apply?** Up to 2,000 markets, 500 trades per wallet and 25 wallets per run.

**Can I focus on one topic?** Yes — filter by tag, activity and order acceptance, and cap the markets and pages collected.

**What if a wallet has no recent trades?** The market board is still returned and the run summary notes the empty wallet lane.

For support, contact Apify support and include the Actor run ID.

# Actor input Schema

## `wallets` (type: `array`):

Polymarket wallet addresses (0x followed by 40 hex characters, any case) whose recent trades are collected. Each fill becomes one record with buy/sell side, shares, price, USDC value, market and timestamp inside the lookback window. Leave empty for a market-only run.

## `lookbackHours` (type: `integer`):

Hours of trade history kept per wallet (1-336). Newest fills are kept first.

## `maxWalletTrades` (type: `integer`):

Most recent trades fetched per wallet (1-500).

## `activeOnly` (type: `boolean`):

Keep only markets that are active and not yet closed or archived.

## `acceptingOrdersOnly` (type: `boolean`):

Additionally keep only markets that are accepting orders (tradable now).

## `tag` (type: `string`):

Keep only markets whose tags contain this value, case-insensitive (e.g. Sports, Crypto, Politics). 'all' or empty disables the filter.

## `maxMarkets` (type: `integer`):

Maximum number of market records returned after filters (1-2000).

## `maxPages` (type: `integer`):

Maximum number of market pages fetched per run (1-30). Higher values can find more markets but take longer.

## `telegramChatId` (type: `string`):

Optional Telegram chat id for the large-trade digest (trades at or above alertMinUsd). Requires the TELEGRAM_BOT_TOKEN environment variable; the bot token is never an input. A failed or skipped send is a warning, never a failed run.

## `alertMinUsd` (type: `number`):

Wallet trades at or above this USDC value go into the Telegram digest (when configured).

## `requestDelaySecs` (type: `number`):

Pause between wallet requests, in seconds.

## Actor input object example

```json
{
  "wallets": [],
  "lookbackHours": 24,
  "maxWalletTrades": 100,
  "activeOnly": true,
  "acceptingOrdersOnly": false,
  "maxMarkets": 200,
  "maxPages": 6,
  "alertMinUsd": 100,
  "requestDelaySecs": 0.25
}
```

# 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 = {
    "wallets": [],
    "lookbackHours": 24,
    "maxWalletTrades": 100,
    "activeOnly": true,
    "acceptingOrdersOnly": false,
    "tag": "",
    "maxMarkets": 200,
    "maxPages": 6,
    "telegramChatId": "",
    "alertMinUsd": 100,
    "requestDelaySecs": 0.25
};

// Run the Actor and wait for it to finish
const run = await client.actor("barefoot_grade/polymarket-clob-monitor").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 = {
    "wallets": [],
    "lookbackHours": 24,
    "maxWalletTrades": 100,
    "activeOnly": True,
    "acceptingOrdersOnly": False,
    "tag": "",
    "maxMarkets": 200,
    "maxPages": 6,
    "telegramChatId": "",
    "alertMinUsd": 100,
    "requestDelaySecs": 0.25,
}

# Run the Actor and wait for it to finish
run = client.actor("barefoot_grade/polymarket-clob-monitor").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 '{
  "wallets": [],
  "lookbackHours": 24,
  "maxWalletTrades": 100,
  "activeOnly": true,
  "acceptingOrdersOnly": false,
  "tag": "",
  "maxMarkets": 200,
  "maxPages": 6,
  "telegramChatId": "",
  "alertMinUsd": 100,
  "requestDelaySecs": 0.25
}' |
apify call barefoot_grade/polymarket-clob-monitor --silent --output-dataset

```

## MCP server setup

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

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/Da2RkNk9XXhKGzdAw/builds/ESRXpL3XnJ7G1oLYb/openapi.json