# TILLA — the aligned crypto + macro feature matrix (full reference)

> One pre-joined dataset: 1,817 columns × 1-minute rows, July 2023 → now, every field on a single timestamp. Built for quants, ML builders and AI agents. Sold as a REST API in six tiers (Free to Enterprise) and as an MCP server. Free tier, no card: https://tillacrypto.com

## What TILLA is

Most vendors sell one slice — price, or on-chain, or macro — and leave you to stitch them together and re-time them. TILLA does the join. Every source is resampled onto the same 1-minute grid so a single row is a complete, model-ready snapshot of the market. That alignment is the product.

The matrix (1,817 aligned columns) spans:
- Crypto majors — BTC/ETH/SOL/BNB and more: OHLCV, VWAP, RSI/EMA suites, returns at 5m/60m/1440m, volatility, candle structure.
- Derivatives & positioning — funding rates, open interest (native + USD), taker buy/sell, global & top-trader long/short, and CFTC COT (leveraged/dealer/asset-manager net).
- On-chain — MVRV, exchange in/outflows, hash rate, active addresses, mempool, miner revenue, supply, fees, and (Max only) BTC node microstructure: fee percentiles, UTXO flow, block structure, straight off our own node.
- Options & microstructure — order-book depth & imbalance (1%/5%), quote volume, trade counts, tick volume, ATM IV, max pain, put/call.
- ETF flows — spot BTC & ETH ETF flows fund-by-fund (IBIT, FBTC, GBTC, ARKB, BITB…) plus cumulative net.
- Altcoins & ratios — nine alt suites with BTC ratios and 20-day correlations.
- Equities & miners — mega-cap tech, BTC-treasury miners (MSTR, MARA, RIOT, CLSK, HUT8, COIN), sector/index ETFs.
- FX — 29 major & cross pairs with full technical suites.
- Macro & rates — indices & futures, VIX term structure (9d/1m/3m), DXY, yield curve (13w→5y→10y), Fed balance sheet, TGA/RRP, commodities, FOMC/BoJ calendar.
- Cross-asset flows & sentiment — house composites, Fear & Greed, attention (Wikipedia, GDELT).
- Calendar & session encodings — time-of-day/slot/minute/day-of-week — free at every tier.

Cadence: it is one 1-minute grid, but each source refreshes on its natural lane — most fields every minute, some derivatives on 5-minute, market structure on 30-minute, macro & rates hourly, slow macro (yields, Fed) daily.

## Who it's for

Quants and funds building signals; ML/AI engineers who want features, not a data-engineering project; and AI agents that need one endpoint to call for market data. If a model needs "everything that mattered at minute T," that's one TILLA row.

## Getting started

1. Get a free key at https://tillacrypto.com (free tier: 31 fields, 1-week history, no card).
2. Authenticate with `Authorization: Bearer tk_live_...`.
3. Call `GET /v1/schema` to list the exact columns your tier serves. Never guess column names.
4. Call `GET /v1/sync?since=1970-01-01` to pull your whole window, then keep passing back `next_since`.

Base URL: https://api.tillacrypto.com

## Endpoints

- `GET /v1/status` — (no key) live feed up/down, latest row timestamp, per-tier window_start/window_end/rows. Cached ~30s.
- `GET /v1/health` — (no key) feed freshness + tier alignment + open outages.
- `GET /v1/tiers` — (no key) `{tier: {history_days, per_minute, daily_quota}}`.
- `GET /v1/schema` — (key) the columns your tier serves + the lowest tier carrying each.
- `GET /v1/features` — (key) `{tier, count, window_start, window_end, columns}`.
- `GET /v1/latest?cols=` — (key) newest 1-minute row from the in-memory feed. `cols` optional comma list.
- `GET /v1/data?cols=&start=&end=&freq=1m&limit=1440&format=json` — (key) a date range. `freq` ∈ {1m,5m,15m,1h,4h,1d}. `limit` ≤ 5000 (≤2000 for coarse freq). Returns `next_start` cursor; `format=csv` for CSV.
- `GET /v1/sync?since=&cols=&limit=5000&format=json` — (key) every row after `since` (YYYY-MM-DD[ HH:MM[:SS]]). Returns `rows, next_since, complete, columns, data`. The incremental endpoint.
- `GET /v1/usage` — (key) tier, columns, calls today/total, per-minute + daily limits.

