Prediction Market Agent using Convex (Skeleton)

This repository contains a skeleton implementation of a prediction‑market arbitrage agent built with Convex’s Agent and RAG components. It is meant to be an illustrative starting point rather than a complete production system.

The goal of the agent is to ingest market data from multiple prediction platforms (such as Polymarket, Kalshi and Jupiter), normalize that data into a unified schema, identify equivalent markets across venues using vector embeddings and RAG, compute potential arbitrage edges (taking into account fees, liquidity and settlement details) and then surface those edges to a human supervisor or automated execution layer.

Note: The Convex agent and RAG APIs evolve over time. This code reflects the capabilities described in Convex documentation and product updates as of 2026. You should consult the latest Convex docs for up‑to‑date APIs and adjust the code accordingly.

Repository Structure

prediction_market_agent/
├── README.md                  # This file
└── convex/
    ├── schema.ts             # Table definitions
    ├── agents/
    │   ├── predictionMarketAgent.ts   # Top‑level agent definition
    │   ├── tools.ts          # Tools exposed to the agent
    │   └── rag.ts            # RAG configuration
    ├── functions/
    │   ├── ingestor.ts       # Ingest raw market data from venues
    │   ├── normalizer.ts     # Normalize raw data into canonical form
    │   ├── matcher.ts        # Match equivalent markets across venues
    │   ├── pricing.ts        # Compute arbitrage edges
    │   └── supervisor.ts     # Escalate to humans for ambiguous cases
    └── workflows/
        └── edgeWorkflow.ts   # Durable workflow for ingestion → matching → pricing

How to Use This Skeleton

1. Install dependencies: You need a working Convex project. Follow the official Convex docs to initialise a new project and install the dependencies convex, @convex-dev/agent and @convex-dev/rag. You can then copy the contents of this convex folder into your project.

2. Define environment variables and credentials: The ingestor functions expect to connect to external venues. Fill in the configuration and authentication details (API keys, endpoints, credentials) in the venues table or via environment variables.

3. Implement the external API calls: The placeholder functions in functions/ingestor.ts and agents/tools.ts contain TODO comments where you should perform HTTP requests to fetch market data or orderbook information. Use Convex http actions or external fetch libraries depending on your environment.

4. Fine‑tune the matching logic: The matcher uses vector search on embedded market questions to find candidate equivalents. You may need to tune the similarity threshold and incorporate additional metadata (e.g. settlement date, underlying event) to avoid false positives.

5. Run the workflow: Schedule edgeWorkflow.run() on a periodic timer or trigger it manually to refresh the data and compute arbitrage edges.

This skeleton demonstrates how to compose Convex’s AI components into a complete arbitrage‑detection pipeline. It intentionally leaves many implementation details open so you can adapt it to your specific requirements.