Quickstart

1. Get an API key

Create an account at surfaceapi.com/portal. Sign in via magic link and generate your API key in the developer portal.

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://surfaceapi.com/api/v1/match/KXMLBGAME-26MAR252005NYYSF-SF \
  -H "X-API-Key: YOUR_API_KEY"

import requests

response = requests.get(
    "https://surfaceapi.com/api/v1/match/KXMLBGAME-26MAR252005NYYSF-SF",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(response.json())

const response = await fetch(
  "https://surfaceapi.com/api/v1/match/KXMLBGAME-26MAR252005NYYSF-SF",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await response.json();
console.log(data);

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://surfaceapi.com/api/v1/match/mlb-nyy-sf-2026-03-25 \
  -H "X-API-Key: YOUR_API_KEY"

Understanding contract ID

The contractID parameter refers to the exchange’s own identifier for a contract. Each exchange uses a different format:

Kalshi — use the market ticker (e.g., KXMLBGAME-26MAR252005NYYSF-SF). You can find this in Kalshi’s GET /markets response under the ticker field. Do not use the event_ticker or series_ticker.
Polymarket — use the market slug (e.g., mlb-nyy-sf-2026-03-25). You can find this in Polymarket’s GET /markets response under the slug field. Do not use the CLOB token IDs, condition ID, or event slug.

The Surface API accepts either format. Query with a Kalshi ticker or Polymarket slug — the response is the same either way.

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:

Header	Value
`X-Match-Limit-Remaining`	New unique clusters remaining today
`X-Match-Limit-Reset`	Next reset (midnight UTC, RFC3339)

Repeat lookups of any contract within the same cluster are always free. See Introduction for full quota rules.

Overview

Endpoints

1. Get an API key

2. Make a request

3. Read the response

It works in both directions

Understanding contract ID

Understanding `is_inverse`

Check your quota

​1. Get an API key

​2. Make a request

​3. Read the response

​It works in both directions

​Understanding contract ID

​Understanding is_inverse

​Check your quota

1. Get an API key

2. Make a request

3. Read the response

It works in both directions

Understanding contract ID

Understanding `is_inverse`

Check your quota