# matchwire

matchwire is a hosted mapping layer for sports prediction markets. It returns one row per
game, matched across Kalshi, Polymarket US, Polymarket International and Predict.fun, with
each venue's own market ID left intact. Mapping only: no prices or order books.

Two things are maintained for you and are the reason to use this instead of wiring the
venues yourself:

1. Alias lists. Every venue titles the same game its own way, and those titles change.
   matchwire keeps the aliases behind each game ID, so your code reads one ID and never
   owns a reconciliation job.
2. Market types. Winners, spreads and handicaps, totals and props are matched too, and
   the line is part of the match, so over 45.5 is never confused with over 48.5.

## Base URL and auth

https://api.matchwire.win — send header `x-api-key: <key>` on every call. JSON responses;
send `Accept-Encoding: gzip` for smaller ones. A key's plan sets which venues and sports it
may read.

## Endpoints

- GET /api/v1/rows — every game in your plan, one row per game.
- GET /api/v1/rows?since=SEQ — only games changed since SEQ, plus `tombstones`.
- GET /api/v1/push[?since=SEQ] — the same updates as a Server-Sent Events stream.
- GET /api/v1/sports — sport names with game counts (use these names in `sport=`).
- GET /api/v1/status — service and per-venue health.

## Filters (comma lists; they combine)

- sport=nfl,baseball — sport names from /api/v1/sports (baseball, not mlb).
- venue=kalshi,poly — venues: kalshi, poly (Polymarket US), polyintl (Polymarket
  International), predictfun.
- type=winner,total,handicap — also map_winner, score, event.
- league=MLB, status=scheduled|live|ended.

## How to integrate

1. Make one full call and save the top-level `seq`.
2. Then poll /api/v1/rows?since=SEQ and save each new `seq`. Changed games come back whole.
   Tombstones ({"id": "...", "deleted": true}) mean remove that game. Under a venue or type
   filter, a game that stops matching the filter also comes back as a tombstone.
3. Key your data on the row `id`. Keep venue market IDs beside it. Never match games by
   title yourself.
4. Each listing carries `request` ({method, url}): the exact call that venue answers for
   that market. Call it as-is to read the market from the venue. If it includes
   `auth: "x-api-key"`, send the user's own key for that venue (Predict.fun needs one).
5. Rows are mapping only. Read prices from the venue with `request`, never from matchwire.

## Row fields

id, sport, league, name, teams, start (UTC), status (scheduled|live|ended; ended games are
removed a day later), listings (the winner market per venue), markets (every matched bet
type: family, period, stat, line, subject, listings), notes (per-venue rule differences),
seq. Listing fields: venue, marketId, type, side, tier, confidence (0 to 1), request.
Unsure matches are held back for review, never served as a guess.

## Errors

401 missing or wrong key. 403 venue or sport outside the plan (the body lists what is
allowed). 429 too many requests this minute: wait `retryAfter` seconds. `truncated: true` means
more than 5,000 rows matched: add a filter.

## MCP and limits

- MCP server: POST https://api.matchwire.win/mcp, same `x-api-key` header, streamable HTTP.
  Read-only tools: list_sports, find_rows, get_row, get_venue_market, service_status. See /docs/mcp.
- Rate limits: 60 requests a minute per key. The /api/v1/push stream is not rate limited.
  Poll deltas, never the full set on a timer.

Do not invent endpoints, parameters or keys that are not in this file or in /docs/.

## Pages

/ /prediction-market-api /polymarket-api (Polymarket International and Polymarket US)
/kalshi-api /mapping /how-to-map-prediction-markets /pmxt-alternative /pmxt-vs-matchwire
/docs /docs/#key /docs/mcp /pricing

## Contact

support@matchwire.win (help, corrections, feed problems)
keys@matchwire.win (API keys, receipts, billing automation)
sales@matchwire.win (commercial license, partnerships)