Skip to main content

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

Build docs developers (and LLMs) love