[![Contributors][contributors-shield]][contributors-url] [![Forks][forks-shield]][forks-url] [![Stargazers][stars-shield]][stars-url] [![Issues][issues-shield]][issues-url] [![MIT License][license-shield]][license-url]

Polymarket Agents

🤖 AI-powered autonomous trading agents for Polymarket prediction markets

Polymarket Agents is a modern, open-source framework for building sophisticated AI trading agents on Polymarket. Leverage state-of-the-art LLMs, RAG (Retrieval-Augmented Generation), and superforecasting methodologies to create intelligent trading systems that analyze markets, events, and news to make informed predictions.

Built with Python 3.12+ | MIT Licensed | Production Ready

This code is free and publicly available under MIT License open source license (terms of service)!

Features

• AI-Powered Trading: Autonomous trading agents using state-of-the-art LLMs
• Polymarket Integration: Full API integration for markets, events, and trading
• RAG Support: Local and remote RAG (Retrieval-Augmented Generation) for market analysis
• Data Sources: Integration with news providers, web search, and betting services
• Superforecasting: Advanced prediction capabilities using superforecaster methodologies
• Trending Markets: Get trending markets sorted by 24-hour volume
• Modern Stack: Built with Python 3.12+, LangChain, FastAPI, and modern tooling
• Docker Ready: Containerized deployment for easy setup

Getting started

This project requires Python 3.12+.

Prerequisites

• Python 3.12 or higher
• pip (Python package manager)
• (Optional) Docker for containerized deployment
• (Optional) NewsAPI key for news integration
• (Optional) Tavily API key for web search

Installation

1. Clone the repository

   git clone https://github.com//blackskyorg//PolyMarket-AI-agent-trading.git
   cd poly-ai-trading-agent
   

2. Create a virtual environment

   Using venv (recommended):

   python -m venv .venv
   

   Or using uv (faster):

   uv venv
   

3. Activate the virtual environment

   • On Windows (PowerShell):

   .venv\Scripts\Activate.ps1
   

   • On Windows (CMD):

   .venv\Scripts\activate.bat
   

   • On macOS and Linux:

   source .venv/bin/activate
   

4. Install the project

   Using pip:

   pip install -e .
   

   Or with development dependencies:

   pip install -e ".[dev]"
   

   Using uv (faster):

   uv pip install -e ".[dev]"
   

5. Set up environment variables

   Create a .env file in the project root:

   # Copy example if available, or create new
   touch .env
   

   Add the following environment variables:

   # Required for trading
   POLYGON_WALLET_PRIVATE_KEY="your_private_key_here"
   
   # Required for AI features
   OPENAI_API_KEY="your_openai_api_key_here"
   
   # Optional - for news integration
   NEWSAPI_API_KEY="your_newsapi_key_here"
   
   # Optional - for web search
   TAVILY_API_KEY="your_tavily_key_here"
   

   Important Notes:

   • Never commit your .env file to version control
   • Keep your POLYGON_WALLET_PRIVATE_KEY secure and never share it
   • You can get a NewsAPI key from newsapi.org
   • You can get a Tavily key from tavily.com

6. Load your wallet with USDC (if trading)

   Before executing trades, ensure your Polygon wallet has sufficient USDC balance for trading.

Usage

Command Line Interface

The CLI is the primary interface for interacting with Polymarket. All commands follow this format:

python -m scripts.python.cli <command-name> [options]

Getting Help

To see all available commands:

python -m scripts.python.cli --help

To get help for a specific command:

python -m scripts.python.cli <command-name> --help

Detailed Command Reference

1. Get All Markets

Retrieve and display markets from Polymarket.

Command:

python -m scripts.python.cli get-all-markets [--limit LIMIT] [--sort-by SORT_BY]

Parameters:

• --limit (optional): Number of markets to retrieve (default: 5)
• --sort-by (optional): Sorting criterion (default: "spread")

Examples:

# Get 10 markets sorted by spread
python -m scripts.python.cli get-all-markets --limit 10 --sort-by spread

