Polymarket is a decentralized prediction markets platform where users can trade on the outcome of future events using blockchain technology. Polymarket provides a comprehensive API, enabling developers and agents to access live market data, event listings, price information, and orderbook statistics to power data-driven workflows and AI automations.
With Polymarket’s API and Aptlystar integration, you can enable agents to programmatically retrieve prediction market information, explore open markets and associated events, analyze historical price data, and access orderbooks and market midpoints. This creates new possibilities for research, automated analysis, and developing intelligent agents that react to real-time event probabilities derived from market prices.
Key features of the Polymarket integration include:
- Market Listing & Filtering: List all current or historical prediction markets, filter by tag, sort, and paginate through results.
- Market Detail: Retrieve details for a single market by market ID or slug, including its outcomes and status.
- Event Listings: Access lists of Polymarket events and detailed event information.
- Orderbook & Price Data: Analyze the orderbook, get the latest market prices, view the midpoint, or obtain historical price information for any market.
- Automation Ready: Build agents or tools that react programmatically to market developments, changing odds, or specific event outcomes.
By using these documented API endpoints, you can seamlessly integrate Polymarket’s rich on-chain prediction market data into your own AI workflows, dashboards, research tools, and trading automations.
Integrate Polymarket prediction markets into the workflow. Can get markets, market, events, event, tags, series, orderbook, price, midpoint, price history, last trade price, spread, tick size, positions, trades, activity, leaderboard, holders, and search.
Retrieve a list of prediction markets from Polymarket with optional filtering
| Parameter | Type | Required | Description |
|---|
closed | string | No | Filter by closed status (true/false). Use false for open markets only. |
order | string | No | Sort field (e.g., volumeNum, liquidityNum, startDate, endDate, createdAt) |
ascending | string | No | Sort direction (true for ascending, false for descending) |
tagId | string | No | Filter by tag ID |
limit | string | No | Number of results per page (e.g., "25"). Max: 50. |
offset | string | No | Number of results to skip for pagination (e.g., "50"). |
| Parameter | Type | Description |
|---|
markets | array | Array of market objects |
↳ id | string | Market ID |
↳ question | string | Market question |
↳ conditionId | string | Condition ID |
↳ slug | string | Market slug |
↳ endDate | string | End date |
↳ image | string | Market image URL |
↳ outcomes | string | Outcomes JSON string |
↳ outcomePrices | string | Outcome prices JSON string |
↳ volume | string | Total volume |
↳ liquidity | string | Total liquidity |
↳ active | boolean | Whether market is active |
↳ closed | boolean | Whether market is closed |
↳ volumeNum | number | Volume as number |
↳ liquidityNum | number | Liquidity as number |
↳ clobTokenIds | array | CLOB token IDs |
Retrieve details of a specific prediction market by ID or slug
| Parameter | Type | Required | Description |
|---|
marketId | string | No | The market ID (e.g., "0x1234...abcd" condition ID format). Required if slug is not provided. |
slug | string | No | The market slug (e.g., "will-trump-win"). URL-friendly identifier. Required if marketId is not provided. |
| Parameter | Type | Description |
|---|
market | object | Market object with details |
↳ id | string | Market ID |
↳ question | string | Market question |
↳ conditionId | string | Condition ID |
↳ slug | string | Market slug |
↳ resolutionSource | string | Resolution source |
↳ endDate | string | End date |
↳ startDate | string | Start date |
↳ image | string | Market image URL |
↳ icon | string | Market icon URL |
↳ description | string | Market description |
↳ outcomes | string | Outcomes JSON string |
↳ outcomePrices | string | Outcome prices JSON string |
↳ volume | string | Total volume |
↳ liquidity | string | Total liquidity |
↳ active | boolean | Whether market is active |
↳ closed | boolean | Whether market is closed |
↳ archived | boolean | Whether market is archived |
↳ volumeNum | number | Volume as number |
↳ liquidityNum | number | Liquidity as number |
↳ clobTokenIds | array | CLOB token IDs |
↳ acceptingOrders | boolean | Whether accepting orders |
↳ negRisk | boolean | Whether negative risk |
Retrieve a list of events from Polymarket with optional filtering
| Parameter | Type | Required | Description |
|---|
closed | string | No | Filter by closed status (true/false). Use false for open events only. |
order | string | No | Sort field (e.g., volume, liquidity, startDate, endDate, createdAt) |
ascending | string | No | Sort direction (true for ascending, false for descending) |
tagId | string | No | Filter by tag ID |
limit | string | No | Number of results per page (e.g., "25"). Max: 50. |
offset | string | No | Number of results to skip for pagination (e.g., "50"). |
| Parameter | Type | Description |
|---|
events | array | Array of event objects |
↳ id | string | Event ID |
↳ ticker | string | Event ticker |
↳ slug | string | Event slug |
↳ title | string | Event title |
↳ description | string | Event description |
↳ startDate | string | Start date |
↳ endDate | string | End date |
↳ image | string | Event image URL |
↳ icon | string | Event icon URL |
↳ active | boolean | Whether event is active |
↳ closed | boolean | Whether event is closed |
↳ archived | boolean | Whether event is archived |
↳ liquidity | number | Total liquidity |
↳ volume | number | Total volume |
↳ markets | array | Array of markets in this event |
Retrieve details of a specific event by ID or slug
| Parameter | Type | Required | Description |
|---|
eventId | string | No | The event ID (e.g., "12345" or UUID format). Required if slug is not provided. |
slug | string | No | The event slug (e.g., "2024-presidential-election"). URL-friendly identifier. Required if eventId is not provided. |
| Parameter | Type | Description |
|---|
event | object | Event object with details |
↳ id | string | Event ID |
↳ ticker | string | Event ticker |
↳ slug | string | Event slug |
↳ title | string | Event title |
↳ description | string | Event description |
↳ startDate | string | Start date |
↳ creationDate | string | Creation date |
↳ endDate | string | End date |
↳ image | string | Event image URL |
↳ icon | string | Event icon URL |
↳ active | boolean | Whether event is active |
↳ closed | boolean | Whether event is closed |
↳ archived | boolean | Whether event is archived |
↳ liquidity | number | Total liquidity |
↳ volume | number | Total volume |
↳ openInterest | number | Open interest |
↳ commentCount | number | Comment count |
↳ markets | array | Array of markets in this event |
Retrieve available tags for filtering markets from Polymarket
| Parameter | Type | Required | Description |
|---|
limit | string | No | Number of results per page (e.g., "25"). Max: 50. |
offset | string | No | Number of results to skip for pagination (e.g., "50"). |
| Parameter | Type | Description |
|---|
tags | array | Array of tag objects |
↳ id | string | Tag ID |
↳ label | string | Tag label |
↳ slug | string | Tag slug |
↳ createdAt | string | Creation timestamp |
↳ updatedAt | string | Last update timestamp |
Search for markets, events, and profiles on Polymarket
| Parameter | Type | Required | Description |
|---|
query | string | Yes | Search query term (e.g., "presidential election", "bitcoin price"). |
limit | string | No | Number of results per page (e.g., "25"). Max: 50. |
page | string | No | Page number for pagination (e.g., "2"). 1-indexed. |
cache | string | No | Enable caching (true/false) |
eventsStatus | string | No | Filter events by status |
limitPerType | string | No | Limit results per type (markets, events, profiles) |
eventsTag | string | No | Filter by event tags (comma-separated) |
sort | string | No | Sort field |
ascending | string | No | Sort direction (true for ascending, false for descending) |
searchTags | string | No | Include tags in search results (true/false) |
searchProfiles | string | No | Include profiles in search results (true/false) |
recurrence | string | No | Filter by recurrence type |
excludeTagId | string | No | Exclude events with these tag IDs (comma-separated) |
keepClosedMarkets | string | No | Include closed markets in results (0 or 1) |
| Parameter | Type | Description |
|---|
results | object | Search results containing markets, events, tags, and profiles arrays |
↳ markets | array | Array of matching market objects |
↳ events | array | Array of matching event objects |
↳ tags | array | Array of matching tag objects |
↳ profiles | array | Array of matching profile objects |
Retrieve series (related market groups) from Polymarket
| Parameter | Type | Required | Description |
|---|
limit | string | No | Number of results per page (e.g., "25"). Max: 50. |
offset | string | No | Number of results to skip for pagination (e.g., "50"). |
| Parameter | Type | Description |
|---|
series | array | Array of series objects |
↳ id | string | Series ID |
↳ ticker | string | Series ticker |
↳ slug | string | Series slug |
↳ title | string | Series title |
↳ seriesType | string | Series type |
↳ recurrence | string | Recurrence pattern |
↳ image | string | Series image URL |
↳ icon | string | Series icon URL |
↳ active | boolean | Whether series is active |
↳ closed | boolean | Whether series is closed |
↳ archived | boolean | Whether series is archived |
↳ featured | boolean | Whether series is featured |
↳ volume | number | Total volume |
↳ liquidity | number | Total liquidity |
↳ eventCount | number | Number of events in series |
Retrieve a specific series (related market group) by ID from Polymarket
| Parameter | Type | Required | Description |
|---|
seriesId | string | Yes | The series ID (e.g., "12345" or UUID format). |
| Parameter | Type | Description |
|---|
series | object | Series object with details |
↳ id | string | Series ID |
↳ ticker | string | Series ticker |
↳ slug | string | Series slug |
↳ title | string | Series title |
↳ seriesType | string | Series type |
↳ recurrence | string | Recurrence pattern |
↳ image | string | Series image URL |
↳ icon | string | Series icon URL |
↳ active | boolean | Whether series is active |
↳ closed | boolean | Whether series is closed |
↳ archived | boolean | Whether series is archived |
↳ featured | boolean | Whether series is featured |
↳ volume | number | Total volume |
↳ liquidity | number | Total liquidity |
↳ commentCount | number | Comment count |
↳ eventCount | number | Number of events in series |
↳ events | array | Array of events in this series |
Retrieve the order book summary for a specific token
| Parameter | Type | Required | Description |
|---|
tokenId | string | Yes | The CLOB token ID from market clobTokenIds array (e.g., "71321045679252212594626385532706912750332728571942532289631379312455583992563"). |
| Parameter | Type | Description |
|---|
orderbook | object | Order book with bids and asks arrays |
↳ market | string | Market identifier |
↳ asset_id | string | Asset token ID |
↳ hash | string | Order book hash |
↳ timestamp | string | Timestamp |
↳ bids | array | Bid orders |
↳ price | string | Bid price |
↳ size | string | Bid size |
↳ asks | array | Ask orders |
↳ price | string | Ask price |
↳ size | string | Ask size |
↳ min_order_size | string | Minimum order size |
↳ tick_size | string | Tick size |
↳ neg_risk | boolean | Whether negative risk |
Retrieve the market price for a specific token and side
| Parameter | Type | Required | Description |
|---|
tokenId | string | Yes | The CLOB token ID from market clobTokenIds array (e.g., "71321045679252212594626385532706912750332728571942532289631379312455583992563"). |
side | string | Yes | Order side: "buy" or "sell". |
| Parameter | Type | Description |
|---|
price | string | Market price |
Retrieve the midpoint price for a specific token
| Parameter | Type | Required | Description |
|---|
tokenId | string | Yes | The CLOB token ID from market clobTokenIds array (e.g., "71321045679252212594626385532706912750332728571942532289631379312455583992563"). |
| Parameter | Type | Description |
|---|
midpoint | string | Midpoint price |
Retrieve historical price data for a specific market token
| Parameter | Type | Required | Description |
|---|
tokenId | string | Yes | The CLOB token ID from market clobTokenIds array (e.g., "71321045679252212594626385532706912750332728571942532289631379312455583992563"). |
interval | string | No | Duration ending at current time (1m, 1h, 6h, 1d, 1w, max). Mutually exclusive with startTs/endTs. |
fidelity | number | No | Data resolution in minutes (e.g., 60 for hourly) |
startTs | number | No | Start timestamp (Unix seconds UTC) |
endTs | number | No | End timestamp (Unix seconds UTC) |
| Parameter | Type | Description |
|---|
history | array | Array of price history entries |
↳ t | number | Unix timestamp |
↳ p | number | Price at timestamp |
Retrieve the last trade price for a specific token
| Parameter | Type | Required | Description |
|---|
tokenId | string | Yes | The CLOB token ID from market clobTokenIds array (e.g., "71321045679252212594626385532706912750332728571942532289631379312455583992563"). |
| Parameter | Type | Description |
|---|
price | string | Last trade price |
side | string | Side of the last trade (BUY or SELL) |
Retrieve the bid-ask spread for a specific token
| Parameter | Type | Required | Description |
|---|
tokenId | string | Yes | The CLOB token ID from market clobTokenIds array (e.g., "71321045679252212594626385532706912750332728571942532289631379312455583992563"). |
| Parameter | Type | Description |
|---|
spread | object | Spread value between bid and ask |
↳ spread | string | The spread value |
Retrieve the minimum tick size for a specific token
| Parameter | Type | Required | Description |
|---|
tokenId | string | Yes | The CLOB token ID from market clobTokenIds array (e.g., "71321045679252212594626385532706912750332728571942532289631379312455583992563"). |
| Parameter | Type | Description |
|---|
tickSize | string | Minimum tick size |
Retrieve user positions from Polymarket
| Parameter | Type | Required | Description |
|---|
user | string | Yes | User wallet address |
market | string | No | Condition IDs to filter positions (e.g., "0x1234...abcd,0x5678...efgh"). Mutually exclusive with eventId. |
eventId | string | No | Event ID to filter positions (e.g., "12345"). Mutually exclusive with market. |
sizeThreshold | string | No | Minimum position size threshold (default: 1) |
redeemable | string | No | Filter for redeemable positions only (true/false) |
mergeable | string | No | Filter for mergeable positions only (true/false) |
sortBy | string | No | Sort field (TOKENS, CURRENT, INITIAL, CASHPNL, PERCENTPNL, TITLE, RESOLVING, PRICE, AVGPRICE) |
sortDirection | string | No | Sort direction (ASC or DESC) |
title | string | No | Search filter by title |
limit | string | No | Number of results per page (e.g., "25"). |
offset | string | No | Number of results to skip for pagination (e.g., "50"). |
| Parameter | Type | Description |
|---|
positions | array | Array of position objects |
↳ proxyWallet | string | Proxy wallet address |
↳ asset | string | Asset token ID |
↳ conditionId | string | Condition ID |
↳ size | number | Position size |
↳ avgPrice | number | Average price |
↳ initialValue | number | Initial value |
↳ currentValue | number | Current value |
↳ cashPnl | number | Cash profit/loss |
↳ percentPnl | number | Percent profit/loss |
↳ totalBought | number | Total bought |
↳ realizedPnl | number | Realized profit/loss |
↳ percentRealizedPnl | number | Percent realized profit/loss |
↳ curPrice | number | Current price |
↳ redeemable | boolean | Whether position is redeemable |
↳ mergeable | boolean | Whether position is mergeable |
↳ title | string | Market title |
↳ slug | string | Market slug |
↳ icon | string | Market icon URL |
↳ eventSlug | string | Event slug |
↳ outcome | string | Outcome name |
↳ outcomeIndex | number | Outcome index |
↳ oppositeOutcome | string | Opposite outcome name |
↳ oppositeAsset | string | Opposite asset token ID |
↳ endDate | string | End date |
↳ negativeRisk | boolean | Whether negative risk |
Retrieve trade history from Polymarket
| Parameter | Type | Required | Description |
|---|
user | string | No | User wallet address to filter trades |
market | string | No | Market/condition ID to filter trades (e.g., "0x1234...abcd"). Mutually exclusive with eventId. |
eventId | string | No | Event ID to filter trades (e.g., "12345"). Mutually exclusive with market. |
side | string | No | Trade direction filter (BUY or SELL) |
takerOnly | string | No | Filter for taker trades only (true/false, default: true) |
filterType | string | No | Filter type (CASH or TOKENS) - requires filterAmount |
filterAmount | string | No | Filter amount threshold - requires filterType |
limit | string | No | Number of results per page (e.g., "50"). Default: 100, max: 10000. |
offset | string | No | Number of results to skip for pagination (e.g., "100"). |
| Parameter | Type | Description |
|---|
trades | array | Array of trade objects |
↳ proxyWallet | string | Proxy wallet address |
↳ side | string | Trade side (BUY or SELL) |
↳ asset | string | Asset token ID |
↳ conditionId | string | Condition ID |
↳ size | number | Trade size |
↳ price | number | Trade price |
↳ timestamp | number | Unix timestamp |
↳ title | string | Market title |
↳ slug | string | Market slug |
↳ icon | string | Market icon URL |
↳ eventSlug | string | Event slug |
↳ outcome | string | Outcome name |
↳ outcomeIndex | number | Outcome index |
↳ name | string | Trader name |
↳ pseudonym | string | Trader pseudonym |
↳ bio | string | Trader bio |
↳ profileImage | string | Profile image URL |
↳ profileImageOptimized | string | Optimized profile image URL |
↳ transactionHash | string | Transaction hash |
Retrieve on-chain activity for a user including trades, splits, merges, redemptions, rewards, and conversions
| Parameter | Type | Required | Description |
|---|
user | string | Yes | User wallet address (0x-prefixed) |
limit | string | No | Maximum results to return (e.g., "50"). Default: 100, max: 500. |
offset | string | No | Number of results to skip for pagination (e.g., "100"). Default: 0, max: 10000. |
market | string | No | Comma-separated condition IDs (e.g., "0x1234...abcd,0x5678...efgh"). Mutually exclusive with eventId. |
eventId | string | No | Comma-separated event IDs (e.g., "12345,67890"). Mutually exclusive with market. |
type | string | No | Activity type filter: TRADE, SPLIT, MERGE, REDEEM, REWARD, CONVERSION, MAKER_REBATE |
start | number | No | Start timestamp (Unix seconds) |
end | number | No | End timestamp (Unix seconds) |
sortBy | string | No | Sort field: TIMESTAMP, TOKENS, or CASH (default: TIMESTAMP) |
sortDirection | string | No | Sort direction: ASC or DESC (default: DESC) |
side | string | No | Trade side filter: BUY or SELL (only applies to trades) |
| Parameter | Type | Description |
|---|
activity | array | Array of activity entries |
↳ proxyWallet | string | User proxy wallet address |
↳ timestamp | number | Unix timestamp of activity |
↳ conditionId | string | Market condition ID |
↳ type | string | Activity type (TRADE, SPLIT, MERGE, REDEEM, REWARD, CONVERSION) |
↳ size | number | Size in tokens |
↳ usdcSize | number | Size in USDC |
↳ transactionHash | string | Blockchain transaction hash |
↳ price | number | Price (for trades) |
↳ asset | string | Asset/token ID |
↳ side | string | Trade side (BUY/SELL) |
↳ outcomeIndex | number | Outcome index |
↳ title | string | Market title |
↳ slug | string | Market slug |
↳ icon | string | Market icon URL |
↳ eventSlug | string | Event slug |
↳ outcome | string | Outcome name |
↳ name | string | User display name |
↳ pseudonym | string | User pseudonym |
↳ bio | string | User bio |
↳ profileImage | string | User profile image URL |
↳ profileImageOptimized | string | Optimized profile image URL |
Retrieve trader leaderboard rankings by profit/loss or volume
| Parameter | Type | Required | Description |
|---|
category | string | No | Category filter: OVERALL, POLITICS, SPORTS, CRYPTO, CULTURE, MENTIONS, WEATHER, ECONOMICS, TECH, FINANCE (default: OVERALL) |
timePeriod | string | No | Time period: DAY, WEEK, MONTH, ALL (default: DAY) |
orderBy | string | No | Order by: PNL or VOL (default: PNL) |
limit | string | No | Number of results to return (e.g., "10"). Range: 1-50, default: 25. |
offset | string | No | Number of results to skip for pagination (e.g., "25"). Range: 0-1000, default: 0. |
user | string | No | Filter by specific user wallet address |
userName | string | No | Filter by username |
| Parameter | Type | Description |
|---|
leaderboard | array | Array of leaderboard entries |
↳ rank | string | Leaderboard rank position |
↳ proxyWallet | string | User proxy wallet address |
↳ userName | string | User display name |
↳ vol | number | Trading volume |
↳ pnl | number | Profit and loss |
↳ profileImage | string | User profile image URL |
↳ xUsername | string | Twitter/X username |
↳ verifiedBadge | boolean | Whether user has verified badge |
Retrieve top holders of a specific market token
| Parameter | Type | Required | Description |
|---|
market | string | Yes | Comma-separated list of condition IDs (e.g., "0x1234...abcd" or "0x1234...abcd,0x5678...efgh"). |
limit | string | No | Number of holders to return (e.g., "10"). Range: 0-20, default: 20. |
minBalance | string | No | Minimum balance threshold (default: 1) |
| Parameter | Type | Description |
|---|
holders | array | Array of market holder groups by token |
↳ token | string | Token/asset ID |
↳ holders | array | Array of holders for this token |
↳ proxyWallet | string | Holder wallet address |
↳ bio | string | Holder bio |
↳ asset | string | Asset ID |
↳ pseudonym | string | Holder pseudonym |
↳ amount | number | Amount held |
↳ displayUsernamePublic | boolean | Whether username is publicly displayed |
↳ outcomeIndex | number | Outcome index |
↳ name | string | Holder display name |
↳ profileImage | string | Profile image URL |
↳ profileImageOptimized | string | Optimized profile image URL |
