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 slug.

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": {
    "kalshi": {
      "KXMLBGAME-26MAR252005NYYSF-SF": {
        "parent_market_id": "KXMLBGAME-26MAR252005NYYSF",
        "question": "New York Y vs San Francisco Winner?",
        "yes_name": "San Francisco",
        "no_name": "NO: San Francisco",
        "is_closed": true
      },
      "KXMLBGAME-26MAR252005NYYSF-NYY": {
        "parent_market_id": "KXMLBGAME-26MAR252005NYYSF",
        "question": "New York Y vs San Francisco Winner?",
        "yes_name": "New York Y",
        "no_name": "NO: New York Y",
        "is_closed": true
      }
    },
    "polymarket": {
      "mlb-nyy-sf-2026-03-25": {
        "parent_market_id": "mlb-nyy-sf-2026-03-25",
        "question": "New York Yankees vs. San Francisco Giants",
        "yes_name": "New York Yankees",
        "no_name": "San Francisco Giants",
        "is_closed": true
      }
    }
  },
  "matches": {
    "kalshi": {
      "KXMLBGAME-26MAR252005NYYSF-SF": {
        "polymarket": {
          "mlb-nyy-sf-2026-03-25": { "is_inverse": false }
        }
      },
      "KXMLBGAME-26MAR252005NYYSF-NYY": {
        "polymarket": {
          "mlb-nyy-sf-2026-03-25": { "is_inverse": true }
        }
      }
    }
  }
}

contracts is keyed first by exchange, then by that exchange’s contract ID. matches follows the same exchange-and-contract keys to show linked contracts and whether their YES/NO sides are inverted. This structure supports clusters with multiple contracts per exchange and can accommodate additional exchanges. For a paginated list of clusters within one configured association, see List match clusters. Resolution rules are omitted by default. Add include_rules=true when you need the rules string for each contract. Use include_rules=false or omit the parameter for a smaller response. 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 authenticated response includes these headers:

Header	Value
`X-RateLimit-Limit`	60 authenticated requests per UTC minute
`X-RateLimit-Remaining`	Requests remaining in the current UTC minute
`X-RateLimit-Reset`	Next minute reset (RFC3339 UTC)
`X-Match-Limit`	25 new unique clusters per day
`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 against the daily quota, but still count toward the minute request limit. Unknown contracts are free against the daily quota, but still count toward the minute request limit. 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