profitable-expert-advisor/polymarket/docs/API_REFERENCE.md

Polymarket API Reference

Complete API reference for the Polymarket Trading Framework.

Table of Contents

• Rate Limits
• Gamma API Client
• CLOB API Client
• Data API Client
• Base Strategy
• Backtesting Engine
• Live Trading Engine
• Error Handling

Rate Limits

Overview

Polymarket APIs implement rate limiting to ensure fair usage. The framework includes built-in rate limit handling.

Rate Limit Specifications

Gamma API (Market Discovery)

• Rate Limit: 60 requests per minute per IP
• Burst: Up to 10 requests in a single second
• Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

CLOB API (Trading & Orderbook)

• Rate Limit: 120 requests per minute per authenticated user
• Burst: Up to 20 requests in a single second
• Headers: Same as Gamma API

Data API (Positions & History)

• Rate Limit: 30 requests per minute per authenticated user
• Burst: Up to 5 requests in a single second

Handling Rate Limits

The framework automatically handles rate limits with:

• Automatic request queuing
• Exponential backoff on 429 (Too Many Requests) errors
• Configurable delays between requests (default: 100ms)

from polymarket.utils.config import Config

# Configure request delay
Config.REQUEST_DELAY = 0.2  # 200ms between requests
Config.MAX_REQUESTS_PER_MINUTE = 60

Rate Limit Errors

When rate limited, the API returns:

• Status Code: 429 Too Many Requests
• Response Body: {"error": "Rate limit exceeded", "retry_after": 60}
• Headers: Retry-After: 60 (seconds to wait)

The framework will automatically retry after the specified delay.

Gamma API Client

Class: GammaClient

Client for Polymarket Gamma API - Market discovery and metadata.

Constructor

GammaClient(timeout: int = 30)

Parameters:

• timeout (int): Request timeout in seconds (default: 30)

Methods

get_events()

Fetch active events/markets.

get_events(
    active: bool = True,
    closed: bool = False,
    limit: int = 100,
    tag_id: Optional[int] = None,
    series_id: Optional[int] = None,
    order: Optional[str] = None,
    ascending: bool = True
) -> List[Dict]

Parameters:

• active (bool): Filter for active events (default: True)
• closed (bool): Filter for closed events (default: False)
• limit (int): Maximum number of results (default: 100, max: 1000)
• tag_id (Optional[int]): Filter by tag/category ID
• series_id (Optional[int]): Filter by series ID (for sports)
• order (Optional[str]): Sort order (e.g., 'startTime', 'volume')
• ascending (bool): Sort ascending or descending (default: True)

Returns:

• List[Dict]: List of event dictionaries with fields:
  • id: Event ID
  • title: Event title
  • slug: Event slug (URL-friendly identifier)
  • description: Event description
  • startDate: Start date (ISO 8601)
  • endDate: End date (ISO 8601)
  • markets: List of markets in this event
  • tags: List of tag IDs

Example:

from polymarket import GammaClient

gamma = GammaClient()
events = gamma.get_events(active=True, limit=10, tag_id=21)  # Get 10 active crypto events

get_event_by_slug()

Get event details by slug.

get_event_by_slug(slug: str) -> Optional[Dict]

Parameters:

• slug (str): Event slug (e.g., 'will-bitcoin-reach-100k-by-2025')

Returns:

• Optional[Dict]: Event dictionary or None if not found

Example:

event = gamma.get_event_by_slug('will-bitcoin-reach-100k-by-2025')

get_market_by_slug()

Get market details by slug.

get_market_by_slug(slug: str) -> Optional[Dict]

Parameters:

• slug (str): Market slug

Returns:

• Optional[Dict]: Market dictionary with:
  • clobTokenIds: List of CLOB token IDs for Yes/No outcomes
  • outcomes: JSON string of outcome names (e.g., '["Yes", "No"]')
  • outcomePrices: JSON string of current prices (e.g., '[0.65, 0.35]')
  • question: Market question
  • endDate: Market end date

Example:

market = gamma.get_market_by_slug('bitcoin-100k-2025')
prices = gamma.get_market_prices(market)
print(f"Yes: {prices['Yes']:.2%}, No: {prices['No']:.2%}")

