Building AI Agents for Polymarket and Kalshi: One Schema Across Prediction Markets

Polymarket agents and Kalshi agents tend to ship as two separate codebases. Your agent asked one question. Three venues answered. None of them used the same schema, the same units, or the same identifier for the same event. That is the actual shape of the problem when you sit down to build agents calling Polymarket, Kalshi, and on-chain options under one contract. The native APIs all work in isolation. Reconciling them is custom code per pair, and the cost compounds every time you add a venue.

This piece walks through what aggregation actually means at the API contract layer, what an agent really wants in the response, and where building it yourself stops being worth the bill.

The problem in one paragraph

The agent asks one logical question. The data layer talks to many venues. The reply is one envelope.

A user types something like "what are the odds the Fed cuts in June" into an agent. Polymarket has a market on it. Kalshi has a different contract on the same event. An on-chain options market on Lyra implies a third probability from put prices. Each venue has a clean API. Each returns different identifiers, different price units, different freshness behavior, and different resolution rules. Without a unification layer, the agent either picks one source and hides the disagreement, or makes three calls and reconciles in prompt context. Both are wrong.

What "aggregate prediction market data" means in practice

Aggregation is not "average the prices." It is unifying market identity across venues, normalizing units per field, attaching per-source freshness to every value, and exposing disagreement as a first-class signal so the agent can reason about it.

There are five dimensions you have to handle:

• Market identity. Which Kalshi contract equals which Polymarket market equals which Lyra option chain? Fuzzy match on title alone is not enough. You need title fuzz plus resolution-source plus close-date range to match the same logical event across venues.
• Price units. Polymarket prices in dollars (0.62). Kalshi prices in cents (62). On-chain options imply a probability from put price, strike, and time to expiry. Same logical value, three encodings. This is exactly the kind of data-labels-are-messy slip where the agent silently pulls the wrong field and the result looks like a hallucination.
• Liquidity and volume. Kalshi reports notional in USD contracts. Polymarket reports in USDC. Lyra reports option open interest in contracts. Aggregation math breaks without a currency and contract-unit conversion step.
• Settlement timing. Kalshi has an explicit expected_settlement_time field. Polymarket's Gamma API surfaces endDate but does not cleanly separate trading-close from final on-chain resolution. On-chain options settle on a fixed expiry timestamp. The agent that mixes these without normalization quotes the wrong horizon.
• Resolution source. Kalshi resolves through its own designated source. Polymarket resolves through UMA's optimistic oracle. On-chain options resolve from the underlying spot oracle. The agent answering "what determines the payout?" gets it wrong if your data layer does not pass this through.

Every one of these is a place where the agent picks plausibly but wrong if the labels are not unified.

The native APIs all work. They just do not agree.

Each venue's native API is fine. The schema mismatch is what eats your week.

Polymarket ships a GraphQL endpoint (Gamma for metadata, CLOB for the order book). Read-only access is open. You get nested JSON with the market object, its conditions, its outcomes, and a 24-hour volume snapshot.

Kalshi ships a REST API. Read access to the Kalshi API is open; trading is KYC-gated. The shape is flat and clean. Cents pricing, explicit settlement timestamps, designated-source resolution metadata.

Lyra and Aevo ship on-chain options as smart contracts on Ethereum L2s, with subgraph-style indexers on top for the read side. You read strike, expiry, and current put/call mid-prices, and you imply a probability from those. There is no "what are the odds on event X" endpoint; you compute it.

For more on Polymarket's specific contract shape, see Polymarket native API vs Dataline. For the perp-DEX adjacent case, see Hyperliquid API for AI agents.

The point is that none of the three native APIs has a concept of the other two. The aggregation work has to live somewhere outside them.

The response shape Polymarket agents actually want

The agent wants one envelope per logical question, with a sources[] array, per-source source_id and freshness_seconds, and a top-level divergence_flag the agent can branch on.

Here is the Dataline response for a real cross-venue query. The agent asks get("election odds: 2026 senate Ohio"). The reply:

