# Polymarket

> Follow the world's largest prediction market: search events and markets, read each outcome's chance, live prices, order books and price history, and track trades, top holders, open interest, the leaderboard and any wallet's positions. Triggers fire when a new event is listed or a price crosses a level. Read-only; no account needed.

App · 20 actions. Web page: https://docs.lodol.com/docs/integrations/polymarket

## Actions

### Get event

Get one event with every market in it: each market's question, outcomes and odds, plus the event's volume, money at stake, dates, topics and rules.

**Inputs**

- Event (`event`, text, required): The event: its polymarket.com link, its slug or its id.
- Most markets (`max_markets`, number): How many of the event's markets to include, the leading ones first, 1 to 500. Defaults to 100. From 1 to 500.

**Outputs**

- `closed_at` (text): When the event closed, once it has (ISO 8601, UTC).
- `comment_count` (number): How many comments the event has.
- `created_at` (text): When the event was created (ISO 8601, UTC).
- `description` (text): The event's rules and background.
- `end_date` (text): When the event is due to end (ISO 8601, UTC).
- `featured` (true/false): True when Polymarket features the event.
- `id` (text): The event's id.
- `liquidity` (number): Money resting in the event's order books, in US dollars.
- `market_count` (number): How many markets the event holds in all.
- `markets` (list): The event's markets with their outcomes and odds, the leading ones first: those still trading, the likeliest first when only one can win (else the most traded). Up to the number asked for.
- `mutually_exclusive` (true/false): True when only one of the event's markets can resolve Yes (one winner among candidates, say).
- `open_interest` (number): Money currently at stake in the event, in US dollars.
- `series_slug` (text): The recurring series the event belongs to, if any.
- `slug` (text): The event's short name in links.
- `start_date` (text): When the event opened (ISO 8601, UTC).
- `status` (text): 'open' or 'closed'.
- `summary` (text): One line with the title and who leads, e.g. 'Fed Decision in October? No change leads at 84.5% (5 markets).'
- `tags` (list): The topics the event is filed under.
- `title` (text): The event's title.
- `url` (text): The event's page on polymarket.com.
- `volume` (number): All money traded in the event, in US dollars.
- `volume_24h` (number): Money traded in the last 24 hours, in US dollars.

**Example output**

```json
{
  "closed_at": null,
  "comment_count": 1520,
  "created_at": "2025-07-03T20:25:56Z",
  "description": "This market will resolve to \"Yes\" if Xi Jinping is removed from power.",
  "end_date": "2027-01-01T04:59:00Z",
  "featured": false,
  "id": "30828",
  "liquidity": 443451.42,
  "market_count": 1,
  "markets": [
    {
      "end_date": "2027-01-01T04:59:00Z",
      "group_title": null,
      "id": "559651",
      "leading_outcome": "No",
      "leading_probability_percent": 97.45,
      "outcomes": [
        {
          "name": "Yes",
          "price": 0.0255,
          "probability_percent": 2.55
        },
        {
          "name": "No",
          "price": 0.9745,
          "probability_percent": 97.45
        }
      ],
      "question": "Xi Jinping out before 2027?",
      "status": "open",
      "url": "https://polymarket.com/event/xi-jinping-out-before-2027",
      "volume_24h": 23302.56
    }
  ],
  "mutually_exclusive": false,
  "open_interest": 4299967.41,
  "series_slug": null,
  "slug": "xi-jinping-out-before-2027",
  "start_date": "2025-07-03T20:37:00Z",
  "status": "open",
  "summary": "Xi Jinping out before 2027? Yes 2.55%, No 97.45%.",
  "tags": [
    {
      "id": "2",
      "label": "Politics",
      "slug": "politics"
    }
  ],
  "title": "Xi Jinping out before 2027?",
  "url": "https://polymarket.com/event/xi-jinping-out-before-2027",
  "volume": 15153269.11,
  "volume_24h": 23302.56
}
```

### Get leaderboard

Get Polymarket's trader leaderboard: the top traders by profit or volume today, this week, this month or all time, overall or in one category such as politics or sports.

**Inputs**

- Period (`period`, text): Today, this week, this month or all time. Defaults to this month. One of: `day` (Today), `week` (This week), `month` (This month), `all` (All time).
- Category (`category`, text): Only trading in markets of this kind. Defaults to overall. One of: `overall`, `politics`, `sports`, `crypto`, `finance`, `economics`, `tech`, `culture`, `weather`, `mentions`, `esports`, `combos`.
- Rank by (`sort_by`, text): Profit or volume traded. Defaults to profit. One of: `PNL` (Profit), `VOLUME` (Volume traded).
- How many (`limit`, number): How many traders to return, 1 to 1,000. Defaults to 25. From 1 to 1000.
- Next page cursor (`cursor`, text): The 'next_cursor' from an earlier page. It carries that page's period, category and ranking, so the other fields are ignored.

**Outputs**

- `count` (number): How many came back on this page.
- `next_cursor` (text): Pass this as 'Next page cursor' to get the next page. Empty when this is the last page.
- `traders` (list): The traders, best first.

**Example output**

```json
{
  "count": 1,
  "next_cursor": "",
  "traders": [
    {
      "pnl": 593128.09,
      "profile_url": "https://polymarket.com/profile/0x96489abcb9f583d6835c8ef95ffc923d05a86825",
      "rank": 1,
      "trader": "anoin123",
      "verified": false,
      "volume": 4167917.85,
      "wallet": "0x96489abcb9f583d6835c8ef95ffc923d05a86825",
      "x_username": null
    }
  ]
}
```

### Get live prices

Get live order-book prices for every outcome of a market: the chance polymarket.com shows, best bid, best ask, midpoint, spread and last trade.

