Gnosis prediction-market-agent-tooling: The Unofficial Developer Guide

TL;DR: Gnosis prediction-market-agent-tooling (PMAT) is the most mature open-source framework for building autonomous prediction market agents — but its own docs say the trading API is “currently undocumented.” This guide is the first comprehensive reference. It covers the AgentMarket class, the DeployableTraderAgent pattern, platform support across Omen/Manifold/Polymarket/Metaculus, configuration, benchmarking, Safe wallet integration, and how to go from zero to a deployed agent.

What This Library Is (And Why Nobody Has Documented It)

Gnosis Labs has been building prediction market infrastructure since before Polymarket existed. Their Conditional Token Framework (CTF) literally powers Polymarket’s smart contracts under the hood. In the AI agent era, they built prediction-market-agent-tooling — a Python framework that abstracts away the differences between prediction market platforms and gives you a clean interface for building, testing, and deploying trading agents.

The library has 729+ commits, 49 GitHub stars, 108 open issues, active development as of March 2026, and it powers the autonomous agents running on Omen/Presagio (the Gnosis-native prediction market). Olas Predict’s Polystrat agent — the first consumer-level autonomous Polymarket trader — was built on top of this tooling.

And yet, the trading API is explicitly undocumented. The README links to a ReadTheDocs site. The PyPI page says to inspect the source code. This guide does that inspection for you.

For context on where this fits in the broader agent stack, see the Agent Betting Stack overview — PMAT spans Layer 3 (Trading) and Layer 4 (Intelligence).

Installation and Setup

PMAT uses Poetry for dependency management and requires Python 3.10+.

# Install via pip (for use as a library in your own project)
pip install prediction-market-agent-tooling

# Or clone and install for development
git clone https://github.com/gnosis/prediction-market-agent-tooling.git
cd prediction-market-agent-tooling
python3.10 -m pip install poetry
python3.10 -m poetry install
python3.10 -m poetry shell

Create a .env file with your credentials:

# Required for Omen trading (Gnosis Chain private key)
BET_FROM_PRIVATE_KEY=0x...

# Required for Manifold trading
MANIFOLD_API_KEY=...

# Required for LLM-powered agents
OPENAI_API_KEY=...

The BET_FROM_PRIVATE_KEY is a Gnosis Chain (formerly xDAI) private key. This is the key your agent uses to sign transactions on Omen. It needs to be funded with wxDAI (wrapped xDAI) for placing bets and xDAI for gas. This is analogous to the Polygon private key you’d use with py-clob-client for Polymarket — but on a different chain.

For wallet security patterns (session keys, spending limits, kill switches), see the Agent Wallet Security guide.

Architecture Overview

The library is organized around three core abstractions:

AgentMarket — The base class representing a prediction market on any platform. Provides a unified interface for reading market data, placing bets, selling positions, and checking balances. Platform-specific subclasses (OmenAgentMarket, ManifoldAgentMarket, etc.) implement the actual API calls.

DeployableTraderAgent — The base class for building your agent. You subclass it, implement one method (answer_binary_market), and the framework handles market scanning, bet execution, and deployment.

Benchmarker — A testing harness that runs your agent against historical markets and compares its predictions to actual outcomes and crowd consensus.

prediction_market_agent_tooling/
├── benchmark/              # Benchmarking framework
│   ├── agents.py           # AbstractBenchmarkedAgent, RandomAgent
│   └── benchmark.py        # Benchmarker class
├── config.py               # APIKeys configuration (reads .env)
├── deploy/
│   └── agent.py            # DeployableTraderAgent base class
├── markets/
│   ├── agent_market.py     # AgentMarket base class, SortBy enum
│   ├── market_type.py      # MarketType enum (OMEN, MANIFOLD, etc.)
│   ├── markets.py          # get_binary_markets() helper
│   ├── omen/
│   │   └── omen.py         # OmenAgentMarket (full read/write)
│   ├── manifold/
│   │   └── manifold.py     # ManifoldAgentMarket (full read/write)
│   ├── polymarket/
│   │   └── polymarket.py   # PolymarketAgentMarket (read-only)
│   └── metaculus/
│       └── metaculus.py     # MetaculusAgentMarket (read-only)
└── tools/                  # Utility functions, monitoring, etc.

Platform Support Matrix

This is the most important table in this guide. Not every platform gets the same level of support.

Omen is the primary target. This makes sense — Gnosis built both the CTF and Omen, and the prediction-market-agent repo that consumes this tooling runs its agents on Omen by default. Manifold gets full support because it uses play money (Mana), making it ideal for testing agent logic without financial risk.