# Get 5 markets (default)
python -m scripts.python.cli get-all-markets

# Get 20 markets
python -m scripts.python.cli get-all-markets --limit 20

Output: Displays a list of markets with details including:

• Market ID
• Question/Title
• Description
• Active status
• Spread
• Outcomes
• Outcome prices

2. Get Trending Markets

Get trending markets sorted by 24-hour volume. This is useful for finding the most active markets.

Command:

python -m scripts.python.cli get-trending-markets [--limit LIMIT]

Parameters:

• --limit (optional): Number of trending markets to retrieve (default: 10)

Examples:

# Get top 10 trending markets
python -m scripts.python.cli get-trending-markets

# Get top 25 trending markets
python -m scripts.python.cli get-trending-markets --limit 25

# Get top 5 trending markets
python -m scripts.python.cli get-trending-markets --limit 5

Output: Displays trending markets sorted by 24-hour volume, showing the most active markets first.

3. Get All Events

Retrieve and display events from Polymarket.

Command:

python -m scripts.python.cli get-all-events [--limit LIMIT] [--sort-by SORT_BY]

Parameters:

• --limit (optional): Number of events to retrieve (default: 5)
• --sort-by (optional): Sorting criterion (default: "number_of_markets")

Examples:

# Get 10 events sorted by number of markets
python -m scripts.python.cli get-all-events --limit 10 --sort-by number_of_markets

# Get 5 events (default)
python -m scripts.python.cli get-all-events

Output: Displays events with details including:

• Event ID
• Title
• Description
• Active status
• Number of associated markets
• End date

4. Get Relevant News

Search for news articles related to specific keywords. Requires NewsAPI key.

Command:

python -m scripts.python.cli get-relevant-news <keywords>

Parameters:

• keywords (required): Comma-separated keywords to search for

Examples:

# Search for news about Bitcoin
python -m scripts.python.cli get-relevant-news "Bitcoin,crypto"

# Search for news about elections
python -m scripts.python.cli get-relevant-news "election,president"

# Search for multiple keywords
python -m scripts.python.cli get-relevant-news "AI,technology,machine learning"

Output: Displays news articles with:

• Title
• Description
• Source
• URL
• Published date

5. Ask LLM

Query the LLM with any question. Useful for getting AI-powered insights.

Command:

python -m scripts.python.cli ask-llm "<your question>"

Parameters:

• user_input (required): Your question or prompt

Examples:

# Ask about trading strategies
python -m scripts.python.cli ask-llm "What are the best markets to trade?"

# Ask for market analysis
python -m scripts.python.cli ask-llm "Should I invest in prediction markets?"

# Ask for general questions
python -m scripts.python.cli ask-llm "Explain how prediction markets work"

Output: Returns AI-generated response based on your question.

6. Ask Polymarket LLM

Query the LLM with context about current Polymarket markets and events. This provides more relevant answers based on actual market data.

Command:

python -m scripts.python.cli ask-polymarket-llm "<your question>"

Parameters:

• user_input (required): Your question about Polymarket

Examples:

# Ask about current markets
python -m scripts.python.cli ask-polymarket-llm "What types of markets are currently trending?"

# Ask for trading recommendations
python -m scripts.python.cli ask-polymarket-llm "Which markets should I focus on for trading?"

# Ask about market opportunities
python -m scripts.python.cli ask-polymarket-llm "What are the best opportunities right now?"

Output: Returns AI-generated response with context from current Polymarket data.

7. Ask Superforecaster

Get superforecaster predictions for specific events and outcomes. Uses advanced prediction methodologies.

Command:

python -m scripts.python.cli ask-superforecaster <event_title> <market_question> <outcome>

Parameters:

• event_title (required): Title of the event
• market_question (required): The market question
• outcome (required): The outcome to predict

Examples:

# Get prediction for a specific outcome
python -m scripts.python.cli ask-superforecaster "2024 US Election" "Who will win?" "Candidate A"

# Get prediction fo