**Inputs**

- Market (`market`, text, required): The market: its polymarket.com link, slug or id, its condition id (0x...), or one of its outcome token ids.

**Outputs**

- `count` (number): How many came back on this page.
- `market_id` (text): The market's id.
- `outcomes` (list): Each outcome's live prices.
- `question` (text): The market's question.
- `summary` (text): One line saying what came back.
- `url` (text): The market's page on polymarket.com.

**Example output**

```json
{
  "count": 1,
  "market_id": "559651",
  "outcomes": [
    {
      "best_ask": 0.026,
      "best_bid": 0.025,
      "last_trade_price": 0.028,
      "last_trade_side": "BUY",
      "midpoint": 0.0255,
      "outcome": "Yes",
      "price": 0.0255,
      "probability_percent": 2.55,
      "spread": 0.001,
      "token_id": "32338220190071351435772801779725302244575775216413325951443816017994629993401"
    }
  ],
  "question": "Xi Jinping out before 2027?",
  "summary": "Xi Jinping out before 2027? Yes 2.55%, No 97.45%.",
  "url": "https://polymarket.com/event/xi-jinping-out-before-2027"
}
```

### Get market

Get one market: its question, each outcome's chance in percent, best bid and ask, last trade, 24-hour move, volume, dates, status and, once resolved, the winning outcome.

**Inputs**

- Market (`market`, text, required): The market: its polymarket.com link, slug or id, its condition id (0x...), or one of its outcome token ids.

**Outputs**

- `accepting_orders` (true/false): True while orders can be placed.
- `best_ask` (number): The lowest price a seller is asking for the first outcome.
- `best_bid` (number): The highest price a buyer is offering for the first outcome.
- `closed_at` (text): When trading closed, once it has (ISO 8601, UTC).
- `condition_id` (text): The market's condition id (0x...): what trades, holders and open interest know it by.
- `created_at` (text): When the market was created (ISO 8601, UTC).
- `description` (text): The market's rules: exactly how it resolves.
- `end_date` (text): When the market is due to end (ISO 8601, UTC).
- `event_id` (text): The id of the event the market belongs to.
- `event_slug` (text): The short name of the event the market belongs to.
- `event_title` (text): The title of the event the market belongs to.
- `group_title` (text): In an event with several markets, this market's short name, e.g. '25 bps decrease' or a candidate's name.
- `id` (text): The market's id.
- `last_trade_price` (number): The price of the first outcome's most recent trade.
- `leading_outcome` (text): The outcome with the highest price.
- `leading_probability_percent` (number): The leading outcome's chance, in percent.
- `liquidity` (number): Money resting in the order book, in US dollars.
- `outcomes` (list): Each outcome with its price and token id.
- `price_change_24h_points` (number): How far the first outcome's chance moved in the last 24 hours, in percentage points (e.g. -1.5).
- `question` (text): The yes/no question the market asks.
- `resolution_source` (text): Where the result is taken from, when stated.
- `slug` (text): The market's short name in links.
- `spread` (number): The ask minus the bid.
- `start_date` (text): When the market opened (ISO 8601, UTC).
- `status` (text): 'open' (trading), 'not trading' (paused or not started), 'closed' (trading over, awaiting the result) or 'resolved' (the result is in).
- `summary` (text): One line with the question and the odds, e.g. 'Xi Jinping out before 2027? Yes 2.55%, No 97.45%.'
- `url` (text): The market's page on polymarket.com.
- `volume` (number): All money traded on the market, in US dollars.
- `volume_24h` (number): Money traded in the last 24 hours, in US dollars.
- `winning_outcome` (text): Once resolved, the outcome that won; otherwise empty.

**Example output**

```json
{
  "accepting_orders": true,
  "best_ask": 0.026,
  "best_bid": 0.025,
  "closed_at": null,
  "condition_id": "0xa467b14d51f01b957109d9cbb1d6c124fab2a089d52ed8f471d23c2812e743b7",
  "created_at": "2025-07-03T20:25:56Z",
  "description": "This market will resolve to \"Yes\" if Xi Jinping is removed from power between July 3, 2025, and December 31, 2026.",
  "end_date": "2027-01-01T04:59:00Z",
  "event_id": "30828",
  "event_slug": "xi-jinping-out-before-2027",
  "event_title": "Xi Jinping out before 2027?",
  "group_title": null,
  "id": "559651",
  "last_trade_price": 0.028,
  "leading_outcome": "No",
  "leading_probability_percent": 97.45,
  "liquidity": 443451.42,
  "outcomes": [
    {
      "name": "Yes",
      "price": 0.0255,
      "probability_percent": 2.55,
      "token_id": "32338220190071351435772801779725302244575775216413325951443816017994629993401"
    },
    {
      "name": "No",
      "price": 0.9745,
      "probability_percent": 97.45,
      "token_id": "25659310674993675562345759665114759892400026242514633218387667107987341231962"
    }
  ],
  "price_change_24h_points": -0.15,
  "question": "Xi Jinping out before 2027?",
  "resolution_source": null,
  "slug": "xi-jinping-out-before-2027",
  "spread": 0.001,
  "start_date": "2025-07-03T20:37:00Z",
  "status": "open",
  "summary": "Xi Jinping out before 2027? Yes 2.55%, No 97.45%.",
  "url": "https://polymarket.com/event/xi-jinping-out-before-2027",
  "volume": 15153269.11,
  "volume_24h": 23302.56,
  "winning_outcome": null
}
```

### Get open interest

Get open interest: the money currently at stake in one market, or across all of Polymarket when no market is given.

**Inputs**