Polymarket and Metaculus are read-only data sources. You can pull market questions, current probabilities, and metadata to inform your agent’s decisions, but you cannot execute trades through the PMAT abstraction. For Polymarket trading, you need to use py-clob-client or the Polymarket US SDK directly. For a comparison of all available trading APIs, see the Prediction Market API Reference.

The AgentMarket Class: Documented

AgentMarket is the abstract base class. Every platform-specific market type inherits from it. Here is what the interface provides, reconstructed from the source code.

Class Methods (Static — Call on the Class)

get_binary_markets(limit, sort_by) -> list[AgentMarket]

Fetches binary (YES/NO) markets from the platform. Returns a list of market objects.

from prediction_market_agent_tooling.markets.omen.omen import OmenAgentMarket
from prediction_market_agent_tooling.markets.agent_market import SortBy

# Get the 10 markets closing soonest
markets = OmenAgentMarket.get_binary_markets(
    limit=10,
    sort_by=SortBy.CLOSING_SOONEST
)

for m in markets:
    print(f"{m.question} — YES: {m.current_p_yes:.2f}, NO: {m.current_p_no:.2f}")

The SortBy enum controls ordering. Key values include CLOSING_SOONEST (most useful for agents targeting near-term markets), NEWEST, and platform-specific sorts.

get_positions(user_id) -> list

Returns open positions for a given user/wallet address.

from prediction_market_agent_tooling.config import APIKeys

my_positions = OmenAgentMarket.get_positions(
    user_id=APIKeys().bet_from_address
)

APIKeys() reads your .env file and derives the wallet address from BET_FROM_PRIVATE_KEY.

Instance Methods (Call on a Market Object)

place_bet(outcome, amount) -> None

Places a bet on the market. outcome=True means YES, outcome=False means NO. The amount is in the platform’s collateral currency (wxDAI for Omen, Mana for Manifold).

market = OmenAgentMarket.get_binary_markets(
    limit=1, sort_by=SortBy.CLOSING_SOONEST
)[0]

# Bet 0.1 wxDAI on YES
market.place_bet(outcome=True, amount=market.get_bet_amount(0.1))

sell_tokens(outcome, amount) -> None

Sells tokens (exits a position). On Omen, this interacts with the FPMM (Fixed Product Market Maker) to sell outcome tokens back into the pool.

# Sell YES tokens, accounting for fees
market.sell_tokens(outcome=True, amount=market.get_bet_amount(0.095))

The slight difference between buy amount (0.1) and sell amount (0.095) in the README example accounts for the AMM’s spread and fees.

get_bet_amount(amount) -> BetAmount

Converts a raw float into the platform-specific bet amount type. This handles unit conversion and validation.

Instance Properties

current_p_yes -> float — Current implied probability of YES (0.0 to 1.0).

current_p_no -> float — Current implied probability of NO (0.0 to 1.0).

question -> str — The human-readable market question.

These properties are what your agent logic reads to make decisions. For example, if your model predicts 80% YES but current_p_yes is 0.55, there is a potential edge.

The get_binary_markets Helper

For convenience, the library provides a top-level helper that selects the right platform class based on a MarketType enum:

from prediction_market_agent_tooling.markets.markets import get_binary_markets
from prediction_market_agent_tooling.markets.market_type import MarketType

# Fetch markets from any supported platform
omen_markets = get_binary_markets(limit=10, market_type=MarketType.OMEN)
manifold_markets = get_binary_markets(limit=10, market_type=MarketType.MANIFOLD)
polymarket_markets = get_binary_markets(limit=10, market_type=MarketType.POLYMARKET)

The MarketType enum includes: OMEN, MANIFOLD, POLYMARKET, METACULUS. Remember that Polymarket and Metaculus only return read-only market data.

Building Your First Agent: The DeployableTraderAgent Pattern

This is the core pattern. Every production agent in the Gnosis ecosystem follows it.

import random
from prediction_market_agent_tooling.deploy.agent import DeployableTraderAgent
from prediction_market_agent_tooling.markets.agent_market import AgentMarket


class DeployableCoinFlipAgent(DeployableTraderAgent):
    """Minimal example: bets randomly on every market."""

    def answer_binary_market(self, market: AgentMarket) -> bool | None:
        """
        Core method you must implement.
        
        Args:
            market: An AgentMarket instance with the question,
                    current probabilities, and trading methods.
        
        Returns:
            True  -> Bet YES on this market
            False -> Bet NO on this market
            None  -> Skip this market (don't bet)
        """
        return random.choice([True, False])

That is a complete agent. The framework handles everything else: scanning for open markets, filtering by criteria, executing the bet at the configured amount, and managing the wallet interaction.

A More Realistic Agent

Here is an agent that uses an LLM to make predictions, only bets when it disagrees with the market by more than 15 percentage points, and skips markets it is not confident about:

import os
from prediction_market_agent_tooling.deploy.agent import DeployableTraderAgent
from prediction_market_agent_tooling.markets.agent_market import AgentMarket


class LLMPredictionAgent(DeployableTraderAgent):
    """Agent that uses an LLM to evaluate market questions."""

    def __init__(self):
        super().__init__()
        # Initialize your LLM client (OpenAI, Claude, etc.)
        from openai import OpenAI
        self.llm = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

    def _get_llm_probability(self, question: str) -> float | None:
        """Ask the LLM to estimate probability of YES."""
        response = self.llm.chat.completions.create(
            model="gpt-4",
            messages=[{
                "role": "user",
                "content": (
                    f"Estimate the probability (0.0 to 1.0) that the answer "
                    f"to this question is YES: '{question}'\n\n"
                    f"Respond with ONLY a number between 0.0 and 1.0."
                )
            }],
            max_tokens=10,
        )
        try:
            return float(response.choices[0].message.content.strip())
        except (ValueError, IndexError):
            return None

    def answer_binary_market(self, market: AgentMarket) -> bool | None:
        # Get LLM's probability estimate
        llm_p_yes = self._get_llm_probability(market.question)
        if llm_p_yes is None:
            return None  # Skip if LLM fails

        # Only bet if we disagree with the market by > 15 percentage points
        market_p_yes = market.current_p_yes
        edge = llm_p_yes - market_p_yes

        if edge > 0.15:
            return True   # Bet YES — we think market underestimates
        elif edge < -0.15:
            return False  # Bet NO — we think market overestimates
        else:
            return None   # Skip — not enough edge

For more sophisticated intelligence layer patterns (multi-agent reasoning, Bayesian aggregation, sentiment analysis), see the Agent Intelligence Guide.

Running the Agent

The companion repo prediction-market-agent provides a CLI runner that accepts agent name and market type:

python prediction_market_agent/run_agent.py \
    --agent coinflip \
    --market-type omen

Available market types are omen, manifold, polymarket, and metaculus — but remember only omen and manifold support actual trade execution.

The prediction-market-agent repo includes over a dozen reference agent implementations: think_thoroughly (chain-of-thought reasoning), prophet_gpt4 (GPT-4 with calibration), microchain (function-calling agent with user guidance), olas_embedding_oa (embedding-based), social_media (sentiment-driven), and more. Each one follows the DeployableTraderAgent pattern.

Benchmarking: Test Before You Trade

PMAT includes a benchmarking framework that lets you test your agent’s prediction accuracy against historical market data before risking real money. This is the responsible path: paper trade → benchmark → testnet → small real money → scale.

import prediction_market_agent_tooling.benchmark.benchmark as bm
from prediction_market_agent_tooling.benchmark.agents import RandomAgent
from prediction_market_agent_tooling.markets.market_type import MarketType
from prediction_market_agent_tooling.markets.markets import get_binary_markets

# Fetch resolved markets for backtesting
benchmarker = bm.Benchmarker(
    markets=get_binary_markets(limit=50, market_type=MarketType.MANIFOLD),
    agents=[
        RandomAgent(agent_name="random_baseline"),
        # Add your custom agent here
    ],
)

benchmarker.run_agents()
report = benchmarker.generate_markdown_report()
print(report)

The benchmark report compares each agent’s predictions against actual outcomes and crowd consensus, producing accuracy metrics and calibration data. Manifold is ideal for benchmarking because it has abundant historical data and no financial risk.

To subclass the benchmarking agent, implement AbstractBenchmarkedAgent and its predict method — distinct from DeployableTraderAgent.answer_binary_market but conceptually similar.

Safe Wallet Integration

PMAT supports using a Gnosis Safe as your agent’s wallet. This adds multisig security — the agent proposes transactions, but one or more human approvers (or other agents) must co-sign before funds move. This maps directly to the Safe wallet pattern in the agent betting stack.

# Create a deterministic Safe for your agent
poetry run python scripts/create_safe_for_agent.py \
    --from-private-key $BET_FROM_PRIVATE_KEY \
    --salt-nonce 42

The salt-nonce parameter makes Safe creation deterministic. Using the same private key and nonce always produces the same Safe address. This is useful for infrastructure-as-code deployments (Terraform, etc.) where you need predictable addresses.

How PMAT Compares to Other Agent Frameworks

*Read-only access

PMAT is the strongest choice when you need multi-platform support, built-in benchmarking, or Safe wallet integration. Polymarket Agents is better for Polymarket-only bots that need built-in LLM tooling. For a comparison of unified trading APIs, see the Unified API Comparison.

Omen / Presagio: The Primary Target Platform

Since PMAT’s full trading support is Omen-centric, understanding the platform matters.

