iturri 0.2.0 → 0.2.2

package/README.md

@@ -0,0 +1,83 @@
+# 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.

package/index.mjs

@@ -3,13 +3,20 @@
 // Data and tooling only — never signals, predictions, or financial advice.
 
 export const BASE_URL = "https://iturri.ai";
+
+// membership token: setToken("...") or ITURRI_TOKEN env (node)
+export let token = (typeof process !== "undefined" && process.env?.ITURRI_TOKEN) || null;
+export const setToken = (t) => { token = t; };
+const authHeaders = () => (token ? { authorization: `Bearer ${token}` } : {});
 export const QUALITY = ["verified", "raw", "reconciled", "interpolated", "disputed", "outage"];
 
 async function get(path, params) {
   const url = new URL(BASE_URL + path);
   for (const [k, v] of Object.entries(params ?? {}))
     if (v !== undefined && v !== null) url.searchParams.set(k, v);
-  const r = await fetch(url);
+  const r = await fetch(url, { headers: authHeaders() });
+  if (r.status === 402)
+    throw new Error("402 payment required — setToken()/ITURRI_TOKEN with a membership token from https://iturri.ai/subscribe, or pay per-call with an x402 client");
   if (!r.ok) throw new Error(`iturri api ${r.status}: ${(await r.json()).error ?? r.statusText}`);
   return r.json();
 }
@@ -55,7 +62,7 @@ export const validate = (symbol, tf, o = {}) => get("/api/validate", { symbol, t
 /** Signed download URLs: pack "crypto"|"equities", or "tokens" with a symbol. */
 export async function bundle(pack, symbol) {
   const r = await fetch(BASE_URL + "/api/bundle", {
-    method: "POST", headers: { "content-type": "application/json" },
+    method: "POST", headers: { "content-type": "application/json", ...authHeaders() },
     body: JSON.stringify({ pack, symbol }),
   });
   if (!r.ok) throw new Error(`iturri api ${r.status}`);

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "iturri",
-  "version": "0.2.0",
-  "description": "Client + CLI for the Iturri verified market-data API — every bar verified or flagged",
+  "version": "0.2.2",
+  "description": "Client + CLI 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.",
+  "keywords": [
+    "trading",
+    "market-data",
+    "crypto",
+    "equities",
+    "ohlcv",
+    "backtesting",
+    "quant",
+    "trading-bot",
+    "mcp",
+    "ai-agent",
+    "verified-data",
+    "x402"
+  ],
+  "homepage": "https://iturri.ai",
+  "bugs": { "email": "dev@iturri.ai" },
+  "repository": { "type": "git", "url": "git+https://github.com/iturri-ai/iturri-js.git" },
+  "author": "Iturri <dev@iturri.ai> (https://iturri.ai)",
   "type": "module",
   "main": "index.mjs",
   "exports": "./index.mjs",