# Polymarket Whale Wallet Trade Monitor and Alerts (`redfoxxie/polymarket-wallet-trade-monitor`) Actor Schedule enriched alerts for new public Polymarket whale-wallet trades. Infer maker/taker role, add notional and dynamic fee context, suppress duplicate alerts across runs, and preview activity free before enabling paid records. No wallet credentials or private API keys required. - **URL**: https://apify.com/redfoxxie/polymarket-wallet-trade-monitor.md - **Developed by:** [João Ferreira](https://apify.com/redfoxxie) (community) - **Categories:** Developer tools, Other, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing $4.00 / 1,000 enriched 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use 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 Unofficial independent tool. It is not affiliated with, sponsored by, or endorsed by Polymarket. Schedule enriched alerts for **new public Polymarket whale-wallet trades**. Monitor up to 20 proxy wallets, infer maker or taker execution, attach notional and dynamic fee context, and suppress previously delivered trades across overlapping runs. The free preview shows whether a wallet set is active before you pay for identifiable alert records. The Actor never places or copies a trade and never requests private keys or wallet credentials. ### What does this Polymarket whale monitor return? Each newly observed paid alert includes: - deterministic `alert_id` for downstream idempotency; - public wallet, transaction, market, outcome, side, price, and shares; - observed trade notional and a notable/large/very-large tier; - exact maker/taker inference from public all-trade and taker-only samples; - current Gamma fee schedule and an estimated fee for inferred taker rows; - whether the wallet traded multiple outcomes in the same market lookback; - role-aware warnings about historical-fill copyability. The default dataset has a documented schema for JSON, CSV, Excel, Apify API, webhook, and MCP/AI-agent workflows. A separate run-summary output exposes candidate counts, fee coverage, duplicate suppression, and delivery status. ### Safe free preview Start with `previewOnly=true`: ```json { "wallets": [ "0x04b6d7e930cf9e493c5e6ef24b496294f95594c8" ], "monitorId": "research-whales", "previewOnly": true, "lookbackMinutes": 20, "maxTradesPerWallet": 500, "minNotionalUsdc": 50, "roles": ["maker", "taker"], "maxAlerts": 200 } ```` Preview mode returns counts, maker/taker totals, and the largest new notional. It omits trade identities, emits no custom paid event, and does not advance the dedupe state. When the preview looks useful, set `previewOnly=false` and schedule the Actor. A practical starting schedule is every 15 minutes with a 20-minute lookback. Keep the same `monitorId` for the same wallet set. ### Search-ready examples The Examples tab can expose a free activity preview and a paid deduplicated monitor as separate runnable tasks. Their configurations are versioned in `public_tasks.json`, including the distinct persistent `monitorId` values that prevent the examples from sharing delivery state. ### Duplicate suppression and delivery safety Each `monitorId` maps to a persistent named key-value store created by the Actor under Apify's limited-permission model. Overlapping lookbacks are intentional: the Actor discards alert IDs already delivered in earlier runs. It commits only alerts whose paid dataset event was successfully delivered, so a charge limit or failed delivery cannot silently mark an unseen alert as complete. Use a different `monitorId` when the wallet set has a different downstream meaning. Reusing one ID for unrelated sets can suppress a trade that was already seen in the shared monitor state. ### Pricing Each delivered `enriched_wallet_trade` costs **$0.004**. There is no start fee, preview mode is free, and a run with no new qualifying trades costs no custom event fee. The launch uses **Pay per event + usage**, so Apify platform usage is billed separately to the account running the Actor, including preview or no-alert runs. `maxAlerts` bounds the maximum number of paid records per run. ### What this monitor does not promise An observed trade is history, not a forward copy signal. Maker fills depend on queue position and are generally not reproducible by buying later. Taker fills may already have moved the market. Dynamic fees are resolved from current public market metadata and may not recreate a historical fee schedule after a market changes. Users remain responsible for Polymarket's terms, geographic restrictions, and applicable law. Use the Actor's Apify Issues tab for reproducible duplicate, fee, or maker/taker concerns and include the run ID, `monitorId`, and `alert_id`. # Actor input Schema ## `wallets` (type: `array`): One to twenty public Polymarket proxy-wallet addresses to monitor. ## `monitorId` (type: `string`): Scheduled runs with the same ID share a dedupe state. Use a different ID for each wallet set. ## `previewOnly` (type: `boolean`): Returns counts and largest notional without trade identities, charges nothing, and does not advance state. ## `lookbackMinutes` (type: `integer`): Fetch trades this many minutes before the current run. Overlap scheduled runs safely; persistent state suppresses delivered duplicates. ## `maxTradesPerWallet` (type: `integer`): Maximum public all-trade and taker-only rows fetched per wallet before filtering the lookback. ## `minNotionalUsdc` (type: `number`): Ignore observed trades whose price multiplied by shares is below this USDC amount. ## `roles` (type: `array`): Return maker fills, taker fills, or both after exact bounded-sample maker/taker inference. ## `maxAlerts` (type: `integer`): Hard cap on new paid alert records delivered in one run. Preview mode never emits these paid events. ## Actor input object example ```json { "wallets": [ "0x04b6d7e930cf9e493c5e6ef24b496294f95594c8" ], "monitorId": "research-whales", "previewOnly": true, "lookbackMinutes": 20, "maxTradesPerWallet": 500, "minNotionalUsdc": 50, "roles": [ "maker", "taker" ], "maxAlerts": 200 } ``` # Actor output Schema ## `alerts` (type: `string`): Paid mode returns one enriched row per newly observed and successfully delivered public trade. Preview mode returns one identity-free summary row. ## `runSummary` (type: `string`): Counts, fee coverage, duplicate suppression, and delivery status for this run. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "wallets": [ "0x04b6d7e930cf9e493c5e6ef24b496294f95594c8" ] }; // Run the Actor and wait for it to finish const run = await client.actor("redfoxxie/polymarket-wallet-trade-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "wallets": ["0x04b6d7e930cf9e493c5e6ef24b496294f95594c8"] } # Run the Actor and wait for it to finish run = client.actor("redfoxxie/polymarket-wallet-trade-monitor").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).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": [ "0x04b6d7e930cf9e493c5e6ef24b496294f95594c8" ] }' | apify call redfoxxie/polymarket-wallet-trade-monitor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=redfoxxie/polymarket-wallet-trade-monitor", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Polymarket Whale Wallet Trade Monitor and Alerts", "description": "Schedule enriched alerts for new public Polymarket whale-wallet trades. Infer maker/taker role, add notional and dynamic fee context, suppress duplicate alerts across runs, and preview activity free before enabling paid records. No wallet credentials or private API keys required.", "version": "0.1", "x-build-id": "Iq1J5sw9KdcXwmdHg" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/redfoxxie~polymarket-wallet-trade-monitor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-redfoxxie-polymarket-wallet-trade-monitor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/redfoxxie~polymarket-wallet-trade-monitor/runs": { "post": { "operationId": "runs-sync-redfoxxie-polymarket-wallet-trade-monitor", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/redfoxxie~polymarket-wallet-trade-monitor/run-sync": { "post": { "operationId": "run-sync-redfoxxie-polymarket-wallet-trade-monitor", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "wallets" ], "properties": { "wallets": { "title": "Wallet addresses", "minItems": 1, "maxItems": 20, "type": "array", "description": "One to twenty public Polymarket proxy-wallet addresses to monitor.", "items": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" } }, "monitorId": { "title": "Persistent monitor ID", "minLength": 1, "maxLength": 48, "type": "string", "description": "Scheduled runs with the same ID share a dedupe state. Use a different ID for each wallet set.", "default": "default" }, "previewOnly": { "title": "Free preview", "type": "boolean", "description": "Returns counts and largest notional without trade identities, charges nothing, and does not advance state.", "default": true }, "lookbackMinutes": { "title": "Lookback minutes", "minimum": 1, "maximum": 1440, "type": "integer", "description": "Fetch trades this many minutes before the current run. Overlap scheduled runs safely; persistent state suppresses delivered duplicates.", "default": 15 }, "maxTradesPerWallet": { "title": "Rows fetched per wallet", "minimum": 50, "maximum": 5000, "type": "integer", "description": "Maximum public all-trade and taker-only rows fetched per wallet before filtering the lookback.", "default": 500 }, "minNotionalUsdc": { "title": "Minimum trade notional", "minimum": 0, "type": "number", "description": "Ignore observed trades whose price multiplied by shares is below this USDC amount.", "default": 50 }, "roles": { "title": "Inferred execution roles", "minItems": 1, "maxItems": 2, "type": "array", "description": "Return maker fills, taker fills, or both after exact bounded-sample maker/taker inference.", "items": { "type": "string", "enum": [ "maker", "taker" ] }, "default": [ "maker", "taker" ] }, "maxAlerts": { "title": "Maximum paid alerts", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Hard cap on new paid alert records delivered in one run. Preview mode never emits these paid events.", "default": 200 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```