Omen (rebranded as Presagio in 2024) is a fully decentralized prediction market running on Gnosis Chain. It uses the Conditional Token Framework (CTF) — the same token standard Polymarket adopted — for representing outcome shares. Markets use a Fixed Product Market Maker (FPMM) rather than an order book, so bets interact with a liquidity pool rather than matching against other orders.

Key differences from Polymarket that affect your agent:

• AMM vs. CLOB: Omen uses an automated market maker. There is no order book. Your bet moves the price based on the bonding curve, not by matching a counterparty. Larger bets incur more slippage.
• Collateral: wxDAI (wrapped xDAI) instead of USDC. xDAI is pegged to the US dollar on Gnosis Chain.
• Resolution: Markets resolve via Kleros arbitration or Realitio oracle, not by Polymarket’s UMA Optimistic Oracle. Resolution can be slower and more contentious.
• Market creation: Anyone can create markets. The market-creator companion repo by Valory even automates this — an agent that reads news, generates market questions via LLM, and deploys them on-chain.
• Liquidity: Significantly lower than Polymarket. Most Omen markets have a few hundred to a few thousand dollars in liquidity. This limits position sizing but also means less competition from sophisticated bots.

For agents exploring the arbitrage angle between Omen and Polymarket (same events, different prices, different platforms), see the Cross-Market Arbitrage Guide.

Configuration: The APIKeys Class

The APIKeys class centralizes credential management. It reads from environment variables (or .env file via python-dotenv).

from prediction_market_agent_tooling.config import APIKeys

keys = APIKeys()

# Derived from BET_FROM_PRIVATE_KEY
keys.bet_from_address        # Your Gnosis Chain wallet address
keys.bet_from_private_key    # The raw private key

# Direct env var reads
keys.manifold_api_key        # MANIFOLD_API_KEY
keys.openai_api_key          # OPENAI_API_KEY

For production deployment, use proper secret management rather than .env files. See the Security Best Practices guide for key rotation, environment isolation, and monitoring patterns.

Limitations and Gotchas

Polymarket is read-only. This is the biggest limitation for builders focused on the largest prediction market. You can read Polymarket data through PMAT’s unified interface, but all trading must go through separate SDKs. Building an agent that reads from all four platforms but trades exclusively on Polymarket is a valid pattern — use PMAT for market discovery and benchmarking, then route execution through py-clob-client.

No Kalshi support. The MarketType enum does not include Kalshi. For agents that need CFTC-regulated market access, integrate the Kalshi API separately.

Omen liquidity is thin. Do not expect to deploy a $100K agent on Omen. Most markets support bet sizes in the single-digit to low-hundreds dollar range before slippage becomes punitive.

GCP deployment is deprecated. The README’s deploy_gcp() method is marked deprecated. Gnosis recommends running your own infrastructure. Docker, a simple VPS, or a Kubernetes pod works.

Version churn. The library is under active development with frequent breaking changes. Pin your dependency version in pyproject.toml and check the changelog before upgrading. The PyPI package has had dozens of releases, sometimes multiple per week.

Safe integration adds complexity. While Safe multisig is great for security, it means transactions require co-signing. For fully autonomous agents, you either need automated co-signers (another agent or a threshold signing service) or use the simpler EOA-only mode.

From Zero to Deployed Agent: Quick Path

1. Install: pip install prediction-market-agent-tooling
2. Configure: Create .env with BET_FROM_PRIVATE_KEY (Gnosis Chain) and MANIFOLD_API_KEY
3. Benchmark on Manifold: Test your prediction logic with play money. No financial risk.
4. Subclass DeployableTraderAgent: Implement answer_binary_market() with your strategy.
5. Run on Manifold: Validate with Mana. Check your win rate over 50+ markets.
6. Fund a Gnosis wallet: Send wxDAI to your agent’s address for Omen trading.
7. Deploy on Omen with small amounts: Start with 0.01–0.1 wxDAI per bet.
8. Monitor: Track your agent’s on-chain activity on the Gnosis Chain block explorer or the Dune dashboard linked in the prediction-market-agent repo.

What’s Next

PMAT is the foundation. To layer on intelligence capabilities, see the Agent Intelligence Guide for LLM analysis patterns, Bayesian reasoning, and multi-agent architectures. For the wallet and identity layers that complete the stack, see the Agent Wallet Comparison and Agent Identity Comparison.

For developers who want to see how production agents are actually built on this framework, clone the prediction-market-agent repo. The think_thoroughly_prophet and prophet_gpt4_kelly agents demonstrate real LLM-powered strategies with Kelly criterion sizing — much more sophisticated than the examples above.

Browse the AgentBets marketplace for agents built on PMAT and other frameworks, or list your own if you have built something worth sharing.