# Polymarket Order Book Execution Intelligence (`redfoxxie/polymarket-execution-intelligence`) Actor

Turn Polymarket public order books into execution-sized data. Get YES/NO VWAPs, worst fill prices, live fee schedules, depth checks, book age, and fee-adjusted pair economics for research, dashboards, automations, and AI agents. No wallet or API key required.

- **URL**: https://apify.com/redfoxxie/polymarket-execution-intelligence.md
- **Developed by:** [João Ferreira](https://apify.com/redfoxxie) (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

$10.00 / 1,000 execution-grade markets

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 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.

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.

Turn public Polymarket order books into **execution-sized market data**. Instead
of repeating a displayed best ask, this Actor walks the YES and NO books for the
share quantity you choose and reports VWAP, worst fill price, available depth,
the live Gamma fee schedule, and fee-adjusted pair economics. It is built for
market research, dashboards, alerts, data pipelines, and AI agents.

The first five output records in every run are free. No Polymarket wallet,
private key, or API key is required.

The Actor is designed for Apify's **limited-permission** runtime: it needs only
its default run storage and public network access. With pay-per-event pricing
and Standby disabled, this also satisfies the technical prerequisites for
agentic-payment discovery when Apify marks the published Actor as eligible.

### Why use this Polymarket order book API?

A quoted price is not necessarily executable for your size. Thin depth can turn
a seemingly attractive market into a poor fill, and Polymarket fee schedules
vary by market. Each output record keeps these concerns together:

- YES and NO best bids and asks;
- book-walked buy and sell VWAPs for the requested share count;
- the worst price needed to complete that quantity;
- tick size and minimum order size for each token;
- live fee type, rate, exponent, rebate rate, and source;
- fee-adjusted cost, PnL, and ROI for buying both binary outcomes;
- book age, missing-depth, crossed/locked-book, and fee-fallback checks;
- negative-risk and augmented-event context.

Results are stored in an exportable Apify dataset with a documented output
schema for JSON, CSV, Excel, API, and MCP/AI-agent workflows.

### Quick start

Run the Actor with the defaults to inspect 50 liquid markets at Polymarket's
five-share minimum:

```json
{
  "maxItems": 50,
  "orderSizeShares": 5,
  "minLiquidityUsdc": 1000,
  "search": "",
  "feeTypes": [],
  "positiveGapsOnly": false
}
````

To inspect Bitcoin markets at a larger execution size, set `search` and
`orderSizeShares`:

```json
{
  "maxItems": 100,
  "orderSizeShares": 25,
  "minLiquidityUsdc": 2500,
  "search": "Bitcoin"
}
```

Use `positiveGapsOnly=true` to return only current observations where the
book-walked pair has positive resolution value after the current fee schedule.
This is a research filter, not a profit guarantee.

### Search-ready examples

After publication, the Examples tab includes runnable tasks for Bitcoin depth,
fee-adjusted pair-gap discovery, and 25-share slippage. Their exact inputs live
in `public_tasks.json`, so the landing-page promise and the run configuration
stay auditable together.

### Example Polymarket execution record

```json
{
  "question": "Will an event happen?",
  "order_size_shares": 5,
  "yes": {"best_ask": 0.48, "buy_vwap": 0.49, "buy_worst_price": 0.50},
  "no": {"best_ask": 0.53, "buy_vwap": 0.53, "buy_worst_price": 0.53},
  "fee": {"rate": 0.07, "exponent": 1, "fee_type": "crypto_fees_v2"},
  "pair_route": {
    "executable": true,
    "net_pnl_at_resolution_usdc": -0.18,
    "standing_positive_gap": false
  },
  "quality": {"crossed_or_locked_book": false, "book_age_ms": 240}
}
```

### Pricing

The launch model is **Pay per event + usage**: the first five records are free,
then each `execution_grade_market` record costs **$0.01**. There is no custom
start fee. Apify platform usage is billed separately by Apify to the account
running the Actor. Set `maxItems` to make the maximum custom-event charge
predictable before running.

### Important execution limitations

A positive pair observation is not an atomic arbitrage. The two outcome orders
must be placed separately, displayed liquidity can cancel, competing orders can
consume depth, and the market can move between observation and execution. The
Actor reads public data and never places orders or requests wallet credentials.

Users remain responsible for Polymarket's terms, geographic restrictions, and
applicable law. Output is factual market data, not financial advice.

### Troubleshooting and support

- Empty output usually means the search, liquidity, fee-type, or positive-gap
  filters excluded every scanned market.
- A null VWAP means the requested size was not available in the current book.
- `fee_schedule_fallback=true` means Gamma did not supply a complete dynamic
  schedule and the record used the Actor's explicit fallback.
- Use the Actor's Apify Issues tab to report a reproducible market/token mismatch
  with the run ID and condition ID.

# Actor input Schema

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

Maximum number of enriched market records. The first five records in each run are free.

## `orderSizeShares` (type: `number`):

Order-book VWAP and fees are calculated for this many shares. Polymarket's minimum is enforced.

## `minLiquidityUsdc` (type: `number`):

Exclude markets whose Gamma-reported liquidity is below this USDC amount.

## `search` (type: `string`):

Optional case-insensitive text filter over market question, slug, and parent event title.

## `feeTypes` (type: `array`):

Optional exact Gamma feeType values, for example crypto\_fees\_v2 or fee\_free.

## `positiveGapsOnly` (type: `boolean`):

Return only markets where both 5-share asks leave positive resolution value after current taker fees. This is detection, not an atomic-fill guarantee.

## Actor input object example

```json
{
  "maxItems": 50,
  "orderSizeShares": 25,
  "minLiquidityUsdc": 2500,
  "search": "Bitcoin",
  "feeTypes": [
    "crypto_fees_v2"
  ],
  "positiveGapsOnly": true
}
```

# Actor output Schema

## `markets` (type: `string`):

Polymarket market metadata, order-book VWAPs, dynamic fees, route economics, and quality checks.

# 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("redfoxxie/polymarket-execution-intelligence").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("redfoxxie/polymarket-execution-intelligence").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 '{}' |
apify call redfoxxie/polymarket-execution-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=redfoxxie/polymarket-execution-intelligence",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Polymarket Order Book Execution Intelligence",
        "description": "Turn Polymarket public order books into execution-sized data. Get YES/NO VWAPs, worst fill prices, live fee schedules, depth checks, book age, and fee-adjusted pair economics for research, dashboards, automations, and AI agents. No wallet or API key required.",
        "version": "0.1",
        "x-build-id": "IZeyuwPqlEx5ejofv"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/redfoxxie~polymarket-execution-intelligence/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-redfoxxie-polymarket-execution-intelligence",
                "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-execution-intelligence/runs": {
            "post": {
                "operationId": "runs-sync-redfoxxie-polymarket-execution-intelligence",
                "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-execution-intelligence/run-sync": {
            "post": {
                "operationId": "run-sync-redfoxxie-polymarket-execution-intelligence",
                "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": {
                    "maxItems": {
                        "title": "Maximum markets",
                        "minimum": 1,
                        "maximum": 200,
                        "type": "integer",
                        "description": "Maximum number of enriched market records. The first five records in each run are free.",
                        "default": 50
                    },
                    "orderSizeShares": {
                        "title": "Execution size in shares",
                        "minimum": 5,
                        "maximum": 1000,
                        "type": "number",
                        "description": "Order-book VWAP and fees are calculated for this many shares. Polymarket's minimum is enforced.",
                        "default": 5
                    },
                    "minLiquidityUsdc": {
                        "title": "Minimum market liquidity",
                        "minimum": 0,
                        "type": "number",
                        "description": "Exclude markets whose Gamma-reported liquidity is below this USDC amount.",
                        "default": 1000
                    },
                    "search": {
                        "title": "Question or event search",
                        "maxLength": 200,
                        "type": "string",
                        "description": "Optional case-insensitive text filter over market question, slug, and parent event title.",
                        "default": ""
                    },
                    "feeTypes": {
                        "title": "Fee schedule filters",
                        "maxItems": 10,
                        "type": "array",
                        "description": "Optional exact Gamma feeType values, for example crypto_fees_v2 or fee_free.",
                        "items": {
                            "type": "string",
                            "maxLength": 64
                        },
                        "default": []
                    },
                    "positiveGapsOnly": {
                        "title": "Only standing positive pair gaps",
                        "type": "boolean",
                        "description": "Return only markets where both 5-share asks leave positive resolution value after current taker fees. This is detection, not an atomic-fill guarantee.",
                        "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```