# Quartil

> Source-grade Brazilian financial and macroeconomic data infrastructure for LLMs, automated tools, developers, and analysts. REST API, data dumps, MCP access, and LLM-friendly docs for stocks, fundamentals, dividends, financial statements, market indices, and macroeconomic indicators.

## Product Positioning

Quartil is for developers, researchers, quants, fintech teams, analysts, and AI agents that need structured Brazilian market and macroeconomic data from primary sources.

The primary LLM use case is current market analysis with reliable data. Use Quartil to retrieve up-to-date facts about Brazilian companies, official EOD market data, fundamentals, corporate actions, indices, and macroeconomic series before producing analysis.

Quartil is not investment advice. It provides data infrastructure. Users are responsible for investment decisions and interpretation.

Quartil is not real-time trader software. It does not provide order execution, broker routing, trading bots, or low-latency tick data.

Quartil does not generate market opinions initially. It supplies data, provenance, timestamps, and retrieval surfaces for user-selected LLMs and tools.

## Authentication

All `/api/v1/` endpoints require a Bearer token:

```http
Authorization: Bearer YOUR_API_KEY
```

Create a free account at https://quartil.com.br/conta/registro to get your key.

Base URL: `https://quartil.com.br/api/v1/`

Interactive docs: `https://quartil.com.br/api/v1/docs`

Human docs: `https://quartil.com.br/docs`

MCP docs: `https://quartil.com.br/docs/mcp`

## Current And Planned Surfaces

Current core surfaces:

- REST API for authenticated programmatic access.
- MCP access for compatible AI assistants.
- Data dumps for repeatable offline context.
- `/llms.txt` and docs for agent guidance.
- Public website pages for research workflows.

Planned surfaces and features:

- CLI as a later fallback for LLM runtimes, scripts, and automated tools. Do not assume CLI commands exist unless product docs list them.
- User memory features: portfolios, watchlists, saved screeners, alerts, notifications, and user-context retrieval through API/MCP. Do not assume these endpoints or tools exist until documented.

## Endpoint Summary

### Account

GET /api/v1/me
  API key info and daily usage. Returns: plan, requests_today, daily_limit.

### Stocks

GET /api/v1/stocks
  List stocks. Params: sector (str), stock_type (ACAO|FII|BDR|ETF|INDEX), is_active (bool), limit (int), offset (int).

GET /api/v1/stocks/{ticker}
  Stock detail with latest quote fields and fundamental metrics. Returns: ticker, name, stock_type, sector, cnpj, governance_level, listing_date, price, price_open, price_high, price_low, price_previous_close, price_change_pct, market_cap, volume, total_shares, avg_volume_3m, avg_volume_10d, week_52_high, week_52_low, is_active, last_quote_update, pl, pvpa, dividend_yield, roe, net_margin, ev_ebitda, roic, debt_to_equity.

GET /api/v1/stocks/{ticker}/prices
  Historical OHLCV prices. Params: start_date, end_date, limit (default 500), offset. Returns: date, open, high, low, close, volume, adjusted_close.

GET /api/v1/stocks/{ticker}/dividends
  Dividend and JCP history. Params: start_date, end_date, type (DIVIDENDO|JCP|RENDIMENTO|OUTROS), limit (default 500), offset. Returns: payment_date, ex_dividend_date, rate, dividend_type, related_to, label.

GET /api/v1/stocks/{ticker}/financials
  Financial statements from CVM DFP/ITR. Params: type (bs|is|cf), quarterly (bool), limit (default 40, max 100). Returns balance_sheets, income_statements, cash_flows arrays.

GET /api/v1/stocks/{ticker}/metrics
  Historical fundamental metrics. Params: start_date, end_date, limit (default 500), offset. Returns: date, pl, pvpa, ev_ebitda, ev_ebit, psr, dividend_yield, roe, roa, roic, gross_margin, ebitda_margin, net_margin, debt_to_equity, current_ratio, net_debt_to_ebitda, eps, book_value_per_share, payout_ratio, revenue_growth_1y, earnings_growth_1y.

