Polymarket API Tutorial: Build a Live 2026 World Cup Prediction Dashboard

Those who have been following the 2026 FIFA World Cup through anything other than television, one set of numbers is worth pausing over. The Polymarket World Cup Winner market has processed $1.96 billion in trading volume, making it the largest prediction market event ever run. Forty-eight national teams, each with its own order book, reprice continuously as money flows in. Spain trades at 16 cents, France sits at 16.05, and England and Portugal are deadlocked at 11. These numbers move every few seconds, and if you are watching them through Polymarket’s web interface, you are seeing one market at a time through a user interface built for clicking buttons, not for analysis.

A hardly surprising limitation, given that the platform was designed for retail users, but one that leaves a considerable amount of insight on the table. What follows is a guide to building a real-time World Cup prediction dashboard in Python that pulls live odds from the Polymarket API, converts contract prices into proper probabilities, visualises probability shifts over time, inspects order book depth before you trade, and runs an arbitrage scanner across all 48 outcomes. Every line of code discussed here was executed against the live Polymarket API, and every number in the output blocks is real market data from the World Cup 2026 winner market.

You need intermediate Python and nothing else. No Polymarket account, no API key, no wallet. Reading market data from Polymarket is completely unauthenticated. You only need credentials when you start placing orders, and this guide stops one step short of that line on purpose. A dashboard that helps you see the market clearly is, as any experienced trader will quietly confirm, worth considerably more than a bot that trades it blindly.

The Two Polymarket APIs You Need to Understand

Before writing a single line of code, it is worth understanding the architecture behind Polymarket’s data, because most tutorials blur two very different systems together, and that confusion costs people hours.

The Gamma API

The Gamma API, available at gamma-api.polymarket.com, is the metadata and discovery layer. It knows about events, markets, slugs, volumes, current prices, and descriptions. When you want to answer the question “what World Cup markets exist and what are they trading at right now,” Gamma is your endpoint. It is a plain REST API that returns JSON, and no authentication is required.

The CLOB API

The CLOB API, available at clob.polymarket.com, is the trading engine’s data interface. CLOB stands for Central Limit Order Book, the same matching architecture used by stock exchanges and cryptocurrency exchanges. This API gives you the actual order book for any outcome token: every resting bid and ask, with price and size. It also serves midpoints, spreads, and historical price series. When you want to answer the question “what would it actually cost me to buy $100,000 of Spain right now,” only the CLOB API can tell you.

Token ID Connection

The connecting tissue between the two is the token ID. Every market on Polymarket has two outcome tokens, YES and NO, each identified by a long numeric string. The Gamma API provides these token IDs in a field called clobTokenIds, and you pass them to the CLOB API to retrieve books and price history. That handoff is the spine of everything that follows.

One more concept before the code begins: Polymarket prices live between 0.00 and 1.00. A YES share pays out 1.00 if the outcome occurs and 0.00 if it does not. So a price of $0.1695 for Spain means the market collectively assigns Spain a 16.95 percent chance of lifting the trophy. Price equals probability, which is what makes prediction market data considerably cleaner to work with than traditional bookmaker odds formats.

Getting Started

Setting up the project requires just four packages: requests for REST calls, pandas for structuring data, plotly for charts, and streamlit for the dashboard. For those who prefer real-time feeds, websockets powers the upgrade discussed later. That is the entire dependency list, and the simplicity, for anyone accustomed to heavier data stacks, is part of the appeal.

Step 1: Pulling All 48 World Cup Markets from the Gamma API

The World Cup Winner market lives at event ID 30615 on Polymarket. You can find any event’s ID by searching the Gamma events endpoint, but for a tutorial it is reasonable to hardcode it.

A few details are worth flagging here, because they trip up almost everyone on first contact with the Gamma API. The outcomePrices and clobTokenIds fields arrive as JSON strings inside the JSON response, so they need to be parsed a second time with json.loads. The groupItemTitle field provides the clean team name, such as “Spain,” rather than the full market question, which matters considerably once you are rendering 48 rows in a dashboard table.

Running this against the live API returns all 48 active markets. The top twelve by price, during the build of this guide, showed Spain leading at 16.95 cents, France close behind at 16.05, and England and Portugal tied at 10.85. One Gamma call, every World Cup market, sub-second response. Even Colombia, at 1.85 cents, had pushed $40 million through its book. That depth of liquidity is what separates the World Cup market from the average prediction market, and it is why the analysis discussed throughout this guide produces numbers that are genuinely tradeable.

Step 2: Implied Probability and the Overround

Prices map to probabilities, but the raw prices across a mutually exclusive market never sum to exactly 1.00. Only one team has the possibility of winning the World Cup, so in a mathematically fair market the 48 probabilities would total precisely 100 percent. Sum the live prices, however, and the result tells a different story.

The live World Cup market carries a 4.30 percent overround. That excess is the cushion market makers collect for providing liquidity, and it is structurally identical to the vig a sportsbook builds into its lines, except here it emerges from spread dynamics rather than being set by a bookmaker.

