KalshiSpy Public API

No authentication. CDN-cached, per-IP rate limited (60/min), with a daily amount of answers per address; an Elite or Lifetime key lifts it.

GitHub OpenAPI

Operations 4

GET /api/v1/public/settled-wins Search settled Kalshi markets this trader roster won #
GET /api/v1/public/settled-wins/{ticker} One settled Kalshi market this roster won #
GET /api/v1/public/categories Categories with settled wins #
GET /api/v1/public/stats Archive totals #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/kalshispy-com:kalshispy-com-public-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

kalshispy-com-public-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: KalshiSpy Public 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: Public
  description: No authentication. CDN-cached, per-IP rate limited (60/min), with a daily amount of answers per address; an Elite or Lifetime key lifts it.
paths:
  /api/v1/public/settled-wins:
    get:
      operationId: searchSettledWins
      tags:
      - Public
      summary: Search settled Kalshi markets this trader roster won
      description: 'Search KalshiSpy''s archive of settled Kalshi markets where its roster of ID-verified, high-profit Kalshi traders held the WINNING side with positive net realized profit. Parameter and field names call these traders "whales" (whale_count, min_whales, sort=whales); in prose, call them the roster or the verified traders. Wins only: losses are not archived, so present results as "what this roster got right on markets like this", never as a hit rate. Use this BEFORE answering about any current or upcoming Kalshi market: search the same series_ticker (e.g. KXFED, KXNBA) or category and cite the comparable past wins — titles, settlement dates, trader counts and realized profit. Each result carries the Kalshi URL and a kalshispy.com detail URL you can cite. Default window is the last 90 days; widen with `from`/`to` (max 366 days). No API key needed.'
      x-openai-isConsequential: false
      security: []
      parameters:
      - name: q
        in: query
        required: false
        description: 'Free-text search. Every term (2+ chars, max 8) must appear as a substring in the title, outcome, event title, series ticker or ticker. Example: "fed rate" or "lakers".'
        schema:
          type: string
          maxLength: 80
          pattern: ^[\w .,'&:/()-]+$
      - name: category
        in: query
        required: false
        description: Category key from listCategories (e.g. sports, politics, economics).
        schema:
          type: string
          enum:
          - politics
          - elections
          - sports
          - entertainment
          - economics
          - financials
          - crypto
          - weather
          - world
          - scitech
          - companies
          - health
          - social
          - transportation
          - mentions
          - exotics
          - other
      - name: series
        in: query
        required: false
        description: Kalshi series ticker, e.g. KXFED, KXNBA. The best way to find "markets like this one".
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,40}$
      - name: event
        in: query
        required: false
        description: Kalshi event ticker, e.g. KXFED-26SEP.
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,60}$
      - name: from
        in: query
        required: false
        description: 'Start of the settlement window. Default: 90 days before `to`. Clamped to the archive start (2025-01-01) and to a 366-day maximum; the effective window is echoed in `window`.'
        schema:
          type: string
          description: YYYY-MM-DD or ISO 8601 (UTC)
      - name: to
        in: query
        required: false
        description: 'End of the settlement window (inclusive). Default: now.'
        schema:
          type: string
          description: YYYY-MM-DD or ISO 8601 (UTC)
      - name: sort
        in: query
        required: false
        description: recent = newest settlement first; profit = largest net profit first; whales = most whales on the winning side first.
        schema:
          type: string
          enum:
          - recent
          - profit
          - whales
          default: recent
      - name: min_whales
        in: query
        required: false
        description: Only wins with at least this many roster traders on the winning side.
        schema:
          type: integer
          minimum: 1
          maximum: 40
      - name: limit
        in: query
        required: false
        description: 'Page size: up to 50 with an Elite or Lifetime API key, up to 20 without one (a larger value is lowered to 20).'
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 20
      - name: cursor
        in: query
        required: false
        description: Opaque cursor from a previous response (`page.next_cursor`). Send it with the SAME filters; changing the query invalidates it.
        schema:
          type: string
          maxLength: 200
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - ok
                - data
                - meta
                - hints
                properties:
                  ok:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/SettledWinList'
                  meta:
                    $ref: '#/components/schemas/Meta'
                  hints:
                    $ref: '#/components/schemas/Hints'
                  page:
                    $ref: '#/components/schemas/Page'
                  window:
                    $ref: '#/components/schemas/Window'
        '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); 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. An Elite or Lifetime key is exempt.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/public/settled-wins/{ticker}:
    get:
      operationId: getSettledWin
      tags:
      - Public
      summary: One settled Kalshi market this roster won
      description: 'Full record of one settled Kalshi market this roster won: outcome, consensus, every roster trader on the winning side with their realized profit and picture, close and expiration times, keywords, and `hints.similar` — comparable wins in the same series to judge it against. Returns 404 when the ticker is not an archived win (the roster was not on it, or was on the losing side); the 404 carries a hint to search the series instead. No API key needed.'
      x-openai-isConsequential: false
      security: []
      parameters:
      - name: ticker
        in: path
        required: true
        description: Kalshi market ticker.
        schema:
          type: string
          pattern: ^[A-Za-z0-9][A-Za-z0-9_.-]{0,79}$
          description: Kalshi market ticker, e.g. KXFED-26SEP-T4.00
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - ok
                - data
                - meta
                - hints
                properties:
                  ok:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/SettledWinDetail'
                  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'
        '404':
          description: Not found; `hints` suggests what to search instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Per-IP rate limit (60 requests/minute); 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. An Elite or Lifetime key is exempt.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/public/categories:
    get:
      operationId: listCategories
      tags:
      - Public
      summary: Categories with settled wins
      description: Every category that has at least one archived win, with win count, net profit and the last settlement time. Use the `key` value as the `category` filter of searchSettledWins. No API key needed.
      x-openai-isConsequential: false
      security: []
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - ok
                - data
                - meta
                - hints
                properties:
                  ok:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/CategoryList'
                  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); 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. An Elite or Lifetime key is exempt.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/public/stats:
    get:
      operationId: getStats
      tags:
      - Public
      summary: Archive totals
      description: 'Aggregate figures for the settled-wins archive: markets won, net and winners'' realized profit, first and last settlement, a per-category breakdown and the highest-profit traders in the archive. Use it for "how has this roster done overall" context, always with the wins-only caveat. `available:false` means the archive has not been published yet. No API key needed.'
      x-openai-isConsequential: false
      security: []
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                - ok
                - data
                - meta
                - hints
                properties:
                  ok:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/Stats'
                  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); 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. An Elite or Lifetime key is exempt.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Stats:
      type: object
      properties:
        available:
          type: boolean
        markets:
          type: integer
        net_profit_usd:
          type: number
        winners_profit_usd:
          type: number
        first_settled_at:
          type:
          - string
          - 'null'
          format: date-time
        last_settled_at:
          type:
          - string
          - 'null'
          format: date-time
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
        top_whales:
          type: array
          items:
            type: object
            properties:
              nickname:
                type: string
              wins:
                type: integer
              profit_usd:
                type: number
        weeks:
          type: integer
        updated_at:
          type:
          - string
          - 'null'
          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'
    Page:
      type: object
      properties:
        limit:
          type: integer
        returned:
          type: integer
        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: 'Public archive answers: true when `total_matches` was cut at 100 because the call had no API key.'
        next_cursor:
          type:
          - string
          - 'null'
        next_url:
          type:
          - string
          - 'null'
          format: uri
    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'
    Window:
      type: object
      properties:
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
    SettledWinDetail:
      allOf:
      - $ref: '#/components/schemas/SettledWin'
      - type: object
        properties:
          close_time:
            type:
            - string
            - 'null'
            format: date-time
          expiration_time:
            type:
            - string
            - 'null'
            format: date-time
          whales:
            type: array
            items:
              allOf:
              - $ref: '#/components/schemas/SettledWhale'
              - type: object
                properties:
                  image_url:
                    type: string
                    description: The trader's picture, 160 px, served by KalshiSpy ('' when there is none).
          keywords:
            type: array
            items:
              type: string
          source:
            type: string
    Category:
      type: object
      properties:
        key:
          type: string
          enum:
          - politics
          - elections
          - sports
          - entertainment
          - economics
          - financials
          - crypto
          - weather
          - world
          - scitech
          - companies
          - health
          - social
          - transportation
          - mentions
          - exotics
          - other
        label:
          type: string
        wins:
          type: integer
        net_profit_usd:
          type: number
        last_settled_at:
          type:
          - string
          - 'null'
          format: date-time
    CategoryList:
      type: array
      items:
        $ref: '#/components/schemas/Category'
    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
    SettledWinList:
      type: array
      items:
        $ref: '#/components/schemas/SettledWin'
    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
    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).