Let Your Agent Track Polymarket for Predictions With a Free API

What You'll Get

Have an agent (Claude Code, Codex, etc.) use Polymarket's official command-line tool to read prediction market data, research on its own, give a probability estimate, compare it with the market price, and record each prediction. Once the markets settle, calculate how accurate its predictions were.

The API is completely free. Checking markets, prices, trends, and open orders requires no sign-up, no wallet, and no money. The agent can query as often as it likes.

If you want to trade, use your own account. Log in and place orders yourself at polymarket.com. Don't hand your account or wallet over to the agent.

Polymarket is restricted in many countries and regions, and trading involves real money. This tutorial covers research and prediction only. It is not investment advice and does not explain how to place orders.

First, Understand One Thing: Price Is Probability

Every question (market) on Polymarket has Yes and No shares. If the outcome occurs, Yes pays 1 dollar per share; otherwise it pays 0. So:

A Yes price of 0.30 dollars ≈ the market believes there is a 30% chance of it happening.
The agent's job: estimate its own probability, say 45%. The bigger the gap between that and the market's 30%, the more worth recording it and checking later who was right.

For more basics, see the Polymarket handbook.

Why It Tends to Be Accurate

For questions on political elections, stock and crypto prices, sports events, and similar topics, Polymarket prices often predict outcomes very well.

The reason is that bettors are accountable with real money:

Being wrong costs money, so people who are just talking don't place big bets.
People with more information, or even some insider knowledge, place big bets that push prices toward the real outcome. The more bettors and the more money involved, the closer the odds get to the true probability.

The author's observation: in this US election, Polymarket's odds pointed to a Democratic win well ahead of time, and that was accurate precisely because people with information advantages were voting with large bets.

This makes it a good source for "the probability the crowd put real money behind." Have the agent research and compare, and you get both the market's judgment and the AI's judgment.

Step 1: Install the Official CLI (2 Minutes)

brew tap Polymarket/polymarket-cli https://github.com/Polymarket/polymarket-cli
brew install polymarket

polymarket status            # check that the API is working
polymarket clob geoblock     # check whether your region is restricted

If you don't have Homebrew, follow the installation script instructions in the official repository, or just ask the agent to install it for you.

Do not run polymarket setup or polymarket wallet create. Those are for trading, and this tutorial doesn't need a wallet.

Step 2: Learn a Few Commands

Searching markets, checking prices, and viewing history don't require a wallet:

# Search markets
polymarket markets search "bitcoin" --limit 5

# View one market's details: question, rules, prices, volume, deadline
polymarket -o json markets get <market slug>

# View price trends (use the token id, the clobTokenIds in market details; the first is usually Yes)
polymarket clob price-history <token-id> --interval 1d

# View current buy and sell orders
polymarket clob book <token-id>

Adding -o json outputs JSON, which is the easiest format for agents to read.

Step 3: Hand the Prediction Task to the Agent

Create a new folder (for example, predictions), open Claude Code inside it, and send it the following:

New accounts get 10 free credits, plus 1 more for each daily check-in. Spend 1 credit to unlock and it stays open for you.

Swap the topic for whatever you care about: replace "US political elections" with "US stock earnings and share prices," "NBA playoffs," "World Cup," or "Bitcoin price," for example.

Step 4: Record Automatically Once a Day

To have the agent keep tracking without asking manually every day, have it write a script that saves these markets' prices daily:

Write a snapshot.sh: for the markets in predictions.csv that have not ended yet, use polymarket -o json to get the current Yes price and append it to prices.csv (date, slug, price).
Then use the built-in scheduler (launchd on Mac, cron on Linux) to run it once every morning at 9 a.m.

The script only reads data, does not call a large model, and uses no tokens. When analysis is needed, have the agent read prices.csv.

Step 5: Score the Agent After Settlement

After the markets close, tell the agent:

Check the markets in predictions.csv that have already settled, fill in the actual outcome (happened=1, didn't happen=0), calculate your Brier score and the market price's Brier score separately, and tell me who was more accurate.

Brier score: for each prediction, calculate (predicted probability − actual outcome)², then take the average. Lower is better, 0 is perfect, and always guessing 50% gives 0.25.

Once you have dozens of records, you can see whether this agent (and the prompts you gave it) actually beat the market, and also see for yourself how accurate market prices are.

Notes

Don't give your private key to the agent. A wallet private key can move money directly, so don't paste it into a conversation, prompt, or any file the agent can read. This tutorial never needs a wallet.
Do the trading yourself. If you want to bet, use your own account at polymarket.com. The agent only handles research and recording. AI can pull wrong information and be overconfident. A large disagreement with the market only means "worth researching further," not that it is right.
Read the rules text. Markets settle according to the literal wording of the rules and the specified information source. Titles can be misleading.
Prices in low-volume markets are unreliable. A few trades can push the price far off.
The CLI is still early. The official docs describe it as experimental software, and commands may change. If you get errors, have the agent run polymarket --help first to see the latest usage.