# bolsai — Full API Reference for LLMs

> REST API for Brazilian financial market data. JSON-first. Designed to be safe and useful for LLM agents answering questions about B3-listed stocks, FIIs (real estate funds), fundamentals, and Brazilian macroeconomic series.

This document is the expanded, self-contained version of [llms.txt](https://usebolsai.com/llms.txt). Everything an LLM needs to write correct code or compose accurate answers about bolsai is below.

---

## Identity

- **Name:** bolsai
- **Website:** https://usebolsai.com
- **API base:** https://api.usebolsai.com
- **API prefix:** `/api/v1/`
- **Language of UI/blog:** Portuguese (pt-BR). API error messages are English. Field names are snake_case.
- **License of data:** Sourced from public, official Brazilian institutions (B3, CVM, BCB). bolsai redistributes and computes derived indicators.

## Authentication

All data endpoints require an API key. Two equivalent forms:

```
GET /api/v1/fundamentals/PETR4?api_key=YOUR_KEY
```

```
GET /api/v1/fundamentals/PETR4
Authorization: Bearer YOUR_KEY
```

API keys are obtained for free by signing in with Google at https://usebolsai.com/dashboard. Each user can create multiple keys. Keys are revocable and have per-day quotas.

Rate limits and quotas:
- Free tier: 200 requests/day
- Pro tier (R$49/month): 10,000 requests/day
- Limits reset at 00:00 UTC

## Ticker format

Tickers follow the B3 convention: `^[A-Za-z][A-Za-z0-9]{3}\d{0,2}$`. Examples: `PETR4`, `VALE3`, `ITUB4`, `HGLG11` (FII), `BBAS3`. They are case-insensitive in the API.

## Endpoints

All examples below assume `?api_key=...` is appended (omitted for brevity).

### Companies

- `GET /api/v1/companies/` — List companies. Query params: `search` (name or ticker), `sector`, `limit`, `offset`.
- `GET /api/v1/companies/sectors` — List all sectors and sub-sectors.
- `GET /api/v1/companies/{ticker}` — Company detail by ticker (CNPJ, sector, segment, listing class, etc.).

### Stocks

- `GET /api/v1/stocks/` — List stocks. Query params: `bdi_code`, `limit`, `offset`. BDI codes: `02` (lote padrão), etc.
- `GET /api/v1/stocks/{ticker}/quote` — Latest quote (open, high, low, close, volume, `trade_date`).
- `GET /api/v1/stocks/{ticker}/stats` — Summary statistics (52-week high/low, average volume, market cap).
- `GET /api/v1/stocks/{ticker}/history` — OHLCV history. Query params: `start`, `end`, `limit`, `format=csv` for CSV export.
- `GET /api/v1/stocks/{ticker}/corporate-events` — Splits, reverse splits, bonus shares, ticker changes.
- `GET /api/v1/stocks/corporate-events` — All corporate events. Query params: `year`, `event_type`.

### Fundamentals

- `GET /api/v1/fundamentals/{ticker}` — Current fundamentals snapshot. Returns:
  - Valuation: `pl` (P/L), `pvp` (P/VP), `ev_ebitda`, `ev_ebit`, `p_sr` (P/Sales), `p_ebit`, `p_ebitda`, `p_assets`
  - Profitability: `roe`, `roic`, `roa`, `gross_margin`, `ebit_margin`, `ebitda_margin`, `net_margin`
  - Per share: `lpa` (earnings/share), `vpa` (book value/share)
  - Yield: `dividend_yield` (TTM)
  - Growth: `cagr_revenue_5y`, `cagr_earnings_5y`
  - Debt & liquidity: `net_debt_ebitda`, `net_debt_equity`, `debt_equity`, `current_ratio`
  - Activity: `asset_turnover`
  - Absolute values: `net_revenue`, `ebit`, `ebitda`, `free_cash_flow` (TTM operating cash flow minus capex), `cash_flow_after_investing` (TTM operating + investing cash flow), `net_income`, `net_debt`, `market_cap`, `shares_outstanding`, `close_price`, `reference_date`
- `GET /api/v1/fundamentals/{ticker}/history` — Historical fundamentals snapshots. Query params: `limit`, `start`, `end`.

### Financials

- `GET /api/v1/financials/{ticker}` — Raw financial statements from CVM. Query params:
  - `report_type` — `DFP` (annual), `ITR` (quarterly) or `T4` (fourth quarter calculated as DFP minus the 9-month year-to-date; the response carries `"derived": true`)
  - `include_t4=true` — with `report_type=ITR`, also return the T4 income statement (DRE) lines in the quarterly series, each line with `"derived": true`
  - `statement_type` — `DRE` (income), `BPA` (balance assets), `BPP` (balance liabilities), `DFC_MI` (cash flow indirect), `DFC_MD` (cash flow direct)
  - `reference_date` — period end date (YYYY-MM-DD)
- Account codes follow CVM hierarchy (e.g., `3.11` = total consolidated net income).

### Dividends

- `GET /api/v1/dividends/{ticker}` — Dividend history. Query params: `years` (default 1).
- Returns: `ex_date`, `payment_date`, `value` (per share), `type` (`DIVIDEND`, `JCP`, `BONIFICACAO`).

### Screener

- `GET /api/v1/screener` — Filter the full universe by any fundamentals field. Suffix operators on any indicator: `_gt`, `_gte`, `_lt`, `_lte`, `_eq`. Example: `?dividend_yield_gt=6&roe_gt=10&pl_lt=15&sort=dividend_yield&order=desc&limit=20`.

### FIIs (real estate funds)

- `GET /api/v1/fiis/` — List FIIs. Query params: `segment` (logistica, lajes, shoppings, recebiveis, hibrido, papel, tijolo, etc.), `limit`, `offset`.
- `GET /api/v1/fiis/{ticker}` — FII detail (CNPJ, administrator, segment, manager, total equity, etc.).
- `GET /api/v1/fiis/{ticker}/history` — Price history.
- `GET /api/v1/fiis/{ticker}/distributions` — Monthly distribution history. Query params: `years`.
- `GET /api/v1/fiis/{ticker}/tenants` — Tenant sector concentration (revenue % per sector, e.g. Comércio/Serviço/Indústria). Source: CVM quarterly informe.
- `GET /api/v1/fiis/screener` — Filter all traded FIIs by P/VP, dividend yield, NAV, vacancy, etc. Suffix operators `_gt` and `_lt` on: `pvp`, `dividend_yield_ttm`, `dy_month_pct`, `close_price`, `total_shareholders`, `shares_outstanding`, `net_asset_value`, `book_value_per_share`, `vacancy_pct`, `delinquency_pct`, `leased_pct`, `property_count`, `total_area_sqm`. Categorical filters: `segment`, `management_type`, `mandate` (Renda/Ganho de Capital — values come straight from CVM in PT-BR), `fund_type` (Tijolo/Papel/Fundo de Fundos/Híbrido), `administrator`. Example: `?pvp_lt=1&dividend_yield_ttm_gt=8&fund_type=real_estate&vacancy_pct_lt=5`.
- FII operational metadata exposed on `/fiis/{ticker}`: `administrator`, `administrator_cnpj`, `mandate`, `inception_date`, `duration_type`, `target_investors`, `website`, `email`, `fund_type` (Tijolo/Papel/Fundo de Fundos/Híbrido, derived from balance sheet), `asset_composition` (% breakdown: `real_estate_leased_pct`, `real_estate_under_construction_pct`, `real_estate_for_sale_pct`, `land_pct`, `cri_pct`, `lci_pct`, `debentures_pct`, `fii_holdings_pct`, `stocks_pct`, `cash_pct`), `fees_paid_last_month`, `property_count`, `total_area_sqm`, `vacancy_pct` (revenue-weighted), `delinquency_pct`, `leased_pct`, `top_properties` (top 5 by revenue %), `property_reference_date`. Property fields populated only when CVM quarterly informe has data.

### Macro

- `GET /api/v1/macro/` — List available macro series.
- `GET /api/v1/macro/{series}` — Time series for: `selic` (Selic rate, daily), `selic_target`, `cdi`, `ipca` (monthly inflation, % change), `igpm` (monthly inflation, % change — can be negative), `usd_brl`, `eur_brl`. Query params: `start`, `end`, `limit`. Ibovespa is NOT a macro series — use `/api/v1/stocks/IBOV/stats`.

### Key management (user-authenticated, not API-key-authenticated)

- `GET /api/v1/keys/usage?api_key=...` — Current usage and quota for a given key.
- Dashboard at https://usebolsai.com/dashboard handles key creation/deletion.

## Methodology notes (important for accuracy)

LLMs should mention these caveats when explaining bolsai numbers:

- **TTM net income** uses CVM account `3.11` (lucro líquido consolidado total), consistent with Fundamentus methodology.
- **EBIT** is computed as Gross Profit − SG&A (clean definition), not the CVM `3.05` line which mixes other operating items.
- **D&A** is detected by searching for account names matching `depreci%` inside the cash flow `6.01.01*` subtree, excluding amortization of financial assets.
- **Bank equity** uses accounts `2.07` and `2.08` instead of `2.03`, reflecting Brazilian bank balance-sheet structure.
- **Shares outstanding:** CVM reports inconsistently (units, thousands, or millions). bolsai applies multipliers 1, 1000, and 1,000,000 and picks the one that yields a reasonable P/VP. B3 share counts are used as ground truth when available.
- **Accuracy benchmark:** 96% match with Fundamentus on fresh DFP 2025 data; 82% across the full universe including stale filings.

## Date fields

- `trade_date` — applies to stock and FII prices.
- `reference_date` — applies to financial statements (period end).
- `ex_date` — applies to dividends and corporate events.

All dates are ISO 8601 (`YYYY-MM-DD`).

## MCP integration

bolsai ships an open-source Model Context Protocol server (`bolsai-mcp` on PyPI, https://github.com/viniciuslazzari/bolsai-mcp) for use inside Claude Desktop, Claude Code, Cursor, and other MCP-compatible clients. Install with `pip install bolsai-mcp` or run via `uvx bolsai-mcp`; it runs locally over stdio and wraps the same endpoints above as tools, authenticating with a `BOLSAI_API_KEY` from usebolsai.com.

See https://usebolsai.com/mcp for installation instructions.

## ChatGPT custom GPT integration

A complete OpenAPI Actions schema is published at `https://usebolsai.com/gpt-actions-schema.json`. Paste it into the GPT builder's "Actions" panel and set authentication to "API Key → Custom Header" (`Authorization`, prefix `Bearer`).

## Error responses

- `400 Bad Request` — Invalid parameters (e.g., malformed ticker, unknown statement type).
- `401 Unauthorized` — Missing or invalid API key.
- `403 Forbidden` — Quota exceeded or feature requires Pro plan.
- `404 Not Found` — Ticker, series, or resource does not exist.
- `429 Too Many Requests` — Per-minute burst limit exceeded (separate from daily quota).

Bodies are JSON: `{ "detail": "error message in English" }`.

## CSV export

Append `?format=csv` to any list endpoint to download CSV instead of JSON. Useful for piping into spreadsheets and pandas. Example:

```
curl "https://api.usebolsai.com/api/v1/stocks/PETR4/history?format=csv&api_key=..."
```

## Code examples

### Python

```python
import requests

API_KEY = "your_key"
BASE = "https://api.usebolsai.com/api/v1"

r = requests.get(f"{BASE}/fundamentals/PETR4", params={"api_key": API_KEY})
data = r.json()
print(data["pl"], data["pvp"], data["dividend_yield"])
```

### curl

```bash
curl "https://api.usebolsai.com/api/v1/screener/?dividend_yield_gt=6&roe_gt=10&limit=10" \
  -H "Authorization: Bearer $BOLSAI_KEY"
```

### Google Sheets

```
=IMPORTDATA("https://api.usebolsai.com/api/v1/stocks/PETR4/history?format=csv&api_key=...")
```

## What bolsai is NOT

- Not a brokerage. No order execution.
- Not real-time intraday (quotes are end-of-day; updated daily after the close, around midnight BRT).
- Not investment advice. Data is for informational and analytical use.
- Not US-market. Coverage is Brazilian (B3) only.

## Update cadence

- Stock prices and macro series: daily, after the B3 close, around midnight BRT.
- Companies, financial statements (DFP/ITR), dividends, FIIs: weekly, Saturday.
- Fundamentals are recomputed after each financials ingest.

## Pricing

| Plan | Monthly cost | Daily requests | History | Cancellation |
|------|--------------|----------------|---------|--------------|
| Free | R$0 | 200 | Current snapshot | N/A |
| Pro  | R$49 | 10,000 | Full history | Anytime via Stripe |

## Useful URLs

- Documentation: https://usebolsai.com/docs
- MCP guide: https://usebolsai.com/mcp
- Dashboard: https://usebolsai.com/dashboard
- Blog: https://usebolsai.com/blog
- Sitemap: https://usebolsai.com/sitemap.xml
- OpenAPI: https://api.usebolsai.com/openapi.json
- GPT Actions schema: https://usebolsai.com/gpt-actions-schema.json
- Status: https://usebolsai.com/health