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/BlackSky-Jose/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 .
   

   With BlockRun x402 support (recommended):

   pip install -e ".[blockrun]"
   

   Or with development dependencies:

   pip install -e ".[dev]"
   

   Using uv (faster):

   uv pip install -e ".[blockrun,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 USDC)
   POLYGON_WALLET_PRIVATE_KEY="your_private_key_here"
   
   # LLM API - Choose ONE option:
   
   # Option 1: BlockRun x402 pay-per-request (recommended)
   # No API key management, pay only for what you use via USDC on Base
   BLOCKRUN_WALLET_KEY="your_base_wallet_private_key_here"
   
   # Option 2: Direct OpenAI API
   OPENAI_API_KEY="your_openai_api_key_here"
   
   # Required for MongoDB (running history storage)
   MONGODB_URI="mongodb://localhost:27017/"
   MONGODB_DATABASE="polymarket_agent"
   
   # 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 private keys secure and never share them
   • BlockRun x402: Pay-per-request LLM access via micropayments on Base. Your private key never leaves your machine - only signatures are sent. Get USDC on Base to start. Learn more at blockrun.ai
   • MongoDB is used to store running history (CLI commands, trades, LLM queries, etc.)
   • If MongoDB is not available, the application will continue to work but history won't be saved
   • You can get a NewsAPI key from newsapi.org
   • You can get a Tavily key from tavily.com

6. Set up MongoDB (for running history)

   MongoDB is used to store all running history including:

   • CLI command executions
   • Trading operations
   • LLM queries and responses
   • Market queries
   • RAG operations
   • News queries
   • Market creation attempts

   Option A: Local MongoDB

   Install MongoDB locally:

   • Windows: Download from mongodb.com
   • macOS: brew install mongodb-community
   • Linux: sudo apt-get install mongodb or follow MongoDB installation guide

   Start MongoDB:

   # Windows
   mongod
   
   # macOS/Linux
   sudo systemctl start mongod
   # or
   mongod
   

   Option B: MongoDB Atlas (Cloud)

   For cloud-hosted MongoDB:

   1. Sign up at MongoDB Atlas
   2. Create a free cluster
   3. Get your connection string
   4. Update MONGODB_URI in your .env file:

      MONGODB_URI="mongodb+srv://username:password@cluster.mongodb.net/"
      

   Note: If MongoDB is not configured or unavailable, the application will continue to work normally, but running history will not be saved.

7. 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
• Descript