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 token ID and get the matched contract on the other exchange, a confidence score, and direct links to both markets.

​
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/KXNBAGAME-26FEB28LACLAL-LAL \
  -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 contract lookups per day. Repeat lookups are always free. Looking up the same contractID again — with the same key — 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 matches 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 cross-exchange match found
429daily_limit_reachedFree tier quota exhausted
500internal_errorUnexpected server error