- Market (`market`, text): The market: its link, slug, id or condition id. Leave blank for all of Polymarket.

**Outputs**

- `condition_id` (text): The market's condition id, for one market.
- `open_interest_usd` (number): The money at stake, in US dollars.
- `question` (text): The market's question, for one market.
- `scope` (text): 'market' for one market, 'all' for Polymarket.
- `summary` (text): One line saying what came back.

**Example output**

```json
{
  "condition_id": "0xa467b14d51f01b957109d9cbb1d6c124fab2a089d52ed8f471d23c2812e743b7",
  "open_interest_usd": 4299967.41,
  "question": "Xi Jinping out before 2027?",
  "scope": "market",
  "summary": "$4,299,967.41 is at stake in 'Xi Jinping out before 2027?'."
}
```

### Get order book

Get the open buy (bid) and sell (ask) orders for one outcome, best prices first, with the spread, last trade, total money on each side and the smallest price step.

**Inputs**

- Market (`market`, text, required): The market: its polymarket.com link, slug or id, its condition id (0x...), or one of its outcome token ids.
- Outcome (`outcome`, text): Which outcome, e.g. Yes, No or a team's name. Leave blank for the first one (Yes on a yes/no market).
- Price levels (`depth`, number): How many price levels of each side to list, 1 to 50. Defaults to 10. From 1 to 50.

**Outputs**

- `ask_levels` (number): How many ask prices there are in all.
- `ask_value_usd` (number): All the asks' value at their prices, in US dollars.
- `asks` (list): Sell orders, lowest price first.
- `best_ask` (number): The lowest price a seller is asking.
- `best_bid` (number): The highest price a buyer is offering.
- `bid_levels` (number): How many bid prices there are in all.
- `bid_value_usd` (number): All the money bid, in US dollars.
- `bids` (list): Buy orders, highest price first.
- `last_trade_price` (number): The outcome's most recent trade price.
- `last_trade_side` (text): Whether that trade was a BUY or a SELL.
- `market_id` (text): The market's id.
- `midpoint` (number): Halfway between the best bid and the best ask.
- `min_order_size` (number): The smallest order allowed, in shares.
- `outcome` (text): The outcome, e.g. 'Yes'.
- `price` (number): The price polymarket.com shows: the midpoint, or the last trade when the spread is wider than 0.10.
- `probability_percent` (number): The same price as a probability in percent, e.g. 37.
- `question` (text): The market's question.
- `spread` (number): The best ask minus the best bid.
- `summary` (text): One line saying what came back.
- `tick_size` (number): The smallest step a price can move by.
- `token_id` (text): The outcome's token id.
- `updated_at` (text): When the book was read (ISO 8601, UTC).

**Example output**

```json
{
  "ask_levels": 132,
  "ask_value_usd": 410607.91,
  "asks": [
    {
      "price": 0.026,
      "shares": 20.0
    }
  ],
  "best_ask": 0.026,
  "best_bid": 0.025,
  "bid_levels": 24,
  "bid_value_usd": 20814.48,
  "bids": [
    {
      "price": 0.025,
      "shares": 11516.29
    }
  ],
  "last_trade_price": 0.028,
  "last_trade_side": "BUY",
  "market_id": "559651",
  "midpoint": 0.0255,
  "min_order_size": 5.0,
  "outcome": "Yes",
  "price": 0.0255,
  "probability_percent": 2.55,
  "question": "Xi Jinping out before 2027?",
  "spread": 0.001,
  "summary": "Yes on 'Xi Jinping out before 2027?': bid 0.025, ask 0.026, showing 2.55%.",
  "tick_size": 0.001,
  "token_id": "32338220190071351435772801779725302244575775216413325951443816017994629993401",
  "updated_at": "2026-10-19T23:57:40Z"
}
```

### Get price history

Get how one outcome's chance moved over the last hour, day, week, month or all time (or between two times up to 15 days apart): every point, plus the start, end, change, high and low.

**Inputs**

- Market (`market`, text, required): The market: its polymarket.com link, slug or id, its condition id (0x...), or one of its outcome token ids.
- Outcome (`outcome`, text): Which outcome, e.g. Yes, No or a team's name. Leave blank for the first one (Yes on a yes/no market).
- Period (`period`, text): How far back to look. Defaults to the last day. Leave blank when giving a start time instead. One of: `1h` (Last hour), `6h` (Last 6 hours), `1d` (Last day), `1w` (Last week), `1m` (Last month), `max` (All time).
- From (`start_time`, date and time): Start of a window of your own, instead of a period. At most 15 days before the end.
- Until (`end_time`, date and time): End of that window. Defaults to now.
- One point every (`resolution`, text): The gap between points. Defaults to one that gives about 100 points; a month needs at least 10 minutes, a week 5. One of: `1` (1 minute), `5` (5 minutes), `15` (15 minutes), `60` (1 hour), `360` (6 hours), `1440` (1 day).

**Outputs**

- `change_points` (number): The move from first to last, in percentage points.
- `count` (number): How many came back on this page.
- `first_price` (number): The price at the first point.
- `high` (number): The highest price in the window.
- `last_price` (number): The price at the last point.
- `low` (number): The lowest price in the window.
- `market_id` (text): The market's id.
- `outcome` (text): The outcome, e.g. 'Yes'.
- `points` (list): The price at each point, oldest first.
- `question` (text): The market's question.
- `resolution_minutes` (number): Minutes between points.
- `summary` (text): One line saying what came back.
- `token_id` (text): The outcome's token id.

**Example output**

