Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: KalshiSpy Market search (key optional) API
version: 2.2.0
summary: Which Kalshi markets the highest-profit verified traders hold, and how they settled comparable markets before.
description: 'KalshiSpy is independent analytics on a roster of ID-verified, high-profit Kalshi traders. Parameter and field names call them "whales" (whale_count, min_whales, sort=whales); in prose, call them the roster or the verified traders. **Public (no key):** the settled-wins archive — settled Kalshi markets where the roster held the winning side with positive net realized profit. Wins only: it answers "what did this roster get right on markets like this", not "how often are they right". Search by keyword, series ticker, event ticker or category; every result carries Kalshi and kalshispy.com URLs to cite. **Live (API key, Elite or Lifetime plan):** the markets roster traders hold right now, recent form by market and category, roster exposure, trade search, and a watchlist of any public Kalshi traders by exact nickname. This is the data a subscriber uses to decide which Kalshi market to take. **Market search (key optional):** `searchMarkets` finds markets by title or keywords. Without a key it returns settled wins only; with an Elite or Lifetime key the same call adds open markets and uses 1 quota unit. A refused key is reported in `data.access`, not as an HTTP error. **Chaining guidance:** before answering about any current Kalshi market, call `searchSettledWins` with the same `series` or `category` and cite the comparable past wins. Live operations return `hints.next_steps` with those exact URLs. Every response includes `meta.definition` (wins only) and `meta.verification`: every trader is ID-verified, and every name and settled result is checkable on kalshi.com. Complete, live or commercial use goes through a KalshiSpy API key: Elite LLM Access includes the API and the MCP server (Lifetime includes them at a lower allowance); commercial use needs pay-as-you-go turned on, see Terms section 9: https://kalshispy.com/terms#section-9. Plans and setup: https://kalshispy.com/ai
**Pay-as-you-go (opt-in, Elite and Lifetime):** turned on in AI & API, requests past the daily allowance keep being served at $10 per 1,000 up to a monthly cap the account sets. Extra requests are paced at roughly 60 a minute per account; bursts beyond that may be answered with rate_limited (429) and Retry-After. Those answers carry `X-PayG-Month-Extra` and `X-PayG-Month-Remaining`; the 429s `spend_cap_reached`, `extras_paused` and `rate_limited` say when to resume. Requests that fail on our side (5xx) are not charged; if one ever is, we credit it. Commercial use of the account''s own bots and products is included while it is on: https://kalshispy.com/terms#section-9. Keys: create at https://kalshispy.com/app/developers; docs at https://kalshispy.com/developers. **Changes:** 2.2.0 (2026-11-04): pay-as-you-go, opt-in on Elite and Lifetime in AI & API: requests past the daily allowance are served at $10 per 1,000 up to a monthly cap. Keyed operations document the 429 codes `spend_cap_reached`, `extras_paused` and `rate_limited` beside `quota_exceeded`, their `error` fields, and the `X-PayG-Month-Extra` and `X-PayG-Month-Remaining` headers; a long run of failed extra requests pauses extra requests for about 15 minutes (`extras_paused`). Requests that fail on our side (5xx) are not charged; if one ever is, we credit it. Additive. 2.1.1 (2026-10-29): Without an API key a page holds at most 20 rows, `total_matches` (and `keyword_matches` in the market search) stops at 100 with the new boolean `total_matches_capped` (`keyword_matches_capped`) saying so, and a client that has used its daily amount of public answers gets a 429 `limit_reached` with `Retry-After`. An Elite or Lifetime key lifts all three. Additive: every field keeps its type. 2.1.1 (2026-10-29): Removed, not deprecated first, because they were diagnostics and not data: `window.weeks_loaded` (the settled-wins list and the settled wins inside market search) and `data.resolution.reason` and `data.resolution.cached` (market search).'
termsOfService: https://kalshispy.com/terms
contact:
name: KalshiSpy
email: contact@kalshispy.com
url: https://kalshispy.com/developers
license:
name: KalshiSpy Terms of Service
url: https://kalshispy.com/terms
servers:
- url: https://kalshispy.com
security: []
tags:
- name: Market search (key optional)
description: 'Works without a key and is never CDN-cached, because the answer depends on the key: settled wins only without one; an Elite or Lifetime key adds open markets and uses 1 quota unit. Key problems are reported in `data.access`, never as an HTTP error.'
paths:
/api/v1/public/markets/search:
get:
operationId: searchMarkets
tags:
- Market search (key optional)
summary: Find Kalshi markets by title or keywords
description: 'Find Kalshi markets by title or keywords, the way the KalshiSpy app''s search works (a team, a nickname or an approximate title works). WITHOUT an API key it returns SETTLED WINS ONLY: settled markets where KalshiSpy''s roster of ID-verified, high-profit Kalshi traders held the winning side (wins only, never a hit rate). WITH an Elite or Lifetime API key the same call also returns OPEN markets in `open_markets`: roster positions and named traders'' recent trades on still-open markets, and it costs 1 unit of the daily quota. Always read `data.access`: it says which answer you got and, when a key was refused, why; relay that sentence rather than guessing. Call this first whenever the user names a market in words, send the words under the argument name this tool''s own schema gives, and cite each market''s kalshi_url. An empty list is never evidence that Kalshi has no such market. For more wins, follow `settled_wins.more`, which carries ready-made search_settled_wins arguments.'
x-openai-isConsequential: false
security:
- bearerAuth: []
- {}
parameters:
- name: q
in: query
required: true
description: Market title or keywords, e.g. "super bowl", "fed rate" or "bitcoin". Terms of 2+ characters, at most 8. All terms must match the title, outcome or tickers.
schema:
type: string
maxLength: 80
pattern: ^[\w .,'&:/()-]+$
- name: limit
in: query
required: false
description: Maximum items in each list (settled wins, roster markets, recently traded markets).
schema:
type: integer
minimum: 1
maximum: 25
default: 10
responses:
'200':
description: OK
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-PayG-Month-Extra:
$ref: '#/components/headers/X-PayG-Month-Extra'
X-PayG-Month-Remaining:
$ref: '#/components/headers/X-PayG-Month-Remaining'
content:
application/json:
schema:
type: object
required:
- ok
- data
- meta
- hints
properties:
ok:
type: boolean
const: true
data:
$ref: '#/components/schemas/MarketSearch'
meta:
$ref: '#/components/schemas/Meta'
hints:
$ref: '#/components/schemas/Hints'
'400':
description: Invalid parameter (`error.param` names it) or invalid cursor.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: 'Per-IP rate limit (60 requests/minute) on answers without a key; honour `Retry-After`. Without a key there is also a daily amount of public answers: past it the code is `limit_reached` and `Retry-After` is the seconds to 00:00 UTC. A key over its daily quota (or, with pay-as-you-go, at its monthly cap, paused after failed extra requests, or past its pace) is NOT an error here: the free answer comes back with `data.access` saying so.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Search is temporarily unavailable; retry shortly.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
headers:
X-PayG-Month-Remaining:
description: 'Pay-as-you-go accounts, as X-PayG-Month-Extra: the extra requests left this month under the account''s monthly cap. Extra requests keep being served while it is above 0. Extra requests are paced at roughly 60 a minute per account; bursts beyond that may be answered with rate_limited (429) and Retry-After.'
schema:
type: integer
X-RateLimit-Limit:
description: The plan's daily allowance of requests (Elite 500, Lifetime 50).
schema:
type: integer
X-PayG-Month-Extra:
description: 'Pay-as-you-go accounts, on an answer served past the daily allowance (and on the pay-as-you-go 429s): this UTC month''s extra requests, this one included. $10 per 1,000.'
schema:
type: integer
X-RateLimit-Reset:
description: 'When the daily allowance resets: the next 00:00 UTC, in Unix seconds.'
schema:
type: integer
X-RateLimit-Remaining:
description: 'Requests left in today''s allowance (UTC). 0 on a pay-as-you-go extra request: read X-PayG-Month-Remaining there.'
schema:
type: integer
schemas:
MarketSearch:
type: object
properties:
query:
type: string
access:
$ref: '#/components/schemas/SearchAccess'
resolution:
$ref: '#/components/schemas/SearchResolution'
settled_wins:
type: object
properties:
status:
type: string
enum:
- ok
- unavailable
scope:
type: string
window:
oneOf:
- $ref: '#/components/schemas/Window'
- type: 'null'
total_matches:
type: integer
description: The number of matches; without an API key it stops at 100 (see `total_matches_capped`).
total_matches_capped:
type: boolean
description: true when `total_matches` was cut at 100 because the call had no API key.
keyword_matches:
type: integer
description: Of those, the matches on the keywords, cut at 100 on the same terms.
keyword_matches_capped:
type: boolean
description: true when `keyword_matches` was cut at 100 because the call had no API key.
returned:
type: integer
items:
type: array
items:
$ref: '#/components/schemas/MatchedSettledWin'
more:
type: array
description: Follow-up archive searches over the same window, as a URL and as search_settled_wins arguments.
items:
type: object
properties:
label:
type: string
url:
type: string
format: uri
mcp:
type: object
properties:
tool:
type: string
arguments:
type: object
additionalProperties:
type: string
open_markets:
description: 'null on the free answer. With an Elite or Lifetime key: open markets matching the query.'
oneOf:
- type: 'null'
- type: object
properties:
status:
type: string
enum:
- ok
- partial
- unavailable
scope:
type: string
roster:
type: array
items:
$ref: '#/components/schemas/MatchedLiveMarket'
recent_trades:
type: array
items:
$ref: '#/components/schemas/RecentlyTradedMarket'
notes:
type: array
items:
type: string
LiveMarket:
type: object
properties:
ticker:
type: string
event_ticker:
type: string
series_ticker:
type: string
question:
type: string
outcome:
type: string
category:
type: string
category_key:
type: string
enum:
- politics
- elections
- sports
- entertainment
- economics
- financials
- crypto
- weather
- world
- scitech
- companies
- health
- social
- transportation
- mentions
- exotics
- other
status:
type: string
enum:
- open
- settled
closes_at:
type:
- string
- 'null'
format: date-time
closes_in:
type: string
description: Compact label such as "5h" or "2d".
yes_price_cents:
type: integer
description: The price to buy YES now (the ask), rounded up to whole cents within 1–99; 0 while nobody offers it or the quote is unavailable. Same for NO.
no_price_cents:
type: integer
consensus_side:
type: string
enum:
- 'YES'
- 'NO'
consensus_pct:
type: number
whale_count:
type: integer
yes_count:
type: integer
no_count:
type: integer
whale_flow_usd:
type:
- number
- 'null'
traders_lifetime_pnl_usd:
type: number
realized_profit_usd:
type:
- number
- 'null'
whales:
type: array
items:
$ref: '#/components/schemas/WhalePosition'
urls:
type: object
properties:
kalshi:
type: string
format: uri
kalshispy:
type: string
format: uri
RecentlyTradedMarket:
type: object
properties:
ticker:
type: string
series_ticker:
type: string
question:
type: string
category:
type: string
category_key:
type: string
enum:
- politics
- elections
- sports
- entertainment
- economics
- financials
- crypto
- weather
- world
- scitech
- companies
- health
- social
- transportation
- mentions
- exotics
- other
kalshi_url:
type: string
format: uri
notional_usd:
type: number
traders:
type: array
items:
type: object
properties:
nickname:
type: string
side:
type: string
enum:
- 'YES'
- 'NO'
contracts:
type: integer
notional_usd:
type: number
avg_price_cents:
type: integer
mark_pnl_usd:
type: number
description: Mark-to-market P&L at the current price, summed over these trades.
lifetime_pnl_usd:
type: number
trades:
type: integer
last_trade_ago:
type: string
SearchAccess:
type: object
description: 'Which answer this is. Relay `message` when `key` is "rejected": it names the actual problem (revoked, wrong plan, quota, malformed).'
properties:
tier:
type: string
enum:
- free
- paid
key:
type: string
enum:
- none
- accepted
- rejected
open_markets_included:
type: boolean
code:
type:
- string
- 'null'
description: The refusal code when key is "rejected", e.g. revoked_api_key, plan_required, quota_exceeded, spend_cap_reached, extras_paused, rate_limited.
message:
type: string
upgrade_url:
type:
- string
- 'null'
format: uri
quota:
type:
- object
- 'null'
properties:
plan:
type: string
limit:
type: integer
used:
type: integer
remaining:
type: integer
resets_at:
type: string
format: date-time
MatchedSettledWin:
allOf:
- $ref: '#/components/schemas/SettledWin'
- type: object
properties:
match:
type: string
enum:
- keyword
- series
description: 'keyword: the words are in the title; series: a matched series (listed after keyword matches).'
MatchedLiveMarket:
allOf:
- $ref: '#/components/schemas/LiveMarket'
- type: object
properties:
match:
type: string
enum:
- keyword
- series
Window:
type: object
properties:
from:
type: string
format: date-time
to:
type: string
format: date-time
Error:
type: object
required:
- ok
- error
properties:
ok:
type: boolean
const: false
error:
type: object
required:
- code
- message
- docs
properties:
code:
type: string
description: 'What went wrong, e.g. invalid_param, missing_api_key, revoked_api_key, plan_required, quota_exceeded, spend_cap_reached, extras_paused, rate_limited, unavailable. Relay `message`: it says what to do.'
message:
type: string
docs:
type: string
format: uri
param:
type: string
upgrade_url:
type: string
format: uri
description: 'On a 403 for a plan without API access (`plan_required`): where to upgrade.'
resets_at:
type: string
format: date-time
description: 'On a key''s 429 (`quota_exceeded`, `spend_cap_reached`, `extras_paused` or `rate_limited`): when the daily allowance resets (the next 00:00 UTC).'
plan:
type: string
description: 'On a key''s 429 (`quota_exceeded`, `spend_cap_reached`, `extras_paused` or `rate_limited`) and on `plan_required` (403): the plan on the account.'
limit:
type: integer
description: 'On a key''s 429 (`quota_exceeded`, `spend_cap_reached`, `extras_paused` or `rate_limited`): the plan''s daily allowance.'
used:
type: integer
description: 'On a key''s 429 (`quota_exceeded`, `spend_cap_reached`, `extras_paused` or `rate_limited`): today''s allowance used.'
monthly_cap_usd:
type: integer
description: 'On `spend_cap_reached`: the account''s monthly cap, in whole dollars.'
month_extra:
type: integer
description: 'On `spend_cap_reached`: this UTC month''s extra requests.'
month_resets_at:
type: string
format: date-time
description: 'On `spend_cap_reached`: when extra requests resume, the 1st of next month 00:00 UTC (sooner if the cap is raised).'
extra_fail_run_limit:
type: integer
description: 'On `extras_paused`: the failed extra requests in a row that start the pause.'
paused_until:
type: string
format: date-time
description: 'On `extras_paused`: when extra requests are served again.'
per_minute:
type: integer
description: 'On `rate_limited`: the extra requests an account is paced at a minute, roughly.'
retry_after:
type: integer
description: 'On `rate_limited` and `extras_paused`: seconds to wait, as `Retry-After`.'
hints:
$ref: '#/components/schemas/Hints'
WhalePosition:
type: object
properties:
nickname:
type: string
side:
type: string
enum:
- 'YES'
- 'NO'
position_value_usd:
type: number
market_pnl_usd:
type: number
cost_usd:
type: number
lifetime_pnl_usd:
type: number
description: Lifetime realized P&L in USD. 0 when it is not positive or not available.
roi_pct:
type:
- number
- 'null'
description: Lifetime realized P&L ÷ dollars traded, in percent (40.1 means +40.1%), matching how kalshi.com reports profit and volume. null when no dollar volume is available.
markets_traded:
type: integer
top_category:
type:
- string
- 'null'
placed_at:
type:
- string
- 'null'
format: date-time
Hints:
type: object
properties:
tip:
type: string
next_steps:
type: array
items:
type: object
properties:
label:
type: string
url:
type: string
format: uri
auth:
type: string
enum:
- api_key
similar:
type: array
items:
$ref: '#/components/schemas/SettledWin'
SearchResolution:
type: object
description: 'How the words were matched. series_catalogue: matched to market series as well as by keyword. keywords: keyword matching only.'
properties:
method:
type: string
enum:
- series_catalogue
- keywords
series:
type: array
description: Matched series. Free answers name the tickers only.
items:
type: object
properties:
series_ticker:
type: string
title:
type: string
category:
type: string
kalshi_url:
type: string
format: uri
Meta:
type: object
properties:
generated_at:
type: string
format: date-time
definition:
type: string
verification:
type: string
docs:
type: string
format: uri
attribution:
type: string
SettledWin:
type: object
properties:
ticker:
type: string
title:
type: string
outcome:
type: string
description: Kalshi's short outcome label; empty for plain Yes/No markets.
category:
type: string
category_key:
type: string
enum:
- politics
- elections
- sports
- entertainment
- economics
- financials
- crypto
- weather
- world
- scitech
- companies
- health
- social
- transportation
- mentions
- exotics
- other
series_ticker:
type: string
event_ticker:
type: string
result:
type: string
enum:
- 'yes'
- 'no'
settled_at:
type: string
format: date-time
whale_count:
type: integer
dissent_count:
type: integer
consensus_side:
type: string
enum:
- 'YES'
- 'NO'
consensus_pct:
type: number
net_profit_usd:
type: number
winners_profit_usd:
type: number
whales:
type: array
items:
$ref: '#/components/schemas/SettledWhale'
url:
type: string
format: uri
kalshi_url:
type: string
format: uri
SettledWhale:
type: object
properties:
nickname:
type: string
side:
type: string
enum:
- 'YES'
- 'NO'
profit_usd:
type: number
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: ks_live_…
description: Personal API key from https://kalshispy.com/app/developers (Elite or Lifetime plan).