Metadata-Version: 2.5
Name: sardine-mcp
Version: 0.1.1
Summary: MCP server for Sardine: how often Kalshi crypto contracts settled YES, counted, not forecast.
Project-URL: Homepage, https://sardine.info
Project-URL: Method, https://sardine.info/how
Author: Jake O'Donnell
License-Expression: MIT
Keywords: bitcoin,data,kalshi,mcp,polymarket,prediction-markets
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<3,>=2.3
Requires-Dist: starlette>=0.40
Requires-Dist: uvicorn>=0.30
Provides-Extra: test
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# Sardine MCP server

Lets AI assistants (Claude, ChatGPT, Cursor, coding agents) look up how often
Kalshi crypto up/down contracts have **settled YES** in a given situation:
this far from the strike, with this much time left. The numbers come from
[sardine.info](https://sardine.info).

These are **counts of what happened before, not forecasts or advice**.
Kalshi's own price is usually the better predictor. Sardine publishes how
accurate its own numbers have been, and this server exposes that too.

## Tools

| Tool | What it answers |
|---|---|
| `list_markets` | Which series are covered (BTC/ETH, 15-minute and hourly) and how well calibrated each one is |
| `get_settlement_rate` | "BTC is $40 below the strike with 7 minutes left. How often has that settled YES?" Returns the rate, a 95% interval and the sample size, plus Kalshi's fee if you pass the ask |
| `get_live_board` | Contracts open right now, with Kalshi's price beside the historical count |
| `get_rate_table` | The full lookup table (distance × time left) for one series |
| `get_track_record` | What Sardine published versus what actually settled |
| `list_datasets` | Downloadable CSV history (opens in Excel) |
| `backtest_rule` | "Would this rule have made money?" Replays Sardine's per-second recordings of Kalshi's 15-minute contracts, with Kalshi's real fee, fills only up to the size on the book, a 2-second order delay, and official settlement. Returns results only: profit per contract with a 95% interval, a zero-delay comparison, stability, breakdowns and warnings |

There's also one resource, `sardine://method`, a plain-English description of
the method.

## Install

**Claude Code**

```bash
claude mcp add sardine -- uvx sardine-mcp
```

**Claude Desktop / Cursor** (`mcpServers` in the config file)

```json
{
  "mcpServers": {
    "sardine": { "command": "uvx", "args": ["sardine-mcp"] }
  }
}
```

**Remote (streamable HTTP)**

```bash
sardine-mcp --http --port 8000   # serves http://127.0.0.1:8000/mcp
# or point any streamable-HTTP client at https://sardine.info/mcp
```

Not on PyPI yet. Until it is, install from this folder:
`pip install -e .`, then run `sardine-mcp`.

With a free key (from https://sardine.info/signup) set as
`SARDINE_API_KEY`, limits are higher and we can tell you before anything
changes.

## REST API and Excel

The same data is served at `https://sardine.info/v1/...`. Add
`format=csv` to any endpoint for a file that opens in Excel. See
`https://sardine.info/developers` and `https://sardine.info/v1/openapi.json`.

## Running the public API yourself

`sardine-gateway` serves the REST API, the remote MCP endpoint, free keys
and usage metering. See `deploy/DEPLOY.md`.

## Data and credit

Market prices come from Kalshi. Statistics and files are by Sardine
(sardine.info). Please credit "Sardine (sardine.info)". No API key is needed
during the free preview.

<!-- MCP Registry ownership marker -->
mcp-name: info.sardine/sardine
