Skip to main content
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://surface.surf/api/v1

​
Authentication

All requests require an API key in the X-API-Key header. 
curl https://surface.surf/api/v1/match/KXMLBGAME-26MAR252005NYYSF-SF \
  -H "X-API-Key: YOUR_API_KEY"
To get a key, reach out at surface.surf.

​
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:
HeaderDescription
X-Match-Limit-RemainingNew unique cluster lookups remaining today
X-Match-Limit-ResetRFC3339 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"
}
Statuserror codeWhen
401unauthorizedMissing, invalid, or revoked API key
404no_matchNo match found — contract may not yet be in the dataset
429daily_limit_reachedFree tier quota exhausted
500internal_errorUnexpected server error