KalshiSpy · Schema

MarketSearch

CompanyAnalyticsFinancePrediction-MarketArtificial Intelligence

Properties

Name Type Description
query string
access object
resolution object
settled_wins object
open_markets object null on the free answer. With an Elite or Lifetime key: open markets matching the query.
View JSON Schema on GitHub

JSON Schema

kalshispy-com-market-search-schema.json Raw ↑
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/kalshispy-com/json-schema/kalshispy-com-market-search-schema.json",
  "title": "MarketSearch",
  "x-generated": "2026-11-13",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/kalshispy-com-openapi.json#/components/schemas/MarketSearch",
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "access": {
      "$ref": "#/$defs/SearchAccess"
    },
    "resolution": {
      "$ref": "#/$defs/SearchResolution"
    },
    "settled_wins": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "ok",
            "unavailable"
          ]
        },
        "scope": {
          "type": "string"
        },
        "window": {
          "oneOf": [
            {
              "$ref": "#/$defs/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": "#/$defs/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": "#/$defs/MatchedLiveMarket"
              }
            },
            "recent_trades": {
              "type": "array",
              "items": {
                "$ref": "#/$defs/RecentlyTradedMarket"
              }
            },
            "notes": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      ]
    }
  },
  "$defs": {
    "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": "#/$defs/WhalePosition"
          }
        },
        "urls": {
          "type": "object",
          "properties": {
            "kalshi": {
              "type": "string",
              "format": "uri"
            },
            "kalshispy": {
              "type": "string",
              "format": "uri"
            }
          }
        }
      }
    },
    "MatchedLiveMarket": {
      "allOf": [
        {
          "$ref": "#/$defs/LiveMarket"
        },
        {
          "type": "object",
          "properties": {
            "match": {
              "type": "string",
              "enum": [
                "keyword",
                "series"
              ]
            }
          }
        }
      ]
    },
    "MatchedSettledWin": {
      "allOf": [
        {
          "$ref": "#/$defs/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)."
            }
          }
        }
      ]
    },
    "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"
            }
          }
        }
      }
    },
    "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"
              }
            }
          }
        }
      }
    },
    "SettledWhale": {
      "type": "object",
      "properties": {
        "nickname": {
          "type": "string"
        },
        "side": {
          "type": "string",
          "enum": [
            "YES",
            "NO"
          ]
        },
        "profit_usd": {
          "type": "number"
        }
      }
    },
    "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": "#/$defs/SettledWhale"
          }
        },
        "url": {
          "type": "string",
          "format": "uri"
        },
        "kalshi_url": {
          "type": "string",
          "format": "uri"
        }
      }
    },
    "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"
        }
      }
    },
    "Window": {
      "type": "object",
      "properties": {
        "from": {
          "type": "string",
          "format": "date-time"
        },
        "to": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}

Work with this as data

Every JSON Schema 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 schemas

4 MCP tools reach this
  • find_json_schemasBrowse and filter every JSON Schema in the catalog.
  • 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 JSON Schema
curl "https://apis.io/api/v1/json-schemas/kalshispy-com-market-search"
All schemas
curl "https://apis.io/api/v1/json-schemas?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.