# Polymarket API

> Polymarket returns prediction market odds, trading volumes, and chance history as a workflow and API.

Polymarket, also called Poly, Search markets finds topic-related markets ranked by total trading volume; enter a topic. List trending markets returns open markets ranked by 24-hour trading volume; optionally choose a category and result count. Get odds history shows an outcome’s chances over time; enter a market question or link, and optionally choose a period and outcome.

- Page: https://fous.com/tools/polymarket
- Handle: `@polymarket`
- Category: [Finance](https://fous.com/tools/category/finance)
- Source website: https://polymarket.com
- Last verified: Sep 29, 2026

## Methods

### Get odds history

Operation `get_odds_history`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Show how a Polymarket outcome’s chance changed over time from a market question or link. Among matching markets, use the highest-volume match. Closed markets may have no points in recent periods.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `market` | string | yes | `"https://polymarket.com/event/xi-jinping-out-before-2027"` | The market question or a Polymarket market link, for example "Xi Jinping out before 2027?". |
| `period` | string | no | `"last_month"` | How far back to show, for example "last_week". Defaults to last_month. |
| `outcome` | string | no | `"No"` | Outcome to track, for example "No". Defaults to the first outcome, usually Yes. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "market"
  ],
  "properties": {
    "market": {
      "type": "string",
      "description": "The market question or a Polymarket market link, for example \"Xi Jinping out before 2027?\".",
      "examples": [
        "https://polymarket.com/event/xi-jinping-out-before-2027",
        "Xi Jinping out before 2027?",
        "Fed rate cut by December 2025 meeting?"
      ]
    },
    "period": {
      "enum": [
        "last_day",
        "last_week",
        "last_month",
        "all_time"
      ],
      "type": "string",
      "default": "last_month",
      "description": "How far back to show, for example \"last_week\". Defaults to last_month.",
      "examples": [
        "last_month",
        "last_week",
        "all_time"
      ]
    },
    "outcome": {
      "type": "string",
      "default": "",
      "description": "Outcome to track, for example \"No\". Defaults to the first outcome, usually Yes.",
      "examples": [
        "No"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "market": "https://polymarket.com/event/xi-jinping-out-before-2027",
      "period": "last_month",
      "outcome": "No"
    },
    {
      "market": "Xi Jinping out before 2027?",
      "period": "last_week"
    },
    {
      "market": "Fed rate cut by December 2025 meeting?",
      "period": "all_time"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `points` | array |  | Historical chances in time order, at hourly or daily spacing depending on the period. |
| `points[].date_time` | string | `"2026-08-30T00:00:23Z"` | Sample time in ISO 8601 UTC. |
| `points[].chance_percent` | number | `95.55` | Chance at this time, as a percentage. |
| `outcome` | string | `"No"` | The tracked outcome. |
| `question` | string | `"Xi Jinping out before 2027?"` | The matched market question. |
| `market_url` | string | `"https://polymarket.com/event/xi-jinping-out-before-2027"` | Link to the Polymarket event containing this market. |
| `current_chance_percent` | number | `96.45` | Current chance, as a percentage from 0 to 100. |

**Example input**

```json
{
  "market": "https://polymarket.com/event/xi-jinping-out-before-2027",
  "period": "last_month",
  "outcome": "No"
}
```

**Example output**

```json
{
  "points": [
    {
      "date_time": "2026-08-30T00:00:23Z",
      "chance_percent": 95.55
    },
    {
      "date_time": "2026-08-31T00:00:22Z",
      "chance_percent": 95.55
    },
    {
      "date_time": "2026-09-01T00:00:34Z",
      "chance_percent": 95.65
    }
  ],
  "outcome": "No",
  "question": "Xi Jinping out before 2027?",
  "market_url": "https://polymarket.com/event/xi-jinping-out-before-2027",
  "current_chance_percent": 96.45
}
```

### List trending markets

Operation `list_trending_markets`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

List the most-traded open Polymarket markets, ranked by 24-hour trading volume. Select a category or see all markets; markets outside the named categories are labeled Other.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `category` | string | no | `"crypto"` | Category to list, such as crypto; all includes every category. |
| `max_results` | integer | no | `5` | Maximum number of markets to return, such as 20 (up to 50). |

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "category": {
      "enum": [
        "all",
        "politics",
        "crypto",
        "sports",
        "economy",
        "tech",
        "culture"
      ],
      "type": "string",
      "default": "all",
      "description": "Category to list, such as crypto; all includes every category.",
      "examples": [
        "crypto",
        "culture",
        "all"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 20,
      "maximum": 50,
      "minimum": 1,
      "description": "Maximum number of markets to return, such as 20 (up to 50).",
      "x-fous-developer": true,
      "examples": [
        5,
        3,
        50
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "category": "crypto",
      "max_results": 5
    },
    {},
    {
      "category": "culture",
      "max_results": 3
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `markets` | array |  | Open markets in descending order of 24-hour trading volume. |
| `markets[].link` | string | `"https://polymarket.com/event/what-price-will-bitcoin-hit-in-september-2026"` | Polymarket event page for this market. |
| `markets[].slug` | string | `"will-bitcoin-dip-to-82pt5k-in-september-2026"` | Polymarket market slug. |
| `markets[].category` | string | `"Crypto"` | Market category. |
| `markets[].end_date` | string or null | `"2026-10-01"` | Scheduled market end date (YYYY-MM-DD). |
| `markets[].question` | string | `"Will Bitcoin dip to $82,500 in September?"` | Market question. |
| `markets[].market_id` | string | `"4797724"` | Polymarket market ID. |
| `markets[].volume_24h_usd` | number | `208708.63` | Trading volume over the last 24 hours in USD. |
| `markets[].leading_outcome` | string or null | `"Yes"` | Outcome with the highest current chance. |
| `markets[].total_volume_usd` | number | `446588.04` | Total trading volume in USD. |
| `markets[].leading_chance_percent` | number or null | `76.5` | Current chance for the leading outcome, in percent. |

**Example input**

```json
{
  "category": "crypto",
  "max_results": 5
}
```

**Example output**

```json
{
  "markets": [
    {
      "link": "https://polymarket.com/event/what-price-will-bitcoin-hit-in-september-2026",
      "slug": "will-bitcoin-dip-to-82pt5k-in-september-2026",
      "category": "Crypto",
      "end_date": "2026-10-01",
      "question": "Will Bitcoin dip to $82,500 in September?",
      "market_id": "4797724",
      "volume_24h_usd": 208708.63,
      "leading_outcome": "Yes",
      "total_volume_usd": 446588.04,
      "leading_chance_percent": 76.5
    },
    {
      "link": "https://polymarket.com/event/what-price-will-bitcoin-hit-in-september-2026",
      "slug": "will-bitcoin-dip-to-80k-in-september-2026-from-september-18",
      "category": "Crypto",
      "end_date": "2026-10-01",
      "question": "Will Bitcoin dip to $80,000 in September?",
      "market_id": "4689727",
      "volume_24h_usd": 165597.52,
      "leading_outcome": "No",
      "total_volume_usd": 536372.93,
      "leading_chance_percent": 82.65
    },
    {
      "link": "https://polymarket.com/event/clarity-act-signed-into-law-in-2026",
      "slug": "clarity-act-signed-into-law-in-2026",
      "category": "Crypto",
      "end_date": "2027-01-01",
      "question": "Clarity Act (H.R.3633) signed into law in 2026?",
      "market_id": "1163699",
      "volume_24h_usd": 152583.58,
      "leading_outcome": "No",
      "total_volume_usd": 23228936.07,
      "leading_chance_percent": 94.75
    }
  ]
}
```

### Search markets

Operation `search_markets`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Find Polymarket prediction markets about a topic, ranked by total trading volume, with outcome chances and market details. Odds are the quoted outcome prices at the time of the search; 24-hour volume may be unavailable for some markets.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `topic` | string | yes | `"Fed rate cut"` | Words describing the event to find, for example Fed rate cut. |
| `max_results` | integer | no | `5` | Maximum markets to return, for example 10. |
| `include_closed` | boolean | no | `true` | Include closed markets too, for example false. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "topic"
  ],
  "properties": {
    "topic": {
      "type": "string",
      "minLength": 1,
      "description": "Words describing the event to find, for example Fed rate cut.",
      "examples": [
        "Fed rate cut",
        "US election",
        "zzzzzxxyy__nonexistent"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 10,
      "maximum": 50,
      "minimum": 1,
      "description": "Maximum markets to return, for example 10.",
      "x-fous-developer": true,
      "examples": [
        5,
        50
      ]
    },
    "include_closed": {
      "type": "boolean",
      "default": false,
      "description": "Include closed markets too, for example false.",
      "examples": [
        true,
        false
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "topic": "Fed rate cut"
    },
    {
      "topic": "US election",
      "max_results": 5,
      "include_closed": true
    },
    {
      "topic": "Fed rate cut",
      "max_results": 50,
      "include_closed": false
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `markets` | array |  | Matching markets, highest total trading volume first. |
| `markets[].link` | string | `"https://polymarket.com/event/how-many-fed-rate-cuts-in-2026/will-no-fed-rate-cuts-happen-in-2026"` | Polymarket market page. |
| `markets[].slug` | string | `"will-no-fed-rate-cuts-happen-in-2026"` | Polymarket market slug. |
| `markets[].status` | string | `"open"` | Market status. |
| `markets[].end_date` | string or null | `"2027-01-01"` | Market end date. |
| `markets[].outcomes` | array |  | Outcome names and current chances in percent. |
| `markets[].question` | string | `"Will no Fed rate cuts happen in 2026?"` | Market question. |
| `markets[].market_id` | string | `"616902"` | Polymarket market ID. |
| `markets[].event_title` | string | `"How many Fed rate cuts in 2026?"` | Title of the enclosing event. |
| `markets[].volume_24h_usd` | number or null | `36527.688199000004` | 24-hour trading volume in USD, if available. |
| `markets[].total_volume_usd` | number or null | `8646599.003723001` | Lifetime trading volume in USD. |

**Example input**

```json
{
  "topic": "Fed rate cut"
}
```

**Example output**

```json
{
  "markets": [
    {
      "link": "https://polymarket.com/event/how-many-fed-rate-cuts-in-2026/will-no-fed-rate-cuts-happen-in-2026",
      "slug": "will-no-fed-rate-cuts-happen-in-2026",
      "status": "open",
      "end_date": "2027-01-01",
      "outcomes": [
        {
          "name": "Yes",
          "chance_percent": 96.95
        },
        {
          "name": "No",
          "chance_percent": 3.05
        }
      ],
      "question": "Will no Fed rate cuts happen in 2026?",
      "market_id": "616902",
      "event_title": "How many Fed rate cuts in 2026?",
      "volume_24h_usd": 36527.688199000004,
      "total_volume_usd": 8646599.003723001
    },
    {
      "link": "https://polymarket.com/event/how-many-fed-rate-cuts-in-2026/will-11-fed-rate-cuts-happen-in-2026",
      "slug": "will-11-fed-rate-cuts-happen-in-2026",
      "status": "open",
      "end_date": "2027-01-01",
      "outcomes": [
        {
          "name": "Yes",
          "chance_percent": 0.05
        },
        {
          "name": "No",
          "chance_percent": 99.95
        }
      ],
      "question": "Will 11 Fed rate cuts happen in 2026?",
      "market_id": "616913",
      "event_title": "How many Fed rate cuts in 2026?",
      "volume_24h_usd": null,
      "total_volume_usd": 5272133.838100998
    },
    {
      "link": "https://polymarket.com/event/how-many-fed-rate-cuts-in-2026/will-10-fed-rate-cuts-happen-in-2026",
      "slug": "will-10-fed-rate-cuts-happen-in-2026",
      "status": "open",
      "end_date": "2027-01-01",
      "outcomes": [
        {
          "name": "Yes",
          "chance_percent": 0.05
        },
        {
          "name": "No",
          "chance_percent": 99.95
        }
      ],
      "question": "Will 10 Fed rate cuts happen in 2026?",
      "market_id": "616912",
      "event_title": "How many Fed rate cuts in 2026?",
      "volume_24h_usd": null,
      "total_volume_usd": 4954179.949515998
    }
  ]
}
```

## Quick start

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@polymarket",
  "visibility": "public",
  "operation": "get_odds_history",
  "version": 1,
  "input": {
    "market": "https://polymarket.com/event/xi-jinping-out-before-2027",
    "period": "last_month",
    "outcome": "No"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

body = json.loads("{\n  \"api\": \"@polymarket\",\n  \"visibility\": \"public\",\n  \"operation\": \"get_odds_history\",\n  \"version\": 1,\n  \"input\": {\n    \"market\": \"https://polymarket.com/event/xi-jinping-out-before-2027\",\n    \"period\": \"last_month\",\n    \"outcome\": \"No\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_000),
  body: JSON.stringify({
  "api": "@polymarket",
  "visibility": "public",
  "operation": "get_odds_history",
  "version": 1,
  "input": {
    "market": "https://polymarket.com/event/xi-jinping-out-before-2027",
    "period": "last_month",
    "outcome": "No"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/polymarket`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `get_odds_history`: Get odds history. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `list_trending_markets`: List trending markets. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `search_markets`: Search markets. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-polymarket https://api.fous.com/mcp/tools/polymarket --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## Use cases

- Compare outcome chances across markets about a topic
- Track changes in an outcome’s chance over time
- Review open markets with the highest 24-hour trading volume
- Find markets by category and compare leading outcomes
- Identify markets with high lifetime trading volume

## FAQ

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this Polymarket tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. With pay as you go, a credit costs 1¢. Monthly plans cost less per credit.

### Do I need a Polymarket account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from polymarket.com when you run it. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified on Sep 29, 2026.

### What are the current chances for markets about a topic?

Use Search markets with a topic to see outcome chances and market details, ranked by total trading volume.

### Which open markets have the highest 24-hour trading volume?

Use List trending markets to see open markets ranked by 24-hour trading volume, optionally filtered by category.

### How has an outcome’s chance changed over time?

Use Get odds history with a market question or link, and optionally specify a period and outcome.

## Related

- [Kalshi API](https://fous.com/tools/kalshi.md): Prediction markets for real-world events.
- [CoinMarketCap API](https://fous.com/tools/coinmarketcap.md): CoinMarketCap returns prices, rankings and current Fear and Greed readings; gainers and losers include up to 30 top-100 coins above $50,000 in 24-hour volume.
- [CoinGecko API](https://fous.com/tools/coingecko.md): CoinGecko returns cryptocurrency prices and histories, sector rankings and details, and trending coins; non-USD historical values cover 365 days, histories 7–365 days, and today’s prices may change.
- [CompaniesMarketCap API](https://fous.com/tools/companiesmarketcap.md): CompaniesMarketCap ranks public companies worldwide or by country and industry across size and financial measures, and provides company figures with market-cap history for completed years.
- [Yahoo Finance API](https://fous.com/tools/yahoo-finance.md): Yahoo Finance provides quotes, movers, company financials, analyst ratings, earnings, news, and up to 5,000 price rows with adjusted returns; prices may be delayed.
- [MSN Money API](https://fous.com/tools/msn-money.md): MSN Money provides stock quotes, key facts, financial news, and market data, including current market movers; quotes and prices may be delayed.
- [TradingView API](https://fous.com/tools/tradingview.md): TradingView provides charts, markets, and technical analysis, with changing buy, sell, or neutral signals and stock screening; quotes may be delayed.
- [Macrotrends API](https://fous.com/tools/macrotrends.md): Macrotrends provides long-term financial and economic charts, company metric histories, and yearly commodity and index prices; current-year prices may be incomplete.
- [All Finance tools](https://fous.com/tools/category/finance)