```json
{
  "change_points": -0.15,
  "count": 1,
  "first_price": 0.027,
  "high": 0.0275,
  "last_price": 0.0255,
  "low": 0.0255,
  "market_id": "559651",
  "outcome": "Yes",
  "points": [
    {
      "price": 0.027,
      "probability_percent": 2.7,
      "time": "2026-10-19T00:00:37Z"
    }
  ],
  "question": "Xi Jinping out before 2027?",
  "resolution_minutes": 15,
  "summary": "Yes on 'Xi Jinping out before 2027?' went from 2.7% to 2.55% (-0.15 points).",
  "token_id": "32338220190071351435772801779725302244575775216413325951443816017994629993401"
}
```

### Get series

Get one series of recurring events with its recent and upcoming events, newest first, to find the next one to watch.

**Inputs**

- Series (`series`, text, required): The series' slug (such as fomc) or id, from 'List series'.

**Outputs**

- `comment_count` (number): How many comments the series has.
- `created_at` (text): When the series was created (ISO 8601, UTC).
- `description` (text): What the series covers, when Polymarket says.
- `event_count` (number): How many events came back.
- `events` (list): Its recent and upcoming events, newest first.
- `id` (text): The series' id.
- `liquidity` (number): Money resting in the series' order books, in US dollars.
- `open_event_count` (number): How many of them are open.
- `recurrence` (text): How often a new event appears: hourly, daily, weekly, monthly...
- `slug` (text): The series' short name, e.g. 'fomc'.
- `start_date` (text): When the series started (ISO 8601, UTC).
- `status` (text): 'open' or 'closed'.
- `title` (text): The series' title, e.g. 'FOMC'.
- `volume` (number): Money traded across the series, in US dollars.
- `volume_24h` (number): Money traded in the last 24 hours, in US dollars.

**Example output**

```json
{
  "comment_count": 9655,
  "created_at": "2023-02-03T22:02:38Z",
  "description": null,
  "event_count": 1,
  "events": [
    {
      "end_date": "2026-12-10T04:59:00Z",
      "id": "770450",
      "slug": "fed-decision-in-december-20260729232808632",
      "start_date": "2026-07-30T00:43:48Z",
      "status": "open",
      "title": "Fed Decision in December?",
      "url": "https://polymarket.com/event/fed-decision-in-december-20260729232808632",
      "volume": 4106886.84
    }
  ],
  "id": "35",
  "liquidity": 5960236.43,
  "open_event_count": 1,
  "recurrence": "monthly",
  "slug": "fomc",
  "start_date": "2021-01-01T17:00:00Z",
  "status": "open",
  "title": "FOMC",
  "volume": 54360246.14,
  "volume_24h": 2992289.44
}
```

### Get trader profile

Get a trader's profile from their wallet: name, join date, markets traded, biggest win, all-time realized and unrealized profit, volume and what their portfolio is worth now.

**Inputs**

- Wallet (`wallet`, text, required): The trader's wallet address (0x followed by 40 characters), or a polymarket.com profile link that holds it.

**Outputs**

- `biggest_win` (number): Their biggest single winning position, in US dollars.
- `found` (true/false): False when the wallet has no profile or trades.
- `joined_at` (text): When they joined (ISO 8601, UTC).
- `markets_traded` (number): How many different markets they have traded.
- `name` (text): The trader's Polymarket name.
- `portfolio_value` (number): What their positions are worth now, in US dollars.
- `profile_url` (text): Their profile on polymarket.com.
- `profile_views` (number): How many times their profile has been viewed.
- `pseudonym` (text): The name Polymarket generated for them.
- `realized_pnl` (number): All-time profit taken (negative for a loss), in US dollars.
- `summary` (text): One line saying what came back.
- `trade_count` (number): How many trades they have made.
- `unrealized_pnl` (number): Profit on paper on what they hold now, in US dollars.
- `verified` (true/false): True for a verified account.
- `volume_usd` (number): All money they have traded, in US dollars.
- `wallet` (text): The wallet address.

**Example output**

```json
{
  "biggest_win": 2549.83,
  "found": true,
  "joined_at": "2024-10-23T01:58:46Z",
  "markets_traded": 25,
  "name": "rollsrolls",
  "portfolio_value": 17492.91,
  "profile_url": "https://polymarket.com/profile/0x2c649b504168c5414277f23135fb9ce36df72099",
  "profile_views": 413,
  "pseudonym": "Common-Airbus",
  "realized_pnl": -30449.69,
  "summary": "rollsrolls has traded 25 markets, with a realized loss of $30,449.69; portfolio worth $17,492.91.",
  "trade_count": 183,
  "unrealized_pnl": -36586.94,
  "verified": false,
  "volume_usd": 147251.76,
  "wallet": "0x2c649b504168c5414277f23135fb9ce36df72099"
}
```

### List activity

List a wallet's activity, newest first: trades, winnings cashed in, rewards and more, optionally only some kinds, one market or a time window. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Wallet (`wallet`, text, required): The trader's wallet address (0x followed by 40 characters), or a polymarket.com profile link that holds it.
- Types (`types`, list): Only these kinds of activity. Leave empty for everything except deposits, withdrawals and tips. One or more of: `TRADE` (Trades), `REDEEM` (Winnings cashed in), `SPLIT` (Splits), `MERGE` (Merges), `CONVERSION` (Conversions), `REWARD` (Liquidity rewards), `YIELD`, `MAKER_REBATE` (Maker rebates), `TAKER_REBATE` (Taker rebates), `REFERRAL_REWARD` (Referral rewards), and 3 more.
- Side (`side`, text): Only buys or only sells. Leave blank for both. One of: `BUY` (Buys), `SELL` (Sells).
- Market (`market`, text): Only this market: its polymarket.com link, slug, id or condition id (0x...).
- From (`start_time`, date and time): Only from this time on.
- Until (`end_time`, date and time): Only up to this time.
- How many (`limit`, number): How many to return, 1 to 1,000. Defaults to 50. From 1 to 1000.
- Next page cursor (`cursor`, text): The 'next_cursor' from an earlier page, to get the page after it.