The fix is straightforward: divide each price by the total. Spain’s raw implied probability of 16.95 percent deflates to a fair probability of 16.25 percent. France drops from 16.05 percent to 15.39 percent. Small differences per team, perhaps, but they compound considerably. If you are comparing Polymarket probabilities against your own model, or against Kalshi, or against bookmaker lines, you must compare de-vigged numbers to de-vigged numbers. Comparing a raw Polymarket price against a normalised model output will manufacture phantom edges that disappear the moment you trade them.

Your dashboard should display both columns. Raw price is what you transact at. Fair probability is what you reason with. The distinction, while it might seem subtle, changes how every subsequent analysis reads.

Step 3: Order Book Depth and the True Cost of Size

The Gamma API tells you the last price. It does not tell you what your order would actually fill at. For that, you need the CLOB API’s book endpoint, keyed by the token ID collected in Step 1.

Spain’s live book at the time of this build showed nearly half a million shares resting at the top bid, with even more at the ask. The bid-ask spread was a single tick. This is, by any reasonable standard, institutional-grade depth.

But depth at the top of the book only protects orders that fit within it. To understand what a larger order truly costs, you need to walk the book level by level and compute the volume-weighted fill price. Running this calculation against Spain’s live ask side produces a result that is worth reading carefully. A $100,000 market buy fills at the top ask with zero slippage, because 568,000 shares at 0.170 absorbs the entire order. Push to $250,000, however, and the average fill jumps to 24.11 cents, a 42 percent premium over the screen price, because the order chews through the entire first level and begins climbing a much thinner upper book.

This single function is the difference between a dashboard that displays prices and a dashboard with genuine trading utility. Screen price is, in many respects, an advertisement. Executable price is reality. Your dashboard should compute executable prices at two or three reference sizes for every market you care about, and the gap between a 10,000 fill and a 250,000 fill tells you instantly how much real liquidity sits behind a quote.

Step 4: Charting Probability Shifts with Historical Prices

A snapshot tells you where the market is. A time series tells you where the money has been moving. The CLOB API serves historical prices through its prices-history endpoint, with parameters for interval, such as one day, one week, one month, or maximum, and fidelity, which sets resolution in minutes.

Pulling one month of history for the five most traded teams produces a picture that contains a real story. A month ago, France was the tournament favourite at 17.7 cents, with Spain trailing at 16.1. By the time of this build, the two lines had fully crossed. Argentina had quietly gained 8 percent while England bled support. None of this is visible on Polymarket’s front end, which shows current prices and a single market’s chart at a time. A dashboard that overlays the contenders on one axis surfaces rotation between teams the moment it begins.

The plotting itself requires only a few lines of Plotly. Multiplying by 100 ensures the y-axis reads as percentages, and the hovermode setting puts all teams in a single hover tooltip, which is what you want when scrubbing the chart for the exact day France and Spain crossed.

Step 5: The Arbitrage Scanner, and Why Naive Scanners Lie

Here is where the dashboard earns its keep for traders, and where a considerable number of people are led astray.

A mutually exclusive multi-outcome market has two structural arbitrage conditions, and both reduce to simple sums. The long arbitrage: if you can buy YES on all 48 teams for a combined cost under 1.00, you lock in profit because exactly one of those positions must resolve to 1.00. Sum the best asks; if the total falls below 1.00, the arb exists. The short arbitrage runs the other way: if you can sell YES on all 48 teams for combined proceeds above 1.00, you collect more premium than the single winning contract will cost you at resolution. Sum the best bids; if the total exceeds 1.00, the arb exists.

Running the scanner on live World Cup data flags something immediately. The scanner detects a live short arbitrage: 1.9 cents of riskless profit per set, on the most liquid prediction market ever to exist. Sell one full set of 48 YES contracts, collect 1.019, pay out 1.00 when one team wins, and keep 0.019. Scale it to 100,000 sets and that is $1,900 of apparently free money, repeatable.

Before wiring up a wallet, however, it is worth extending the scanner one level deeper. Top-of-book prices are not sufficient. You also need top-of-book sizes, because an arbitrage you cannot fill on every leg simultaneously is not, in any meaningful sense, an arbitrage. Pull the full order book for all 48 outcomes and check the depth behind each bid.

The result is instructive, and for many people, humbling. The arbitrage evaporates entirely. Curaçao, Jordan, New Zealand, Haiti, and Uzbekistan have no resting bids at all. Nobody is willing to pay even a tenth of a cent for the YES side of a 500-to-1 longshot, which means five of the 48 legs cannot be sold at any price. The short arb requires selling all 48 legs. Executable capacity: zero sets. Riskless profit: zero dollars.

This is, arguably, the most important lesson in this entire guide, and it is why the depth function from Step 3 belongs at the heart of your scanner. A naive arbitrage scanner built on top-of-book prices alone will flag opportunities all day long, and every one of them will fail at execution on the thin legs. The market is not leaving $1,900 per hundred thousand sets on the table. It only looks that way from the price layer. Professional arbitrage desks devote most of their engineering effort to exactly this problem, and your dashboard should display arb signals with their executable capacity attached, or it will train you to chase ghosts.

