KalshiSpy Market search (key optional) API

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.

GitHub OpenAPI

Operations 1

GET /api/v1/public/markets/search Find Kalshi markets by title or keywords #

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-market-search-key-optional-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-market-search-key-optional-api-openapi.yml Raw ↑
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).