{
  "answer": "Polymarket implies 58%. Kalshi implies 62%. Lyra-derived puts imply 60%. Sources disagree by 4 points; quote the range.",
  "logical_market_id": "dataline:event:senate-2026-OH",
  "sources": [
    {
      "source_id": "polymarket:market:0x...",
      "venue": "polymarket",
      "value": 0.58,
      "freshness_seconds": 12,
      "resolution_method": "uma_optimistic_oracle",
      "expected_settlement_ts": "2026-11-03T23:00:00Z"
    },
    {
      "source_id": "kalshi:market:ELECTION-2026-SEN-OH-D",
      "venue": "kalshi",
      "value": 0.62,
      "freshness_seconds": 6,
      "resolution_method": "kalshi_designated_source",
      "expected_settlement_ts": "2026-11-03T23:00:00Z"
    },
    {
      "source_id": "lyra:put-chain:0x...",
      "venue": "lyra",
      "value": 0.60,
      "freshness_seconds": 28,
      "resolution_method": "implied_from_options",
      "expected_settlement_ts": "2026-10-31T08:00:00Z"
    }
  ],
  "divergence_flag": "minor",
  "divergence_basis_points": 400,
  "median": 0.60,
  "range": [0.58, 0.62]
}

Three things to notice.

First, source_id is inline on every source. The agent's audit log writes itself; there is no second call to attach provenance after the fact.

Second, freshness_seconds is per-source. The Polymarket figure is 12 seconds old, Kalshi 6, Lyra 28. The agent can decide whether to trust the Lyra value as fresh enough for the question, or weight it down.

Third, divergence_flag is top-level. The agent does not have to compute the gap itself. If sources agree within a configured threshold, the field is null and the agent ships the median. If they disagree, the agent gets a labeled signal and can branch on it.

That is the entire contract. The shape is the differentiator.

Cross-venue divergence as an agent-grounding signal

When two venues price the same event differently, that disagreement is information. A single-source feed silently hides it. A unified schema with a divergence_flag makes the disagreement legible so the agent can decide what to do.

The rule we ship by default is simple. If the spread across sources is under three points, agreement is good enough and the agent quotes the median with a confidence boost. If the spread is three to ten points, the flag fires minor and the recommended behavior is to quote the range, not a single number. If the spread is over ten points, the flag fires major and the agent should surface the gap explicitly to the user, or refuse to commit.

This is the part that matters for grounding. A trading agent quoting a single price hides the model from a real signal. The cross-venue gap is often the most informative thing about a question. If Polymarket says 58 and Kalshi says 62 on the same Senate race, the four-point spread tells the agent that participation costs (KYC, geography, USDC vs USD) are creating real friction between the two pools. That is worth surfacing.

None of the on-chain data layers covers this case. Bitquery, Dune, Alchemy, QuickNode, and Goldsky are all RPC-shaped or indexer-shaped. None of them indexes Kalshi, because Kalshi is off-chain. None of them frames divergence as a signal, because their product is a feed of raw on-chain events. The aggregation across regulated and crypto-native venues is structurally outside their scope, and the framing of disagreement-as-evidence is open territory.

For an agent that must explain its answers, this is the contract that earns the right to quote a number with confidence.

What aggregation costs you if you build it yourself

The work is real and it never stops. Schema drift on either side breaks you. Settlement-window normalization is a rolling project. Geographic restrictions on Kalshi force fallback logic the day a user logs in from the wrong country.

A short list of what you actually maintain when you roll your own:

• One indexer per source. Polymarket's Gamma schema shifted twice in the last 18 months. Each migration was clean and each cost code.
• A normalization layer per field. Cents to dollars, USD-notional to USDC-notional, contract-units to implied-probability. The conversion rules are not hard, but they have to live somewhere, and they have to be tested.
• A market-matching framework. Title fuzz alone is not enough. You need resolution-source and close-date filters to avoid matching a 2026 Senate Ohio market on Polymarket to a 2024 Senate Ohio market on Kalshi.
• Divergence rules per question-class. Binary-yes-no markets, scalar prediction markets, and on-chain options each need a different divergence-threshold rule. Three-point gap means something different on a 50/50 race than on a 95/5 question.
• Fallback logic when a venue is offline or geo-blocked. Kalshi is US-only. Polymarket has its own geographic restrictions. The aggregator has to decide what to return when one source is unreachable.