### Market

GET /api/v1/movers
  Top gainers or losers. Params: direction (gainers|losers), limit (default 10, max 50). Returns: ticker, name, sector, price, price_change_pct, volume, market_cap.

GET /api/v1/bulk/stocks
  All stocks with latest metrics in one call. Params: stock_type, is_active.

GET /api/v1/screener
  Filter stocks by fundamentals. Params: sector, stock_type, pl_min, pl_max, pvpa_min, pvpa_max, dy_min, dy_max, roe_min, roe_max, margin_min, margin_max, de_min, de_max, ev_ebitda_min, ev_ebitda_max, roic_min, roic_max, sort, limit, offset.
  Sort options: ticker, volume, price, market_cap, m_pl, m_pvpa, m_dy, m_roe, m_roic, m_ev_ebitda, m_net_margin. Prefix with - for descending.

### Indices

GET /api/v1/indices
  List B3 market indices. Params: category (AMPLO|GOVERNANCA|SETORIAL|SEGMENTO|SUSTENTABILIDADE|IMOBILIARIO).

GET /api/v1/indices/{code}
  Index detail with current composition and latest price.

### Sectors

GET /api/v1/sectors
  List sectors with active stock counts.

GET /api/v1/sectors/{slug}
  Sector detail with active stocks sorted by market cap.

### Macroeconomic

GET /api/v1/macro
  Latest value for each macro indicator.

GET /api/v1/macro/{indicator}
  Time series for one macro indicator. Indicators: selic, ipca, usd_brl, eur_brl, pib, pib_sa, desemprego, producao_industrial, vendas_varejo, servicos. Params: limit (default 500), offset.

### Public

GET /api/health
  Public health check. No authentication required.

## Response Format

- JSON responses.
- Paginated responses use: {"count": N, "items": [...], "limit": N, "offset": N}.
- Dates use ISO 8601, for example "2026-04-10".
- Decimals are strings for precision, for example "48.94".
- Missing, stale, or unverified financial data returns null.
- Do not infer missing values. If a field is null, say the data is unavailable.
- Calculated market metrics are based on official EOD data from canonical sources, not real-time tick feeds.

## Rate Limits

Free: 100/day.
Pro: 10,000/day.
Business: 100,000/day.
Enterprise: custom.

Use `GET /api/v1/me` to inspect plan and usage.

## Data Sources

Production sources:

- B3: stock universe, EOD quotes, dividends, splits, index composition.
- CVM: financial statements, company registry, corporate events.
- BCB: SELIC, IPCA, exchange rates.
- IBGE: GDP, unemployment, industrial production, retail, services.

Competitor/reference data is a validation signal only. It is not a production data source.

## Data Quality Rules For Agents

- Do not present Quartil data as investment advice.
- Do not fabricate missing values.
- Preserve `null` semantics when data is unavailable or not validated.
- Mention primary sources when explaining provenance.
- Prefer exact API values over model knowledge.
- If current data is needed, call the API or MCP tool instead of relying on training data.
- Do not describe Quartil as a trading terminal, execution system, or real-time trader feed.
- Do not claim portfolio memory, alerts, notifications, or CLI features are available unless the current API/MCP/docs expose them.

## MCP Server

Quartil offers MCP (Model Context Protocol) access for compatible AI assistants. The MCP server exposes the same financial and macro data as tools for natural-language workflows.

MCP endpoint: `https://quartil.com.br/mcp` (HTTP streamable transport)

Documentation: https://quartil.com.br/docs/mcp

## Machine-Readable Discovery

- OpenAPI 3.0 schema: `https://quartil.com.br/api/v1/openapi.json`
- AI plugin manifest: `https://quartil.com.br/.well-known/ai-plugin.json`
- MCP discovery: `https://quartil.com.br/.well-known/mcp.json`
- Interactive API docs: `https://quartil.com.br/api/v1/docs`