{
  "openapi": "3.0.1",
  "info": {
    "title": "Polymarket Scraper — Odds, Order Book & Trades",
    "description": "Scrape polymarket.com prediction markets as structured JSON. Every row carries the question with its outcomes and live prices, the volume and liquidity behind them, plus tags and resolution dates. Filter before the run costs anything. Order book and trades on request.",
    "version": "0.1",
    "x-build-id": "hAcj2KHygH2yvrWVg"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/blackfalcondata~polymarket-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-blackfalcondata-polymarket-scraper",
        "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/blackfalcondata~polymarket-scraper/runs": {
      "post": {
        "operationId": "runs-sync-blackfalcondata-polymarket-scraper",
        "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/blackfalcondata~polymarket-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-blackfalcondata-polymarket-scraper",
        "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",
        "properties": {
          "query": {
            "title": "🔍 Search Term(s)",
            "type": "string",
            "description": "What the markets should be about — e.g. \"election\", \"bitcoin\", \"fed rate cut\". Paste a JSON array like [\"election\",\"bitcoin\"] to run several searches in one go."
          },
          "mode": {
            "title": "🧭 What to collect",
            "enum": [
              "markets",
              "wallets",
              "walletPnl"
            ],
            "type": "string",
            "description": "Markets searches the Polymarket catalogue. Wallet positions reports what each wallet below holds — every position with its size, entry price, current value and profit, both realised and unrealised. Wallet P&L analysis rebuilds each wallet's trading record over the window below: realised profit, win rate, entry prices and every market it traded, one summary row per wallet plus one row per market. Market filters and depth options apply to market searches only.",
            "default": "markets"
          },
          "walletAddresses": {
            "title": "👛 Wallet addresses",
            "type": "array",
            "description": "Polymarket wallet addresses (0x followed by 40 hex characters), one per line. Used when What to collect is Wallet positions or Wallet P&L analysis. Every position each wallet holds is returned, including very small ones.",
            "items": {
              "type": "string"
            }
          },
          "pnlWindowDays": {
            "title": "📅 P&L window (days)",
            "minimum": 1,
            "maximum": 365,
            "type": "integer",
            "description": "How many days of trading the Wallet P&L analysis covers, counted back from now. Positions opened before the window are still priced on their full history. Used only with Wallet P&L analysis.",
            "default": 30
          },
          "status": {
            "title": "📊 Market status",
            "enum": [
              "any",
              "open",
              "closed"
            ],
            "type": "string",
            "description": "Return only open markets (still trading), only closed ones (settled), or both. Default: both.",
            "default": "any"
          },
          "tagIds": {
            "title": "🏷️ Tag IDs",
            "type": "array",
            "description": "Only markets carrying at least one of these Polymarket tag IDs. Several IDs widen the result (any match), they do not narrow it. Tag IDs appear on every row under \"tags\".",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "marketSlugs": {
            "title": "🔗 Market slugs",
            "type": "array",
            "description": "Fetch exactly these markets by slug, e.g. \"xi-jinping-out-before-2027\". Exact match.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "conditionIds": {
            "title": "🧾 Condition IDs",
            "type": "array",
            "description": "Fetch exactly these markets by on-chain condition ID (0x...). Exact match.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "minTotalVolume": {
            "title": "💰 Min lifetime volume (USD)",
            "minimum": 0,
            "type": "integer",
            "description": "Skip markets that have traded less than this in total. Leave empty for no floor."
          },
          "minVolume24h": {
            "title": "📈 Min 24h volume (USD)",
            "minimum": 0,
            "type": "integer",
            "description": "Skip markets that traded less than this in the last 24 hours — the usual way to cut dormant markets."
          },
          "minLiquidity": {
            "title": "💧 Min liquidity (USD)",
            "minimum": 0,
            "type": "integer",
            "description": "Skip thin markets with less resting liquidity than this."
          },
          "endDateMin": {
            "title": "📅 Ends on or after",
            "type": "string",
            "description": "Only markets resolving on or after this date (YYYY-MM-DD)."
          },
          "endDateMax": {
            "title": "📆 Ends on or before",
            "type": "string",
            "description": "Only markets resolving on or before this date (YYYY-MM-DD)."
          },
          "includeOrderBook": {
            "title": "📖 Include order book",
            "type": "boolean",
            "description": "Add the live resting order book for every outcome — bids, asks, best prices, spread and the USD resting on each side. Cheap: the whole page is fetched in one batched request.",
            "default": false
          },
          "orderBookDepth": {
            "title": "📐 Order book depth",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "How many price levels per side to keep. Best-priced first. The USD depth totals always describe the FULL book, not this slice.",
            "default": 10
          },
          "includeRecentTrades": {
            "title": "🧾 Include recent trades",
            "type": "boolean",
            "description": "Add the most recent trades on each market — wallet, side, size, price and time. Costs one extra request per market.",
            "default": false
          },
          "recentTradesLimit": {
            "title": "🔢 Trades per market",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "How many recent trades to return per market.",
            "default": 20
          },
          "includeTopHolders": {
            "title": "🐳 Include top holders",
            "type": "boolean",
            "description": "Add the largest positions in each market — wallet, display name, which outcome they are on, and size. Costs one extra request per market.",
            "default": false
          },
          "topHoldersLimit": {
            "title": "🔢 Holders per market",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "How many of the largest holders to return per market, counted across both outcomes.",
            "default": 10
          },
          "includePriceHistory": {
            "title": "📈 Include price history",
            "type": "boolean",
            "description": "Add a price series per outcome. This is the most expensive switch: one request per outcome, so a two-outcome market costs two extra requests.",
            "default": false
          },
          "priceHistoryInterval": {
            "title": "⏱️ Price history window",
            "enum": [
              "1h",
              "6h",
              "1d",
              "1w",
              "1m",
              "max"
            ],
            "type": "string",
            "description": "How far back the price series reaches. Hourly points.",
            "default": "1w"
          },
          "includeRawData": {
            "title": "🧱 Include raw API record",
            "type": "boolean",
            "description": "Attach the untouched source record to every row. Useful when you want a field this actor does not map yet. It roughly doubles the row size.",
            "default": false
          },
          "maxResults": {
            "title": "💯 Max Results",
            "minimum": 0,
            "maximum": 250000,
            "type": "integer",
            "description": "Maximum number of markets to return. 0 means every market that matches — about 190,000 open markets, or roughly 490,000 including settled ones. A run also stops at your own cost limit and tells you, so narrow with the filters below and let incremental mode pick up the rest.",
            "default": 100
          },
          "descriptionMaxLength": {
            "title": "✂️ Description Max Length",
            "minimum": 0,
            "type": "integer",
            "description": "Truncate the market's resolution rules to N chars. 0 = no truncation.",
            "default": 0
          },
          "compact": {
            "title": "📦 Compact Output",
            "type": "boolean",
            "description": "Core market fields only — question, prices, volume, status (for AI-agent/MCP workflows).",
            "default": false
          },
          "incrementalMode": {
            "title": "♻️ Incremental Mode",
            "type": "boolean",
            "description": "Compare against previous run state. stateKey is optional — defaults to a value derived from search inputs so different searches never share state.",
            "default": false
          },
          "stateKey": {
            "title": "🔑 State Key",
            "type": "string",
            "description": "Optional. Stable identifier for the tracked set of markets. Leave empty to auto-generate from search inputs."
          },
          "skipReposts": {
            "title": "🚫 Skip Reposts",
            "type": "boolean",
            "description": "When incremental, skip markets whose content matches an expired market from a prior run (cross-run duplicate detection).",
            "default": false
          },
          "telegramToken": {
            "title": "🔑 Telegram Bot Token",
            "type": "string",
            "description": "Telegram bot token (from @BotFather). Required for Telegram notifications."
          },
          "telegramChatId": {
            "title": "💬 Telegram Chat ID",
            "type": "string",
            "description": "Telegram chat or channel ID (e.g. \"-100123456789\"). Required when telegramToken is set."
          },
          "discordWebhookUrl": {
            "title": "🎮 Discord Webhook URL",
            "type": "string",
            "description": "Discord incoming webhook URL. Server Settings → Integrations → Webhooks → New Webhook."
          },
          "slackWebhookUrl": {
            "title": "💼 Slack Webhook URL",
            "type": "string",
            "description": "Slack incoming webhook URL. api.slack.com/messaging/webhooks."
          },
          "notificationLimit": {
            "title": "📊 Max Markets Per Notification",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Maximum number of markets included in each notification message (1–20).",
            "default": 5
          },
          "notifyOnlyChanges": {
            "title": "🔄 Notify Only New/Updated",
            "type": "boolean",
            "description": "When Incremental Mode is on, only send notifications for NEW and UPDATED markets. Has no effect outside incremental mode.",
            "default": false
          },
          "whatsappAccessToken": {
            "title": "📱 WhatsApp Access Token",
            "type": "string",
            "description": "WhatsApp Cloud API permanent access token (System User token from Meta Business). Recipient must have messaged the business number within the last 24h (service-conversation window — free since Nov 2024)."
          },
          "whatsappPhoneNumberId": {
            "title": "📞 WhatsApp Phone Number ID",
            "type": "string",
            "description": "Your WhatsApp Business phone-number ID (numeric, from Meta dashboard). Required when whatsappAccessToken is set."
          },
          "whatsappTo": {
            "title": "📲 WhatsApp Recipient",
            "type": "string",
            "description": "Recipient phone in E.164 format without + (e.g. \"436641234567\"). Recipient must have messaged your business number within last 24h."
          },
          "webhookUrl": {
            "title": "🪝 Generic Webhook URL",
            "type": "string",
            "description": "Receives a JSON POST with {metadata, items} after each run. Universal escape hatch for n8n / Make / Zapier / custom backends."
          },
          "webhookHeaders": {
            "title": "📋 Webhook Headers",
            "type": "object",
            "description": "Optional JSON object of custom headers (e.g. {\"Authorization\":\"Bearer ...\"})."
          },
          "appConnector": {
            "title": "Send results to a connected app",
            "type": "string",
            "description": "Optional. Pick a connected app under Settings → API & Integrations to receive your results. Best-effort across MCP connectors as Apify expands its catalog."
          },
          "mcpIssueTeam": {
            "title": "Issue tracker team",
            "type": "string",
            "description": "Only when the connected app is an issue tracker: the team (name or ID) the summary issue is created under, if that app requires one."
          },
          "descriptionFormat": {
            "title": "Description format",
            "enum": [
              "all",
              "text",
              "html",
              "markdown"
            ],
            "type": "string",
            "description": "Pick a single description representation. Polymarket serves plain-text resolution rules, so `all` and `text` are equivalent here.",
            "default": "all"
          },
          "excludeEmptyFields": {
            "title": "Exclude empty fields from output",
            "type": "boolean",
            "description": "Drop null, empty-string, and empty-array fields from each record before push. Smaller payloads for AI agents and dashboards.",
            "default": false
          },
          "emitUnchanged": {
            "title": "🔄 Emit Unchanged Markets",
            "type": "boolean",
            "description": "When incremental mode is on, also emit markets whose tracked content has not changed since the last run.",
            "default": false
          },
          "emitExpired": {
            "title": "⚰️ Emit Expired Markets",
            "type": "boolean",
            "description": "When incremental mode is on, also emit markets that were seen before but are no longer found.",
            "default": false
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}