Polymarket Market API

API reference for Polymarket prediction market integration

Overview

Polymarket is a real-money prediction market platform built on Polygon that allows users to trade on the outcome of future events using USDC. The Polymarket market API provides access to high-liquidity markets with significant trading volume.

MarketType Enum

from prediction_market_agent_tooling.markets.markets import MarketType

market_type = MarketType.POLYMARKET

Market Class

PolymarketAgentMarket

The PolymarketAgentMarket class extends AgentMarket and provides Polymarket-specific functionality.

from prediction_market_agent_tooling.markets.polymarket.polymarket import PolymarketAgentMarket

Core Methods

Get Markets

Retrieve available prediction markets from Polymarket.

from prediction_market_agent_tooling.markets.agent_market import FilterBy, SortBy

markets = PolymarketAgentMarket.get_markets(
    limit=500,
    filter_by=FilterBy.OPEN,
    sort_by=SortBy.HIGHEST_LIQUIDITY
)

limit · int

Maximum number of markets to retrieve (commonly 500 for Polymarket)

filter_by · FilterBy

Filter markets by status (OPEN, RESOLVED, etc.)

sort_by · SortBy

Sort order (HIGHEST_LIQUIDITY recommended for Polymarket)

markets · list[PolymarketAgentMarket]

List of market objects matching the query criteria

Get Binary Market

Retrieve a specific binary market by ID.

market = PolymarketAgentMarket.get_binary_market(
    id="polymarket-market-id"
)

id · str · required

Polymarket market ID (condition ID)

market · PolymarketAgentMarket

Market object containing question, probabilities, and trading information

Buy Tokens

Purchase outcome tokens for a market.

market.buy_tokens(
    outcome="Yes",
    amount=USD(100)  # In USDC
)

outcome · str · required

Outcome to bet on (“Yes” or “No” for binary markets)

amount · USD · required

Amount to spend in USDC

Get Trade Balance

Get available USDC balance for trading.

balance = PolymarketAgentMarket.get_trade_balance(api_keys)

api_keys · APIKeys · required

API keys containing Polymarket credentials and wallet

balance · USD

Available USDC balance for trading

Market Data Model

Market Properties

id · str

Polymarket market condition ID

question · str

Market question text

description · str | None

Market description with additional context

outcomes · list[str]

Available outcomes (e.g., [“Yes”, “No”] for binary markets)

p_yes · Probability

Current probability of “Yes” outcome (0.0 to 1.0)

volume · USD | None

Total trading volume in USDC

close_time · DatetimeUTC | None

When the market closes for trading

created_time · DatetimeUTC | None

When the market was created

url · str

Direct link to the market on Polymarket

is_open · bool

Whether the market is currently open for trading

resolution · str | None

Final resolution outcome (if resolved)

Polymarket-Specific Features

Real-Money Trading

Polymarket uses USDC (USD Coin) for real-money predictions on Polygon.

# All amounts are in USDC
market.buy_tokens(outcome="Yes", amount=USD(50))  # 50 USDC

High Liquidity Markets

Polymarket is known for high-liquidity markets, especially on political and current events.

# Fetch by highest liquidity
markets = PolymarketAgentMarket.get_markets(
    limit=500,
    filter_by=FilterBy.OPEN,
    sort_by=SortBy.HIGHEST_LIQUIDITY
)

The Graph Integration

Polymarket market data is accessible via The Graph protocol.

# Query historical market data
url = f"https://gateway.thegraph.com/api/{api_key}/subgraphs/id/81Dm16JjuFSrqz813HysXoUPvzTwE7fsfPk2RTf66nyC"

Real-World Examples

Historical Data Analysis

Query historical Polymarket data for sentiment analysis.

import httpx
from prediction_market_agent.agents.berlin1_agent.polysent_agent import (
    get_polymarket_history,
)

# Get historical data for a market question
history_data = get_polymarket_history(market.question)

# Returns market history with outcomes and prices
for market_data in history_data:
    print(f"Question: {market_data['question']}")
    print(f"Volume: {market_data['volume']}")
    for outcome in market_data['outcomes']:
        print(f"  {outcome['name']}: {outcome['price']}")

