> ## Documentation Index > Fetch the complete documentation index at: https://docs.surfaceapi.com/llms.txt > Use this file to discover all available pages before exploring further. # Quickstart > Make your first match request in under a minute. ## 1. Get an API key Create an account at [surfaceapi.com/portal](https://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](#understanding-contract-id). ```bash cURL theme={null} curl https://surfaceapi.com/api/v1/match/KXMLBGAME-26MAR252005NYYSF-SF \ -H "X-API-Key: YOUR_API_KEY" ``` ```python Python theme={null} import requests response = requests.get( "https://surfaceapi.com/api/v1/match/KXMLBGAME-26MAR252005NYYSF-SF", headers={"X-API-Key": "YOUR_API_KEY"}, ) print(response.json()) ``` ```javascript JavaScript theme={null} 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 ```json theme={null} { "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: ```bash theme={null} 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](/api-reference/introduction#rate-limits) for full quota rules.