canonical: https://jentic.com/apis/kalshispy.com/kalshispy # KalshiSpy API The KalshiSpy API reports what a roster of ID-verified, high-profit Kalshi traders is doing and has gotten right. Its public settled-wins archive, open without a key, searches settled Kalshi markets where the roster held the winning side with positive net realized profit, by keyword, series ticker, event ticker, category, and date window. With an Elite or Lifetime API key it adds the live feed of open markets where two or more roster traders hold the same side, recent form by market and category, the traders' exposure and lifetime P&L, and trade search by series or trader. The archive is wins only, so results describe what the roster got right on comparable markets, not how often it is right. ## For AI agents Search KalshiSpy's public archive of settled Kalshi markets the verified trader roster won, and with an Elite or Lifetime key read live markets where the roster agrees, its recent form, exposure, and trades. ## Scope Does not place trades, hold funds, or report the roster's losses. Use for analytics on a verified Kalshi trader roster's settled wins, live positions, and trades only. ## Capabilities - Search settled Kalshi markets the roster won by q, category, series, event, and a from/to settlement window, sorted by recent, profit, or roster size - Read one archived win by Kalshi ticker with its outcome, consensus, each winning trader's realized profit, and hints.similar comparable wins - List categories that have archived wins and pull archive totals including net realized profit and a per-category breakdown - Find Kalshi markets by title or keywords with fuzzy series matching, adding open markets when an Elite or Lifetime key is sent - List open Kalshi markets where two or more roster traders hold the same side, filtered by category, series, side, and min_whales - Check the roster's recent form, streaks, and per-category win rates from past settled trades - Search recent trades by series ticker or trader nickname with a min_amount contracts filter ## Use cases ### Grounded Market Research Through Jentic An AI agent asked about a current Kalshi market first searches KalshiSpy's settled-wins archive with the same series or category and cites the comparable past wins, each with its Kalshi and kalshispy.com URLs. Through Jentic the agent discovers the public archive operations by intent and calls them without any key, and adds the live operations only if you store an Elite or Lifetime key. Example prompt: Search settled wins with series 'KXFED' and sort 'profit', read the top result by ticker, and summarise the roster's past wins on Fed rate markets with the wins-only caveat and the cited URLs ### Live Roster Consensus Watch A subscriber with an Elite or Lifetime plan wants to see where the verified traders agree right now. The agent lists open markets where two or more roster traders hold the same side, filters by category and consensus side, and sorts by whale_flow or closing_soon, then pairs each market with the roster's past wins in the same series. Example prompt: Get live markets with category 'economics', side 'YES', min_whales 3, and sort 'closing_soon', then call searchSettledWins for each market's series and report comparable wins ### Category Form Check Before acting on a market, a trader asks whether the roster has a record in that category. The agent reads the hot markets endpoint for per-category win rates and streaks rebuilt from past settled trades, and the public stats endpoint for archive totals by category. Example prompt: Get the roster's recent form, read the per-category win rate for 'sports', and compare it with the sports breakdown from the archive stats ### Series and Trader Trade Search An analyst tracks one Kalshi series or one named trader. The agent uses the search endpoint with mode title to find the series ticker, then mode series to list recent trades by named traders on it, or mode trader with a nickname, filtering out small trades with min_amount. Example prompt: Search with mode 'title' and q 'bitcoin' to find the series ticker, then search with mode 'series' and min_amount 500 to list recent large trades on it ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/api/v1/public/settled-wins` | Search settled markets the roster won | | GET | `/api/v1/public/settled-wins/{ticker}` | Get one settled win | | GET | `/api/v1/public/markets/search` | Find Kalshi markets by title | | GET | `/api/v1/markets/live` | List live markets with roster positions | | GET | `/api/v1/markets/hot` | Get the roster's recent form | | GET | `/api/v1/search` | Search series or trades | ## Key resources - **Settled wins** — Public archive of settled Kalshi markets the roster won, searchable and readable by ticker. - **Live markets** — Open Kalshi markets where two or more roster traders hold the same side (API key required). - **Roster traders** — The ID-verified traders behind the live feed with exposure, P&L, and form (API key required). - **Categories and stats** — Categories with archived wins and aggregate archive figures. ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 63 / 100 - **Maturity:** AI-Aware - **Dimensions:** - Foundational Compliance: 90 / 100 - Developer Experience & Jentic Compatibility: 63 / 100 - AI-Readiness & Agent Experience: 43 / 100 - Agent Usability: 94 / 100 - Security: 60 / 100 - AI Discoverability: 64 / 100 - **View full report:** https://jentic.com/apis/kalshispy.com/kalshispy/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Calling KalshiSpy by hand means knowing which operations are open and which need a ks_live_ bearer key, handling cursor paging on the archive, and chaining live markets back to settled wins by series. Through Jentic you install once, import the KalshiSpy API from the API Directory, store your Elite or Lifetime key once if you have one, and your agent calls it. - **Permission scoping:** KalshiSpy puts the Kalshi ticker in the URL path for single settled wins and single live markets (`/api/v1/markets/live/{ticker}`), while searches carry their filters as query parameters. Rules bound which operations your agent may call, so you can keep it on the public archive and leave the quota-using live operations out unless you add them. - **Credential handling:** Your KalshiSpy API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'past Kalshi wins on Fed markets' or 'where top Kalshi traders agree now', and Jentic returns the matching KalshiSpy operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Betfair Exchange Streaming API** — Betfair streams exchange market and order data for a betting exchange rather than analytics on Kalshi traders. - **The Odds API** — The Odds API gives sportsbook odds to compare against Kalshi sports markets the roster is on. - **Alpha Vantage** — Alpha Vantage supplies market and economic data for context on Kalshi economics and financials markets. ## FAQ ### What authentication does the KalshiSpy API use? Per its OpenAPI spec, the public archive endpoints need no credential: settled-wins search, a single settled win, categories, and stats. The live operations use bearer authentication with a personal API key in ks_live_ format from an Elite or Lifetime plan, and market search accepts the key optionally to add open markets. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at call time. ### Is there a KalshiSpy MCP server? You don't need an MCP server to give your agent the KalshiSpy API. Jentic connects it directly from the API Directory: import it, add your API key if you have an Elite or Lifetime plan, and your agent calls it, finding operations on demand instead of loading a server's tool definitions into its context. ### Can I limit what my agent is allowed to do with the KalshiSpy API? Yes. Write a rule that allows only the public settled-wins search and settled-win read, and a research agent can cite past wins without spending your plan's quota on live operations. Add the live markets operation when you want it to see current roster positions, and every call it makes is logged. ### Does the KalshiSpy API show how often the roster is right? No. Per the spec, the settled-wins archive is wins only: losses are not archived. Results answer what the roster got right on markets like this one, and every response includes meta.definition and meta.verification so your agent can state that caveat and point to checkable results on kalshi.com. ### Can my agent place trades on Kalshi through the KalshiSpy API? No. KalshiSpy is read-only analytics on the roster's positions and settled results. It returns Kalshi URLs for each market, but placing orders happens on Kalshi itself. ### What are the rate limits for the KalshiSpy API? The OpenAPI spec does not state a numeric rate limit. It notes that keyed market searches draw on your plan's quota, so check https://kalshispy.com/developers for current Elite and Lifetime allowances. ### How do I search past Kalshi wins with the KalshiSpy API through Jentic? Search Jentic for an intent like 'find settled Kalshi markets the top traders won', import the KalshiSpy API from the API Directory, and your agent calls GET `/api/v1/public/settled-wins` with a series such as KXFED or a category such as politics. It can then call GET `/api/v1/public/settled-wins/{ticker}` for the full record. To run it on your own infrastructure, install Jentic One from its GitHub repo.