# Leeway — Full API / MCP Reference for LLMs

## Overview

Leeway is the KI-Analyst for stocks (Business-Rating, Market-Fit-Rating, Cycle-Rating, Leeway-Score) and a financial data API with MCP support.
Data is served as JSON via REST. The MCP server exposes one catalogue of 24 tools; several REST routes share a tool and are selected with view or topic. Logo images stay on the HTTP API. Product: https://leeway.tech/ — methodology: https://leeway.tech/hilfe

- Website: https://leeway.tech/data-api
- MCP onboarding: https://leeway.tech/mcp
- MCP setup: https://leeway.tech/mcp/setup
- Context API: https://leeway.tech/ki-kontext
- Shared cache: https://leeway.tech/ki-teilen
- REST base: https://api.leeway.tech/api/v1/public
- OpenAPI 3.0: https://api.leeway.tech/openapi.json
- MCP endpoint: https://mcp.leeway.tech/mcp
- MCP health: https://mcp.leeway.tech/health

## Authentication

### REST API
- Query parameter: `?apitoken=YOUR_TOKEN`
- Sample data: `SAP.XETRA` endpoints work without token on some routes

### MCP
- HTTP: `Authorization: Bearer YOUR_TOKEN` on every MCP request
- stdio bridge (Claude Desktop, via `npx mcp-remote`): same `Authorization: Bearer YOUR_TOKEN`, passed as `--header`
- Token source: https://leeway.tech/account (free signup, 50 units/day)

## Rate Limits

- Burst: 1 request per 250ms per token/IP
- Daily units: free 50/day, paid 100,000/day
- HTTP 429 when exceeded
- Check remaining: tool `general_account` with `view=requests_left`
- AI wallet: tool `general_account` with `view=credits`

## MCP Tools (24 tools)

A tool calls one REST route. Where a tool lists several views, pass `view` (or `family` / `topic`) and only the parameters that view accepts.

### General
| Tool | Call | REST path |
|------|------|-----------|
| general_isin | isin | GET /general/isin/{isin} |
| general_mainstock | isin | GET /general/mainstock/{isin} |
| general_directory | view=exchanges | GET /general/exchanges |
| general_directory | view=symbols, exchange | GET /general/symbols/{exchange} |
| general_screener | filters, signals, or preset | GET /general/screener |
| general_tradingperiod | symbolExchange | GET /general/tradingperiod/{symbolExchange} |
| general_account | view=credits | GET /general/credits |
| general_account | view=requests_left | GET /general/dailyrequestsleft |

### Prices and fundamentals
| Tool | Call | REST path |
|------|------|-----------|
| prices | view=eod, symbolExchange | GET /historicalquotes/{symbolExchange} |
| prices | view=live, symbolExchange | GET /live/{symbolExchange} |
| prices | view=intraday, symbolExchange, interval | GET /intraday/{symbolExchange} |
| prices_relative_move | symbolExchange | GET /live/relative-move/{symbolExchange} |
| market_cap | view=history, symbolExchange | GET /historicalquotes/marketcap/{symbolExchange} |
| market_cap | view=aggregation, type | GET /historicalquotes/marketcap/aggregation/{type} |
| benchmark | symbol, benchmark | GET /historicalquotes/benchmark |
| market_lastday | exchange | GET /historicalquotes/marketwide-lastday-quote/{exchange} |
| fundamentals | view=statements, symbolExchange | GET /fundamentals/{symbolExchange} |
| fundamentals | view=keyfigures, symbolExchange | GET /fundamentals/keyfigures/{symbolExchange} |
| fundamentals | view=forecast, symbolExchange | GET /fundamentals/forecast/{symbolExchange} |
| ratings | symbolExchange | GET /ratings/{symbolExchange} |
| dividends | view=latest, symbolExchange | GET /dividends/{symbolExchange} |
| dividends | view=history, symbolExchange | GET /dividends/history/{symbolExchange} |
| splits | symbolExchange | GET /splits/{symbolExchange} |

Market-Fit, Business and Leeway-Score range from −100 to +100; Cycle from 0 to 100. Market-Fit factor names: ROA = `totalCapitalReturn` (net income / total capital); EBT margin = `ebtMargin`; P/EBT = `pebtRatio`.

### Events, macro, sentiment
| Tool | Call | REST path |
|------|------|-----------|
| events | view=ipos, earnings, or splits | GET /events/ipos, /events/earnings, /events/splits |
| events | view=trends, symbols | GET /events/trends |
| macro | view=indicators | GET /macro/indicators |
| macro | view=countries | GET /macro/countries |
| macro | view=series, country | GET /macro/{country} |
| sentiment | family, optional series | GET /sentiment/… |
| government | optional series | GET /government/ and /government/series/{series} |
| bond | isin | GET /bond/{isin} |
| news | optional s | GET /news/ |

Logo images are not MCP tools. Fetch them from GET /img/logos/{path} and GET /img/logosbycodeexchange/{codeexchange}.

## Typical Workflow

1. `general_isin` with "SAP" or an ISIN → `SAP.XETRA`
2. `fundamentals` with view=statements and symbolExchange `SAP.XETRA`
3. `prices` with view=eod and symbolExchange `SAP.XETRA`
4. `general_screener` with filters for European tech stocks

## Symbol Format

Use `SYMBOL.EXCHANGE` (e.g. `DTE.XETRA`, `AAPL.US`).

## Research Briefs (pay-per-use)