get_tags()

Get all available tags/categories.

get_tags(limit: int = 100) -> List[Dict]

Returns:

• List[Dict]: List of tag dictionaries with id and name fields

Example:

tags = gamma.get_tags()
for tag in tags:
    print(f"{tag['id']}: {tag['name']}")

get_sports()

Get all supported sports leagues.

get_sports() -> List[Dict]

Returns:

• List[Dict]: List of sports league dictionaries

get_market_prices()

Extract current prices from market data.

get_market_prices(market: Dict) -> Dict[str, float]

Parameters:

• market (Dict): Market dictionary with outcomes and outcomePrices

Returns:

• Dict[str, float]: Dictionary mapping outcome to price (probability)

Example:

prices = gamma.get_market_prices(market)
yes_prob = prices['Yes']  # 0.65 = 65% probability

CLOB API Client

Class: ClobClient

Client for Polymarket CLOB API - Trading and orderbook data.

Methods

get_price()

Get current price for a token.

get_price(token_id: str, side: str = 'buy') -> float

Parameters:

• token_id (str): CLOB token ID
• side (str): 'buy' or 'sell' (default: 'buy')

Returns:

• float: Current price (0.0 to 1.0)

Example:

from polymarket import ClobClient

clob = ClobClient()
token_id = market['clobTokenIds'][0]
price = clob.get_price(token_id, side='buy')

get_orderbook()

Get orderbook depth for a token.

get_orderbook(token_id: str) -> Dict

Returns:

• Dict: Dictionary with:
  • bids: List of bid orders [{"price": float, "size": float}, ...]
  • asks: List of ask orders [{"price": float, "size": float}, ...]

Example:

book = clob.get_orderbook(token_id)
best_bid = book['bids'][0]['price']
best_ask = book['asks'][0]['price']

get_best_bid_ask()

Get best bid and ask prices.

get_best_bid_ask(token_id: str) -> Dict[str, float]

Returns:

• Dict[str, float]: Dictionary with:
  • bid: Best bid price
  • ask: Best ask price
  • spread: Bid-ask spread
  • mid: Mid price ((bid + ask) / 2)

get_market_depth()

Get market depth up to specified levels.

get_market_depth(token_id: str, levels: int = 10) -> Dict

Returns:

• Dict: Dictionary with:
  • bids: Top N bid levels
  • asks: Top N ask levels
  • bid_depth: Cumulative bid depth
  • ask_depth: Cumulative ask depth
  • total_depth: Total market depth

calculate_impact()

Calculate estimated price impact for a trade size.

calculate_impact(token_id: str, size: float, side: str) -> Dict

Parameters:

• token_id (str): CLOB token ID
• size (float): Trade size in tokens
• side (str): 'buy' or 'sell'

Returns:

• Dict: Dictionary with:
  • average_price: Average execution price
  • best_price: Best available price
  • price_impact: Price impact percentage
  • levels_consumed: Number of orderbook levels consumed
  • slippage: Price slippage

Example:

impact = clob.calculate_impact(token_id, size=100, side='buy')
print(f"Price impact: {impact['price_impact']:.2%}")
print(f"Average price: {impact['average_price']:.4f}")

Data API Client

Class: DataClient

Client for Polymarket Data API - Positions and history.

Constructor

DataClient(api_key: Optional[str] = None, timeout: int = 30)

Parameters:

• api_key (Optional[str]): API key for authenticated requests
• timeout (int): Request timeout in seconds

Methods

get_positions()

Get user positions.

get_positions(user_address: str) -> List[Dict]

Parameters:

• user_address (str): User wallet address (0x...)

Returns:

• List[Dict]: List of position dictionaries

get_trades()

Get user trade history.

get_trades(user_address: str, limit: int = 100) -> List[Dict]

Parameters:

• user_address (str): User wallet address
• limit (int): Maximum number of trades (default: 100)

Returns:

• List[Dict]: List of trade dictionaries

get_portfolio()

Get user portfolio summary.

get_portfolio(user_address: str) -> Dict

Returns:

• Dict: Portfolio dictionary with balances, positions, etc.

Base Strategy

Class: BaseStrategy