**Outputs**

- `activity` (list): The activity, newest first.
- `count` (number): How many came back on this page.
- `newest_at` (text): When the newest activity happened.
- `next_cursor` (text): Pass this as 'Next page cursor' to get the next page. Empty when this is the last page.
- `wallet` (text): The wallet address.

**Example output**

```json
{
  "activity": [
    {
      "condition_id": "0x0844f5be2e87761e128eac1b68d4880b47aa06ff4108be71eaaf7ed3fc463d41",
      "event_slug": "will-xi-jinping-visit-us-before-2027",
      "market": "Will Xi Jinping visit US by September 30?",
      "market_slug": "will-xi-jinping-visit-us-by-september-30",
      "market_url": "https://polymarket.com/event/will-xi-jinping-visit-us-before-2027",
      "outcome": "No",
      "price": 0.0907,
      "shares": 3365.07,
      "side": "BUY",
      "time": "2026-09-19T05:17:09Z",
      "token_id": "87089259561104501707935243636099207812295673263153221247508255370159311484027",
      "transaction_hash": "0xc538e175f9228ecaf740b33e4f735a5cd475e4f7f9a17571bc1b46fa0740bdfb",
      "type": "TRADE",
      "value_usd": 316.41
    }
  ],
  "count": 1,
  "newest_at": "2026-09-19T05:17:09Z",
  "next_cursor": "",
  "wallet": "0x2c649b504168c5414277f23135fb9ce36df72099"
}
```

### List comments

Read the discussion under an event (or a series): each comment with its author, time and reactions, newest first by default.

**Inputs**

- Event (`event`, text): The event whose comments to read: its link, slug or id. Give this or a series.
- Series (`series`, text): Or the series whose comments to read: its slug or id.
- Sort by (`sort_by`, text): Newest first, oldest first or most reactions. Defaults to newest. One of: `newest` (Newest first), `oldest` (Oldest first), `most_liked` (Most reactions).
- Holders only (`holders_only`, true/false): Only comments from people holding a position in the event.
- How many (`limit`, number): How many comments to return, 1 to 100. Defaults to 20. From 1 to 100.
- Skip (`offset`, number): How many to skip, to page through. Defaults to 0. At least 0.

**Outputs**

- `comments` (list): The comments.
- `count` (number): How many came back on this page.

**Example output**

```json
{
  "comments": [
    {
      "author": "Old-Birthday",
      "created_at": "2026-10-17T12:06:08Z",
      "id": "3296505",
      "reactions": 0,
      "reply_to": null,
      "text": "Who actually has a convincing ground game?",
      "wallet": "0xcf7eb75117117c5902cf213c16fea848e72a2808"
    }
  ],
  "count": 1
}
```

### List events

List events (a question page on polymarket.com, holding one or more markets) by topic, series, title, dates, volume or liquidity, sorted how you like. Each comes with its markets and their odds. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Topic (`tag`, text): Only this topic. Pick one, or type a tag's slug such as crypto.
- Series (`series`, text): Only events of this recurring series: its slug (such as fomc) or id, from 'List series'.
- Status (`status`, text): Open events, closed ones, or both. Defaults to open. One of: `open`, `closed`, `any` (Open or closed).
- Sort by (`sort_by`, text): The order to list them in. Defaults to most traded in the last 24 hours. Ending soonest skips open events already past their end date. One of: `volume_24h` (Most traded in the last 24 hours), `volume` (Most traded ever), `liquidity` (Most liquidity), `open_interest` (Most money at stake), `newest` (Newest first), `ending_soonest` (Ending soonest), `recently_closed` (Most recently closed).
- Title contains (`title_contains`, text): Only events whose title contains these words, in this order.
- Featured only (`featured`, true/false): Only events Polymarket features on its home page.
- Started on or after (`starts_after`, date): Only events that opened on or after this date.
- Started on or before (`starts_before`, date): Only events that opened on or before this date.
- Ends on or after (`ends_after`, date): Only events due to end on or after this date.
- Ends on or before (`ends_before`, date): Only events due to end on or before this date.
- Minimum volume ($) (`min_volume`, number): Only events with at least this much traded, in US dollars. At least 0.
- Minimum liquidity ($) (`min_liquidity`, number): Only events with at least this much money in their order books, in US dollars. At least 0.
- Markets per event (`markets_per_event`, number): How many of each event's markets to include, the leading ones first, 0 to 50. Defaults to 5; 'Get event' gives more. From 0 to 50.
- How many (`limit`, number): How many events to return, 1 to 100. Defaults to 20. From 1 to 100.
- Next page cursor (`cursor`, text): The 'next_cursor' from an earlier page, to get the page after it.

**Outputs**

- `count` (number): How many came back on this page.
- `events` (list): The events, with their markets.
- `next_cursor` (text): Pass this as 'Next page cursor' to get the next page. Empty when this is the last page.

**Example output**