Named, dated research objects, separate from the Data API tools listed above. On MCP they are `ai_company` (topic), `ai_asset` (topic), and `ai_market` (view). Billing runs against a wallet, in addition to the daily request units.

- Base: `https://api.leeway.tech/api/v1/public/ai`
- Auth: same token as the rest of the public API (`?apitoken=` on REST, Bearer or OAuth on MCP)
- Cache: shared across all users, keyed by ticker (or the ticker derived from a thesis) plus research type
- `maxAgeDays` / `maxAgeHours` set how old a stored piece may be; `0` forces a fresh run. The weekly briefing, the daily briefing, and the CIO view reject those parameters and return the latest stored text.
- Cache read: EUR 0.02. Generate: EUR 0.02 plus the provider cost actually incurred, converted from USD at the last EURUSD close and rounded up
- A generate is anything that incurs provider cost, including a translation or rewrite not yet cached. A cache hit is a call on which no provider USD was spent
- Failed calls are not billed. An insufficient wallet returns HTTP 402 with the required and current amount in millieuros
- A successful billed response reports the amount charged in millieuros, whether it was a cache hit, the as-of date and a usage id
- Wallet: EUR 5 included per billing period on Investor, EUR 15 on Trader; top-ups of 10 / 25 / 50 / 100 / 200 EUR

| Object | REST path | Default freshness | lang |
|--------|-----------|-------------------|------|
| What's new | GET /research/equity/whatsnew/{ticker} | 7 days | de, en |
| Timeline | GET /research/equity/timeline/{ticker} | 30 days | de, en |
| Competitors | GET /research/equity/competitors/{ticker} | 90 days | de, en |
| Risks | GET /research/equity/risks/{ticker} | 90 days | de, en |
| Price drivers | GET /research/equity/price-drivers/{ticker} | 30 days | — |
| Industry what's new | GET /research/equity/industry/{ticker} | 7 days | — |
| Sector what's new | GET /research/equity/sector/{ticker} | 7 days | — |

Assets use commodity and FX tickers such as `XAUUSD.COMM`: `GET /research/asset/whatsnew/{ticker}` (1 day), `GET /research/asset/timeline/{ticker}`, `GET /research/asset/price-drivers/{ticker}`, and `GET /research/asset/events/{ticker}` (7 days). The theme timeline is `GET /research/theme/timeline?thesis=...` (7 days). The weekly briefing, the daily briefing, and the CIO view are stored reads. `length=short` returns the email and `length=long` returns the website text. They do not take a freshness window and they do not generate. `GET /research/market/whatsnew-weekly` is included for every account. `GET /research/market/whatsnew-today` requires a trader subscription; its email and its website article are the same text. `GET /research/market/cio-view` requires an investor or trader subscription and `lang=de` or `lang=en`. None of the three charges the wallet. A missing version returns HTTP 404. `GET /research/market/timeline-weekly` (8 days) remains a wallet cache read and returns 404 when no fresh document exists.

Previously published unnamespaced research paths remain available as compatibility aliases, but new integrations should use the normalized paths above.

Limits: a company what's new requires an existing quality rating for that company; industry and sector return 400 where the company carries no classification. A token restricted to the Data API endpoint groups may be refused before billing.

Pages: https://leeway.tech/recherche-briefings and https://leeway.tech/recherche-kosten (EN: /en/research-briefings, /en/research-cost).

## Research

Leeway publishes long-form investment theses at https://leeway.tech/research. They are separate from the ratings above: the ratings are rule-based and computed from balance sheet, valuation and cycle data; the theses are qualitative and model-produced.

How a thesis is produced:

1. The same opening question goes to several independent model families that cannot see one another. Disagreements are kept, not averaged.
2. Every fact-dependent claim is decomposed into search questions and answered with dated, sourced web research. Question, answer, sources and timestamp are logged.
3. Adversarial review roles attack the thesis: strongest refutation, awkward edge cases, whether a path from thesis to share price exists, and timeline consistency. Each role raises its own questions, again answered with evidence.
4. Surviving theses are merged and attacked a second time. The counter-position and unresolved tension published on each page come from this step.
5. Vehicles are named last and resolved against the Leeway universe. Names without an unambiguous match stay unlinked.

Stated limits: not a price forecast, no knowledge after the publication date shown on each page, not calibrated to short-term market moves.

Every theme page carries: the thesis claims, where the surplus lands, named companies with Leeway ratings, dated catalysts, scenario weights, the counter-position, the unresolved tension, what would falsify it, and an FAQ.

| Theme | URL | Claim |
|-------|-----|-------|
| Staples | https://leeway.tech/research/human-basics | Staples secure the revenue. They do not secure the valuation. |
| Permission and proof | https://leeway.tech/research/permission-proof | Cognition gets cheap. Permission and proof stay scarce. |
| Testing and certification | https://leeway.tech/research/deputised-state | The state issues duties, not money. The testing groups keep the return. |
| Robot revolution | https://leeway.tech/research/robot-revolution | The robot revolution is real. The profits sit elsewhere. |
| Beyond the grid | https://leeway.tech/research/beyond-the-grid | Beyond the Grid: The Hidden Bottlenecks Driving the Next Decade of Industrial Returns. |

English versions are served under `/en/research/...`.

## Positioning

European coverage is a key differentiator: XETRA, Frankfurt, Euronext Paris/Amsterdam, LSE plus US markets.

## Contact

kontakt@leeway.tech