Base class for all Polymarket trading strategies.

Constructor

BaseStrategy(name: str, initial_balance: float = 1000.0)

Abstract Methods

analyze_market()

Analyze market and generate trading signal.

@abstractmethod
def analyze_market(self, market_data: Dict) -> Optional[MarketSignal]:
    """
    Args:
        market_data: Dictionary containing:
            - 'event': Event information
            - 'market': Market information
            - 'prices': Current outcome prices
            - 'orderbook': Orderbook data
            - 'history': Historical price data (if available)
    
    Returns:
        MarketSignal or None if no trade
    """

get_parameters()

Return strategy parameters.

@abstractmethod
def get_parameters(self) -> Dict[str, Any]:
    """Returns: Dictionary of parameter names and values"""

Properties

• name: Strategy name
• initial_balance: Starting USDC balance
• current_balance: Current USDC balance
• equity: Current equity (balance + unrealized PnL)
• positions: Dictionary of open positions (token_id -> Position)
• total_trades: Total number of trades executed
• winning_trades: Number of winning trades
• losing_trades: Number of losing trades
• max_drawdown: Maximum drawdown (0.0 to 1.0)

Methods

update_position()

Update position with current price.

update_position(token_id: str, current_price: float) -> None

calculate_equity()

Calculate current equity (balance + unrealized PnL).

calculate_equity(self) -> float

can_open_position()

Check if strategy can open a new position.

can_open_position(self, size: float, token_id: str) -> bool

get_performance_metrics()

Get current performance metrics.

get_performance_metrics(self) -> Dict[str, Any]

Returns:

• Dictionary with: total_trades, winning_trades, losing_trades, win_rate, total_profit, total_loss, net_profit, profit_factor, max_drawdown, current_balance, equity, unrealized_pnl, open_positions

Backtesting Engine

Class: BacktestEngine

Main backtesting engine for Polymarket strategies.

Constructor

BacktestEngine(
    strategy: BaseStrategy,
    start_date: datetime,
    end_date: datetime,
    initial_balance: float = 1000.0
)

Methods

run()

Run the backtest.

run(self, markets: Optional[List[Dict]] = None) -> Dict[str, Any]

Returns:

• Dictionary with backtest results including:
  • total_return: Total return percentage
  • total_trades: Number of trades
  • win_rate: Win rate percentage
  • sharpe_ratio: Sharpe ratio
  • max_drawdown: Maximum drawdown percentage
  • equity_curve: List of equity values over time
  • trades: List of all trades executed

generate_report()

Generate backtest report.

generate_report(self, output_file: Optional[str] = None) -> None

Live Trading Engine

Class: LiveTradingEngine

Live trading engine for Polymarket.

Constructor

LiveTradingEngine(
    strategy: BaseStrategy,
    poll_interval: int = 60
)

Parameters:

• strategy: Strategy instance to trade
• poll_interval: Seconds between market checks (default: 60)

Methods

add_market()

Add a market to monitor.

add_market(
    event_slug: Optional[str] = None,
    market_slug: Optional[str] = None
) -> None

monitor_tag()

Monitor all active markets in a tag/category.

monitor_tag(self, tag_id: int, limit: int = 20) -> None

start()

Start the live trading engine.

start(self) -> None

stop()

Stop the trading engine.

stop(self) -> None

Error Handling

Common Errors

ConnectionError

• Cause: Network connectivity issues
• Solution: Check internet connection, retry with exponential backoff

TimeoutError

• Cause: Request timeout exceeded
• Solution: Increase timeout value or check API status

RateLimitError

• Cause: Rate limit exceeded
• Solution: Framework automatically handles with retry logic

AuthenticationError

• Cause: Invalid API credentials
• Solution: Verify API keys and wallet address in .env file

MarketNotFoundError

• Cause: Market slug or ID not found
• Solution: Verify market exists and is active

Error Response Format

All API errors return JSON:

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {}
}

Retry Logic

The framework implements automatic retry for:

• Network errors (up to 3 retries)
• Rate limit errors (with exponential backoff)
• 5xx server errors (up to 3 retries)

No retry for:

• 4xx client errors (except 429)
• Authentication errors
• Validation errors