```json
{
  "count": 1,
  "events": [
    {
      "closed_at": null,
      "comment_count": 1520,
      "created_at": "2025-07-03T20:25:56Z",
      "description": "This market will resolve to \"Yes\" if Xi Jinping is removed from power.",
      "end_date": "2027-01-01T04:59:00Z",
      "featured": false,
      "id": "30828",
      "liquidity": 443451.42,
      "market_count": 1,
      "markets": [
        {
          "id": "559651",
          "name": "Xi Jinping out before 2027?",
          "outcome": "Yes",
          "probability_percent": 2.55,
          "status": "open",
          "volume_24h": 23302.56
        }
      ],
      "mutually_exclusive": false,
      "open_interest": 4299967.41,
      "series_slug": null,
      "slug": "xi-jinping-out-before-2027",
      "start_date": "2025-07-03T20:37:00Z",
      "status": "open",
      "summary": "Xi Jinping out before 2027? Yes 2.55%, No 97.45%.",
      "tags": [
        {
          "id": "2",
          "label": "Politics",
          "slug": "politics"
        }
      ],
      "title": "Xi Jinping out before 2027?",
      "url": "https://polymarket.com/event/xi-jinping-out-before-2027",
      "volume": 15153269.11,
      "volume_24h": 23302.56
    }
  ],
  "next_cursor": ""
}
```

### List markets

List individual markets (one yes/no question each) by topic, end date, volume or liquidity: the most traded, the newest, those ending soonest or the biggest movers of the day. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Topic (`tag`, text): Only this topic. Pick one, or type a tag's slug such as crypto.
- Status (`status`, text): Open markets or closed ones. Defaults to open. One of: `open`, `closed`.
- Sort by (`sort_by`, text): The order to list them in. Defaults to most traded in the last 24 hours. A rise or fall is in the first outcome's chance. One of: `volume_24h` (Most traded in the last 24 hours), `volume` (Most traded ever), `liquidity` (Most liquidity), `newest` (Newest first), `ending_soonest` (Ending soonest), `biggest_rise` (Biggest 24-hour rise), `biggest_fall` (Biggest 24-hour fall), `recently_closed` (Most recently closed).
- Ends on or after (`ends_after`, date): Only markets due to end on or after this date.
- Ends on or before (`ends_before`, date): Only markets due to end on or before this date.
- Minimum volume ($) (`min_volume`, number): Only markets with at least this much traded, in US dollars. At least 0.
- Minimum liquidity ($) (`min_liquidity`, number): Only markets with at least this much money in their order book, in US dollars. At least 0.
- How many (`limit`, number): How many markets to return, 1 to 100. Defaults to 20. From 1 to 100.
- Next page cursor (`cursor`, text): The 'next_cursor' from an earlier page, to get the page after it.

**Outputs**

- `count` (number): How many came back on this page.
- `markets` (list): The markets.
- `next_cursor` (text): Pass this as 'Next page cursor' to get the next page. Empty when this is the last page.

**Example output**

```json
{
  "count": 1,
  "markets": [
    {
      "accepting_orders": true,
      "best_ask": 0.026,
      "best_bid": 0.025,
      "closed_at": null,
      "condition_id": "0xa467b14d51f01b957109d9cbb1d6c124fab2a089d52ed8f471d23c2812e743b7",
      "created_at": "2025-07-03T20:25:56Z",
      "description": "This market will resolve to \"Yes\" if Xi Jinping is removed from power between July 3, 2025, and December 31, 2026.",
      "end_date": "2027-01-01T04:59:00Z",
      "event_id": "30828",
      "event_slug": "xi-jinping-out-before-2027",
      "event_title": "Xi Jinping out before 2027?",
      "group_title": null,
      "id": "559651",
      "last_trade_price": 0.028,
      "leading_outcome": "No",
      "leading_probability_percent": 97.45,
      "liquidity": 443451.42,
      "outcomes": [
        {
          "name": "Yes",
          "price": 0.0255,
          "probability_percent": 2.55,
          "token_id": "32338220190071351435772801779725302244575775216413325951443816017994629993401"
        },
        {
          "name": "No",
          "price": 0.9745,
          "probability_percent": 97.45,
          "token_id": "25659310674993675562345759665114759892400026242514633218387667107987341231962"
        }
      ],
      "price_change_24h_points": -0.15,
      "question": "Xi Jinping out before 2027?",
      "resolution_source": null,
      "slug": "xi-jinping-out-before-2027",
      "spread": 0.001,
      "start_date": "2025-07-03T20:37:00Z",
      "status": "open",
      "summary": "Xi Jinping out before 2027? Yes 2.55%, No 97.45%.",
      "url": "https://polymarket.com/event/xi-jinping-out-before-2027",
      "volume": 15153269.11,
      "volume_24h": 23302.56,
      "winning_outcome": null
    }
  ],
  "next_cursor": ""
}
```

### List positions

List a wallet's positions: the shares it holds (or held) in each market, what they cost, what they are worth now, and the profit or loss. Open positions by default. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Wallet (`wallet`, text, required): The trader's wallet address (0x followed by 40 characters), or a polymarket.com profile link that holds it.
- Which positions (`status`, text): Defaults to open positions (still held). One of: `OPEN` (Open (still held)), `REDEEMABLE` (Won and ready to cash in), `REDEEMABLE_LOST` (Lost, still held), `MERGEABLE` (Holding both sides), `CLOSED` (Closed (sold or cashed in)).
- Sort by (`sort_by`, text): Biggest first. Defaults to current value for open positions and realized profit for closed ones. One of: `CURRENT_VALUE` (Current value), `TOTAL_PNL` (Total profit), `UNREALIZED_PNL` (Unrealized profit), `REALIZED_PNL` (Realized profit), `TOKENS` (Number of shares), `PRICE` (Current price), `TIMESTAMP` (Most recent activity).
- Market contains (`title_contains`, text): Only positions in markets whose question contains these words.
- Market (`market`, text): Only this market: its polymarket.com link, slug, id or condition id (0x...).
- How many (`limit`, number): How many to return, 1 to 1,000. Defaults to 50. From 1 to 1000.
- Next page cursor (`cursor`, text): The 'next_cursor' from an earlier page, to get the page after it.

