Build a Simple Polymarket Market Scanner With Python

Prediction markets are interesting from a developer's perspective because the data is not just a number.

A market has a question.

It has possible outcomes.

It has prices.

It has an order book.

It has liquidity.

And all of those things can change while you are looking at them.

That makes Polymarket a surprisingly interesting dataset to work with.

Instead of manually opening markets and scrolling through them, you can use the API to build a small research tool that finds markets, extracts their data, and gives you a cleaner starting point for analysis.

In this tutorial, we'll build a simple version in Python.

The goal isn't to build a trading bot.

The goal is to build something more useful for research:

Find a market, inspect its data, inspect its order book, then decide whether it deserves deeper research.

How Polymarket's APIs fit together

Polymarket separates its market data across different APIs.

The Gamma API is useful for discovering markets and retrieving market metadata.

The CLOB API is where you'll find order-book and pricing information.

There is also a Data API for things such as trades and positions.

For our small research tool, we mainly need Gamma and CLOB.

A simple way to think about the workflow is:

Gamma API
Find markets
Get market metadata
Get YES / NO token IDs

CLOB API
Get prices
Get order book
Analyze the market

The important part is that the market metadata gives you the token IDs you need to query the CLOB.

Polymarket's documentation and Institute examples show this workflow directly.

Step 1: Get some active markets

Let's start by asking Gamma for active markets.

import requests

url = "https://gamma-api.polymarket.com/markets"

params = {
"active": "true",
"closed": "false",
"limit": 10
}

response = requests.get(url, params=params)
response.raise_for_status()

markets = response.json()

for market in markets:
print(market.get("question"))

That's already useful.

Instead of manually browsing Polymarket, your program can now retrieve a list of markets.

But a list of questions isn't enough.

We want to know what each market is trading at.

Step 2: Look at the market data

A market response contains metadata that can help you understand what you're looking at.

For example:

for market in markets:
print("Question:", market.get("question"))
print("Liquidity:", market.get("liquidity"))
print("Volume:", market.get("volume"))
print()

You can also inspect the complete response while developing:

print(markets[0])

This is a good habit when working with an API you haven't used before.

Don't assume the field names or structure.

Look at the actual response.

Then build your code around it.

Step 3: Get the outcome token IDs

This is where things get more interesting.

Polymarket markets have outcome tokens, and the CLOB uses the relevant token ID when you request order-book or price information.

For a binary market, you'll typically have YES and NO outcomes.

The market response exposes the CLOB token IDs.

Depending on the API response, some fields may arrive as JSON-encoded strings, so make sure you inspect and parse them correctly.

For example:

import json

market = markets[0]

token_ids = market.get("clobTokenIds")

if isinstance(token_ids, str):
token_ids = json.loads(token_ids)

print(token_ids)

Now you have the identifiers needed to query the CLOB.

Step 4: Get the current price

Let's take the first token and ask the CLOB for its current price.

token_id = token_ids[0]

url = "https://clob.polymarket.com/price"

params = {
"token_id": token_id,
"side": "BUY"
}

response = requests.get(url, params=params)
response.raise_for_status()

price_data = response.json()

print(price_data)

The CLOB API provides price information for a specific token and side.

Now we have something much more useful than a market title.

We have a market and a current executable price.

But there is still a problem.

One price doesn't tell you much about liquidity.

Step 5: Read the order book

This is where the project becomes more interesting.

The order book shows the bids and asks currently sitting in the market.

url = "https://clob.polymarket.com/book"

params = {
"token_id": token_id
}

response = requests.get(url, params=params)
response.raise_for_status()

book = response.json()

print("Bids:")
print(book.get("bids"))

print("Asks:")
print(book.get("asks"))

Now you can inspect the actual market structure.

For example, imagine you find something like:

Bids
0.47 → 100 shares
0.46 → 250 shares
0.45 → 500 shares

Asks
0.53 → 80 shares
0.54 → 150 shares
0.55 → 400 shares

The displayed probability might look like roughly 50%.

But the order book tells you something more important.

There is a meaningful gap between what buyers are offering and what sellers are asking.

That is the spread.

And if you want to trade, the spread matters.

Turn the order book into something readable

Raw API responses are useful for debugging.

They're not particularly useful for humans.

Let's extract the best bid and best ask.

bids = book.get("bids", [])
asks = book.get("asks", [])

best_bid = max(
float(order["price"])
for order in bids
) if bids else None

best_ask = min(
float(order["price"])
for order in asks
) if asks else None

print("Best bid:", best_bid)
print("Best ask:", best_ask)

if best_bid is not None and best_ask is not None:
spread = best_ask - best_bid
print("Spread:", spread)

Now your script can answer a much more useful question:

What does the market actually look like right now?

Not just what the headline says.

Not just what the displayed probability says.

But what buyers and sellers are actually offering.

Add a simple market filter

Now let's turn this into something closer to a scanner.

Suppose you only want to investigate markets with enough liquidity.

You can create a basic filter:

MIN_LIQUIDITY = 10000

for market in markets:
liquidity = float(market.get("liquidity") or 0)

if liquidity >= MIN_LIQUIDITY:
    print(
        market.get("question"),
        "Liquidity:",
        liquidity
    )

This isn't a trading strategy.

It's simply a way to reduce the number of markets you need to manually inspect.

And that's an important distinction.

A scanner should help you find things worth researching.

It shouldn't pretend to know which trade will win.

You can take this much further

Once you have the basic pipeline working, there are several directions you can take it.

You could collect historical prices and calculate how quickly markets move after major events.

You could monitor changes in spreads.

You could compare market prices against your own probability model.

You could rank markets by liquidity.

You could detect unusually large changes in price.

You could build a dashboard showing the most interesting markets.

You could even send yourself an alert when a market meets a set of conditions.

Polymarket's CLOB API also exposes historical price data, which makes time-series analysis possible rather than limiting you to the current snapshot.

One thing I would not do

Don't jump straight from:

API
Signal
Automatic trade

That's where a fun data project becomes a very different problem.

A price moving from 40¢ to 45¢ doesn't automatically mean you've discovered an opportunity.

You still need to understand the question.

You need to understand the resolution rules.

You need to understand liquidity and execution.

And you need a reason for believing your estimate is different from the market's.

The API gives you data.

It doesn't give you a thesis.

The interesting part isn't the bot

That's probably the biggest lesson from building something like this.

The interesting part isn't automatically placing trades.

It's being able to turn a prediction market into structured data that you can actually investigate.

Instead of opening twenty tabs, you can write a script that asks:

What markets are active?

Which ones have meaningful liquidity?

What are they currently priced at?

What does the order book look like?

How has the price moved?

Which markets deserve human attention?

That is a much better starting point for building.

And once you have that foundation, you can experiment.

Build a dashboard.

Build a notification system.

Build a historical analysis tool.

Build your own probability model.

Or eventually connect the research layer to a trading system.

But start with the data.

Because before you build a trading bot, you should probably build something that helps you understand the market first.

**The best automated trading systems don't start with an order.

They start with better information.**