Skip to main content

1. Get an API key

Reach out at surface.surf to request access. You’ll receive a key in the format surf_....

2. Make a request

Pass your key in the X-API-Key header. You can look up any Kalshi ticker or Polymarket contract ID.
curl https://surface.surf/api/v1/match/KXMLBGAME-26MAR252005NYYSF-SF \
  -H "X-API-Key: YOUR_API_KEY"

3. Read the response

{
  "contracts": [
    {
      "id": "KXMLBGAME-26MAR252005NYYSF-SF",
      "parent_market_id": "KXMLBGAME-26MAR252005NYYSF",
      "exchange": "kalshi",
      "question": "New York Y vs San Francisco Winner?",
      "yes_name": "San Francisco",
      "no_name": "NO: San Francisco",
      "rules": "If San Francisco wins the New York Y vs San Francisco professional baseball game originally scheduled for Mar 25, 2026 at 8:05 PM EDT, then the market resolves to Yes.\n\nThe following market refers to the New York Y vs San Francisco professional baseball game originally scheduled for Mar 25, 2026 at 8:05 PM EDT. If this game is postponed or delayed, the market will remain open and close after the rescheduled game has finished (within two days). If the game is cancelled or rescheduled to over two days away, the market will resolve to a fair price in accordance with the rules."
    },
    {
      "id": "mlb-nyy-sf-2026-03-25",
      "parent_market_id": "mlb-nyy-sf-2026-03-25",
      "exchange": "polymarket",
      "question": "New York Yankees vs. San Francisco Giants",
      "yes_name": "New York Yankees",
      "no_name": "San Francisco Giants",
      "rules": "In the upcoming MLB game between the New York Yankees and San Francisco Giants, scheduled for March 25 at 8:05PM ET:\n\nThis market will resolve to \"New York Yankees\" if the New York Yankees win the game.\n\nThis market will resolve to \"San Francisco Giants\" if the San Francisco Giants win the game.\n\nIf the game is postponed, this market will remain open until the game has been completed. If the game is canceled entirely, with no make-up game, or ends in a tie, this market will resolve 50-50.\n\nThe primary resolution source for this market is the official final statistics of the event as recognized by the governing body or event organizers. However, if the governing body or event organizers have not published final match statistics within 24 hours after the event's conclusion, a consensus of credible reporting may be used instead."
    },
    {
      "id": "KXMLBGAME-26MAR252005NYYSF-NYY",
      "parent_market_id": "KXMLBGAME-26MAR252005NYYSF",
      "exchange": "kalshi",
      "question": "New York Y vs San Francisco Winner?",
      "yes_name": "New York Y",
      "no_name": "NO: New York Y",
      "rules": "If New York Y wins the New York Y vs San Francisco professional baseball game originally scheduled for Mar 25, 2026 at 8:05 PM EDT, then the market resolves to Yes.\n\nThe following market refers to the New York Y vs San Francisco professional baseball game originally scheduled for Mar 25, 2026 at 8:05 PM EDT. If this game is postponed or delayed, the market will remain open and close after the rescheduled game has finished (within two days). If the game is cancelled or rescheduled to over two days away, the market will resolve to a fair price in accordance with the rules."
    }
  ],
  "relationships": [
    { "from": "KXMLBGAME-26MAR252005NYYSF-SF", "to": "mlb-nyy-sf-2026-03-25", "is_inverse": false },
    { "from": "KXMLBGAME-26MAR252005NYYSF-NYY", "to": "mlb-nyy-sf-2026-03-25", "is_inverse": true }
  ]
}
contracts contains every contract in the cross-exchange group — all Kalshi contracts for the same event plus the Polymarket contract they map to. relationships describes the directed mapping from each Kalshi contract to the Polymarket contract, including whether the YES/NO sides are inverted. Surface validates team, date, and side alignment before accepting a match. If something doesn’t check out, it’s blocked — you won’t receive a partial or uncertain result.

It works in both directions

The response is identical regardless of which contract ID you query. Pass the Polymarket ID to get the same cluster:
curl https://surface.surf/api/v1/match/mlb-nyy-sf-2026-03-25 \
  -H "X-API-Key: YOUR_API_KEY"

Understanding is_inverse

Sports games on Kalshi have two contracts — one for each team. One maps directly to Polymarket (is_inverse: false) and the other is the inverse side (is_inverse: true). When is_inverse is true, YES on that Kalshi contract is equivalent to NO on the Polymarket contract. In this example, KXMLBGAME-26MAR252005NYYSF-NYY (Yankees YES) is inverse to the Polymarket contract where Yankees YES is also the direct side. Invert prices and sides accordingly.

Check your quota

Every response includes two headers:
HeaderValue
X-Match-Limit-RemainingNew unique clusters remaining today
X-Match-Limit-ResetNext reset (midnight UTC, RFC3339)
Repeat lookups of any contract within the same cluster are always free. See Introduction for full quota rules.