Metadata-Version: 2.4
Name: iturri
Version: 0.2.2
Summary: Client for the Iturri verified market-data API — quality-flagged candles, funding, open interest, order flow and ML-ready bundles for trading bots and AI agents. MCP + x402 native.
Author-email: Iturri <dev@iturri.ai>
License: MIT
Project-URL: Homepage, https://iturri.ai
Project-URL: Documentation, https://iturri.ai/#docs
Project-URL: Repository, https://github.com/iturri-ai/iturri-python
Project-URL: Changelog, https://iturri.ai/blog/
Keywords: trading,market-data,crypto,equities,ohlcv,backtesting,quant,trading-bot,mcp,ai-agent,verified-data,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == "pandas"

# iturri

Python client for the [Iturri](https://iturri.ai) verified market-data API —
historical market data for trading bots, backtests, and AI agents where
**every bar carries a quality flag** (`verified · raw · reconciled ·
interpolated · disputed · outage`) and every candle is traceable to a
checksummed primary source.

- 124M+ quality-flagged OHLCV bars: 34 crypto symbols (1m/5m/15m/1h/1d since
  2015) + 86 US stocks & ETFs (consolidated-tape EOD since 2016, as-traded
  and split-adjusted bases)
- Funding rates, open interest, taker order flow, curated events, market
  context (Fear & Greed, VIX, DXY…)
- Leakage-safe feature matrices, multi-timeframe aligned bundles, BSQ token
  sequences, training packs
- Agent-native: [11 MCP tools](https://iturri.ai/mcp) and
  [x402 micropayments](https://iturri.ai/blog/market-data-api-for-ai-agents)
  (USDC on Base) — no account, no API key

Zero hard dependencies. With pandas installed you get DataFrames; without
it, columnar dicts.

## Install

```sh
pip install iturri            # or: pip install "iturri[pandas]"
```

## Quickstart

```python
import iturri

iturri.catalog()                          # free discovery — symbols, ranges, pricing

iturri.token = "…"                        # membership token from iturri.ai/subscribe
                                          # (or: export ITURRI_TOKEN)

df = iturri.bars("BTC", "1h", start="2024-01-01", end="2024-02-01")
df = df[df.quality == "verified"]         # the whole point

feats = iturri.features("SPY", "1d_split", start="2026-06-01")
iturri.bundle("crypto")                   # signed training-pack URLs
```

Without a token, priced endpoints return HTTP 402 with an
[x402](https://iturri.ai/#docs) quote — payment-capable agents settle per
call ($0.001 per 1,000 candles) with no human in the loop.

## Full surface

`catalog` · `bars` · `features` · `funding` · `open_interest` · `orderflow` ·
`context` · `events` · `regime` · `validate` · `bundle` — mirroring the
11 MCP tools at `https://iturri.ai/mcp`.

`validate(symbol, tf, start=…, end=…)` returns a data-quality report
(coverage, gaps, flag distribution) so you can audit a range **before**
backtesting on it.

## For AI agents (MCP)

```json
{ "mcpServers": { "iturri": { "type": "http", "url": "https://iturri.ai/mcp" } } }
```

`describe_catalog` is free forever. See the
[MCP tutorial](https://iturri.ai/blog/connect-trading-data-to-claude-mcp).

## Links

Docs: https://iturri.ai/#docs · OpenAPI: https://iturri.ai/openapi.json ·
llms.txt: https://iturri.ai/llms.txt · JS SDK + CLI: `npm i iturri` ·
Sourcing & verification policy: https://iturri.ai/sourcing

---

Iturri sells **data and tooling only**. Nothing in any dataset, feature,
label, or tool is a trading signal, a prediction, or financial advice.
