agents

The Problem

Traders seeking to automate Polymarket positions face fragmented integration points between AI agent frameworks and prediction market APIs, requiring custom implementation of order signing, market data parsing, and RAG pipeline construction for informed trading decisions.

What This Does

This repo provides a modular developer framework for building AI agents that trade on Polymarket. The agents/ directory contains twelve Python modules organized into three subsystems: application/ handles trade execution and cron-based scheduling (trade.py, executor.py, cron.py), connectors/ standardizes data sourcing with chroma.py for vector storage, news.py for news feeds, and search.py for web queries, while polymarket/ implements the Polymarket class for API interaction and gamma.py for the Gamma API subset. Data models reside in agents/utils/objects.py using Pydantic, and utility functions are in agents/utils/utils.py. The architecture explicitly separates concerns—connectors fetch and vectorize data, the Polymarket class handles order construction and signing, and application scripts orchestrate execution.

How To Use It

Setup: Clone the repository and install dependencies from requirements.txt using pip install -r requirements.txt. The README documents creating a .env from the example: cp .env.example .env, then setting POLYGONWALLETPRIVATEKEY and OPENAIAPIKEY. Load the wallet with USDC before trading.

Configuration: The .env.example file at the root requires POLYGONWALLETPRIVATEKEY and OPENAIAPIKEY. Additional configuration may be needed for connector-specific keys depending on chosen data sources.

Running it: The entry points are scripts/python/cli.py for the command-line interface and scripts/python/server.py for server mode. To trade directly, execute python agents/application/trade.py (ensure PYTHONPATH="." is set when running outside Docker). Docker workflows are documented in scripts/bash/ with build-docker.sh and run-docker-dev.sh.

Real-World Use

A developer building a sentiment-driven trading agent would import GammaMarketClient from agents/polymarket/gamma.py to fetch market metadata, initialize a Polymarket instance with their API keys, and use chroma.py to vectorize news articles from agents/connectors/news.py. Trades could be executed via the trade() method on the Polymarket class, with Pydantic models from agents/utils/objects.py validating order parameters before submission. This pattern separates data ingestion, market analysis, and execution into independently maintainable components.

Code Health & Issues

Low risk - Dependencies declared without a lockfile: requirements.txt lacks a corresponding requirements.lock or Pipfile.lock, creating non-reproducible build risk. Verify hashes before production deployment. Medium risk - Limited test coverage: only tests/test.py is present; no CI pipeline exercises the full agent workflow beyond dependency review. Low risk - Secrets in versioned examples: .env.example contains placeholder keys committed to the repo; while not actual secrets, this pattern should be documented as a "do not commit real keys" guideline. Low risk - No input validation layer documented: connector and API interaction files lack evident schema validation beyond Pydantic models, which may allow malformed data through RAG pipelines.

The repo has CI configured (GitHub Actions workflows present in .github/workflows/), a .pre-commit-config.yaml, and MIT licensing, but the single test file and absent lockfile are the most concrete hygiene gaps.

The Bottom Line

This is a functional, well-structured framework for Python-savvy traders who need to connect AI agents to Polymarket's API and data sources. It excels at modularity—connectors, API clients, and trade execution are cleanly separated—but the lack of a dependency lockfile and sparse test suite limit its readiness for production teams without additional CI/CD and pinning work. Ideal for solo developers or research prototypes; larger organizations should pin dependencies and expand test coverage before deployment.