Market Replication

Replicate high-quality Polymarket markets to other platforms.

from prediction_market_agent.agents.replicate_to_omen_agent.omen_replicate import (
    omen_replicate_from_tx,
)

# Fetch top 500 Polymarket markets by liquidity
markets = get_binary_markets(
    500,
    MarketType.POLYMARKET,
    filter_by=FilterBy.OPEN,
    sort_by=SortBy.HIGHEST_LIQUIDITY
)

# Replicate to Omen
created_addresses = omen_replicate_from_tx(
    api_keys=api_keys,
    market_type=MarketType.POLYMARKET,
    n_to_replicate=5,
    initial_funds=USD(10),
    collateral_token_address=collateral_token,
    replicated_market_table_handler=handler
)

Trading Strategy Example

from prediction_market_agent_tooling.deploy.agent import DeployableTraderAgent

class PolymarketTradingAgent(DeployableTraderAgent):
    bet_on_n_markets_per_run = 2

    def answer_binary_market(self, market: AgentMarket) -> ProbabilisticAnswer | None:
        # Analyze Polymarket-specific factors
        if market.volume and market.volume > USD(10000):
            # High liquidity market - more reliable price discovery
            prediction = self.predict_with_high_confidence(market)
        else:
            # Lower liquidity - be more cautious
            prediction = self.predict_with_low_confidence(market)
        
        return prediction

# Run agent
agent = PolymarketTradingAgent()
agent.run(market_type=MarketType.POLYMARKET)

Microchain Function

Use Polymarket in microchain-based agents.

from prediction_market_agent.agents.microchain_agent.utils import (
    get_binary_markets,
)

# Note: Polymarket uses NONE sort by default in microchain
markets = get_binary_markets(
    market_type=MarketType.POLYMARKET
)  # Uses SortBy.NONE internally

Platform Details

• Blockchain: Polygon (Layer 2)
• Currency: USDC (USD Coin)
• Website: https://polymarket.com
• Market Types: Primarily binary (Yes/No)
• Focus: Political events, current affairs, crypto
• Liquidity: Often highest among prediction markets
• Resolution: UMA protocol for decentralized resolution

Market Categories

Polymarket markets typically cover:

• Politics & elections
• Cryptocurrency prices
• Sports outcomes
• Current events
• Pop culture
• Economic indicators

Advantages

• Real Money: USDC-based real-money predictions
• High Liquidity: Large trading volumes
• Quality Markets: Professional market creation
• Decentralized Resolution: UMA protocol
• Institutional Interest: Growing institutional participation

Considerations

Sorting Behavior

When fetching Polymarket markets for trading:

# Use NONE sort in microchain agents
if market_type == MarketType.POLYMARKET:
    sort_by = SortBy.NONE
else:
    sort_by = SortBy.CLOSING_SOONEST

Volume-Based Filtering

Focus on high-volume markets for better price discovery.

markets_sorted = sorted(
    markets,
    key=lambda m: m.volume or 0,
    reverse=True,
)

Regulatory Compliance

Polymarket has geographic restrictions. Ensure compliance with local regulations.

GraphQL Query Example

{
  binaryMarkets(first: 5, where: {question_contains: "Bitcoin"}) {
    id
    question
    outcomes {
      name
      price
    }
    volume
    startTime
    endTime
  }
}

Error Handling

try:
    market = PolymarketAgentMarket.get_binary_market(id=market_id)
    market.buy_tokens(outcome="Yes", amount=USD(100))
except Exception as e:
    logger.error(f"Polymarket trade failed: {e}")
    # Handle insufficient balance, market closed, etc.

Best Practices

1. Sort by Liquidity: Use SortBy.HIGHEST_LIQUIDITY for better markets
2. Check Volume: Verify sufficient volume before trading
3. Monitor Fees: Account for trading fees in calculations
4. Verify Resolution: Understand UMA resolution process
5. Manage Risk: Use appropriate position sizing

See Also

• Omen Market API
• Manifold Market API
• Metaculus Market API