**Outputs**

- `count` (number): How many came back on this page.
- `next_cursor` (text): Pass this as 'Next page cursor' to get the next page. Empty when this is the last page.
- `positions` (list): The positions.
- `total_value` (number): These positions' current value, in US dollars.
- `wallet` (text): The wallet address.

**Example output**

```json
{
  "count": 1,
  "next_cursor": "",
  "positions": [
    {
      "average_price": 0.0795,
      "condition_id": "0xa467b14d51f01b957109d9cbb1d6c124fab2a089d52ed8f471d23c2812e743b7",
      "cost": 54543.98,
      "current_price": 0.0255,
      "current_value": 17492.91,
      "end_date": "2027-01-01T00:00:00Z",
      "event_id": "30828",
      "event_slug": "xi-jinping-out-before-2027",
      "last_activity_at": "2026-09-19T05:08:54Z",
      "market": "Xi Jinping out before 2027?",
      "market_slug": "xi-jinping-out-before-2027",
      "market_url": "https://polymarket.com/event/xi-jinping-out-before-2027",
      "outcome": "Yes",
      "realized_pnl": -14827.12,
      "redeemable": false,
      "return_percent": -67.93,
      "shares": 685996.5037,
      "status": "OPEN",
      "token_id": "32338220190071351435772801779725302244575775216413325951443816017994629993401",
      "total_pnl": -51878.19,
      "unrealized_pnl": -37051.07
    }
  ],
  "total_value": 17492.91,
  "wallet": "0x2c649b504168c5414277f23135fb9ce36df72099"
}
```

### List related tags

List the topics most often filed alongside one (Politics brings Trump, Midterms, Senate Elections...), with how many open events each has.

**Inputs**

- Topic (`tag`, text, required): The topic to start from. Pick one, or type a tag's slug.

**Outputs**

- `count` (number): How many came back on this page.
- `tag` (object): The topic started from.
- `tags` (list): The related topics, most related first.

**Example output**

```json
{
  "count": 1,
  "tag": {
    "id": "2",
    "label": "Politics",
    "slug": "politics"
  },
  "tags": [
    {
      "id": "126",
      "label": "Trump",
      "open_events": 333,
      "slug": "trump"
    }
  ]
}
```

### List series

List series: recurring events such as each Fed decision, NFL games or daily crypto prices, with how often a new one appears and how much they trade.

**Inputs**

- How often (`recurrence`, text): Only series with a new event this often. One of: `hourly`, `daily`, `weekly`, `monthly`, `annual` (Yearly).
- Status (`status`, text): Open series, closed ones, or both. Defaults to open. One of: `open`, `closed`, `any` (Open or closed).
- Sort by (`sort_by`, text): The order to list them in. Defaults to most traded today. One of: `volume_24h` (Most traded in the last 24 hours), `volume` (Most traded ever), `newest` (Newest first).
- How many (`limit`, number): How many series to return, 1 to 50. Defaults to 20. From 1 to 50.
- Skip (`offset`, number): How many to skip, to page through. Defaults to 0. At least 0.

**Outputs**

- `count` (number): How many came back on this page.
- `series` (list): The series.

**Example output**

```json
{
  "count": 1,
  "series": [
    {
      "comment_count": 9655,
      "created_at": "2023-02-03T22:02:38Z",
      "description": null,
      "id": "35",
      "liquidity": 5960236.43,
      "recurrence": "monthly",
      "slug": "fomc",
      "start_date": "2021-01-01T17:00:00Z",
      "status": "open",
      "title": "FOMC",
      "volume": 54360246.14,
      "volume_24h": 2992289.44
    }
  ]
}
```

### List sports teams

List the sports teams Polymarket runs markets on, by league: name, short code, record, logo and color.

**Inputs**

- League (`league`, text): Only teams in this league. Pick one, or type its code such as nfl.
- Team name (`name`, text): Only the team with exactly this name, e.g. Dallas Cowboys.
- How many (`limit`, number): How many teams to return, 1 to 100. Defaults to 50. From 1 to 100.
- Skip (`offset`, number): How many to skip, to page through. Defaults to 0. At least 0.

**Outputs**

- `count` (number): How many came back on this page.
- `teams` (list): The teams.

**Example output**

```json
{
  "count": 1,
  "teams": [
    {
      "abbreviation": "DAL",
      "color": "#004A93",
      "id": "100049",
      "league": "nfl",
      "logo": "https://polymarket-upload.s3.us-east-2.amazonaws.com/NFL+Team+Logos/DAL.png",
      "name": "Dallas Cowboys",
      "record": "2-4-0"
    }
  ]
}
```

### List top holders

List the biggest holders of each of a market's outcomes, ranked by shares held, with their wallet and Polymarket name.

**Inputs**

- Market (`market`, text, required): The market: its polymarket.com link, slug or id, its condition id (0x...), or one of its outcome token ids.
- Holders per outcome (`limit`, number): How many holders of each outcome, 1 to 100. Defaults to 20. From 1 to 100.
- Minimum shares (`min_shares`, number): Only holders with at least this many shares. At least 0.

**Outputs**

- `condition_id` (text): The market's condition id.
- `count` (number): How many came back on this page.
- `holders` (list): The holders, grouped by outcome, biggest first.
- `market_id` (text): The market's id.
- `question` (text): The market's question.

**Example output**

