Introduction

The Surface API gives you programmatic access to Surface’s cross-exchange matching system. Look up any Kalshi contract ticker or Polymarket contract ID and get the full cluster — every contract in the same cross-exchange group, their resolution rules, and the relationships between them. Every match passes through a multi-stage validation pipeline. Team, date, line, and side alignment are all checked before a result is accepted. If a candidate doesn’t clear the bar, it’s rejected rather than returned.

Base URL

https://surfaceapi.com/api/v1

Authentication

All requests require an API key in the X-API-Key header.

curl https://surfaceapi.com/api/v1/match/KXMLBGAME-26MAR252005NYYSF-SF \
  -H "X-API-Key: YOUR_API_KEY"

Create an account and generate a key at surfaceapi.com/portal.

Rate limits

The free tier allows 25 new unique cluster lookups per day. Repeat lookups are always free. Looking up any contract ID within a cluster you’ve already accessed never counts against your quota. 404s are also free. If no match is found for a contract, that request does not consume a quota slot. Quota resets at midnight UTC each day. Two response headers are present on every request:

Header	Description
`X-Match-Limit-Remaining`	New unique cluster lookups remaining today
`X-Match-Limit-Reset`	RFC3339 UTC timestamp of the next reset

Errors

All errors use the same envelope:

{
  "error": "unauthorized",
  "message": "Invalid or revoked API key."
}

On a 429, three additional fields are included:

{
  "error": "daily_limit_reached",
  "message": "Free tier limit of 25 new matches per day reached. Resets at midnight UTC.",
  "limit": 25,
  "used": 25,
  "resets_at": "2026-03-03T00:00:00Z"
}

Status	`error` code	When
`401`	`unauthorized`	Missing, invalid, or revoked API key
`404`	`no_match`	No match found — contract may not yet be in the dataset
`429`	`daily_limit_reached`	Free tier quota exhausted
`500`	`internal_error`	Unexpected server error

Overview

Endpoints

Base URL

Authentication

Rate limits

Errors

​Base URL

​Authentication

​Rate limits

​Errors

Base URL

Authentication

Rate limits

Errors