Introduction

The Surface API gives you programmatic access to Surface’s cross-exchange matching system. Look up one Kalshi contract ticker or Polymarket contract slug, or list clusters within one configured series/tag association. Responses group contract details and match links by exchange and contract ID. Add include_rules=true when you also need resolution rules. 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 60 authenticated requests per minute. This is enforced in fixed UTC minute windows. Every authenticated request counts toward this limit, including repeated lookups and unknown contracts. 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 against the daily quota. If no match is found for a contract, that request does not consume a daily quota slot, but it still counts toward the minute request limit. The daily quota resets at midnight UTC each day. These response headers are present on every authenticated request:

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

The request-rate headers are also present on every authenticated response:

Header	Description
`X-RateLimit-Limit`	Requests allowed in the current UTC minute
`X-RateLimit-Remaining`	Requests remaining in the current UTC minute
`X-RateLimit-Reset`	RFC3339 UTC timestamp of the next minute window

Errors

All errors use the same envelope:

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

On a 429, three additional fields are included. The Retry-After header gives the number of seconds to wait.

{
  "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`	`rate_limit_reached`	60 authenticated requests used in the current UTC minute
`429`	`daily_limit_reached`	25 new unique cluster lookups used today
`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