Partial arbitrage across subsets is, for those willing to dig deeper, where the real hunting happens. The condition “sell every leg” can be relaxed: if the top 20 teams’ bids sum close to 1.00 on their own, shorting just those legs leaves you exposed only to a longshot winning, a risk you might price at a fraction of a cent. The scaffolding above provides everything needed to build that extension.

Step 6: Going Real-Time with the Polymarket WebSocket

Polling the REST APIs every few seconds works perfectly well for a personal dashboard, and for most users it is honestly sufficient. But Polymarket also runs a public WebSocket feed that pushes order book changes the moment they happen, and upgrading to it removes both the polling lag and the rate-limit pressure.

The market channel lives at wss://[ws-subscriptions-clob.polymarket.com/ws/market](https://ws-subscriptions-clob.polymarket.com/ws/market). You connect, send one subscription message listing the token IDs you care about, and the server begins streaming events. Two event types matter. On connection, you receive a book event per token, a full snapshot of bids and asks identical in shape to the REST book endpoint. After that, you receive price_change events carrying only the levels that moved.

The standard pattern is to hold the snapshot in a dictionary keyed by price level and apply each price_change as a patch. Your arbitrage scanner then re-runs on every patch rather than every poll cycle, which means you evaluate the arb condition within milliseconds of any book change across all 48 outcomes. If a genuine dislocation ever does appear in this market, it will live for seconds at most. WebSocket-driven scanning is the only architecture that gives you a realistic chance of catching it.

One practical caution, and it is one that has cost many developers a confused half hour against a silent connection: the subscription message takes the token IDs under the key assets_ids, with an s in the middle, an awkward spelling that is easy to overlook.

Step 7: Assembling the Streamlit Dashboard

Everything discussed so far is a data layer in a single file. Streamlit turns it into a served, auto-refreshing dashboard with remarkably little additional code.

Running it with the appropriate command opens the dashboard at localhost:8501. The caching decorator does quiet but important work: it stores the Gamma pull for 30 seconds so that every widget interaction does not re-hit the API, while still refreshing twice a minute. For faster updates, the TTL can be reduced or the data layer can be swapped onto the WebSocket feed from Step 6 with a background thread writing into session state.

The result is a single screen showing live prices and fair probabilities for all 48 teams, a 30-day probability shift chart for any set of contenders, the arbitrage check with its warning to verify depth, and executable price ladders for any book you select. That last panel alone puts you ahead of anyone trading off the Polymarket front end, and it does so with a few hundred lines of Python rather than a subscription to a professional terminal.

Extending the Dashboard

The build described above is a foundation, and several extensions are, for those who want to take it further, obvious next moves.

Cross-Platform Comparison

Cross-platform comparison is arguably the highest-value addition. Kalshi runs its own World Cup markets under CFTC regulation, with its own REST API. Pull both platforms into one normalised table and you can scan for cross-venue divergence, which historically runs wider and lasts longer than anything within a single venue, because capital cannot move instantly between a crypto-settled order book and a regulated U.S. exchange.

Alerting

Alerting transforms the dashboard from a screen you watch into a system that watches for you. Wrapping the scanner in a loop that fires a notification when any team moves more than two cents in an hour, when the overround compresses below 3 percent, or when executable depth at the top of any major book drops below a threshold you set turns passive observation into active intelligence. During the group stage, when 48 books reprice on every goal, alerts are the only realistic way to keep pace.

Match-Level Markets

Match-level markets multiply the surface area considerably. Everything discussed here targets the tournament winner market, but Polymarket also lists group winners, group runners-up, and individual fixtures. The code is identical; only the event ID changes. Group-stage markets are thinner and slower to reprice than the headline market, which makes them, for those hunting genuine mispricings, the more plausible hunting ground.

Rate Limits

Rate limits deserve respect. The public endpoints tolerate the request volumes described here without complaint, and the 48-book depth scan completes in under six seconds with sequential requests. If you parallelise aggressively, it is worth backing off on 429 responses and caching anything that has not changed. The WebSocket feed exists precisely so that high-frequency consumers stay off the REST endpoints.

What You Have Built

Whether one views this as a technical exercise or a genuine trading tool, the result is a working real-time prediction market dashboard. Live World Cup 2026 odds from the Polymarket Gamma API. Fair probabilities with the 4.30 percent overround stripped out. Order book depth and true executable prices from the CLOB API. Thirty-day probability shift charts that caught the France-to-Spain favourite rotation. An arbitrage scanner honest enough to tell you when its own signal is unfillable. And a WebSocket upgrade path for millisecond reaction times.

The deeper takeaway, and it is one that applies well beyond this particular tournament, is about the data itself. The $1.96 billion World Cup market is the best free real-time probability feed in sports, and almost everyone consumes it through a web page built for retail clicking. A few hundred lines of Python against two public APIs gives you a strictly better view than the platform’s own interface, plus the execution mathematics that the interface will never show you.

Whether one is building this dashboard as a learning project or as the foundation for a genuine trading operation, the direction of travel is clear. The tools are public, the data is free, and the tournament runs through July 2026. That, for anyone willing to put in the work, is more than enough time to point this dashboard at the market and see what it reveals.