Metadata-Version: 2.4
Name: finzdata-kimi
Version: 0.1.3
Summary: FinzData for Kimi: point-in-time market data, macro and backtests through function calling and MCP.
Author-email: FinzData <info@finzdata.com>
License: MIT
Project-URL: Homepage, https://finzdata.com/agents
Project-URL: Documentation, https://finzdata.com/docs
Project-URL: Source, https://github.com/FinzData/finzdata-kimi
Keywords: kimi,kimi-k3,moonshot,kimi-cli,finzdata,mcp,market-data,function-calling,backtesting,ai-agents
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certifi
Dynamic: license-file

<p align="center"><a href="https://finzdata.com"><img src="https://finzdata.com/assets/brand/finzdata-logo-full.png" alt="FinzData" width="360"></a></p>

# FinzData for Kimi

Built for AI, quants, data scientists and financial analysts who backtest. Clean data. Real insights. Real alpha.

FinzData gives Kimi point-in-time market data, macro vintages and server-side backtests through function calling and MCP —
so the model answers market questions with real numbers it can cite, never guesses.

## No API key needed

FinzData works the moment you install it: no FinzData account and no FinzData key. Your model gets the free AI preview
(the last 6 months of data) automatically, and it knows to tell you when older or deeper data needs a key.
When you want more, get a free API key (email only, 12 months of data) at https://finzdata.com/account, or full
history at https://finzdata.com/shop, then set `FINZDATA_API_KEY`. Nothing else changes.

## Install

```bash
pip install finzdata-kimi
```

## Quick start

```python
from finzdata_kimi import ask
print(ask("How did managed money positioning in crude oil change over the last 3 months?"))   # no FinzData key needed
```

## What to ask

- "How are speculators positioned in crude oil futures by the latest COT report?"
- "Show SPY's dealer gamma, call wall and put wall for the last 30 sessions."
- "What did the first-published CPI print say last month, before revisions?"
- "Backtest a 12-month momentum strategy on US stocks, delisted names included."
- "How many ships transited the Strait of Hormuz each day last month?"
- "Who are the largest 13F holders of NVDA, and who added the most last quarter?"

## Free strategies

Every strategy on the [FinzData strategies page](https://data.finzdata.com/strategies) re-runs free on its full
history (since 2000, delisted stocks included), on FinzData's servers, with no API key: ask the model to list the
strategies and re-run one. Changing a strategy or testing your own idea over full history needs a purchase.

## FinzData Workspace on Cloudflare

For an agent that keeps files and runs code next to the data between sessions, add the FinzData Workspace MCP server
`https://workspace.finzdata.com/mcp` with a free FinzData key (email only, https://finzdata.com/account). Its
`strategy_run` tool saves a strategy's spec and results into the workspace for analysis.

## Command line

```bash
finzdata-kimi "How did managed money positioning in crude oil change over the last 3 months?"
finzdata-kimi --show-tools
```

## Moonshot API

Set `MOONSHOT_API_KEY` and ask. The default model is `kimi-k3`, which always thinks before it answers; FinzData passes its reasoning back unchanged between tool calls, as Kimi requires. Override with `model=` or `FINZDATA_KIMI_MODEL`.
Mainland China accounts: set `FINZDATA_KIMI_REGION=cn` to use `https://api.moonshot.cn/v1`.

## Kimi CLI and Kimi Code

One command adds FinzData to the Kimi CLI's MCP config (`~/.kimi/mcp.json`), keeping every server already there:

```bash
finzdata-kimi --install-cli-config
```

Or add it by hand:

```json
{
  "mcpServers": {
    "finzdata": {
      "url": "https://api.finzdata.com/mcp",
      "type": "streamable-http",
      "transport": "http"
    }
  }
}
```

Any agent that accepts an MCP server URL can use `https://api.finzdata.com/mcp` the same way.

## Kimi open weights

The Kimi models on Hugging Face (`moonshotai/Kimi-K3` and family) work through `pip install finzdata-huggingface` (Inference Providers) or any
OpenAI-compatible server you host (vLLM with tool calling enabled and the Kimi tool-call parser) using `ask(..., base_url="http://localhost:8000/v1")`.

## Use with any OpenAI-compatible server

```python
from finzdata_kimi import openai_tools, FinzDataMCP
tools = openai_tools()          # pass as `tools=` to any chat.completions call
result = FinzDataMCP().call("get_cot", {"market": "crude"})   # run the tool the model picked
```

## Tool profiles

`lite` (6 core tools, for small models), `data` (23 data, backtest and strategy tools, the default) and `full` (every read tool).
Tools that change data on FinzData are never exposed unless you ask for them explicitly.

## Coverage

16,000+ US stocks that have traded on NYSE and Nasdaq since January 2000, delisted included, point in time; 5,100+ ETFs; 139 futures markets with every contract since 2007; point-in-time options gamma (GEX) for single stocks, ETFs and the major indexes; CFTC COT since 1986; 13F holdings; SEC fundamentals as filed; end-of-day options chains; 22,700+ macro series with every vintage kept; 512 crypto pairs (Bitcoin since 2013); FX for 79 currency pairs; 123 indexes incl. the VIX term structure; tick trades for 1,100+ US stocks and ETFs; FinzData Global Macro Pulse (ship transits through 28 chokepoints, port calls, flights, toll traffic); 1, 5, 15, 30-minute, hourly and daily bars; server-side backtests.

## Access

No key needed to start: AI/MCP use gives the last 6 months. A free account (email only, https://finzdata.com/account) gives the last 12 months of daily US stock bars, COT, SEC fundamentals, US macro and 13F, and the last 30 days of futures and daily GEX. Full history: https://finzdata.com/shop — $19 one ticker, $49 one futures market, $195 for 5 years of the whole US market.

With a key:

```bash
export FINZDATA_API_KEY=fz_...   # free at https://finzdata.com/account
```

or pass `finzdata_api_key="fz_..."` to `ask`.

## Links

- Site: https://finzdata.com
- Docs: https://finzdata.com/docs
- MCP server: https://api.finzdata.com/mcp
- Python client: `pip install finzdata`
- Contact: the FinzData team, info@finzdata.com