```json
{
  "condition_id": "0xa467b14d51f01b957109d9cbb1d6c124fab2a089d52ed8f471d23c2812e743b7",
  "count": 1,
  "holders": [
    {
      "outcome": "Yes",
      "rank": 1,
      "shares": 685996.5,
      "trader": "rollsrolls",
      "verified": false,
      "wallet": "0x2c649b504168c5414277f23135fb9ce36df72099"
    }
  ],
  "market_id": "559651",
  "question": "Xi Jinping out before 2027?"
}
```

### List trades

List recent trades, newest first: across Polymarket, in one market or event, or by one wallet. Each with its side, outcome, price, size in dollars and trader. Filter out small trades to watch the big money. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Market (`market`, text): Only this market: its polymarket.com link, slug, id or condition id (0x...).
- Event (`event`, text): Or only trades in this event's markets: its link, slug or id.
- Wallet (`wallet`, text): Only this trader's trades: their wallet address (0x...).
- Side (`side`, text): Only buys or only sells. Leave blank for both. One of: `BUY` (Buys), `SELL` (Sells).
- Minimum trade size ($) (`min_value`, number): Only trades worth at least this much, in US dollars. At least 0.
- From (`start_time`, date and time): With a wallet: only trades from this time on.
- Until (`end_time`, date and time): With a wallet: only trades up to this time.
- How many (`limit`, number): How many to return, 1 to 1,000. Defaults to 50. From 1 to 1000.
- Next page cursor (`cursor`, text): The 'next_cursor' from an earlier page, to get the page after it.

**Outputs**

- `count` (number): How many came back on this page.
- `newest_at` (text): When the newest trade happened.
- `next_cursor` (text): Pass this as 'Next page cursor' to get the next page. Empty when this is the last page.
- `trades` (list): The trades, newest first.

**Example output**

```json
{
  "count": 1,
  "newest_at": "2026-10-19T22:36:35Z",
  "next_cursor": "",
  "trades": [
    {
      "condition_id": "0xa467b14d51f01b957109d9cbb1d6c124fab2a089d52ed8f471d23c2812e743b7",
      "event_slug": "xi-jinping-out-before-2027",
      "market": "Xi Jinping out before 2027?",
      "market_slug": "xi-jinping-out-before-2027",
      "market_url": "https://polymarket.com/event/xi-jinping-out-before-2027",
      "outcome": "No",
      "price": 0.9727,
      "probability_percent": 97.27,
      "shares": 881.91,
      "side": "SELL",
      "time": "2026-10-19T22:36:35Z",
      "token_id": "25659310674993675562345759665114759892400026242514633218387667107987341231962",
      "trader": null,
      "transaction_hash": "0xc538e175f9228ecaf740b33e4f735a5cd475e4f7f9a17571bc1b46fa0740bdfb",
      "value_usd": 857.82,
      "wallet": "0xcd23d247c85603ba0e06030b262124c0c0145f5d"
    }
  ]
}
```

### Search Polymarket

Search Polymarket by words: matching events (each with its markets and odds), topics and traders, most traded first.

**Inputs**

- Search for (`query`, text, required): Words to look for in event titles, tags and trader names.
- Events (`status`, text): Open events, closed ones, or both. Defaults to open. One of: `open`, `closed`, `any` (Open or closed).
- Topic (`tag`, text): Only this topic. Pick one, or type a tag's slug such as crypto.
- Markets per event (`markets_per_event`, number): How many of each event's markets to include, the leading ones first, 0 to 50. Defaults to 5; 'Get event' gives more. From 0 to 50.
- How many (`limit`, number): How many events to return, 1 to 50. Defaults to 10. From 1 to 50.
- Page (`page`, number): Which page of results, starting at 1. At least 1.

**Outputs**

- `count` (number): How many came back on this page.
- `events` (list): The matching events, with their markets.
- `has_more` (true/false): True when a later page has more events.
- `query` (text): The words searched for.
- `summary` (text): One line saying what came back.
- `tags` (list): Matching topics.
- `total_results` (number): How many events match in all.
- `traders` (list): Matching traders.

**Example output**

```json
{
  "count": 1,
  "events": [
    {
      "closed_at": null,
      "comment_count": 1520,
      "created_at": "2025-07-03T20:25:56Z",
      "description": "This market will resolve to \"Yes\" if Xi Jinping is removed from power.",
      "end_date": "2027-01-01T04:59:00Z",
      "featured": false,
      "id": "30828",
      "liquidity": 443451.42,
      "market_count": 1,
      "markets": [
        {
          "id": "559651",
          "name": "Xi Jinping out before 2027?",
          "outcome": "Yes",
          "probability_percent": 2.55,
          "status": "open",
          "volume_24h": 23302.56
        }
      ],
      "mutually_exclusive": false,
      "open_interest": 4299967.41,
      "series_slug": null,
      "slug": "xi-jinping-out-before-2027",
      "start_date": "2025-07-03T20:37:00Z",
      "status": "open",
      "summary": "Xi Jinping out before 2027? Yes 2.55%, No 97.45%.",
      "tags": [
        {
          "id": "2",
          "label": "Politics",
          "slug": "politics"
        }
      ],
      "title": "Xi Jinping out before 2027?",
      "url": "https://polymarket.com/event/xi-jinping-out-before-2027",
      "volume": 15153269.11,
      "volume_24h": 23302.56
    }
  ],
  "has_more": true,
  "query": "xi jinping",
  "summary": "8 events match 'xi jinping'; showing 1.",
  "tags": [
    {
      "events": 120,
      "id": "2",
      "label": "Politics",
      "slug": "politics"
    }
  ],
  "total_results": 8,
  "traders": [
    {
      "name": "rollsrolls",
      "pseudonym": "Common-Airbus",
      "wallet": "0x2c649b504168c5414277f23135fb9ce36df72099"
    }
  ]
}
```
