# iturri

JavaScript client + CLI for the [Iturri](https://iturri.ai) verified
market-data API — historical market data for trading bots 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 dependencies, ESM, Node ≥ 18

## Install

```sh
npm i iturri
```

## Quickstart

```js
import { catalog, bars, features, setToken } from "iturri";

await catalog();                    // free discovery — symbols, ranges, pricing

setToken("…");                      // membership token from iturri.ai/subscribe
                                    // (or export ITURRI_TOKEN)

const rows = await bars("BTC", "1h", { start: "2024-01-01", end: "2024-02-01" });
const clean = rows.filter(r => r.quality === "verified");   // the whole point

const feats = await features("SPY", "1d_split", { start: "2026-06-01" });
```

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.

## CLI

```sh
npx iturri catalog
npx iturri bars BTC 1h --start 2024-01-01 --end 2024-02-01
npx iturri features SPY 1d_split --start 2026-06-01
npx iturri bundle crypto            # signed training-pack URLs
```

## Full surface

`catalog` · `bars` · `features` · `funding` · `openInterest` · `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 · Python SDK: `pip install 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.