Errors: 401 missing/invalid key · 403 outside your tier (data your plan doesn't include) · 429 rate limit or daily quota (see `Retry-After`) · 400 bad parameter. Rate limits and daily quotas are per key, per tier.

## Example calls

Get the latest BTC close and Fear & Greed (any tier):
```
curl -H "Authorization: Bearer tk_live_..." \
  "https://api.tillacrypto.com/v1/latest?cols=btc_close,fear_greed"
```

Build a local copy from empty, paging forward:
```
curl -H "Authorization: Bearer tk_live_..." \
  "https://api.tillacrypto.com/v1/sync?since=1970-01-01"
# response includes next_since; call again with since=<next_since> until complete=true
```

Pull an hourly range as CSV:
```
curl -H "Authorization: Bearer tk_live_..." \
  "https://api.tillacrypto.com/v1/data?start=2026-01-01&end=2026-02-01&freq=1h&format=csv"
```

## Use it from an AI agent (MCP)

TILLA ships an official Model Context Protocol server, so an agent can query it directly. Add `tilla-mcp` to any MCP client (Claude Desktop, Claude Code, Cursor, ChatGPT connectors) with your key in `TILLA_API_KEY`. Tools: `tilla_about`, `tilla_status`, `tilla_tiers`, `tilla_schema`, `tilla_features`, `tilla_latest`, `tilla_history`, `tilla_sync`, `tilla_usage`. Repo: https://github.com/tillacrypto/tilla-mcp

## Plans

Tiers are cumulative — each includes everything below — and every field is scored on its single-feature predictive power vs next-day BTC/SPX/EUR-USD returns, so lower tiers get the most valuable fields first.

- Free — $0 · 31 fields · 1-week history · 10 req/min · 500/day. BTC/ETH/SOL/BNB + Fear & Greed, dominance, ETF flow, 10Y yield.
- Trader — $49/mo · 157 fields · 6 months+ · 60 req/min · 50k/day. BTC on-chain & mempool, funding & OI, FX majors, key US equities.
- Builder — $129/mo · 617 fields · 13 months+ · 120 req/min · 200k/day. Full technicals, macro & rates, per-fund ETF flows, cross-asset betas.
- Pro — $499/mo · 1,264 fields · 3 years+ (full) · unlimited requests. All 9 alt suites, long/short & OI, deep on-chain, house composites. Commercial-use license.
- Max — $1,299/mo · 1,817 fields · 3 years+ (full) · unlimited requests. Everything, incl. the crown-jewel BTC node microstructure (fee percentiles, UTXO flow, block structure) sold nowhere else.
- Enterprise — from $2,500/mo · all 1,817 fields · 3 years+ (full) · uncapped + priority. Everything in Max plus a redistribution & resale license, bulk Parquet/CSV historical delivery, multi-seat keys, an uptime SLA and dedicated support. Quoted per deal — contact support@tillacrypto.com.

Commercial use (embedding the data in a product/fund/paid service) requires an active Pro or Max plan. Resale or redistribution of the raw feed is not permitted on the self-serve tiers — it is available only under an Enterprise license. You keep every row you pull; the look-back sets where history starts and the feed never stops.

## Samples (no key needed)

Inspect the real data and the alignment before signing up — no key:
- One fully-aligned 1-minute row per tier (every column that tier includes), as JSON: https://tillacrypto.com/download/{free,trader,builder,pro,max}.json
- A full day of that tier as a SQLite database: https://tillacrypto.com/download/{free,trader,builder,pro,max}.db

`max.json` is a single timestamp carrying all 1,817 columns — the clearest demonstration that every source is joined onto one 1-minute clock. Via the MCP server, the `tilla_sample` tool returns the same aligned row for any tier without a key.

## Links

- Home: https://tillacrypto.com
- Docs: https://tillacrypto.com/#docs
- OpenAPI: https://api.tillacrypto.com/openapi.yaml
- MCP server: https://github.com/tillacrypto/tilla-mcp
- Support: support@tillacrypto.com