This is real engineering. Most teams hit a wall at the second or third venue and start looking for the next layer up. The cross-over point usually shows up when an Alchemy or RPC bill creeps past two thousand a month, the team realizes the cross-venue normalization work is also non-trivial, and the question becomes whether to spin up a data-platform sub-team or buy the contract.

If you are interested in the unified schema as a hosted endpoint, the MCP server exposes it as a first-class tool for any MCP-aware host, and /pricing covers the free tier and usage curve.

When you should still call the native APIs directly

Three cases stay native: execution, single-venue agents, and tick streaming.

• Trading execution. Kalshi requires KYC and a funded account; Polymarket requires wallet signing; on-chain options need on-chain transactions. Writes stay native by design.
• Single-venue agents. If your agent only ever touches one venue, the aggregation contract buys you nothing. Call the native API, save the wrapper hop.
• Tick-by-tick streaming. Dataline is request-response shaped for agent calls. If your agent needs every CLOB tick, call Polymarket's websocket directly. If you need every options-chain quote update, subscribe to the venue's stream.

For everything else — the explanation path, the audit path, the cross-venue reasoning — the unified schema is the cheaper layer.

FAQ

What does it mean to aggregate prediction market data? It means returning one answer to one logical question across multiple venues, with per-source attribution and an explicit signal for when sources disagree. Averaging the prices is not aggregation. Unifying the schema is.

Can one API return odds from Polymarket and Kalshi together? Yes. Dataline's unified endpoint returns one envelope with a sources[] array containing both venues (and any on-chain options markets the question maps to). Each entry carries its own source_id and freshness_seconds, and a top-level divergence_flag fires when the venues disagree more than a configured threshold.

How does an agent handle two venues that disagree on the same event? The agent reads the divergence_flag and the spread. Under the default rule, the agent quotes the median when sources agree within three points, the range when they disagree by three to ten points, and surfaces the gap explicitly when the spread is wider. The contract makes the disagreement legible so the agent does not have to compute it.

Why do prediction markets disagree on the same question? Different participation costs. Kalshi is US-only, KYC-gated, USD-denominated, custodial. Polymarket is crypto-native, USDC-denominated, non-custodial in most jurisdictions. On-chain options imply a probability from put prices, which are sensitive to volatility assumptions. Friction between the venues is real and shows up in the spread.

Does aggregation cover on-chain options markets like Lyra and Aevo? Yes. On-chain options expose a put/call chain and an expiry. Dataline computes an implied probability from the put price, strike, and time to expiry, and returns it as another sources[] entry with the same shape as the Polymarket and Kalshi entries. The agent does not need to know which math produced the number, only that the source_id and freshness_seconds are inline.

How does Dataline normalize Polymarket's dollar prices with Kalshi's cent prices? Every value field in the response is normalized to a probability between 0 and 1. Polymarket's 0.62 stays at 0.62. Kalshi's 62 becomes 0.62. On-chain options compute to wherever the put-implied probability lands. The agent sees one unit across sources and never has to remember which venue uses which encoding.

What is a divergence flag in the response? A top-level field that fires when the spread between sources exceeds a configured threshold. The default classes are null (sources agree), minor (three to ten point spread), and major (over ten points). The agent branches on it. Cross-venue disagreement is a signal the agent should respond to, not a defect the API should hide.

Can I aggregate prediction markets without writing my own normalization layer? Yes. The MCP server and the REST endpoint both expose the unified schema as a hosted contract. The first-party normalization, market-matching, and divergence rules ship with the response. The agent calls one tool and gets the cross-venue answer back.

What to do next

If you are building an agent that touches more than one prediction-market venue, the contract above is the shortest path from "three working APIs" to "one auditable answer." Free tier covers exploratory work; production usage runs on a usage-based plan with public pricing.

The unified schema is also exposed as an MCP server for any MCP-aware host (Claude Desktop, Cline, Cursor agents). If you have been searching for a Kalshi MCP that also covers Polymarket and on-chain options, this is the one tool registration that covers all three venues, with divergence flags inline.