# Bolsix integration reference

Bolsix is a Brazilian financial-data service designed for AI agents and backend applications. It serves structured data sourced from B3 (quotes and prices), CVM (fundamentals, filings, distributions, and FII informes), and BCB (rates, macro series, and PTAX).

REST base URL: https://api.bolsix.io
Hosted MCP URL: https://mcp.bolsix.io/
OpenAPI: https://api.bolsix.io/openapi.json
Account and API keys: https://bolsix.io/auth/signup

## Authentication

Hosted MCP uses browser-based OAuth with the `read` scope. Recommended Claude Code setup:

    claude mcp add --transport http bolsix https://mcp.bolsix.io/

Keyless demo: without any key, PETR4, VALE3, ITUB4, HGLG11 and BOVA11 are served on GET /v1/stocks/quote, /v1/stocks/prices, /v1/stocks/fundamentals and /v1/stocks/dividends, 100 requests per day per IP (UTC day); responses carry X-Bolsix-Demo: true. Anything else without a key is a 401 whose message lists what the demo covers.

    curl "https://api.bolsix.io/v1/stocks/quote?symbols=PETR4,VALE3"

Everything else uses a Bolsix API key (free: 1,000 requests per day). Send it as:

    Authorization: Bearer bx_live_...

An `X-API-Key: bx_live_...` header works too. Do not expose API keys in frontend code. Query-string `token` authentication exists for compatibility, but a header is recommended because URLs are commonly logged.

Other MCP clients (Claude Desktop custom connectors, ChatGPT in Developer mode, Codex via `codex mcp add bolsix --url https://mcp.bolsix.io/` then `codex mcp login bolsix`, Cursor) use the same hosted URL, https://mcp.bolsix.io/, with browser sign-in:

    { "mcpServers": { "bolsix": { "url": "https://mcp.bolsix.io/" } } }

## REST contract

Successful responses generally use:

    { "data": ..., "meta": { "data_source": "...", "took_ms": 1 }, "status": "ok" }

Errors use:

    { "status": "error", "code": 401, "message": "Missing API key" }

A parameter that fails validation returns 422 in the same shape, naming each bad field in the message and listing them in `errors` (field, location, message, input), e.g. "Invalid request: limit: Input should be less than or equal to 200".

A 404 for a ticker that was renamed names its current ticker, in the message and as `renamed_to` (e.g. {"ELET3": "AXIA3"}); retry with the new symbol.

Each API key has a daily request quota (1,000 on the free plan) that resets at 00:00 UTC. Authenticated responses include X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds). A spent quota returns 429 with Retry-After (seconds until the reset); wait rather than retrying immediately.

Dates use YYYY-MM-DD. Timestamps use ISO 8601. Symbols use native B3 tickers (PETR4); Yahoo spellings are accepted and normalized: a .SA suffix is dropped, and IBOV, ^BVSP and IBOVESPA mean IBOV11, the Ibovespa. Prices and filings return meta.next_cursor for cursor pagination. Instrument listings use limit and offset. Every HTTP response includes X-Took-Ms.

## Public REST endpoints

Market data:
- GET /v1/stocks/quote — required: symbols; optional: fields. Up to 100 comma-separated symbols. Symbols with no quote are listed in meta.not_found with a meta.warnings entry (and meta.renamed_to for a renamed ticker); a request where none has a quote is a 404.
- GET /v1/stocks/prices — required: symbol; optional: interval=1d|1w|1mo, start_date, end_date, limit 1–2000, cursor, adjust=split|raw|total_return. Weekly and monthly bars are built from daily ones and dated by the period's last session.
- GET /v1/stocks/list — optional: name (company name or ticker prefix, e.g. Petrobras, Itaú, PETR), asset_class=stock|fii|bdr|etf|index, sector (matches sector, subsector or segment, e.g. Financeiro, Bancos), limit, offset. Name and sector ignore case, accents and punctuation. An unknown asset_class is a 400; a sector or name that matches nothing returns meta.warnings (with the valid sectors). meta.total counts every match; meta.count is the rows on this page.
- GET /v1/stocks/bulk/quotes — all active cached quotes in one request.
- GET /v1/stocks/corporate-actions — required: symbol. Splits, reverse splits, bonuses, renames, and lineage.

Fundamentals and disclosures:
- GET /v1/stocks/fundamentals — required: symbol; optional: period=annual|quarterly|ttm (see Periods below), limit 1–20.
- GET /v1/stocks/statements — required: symbol; optional: statement=income|balance|cashflow, period=annual|quarterly, limit 1–20, as_of. Includes provenance.
- GET /v1/stocks/dividends — required: symbol; optional: limit 1–200, event_type=dividend|jcp|return_of_capital|bonus|other, start_date and end_date (bounds on com_date), cursor. Newest first; while older events remain, meta.next_cursor is set: pass it as cursor for the next page. A page never splits one com_date's events, so it can hold a few more than limit; an empty window of a covered symbol is an empty page, not a 404. return_of_capital (fund quota amortizations, cash capital reductions, and capital returned in another company's shares, such as Bradespar's Vale shares in 2021, valued on the ex-session) hands back capital and is not income: leave it out of yields. Each event has com_date (data com: the last session in which buying the share earns the payout), ex_date (the next B3 session), payment_date when B3 has announced it, and the share-class ISIN. A FII's latest 12 months come from B3 (source b3) and its earlier distributions, from 2020, from the fund's own structured notices on B3's FundosNet (source fnet). Several events can share a com_date (e.g. two JCP tranches, or one declaration paid in installments, numbered by installment); each is a separate payout, so sum them.
- GET /v1/stocks/filings — required: symbol; optional: category=fato_relevante|comunicado|aviso_acionistas|resultado|calendario, since, limit, cursor. Includes CVM doc_url.
- GET /v1/stocks/calendar — optional: symbol, since, until, limit 1–500. DFP/ITR delivery calendar, market-wide or for one company; a symbol that files no CVM results (FIIs, BDRs) is a 404.
- GET /v1/stocks/screen — optional filters for asset_class, sector, P/E, P/B, EV/EBITDA, net debt/EBITDA, ROE, ROA, net margin, dividend yield, and market cap; sort_by, sort_order, limit. Ratio filters are decimals (min_roe=0.15 means ROE ≥ 15%); a ROE/ROA/margin/yield filter above 1 returns a meta.warnings entry, since it is almost always a percentage by mistake. sector works as on /v1/stocks/list. Rows with dividend_yield above 0.5 (50%) are named in meta.warnings: usually a fund liquidating or returning capital, not recurring income; check dividends or pass max_dy=0.5.

Macro and FIIs:
- GET /v1/macro/rates — latest SELIC (Copom target), selic_effective (Selic over, annualized), CDI, IPCA, and IPCA 12-month values.
- GET /v1/macro/currency — latest official USD/BRL PTAX buy and sell rates.
- GET /v1/macro/series — required: series_id; optional: start_date, end_date, limit 1–5000. Valid IDs: selic, cdi, ipca, ipca_12m, usd_brl_buy, usd_brl_sell, pib_qoq.
- GET /v1/fii/portfolio — required: symbol. Allocation, NAV, holders, property count, area, vacancy, and delinquency.

Watchlists:
- GET /v1/watchlist — account watchlist.
- PUT /v1/watchlist — JSON body {"symbols": ["PETR4"]}; replaces watchlist.
- POST /v1/watchlist/add — same body; adds valid symbols.
- POST /v1/watchlist/remove — same body; removes symbols.
- GET /v1/watchlist/briefing — optional: since, filings_per_ticker. New filings, financial deltas, distributions, net yield, and price.

Account verification:
- GET /v1/auth/me — returns the current key's customer_name, plan, and daily_limit.

## MCP tools

- get_watchlist_briefing: complete multi-ticker change briefing computed server-side.
- get_watchlist, set_watchlist, add_to_watchlist, remove_from_watchlist: account watchlist management.
- get_filings: CVM disclosures with canonical source URLs.
- get_results_calendar: DFP/ITR deliveries, market-wide or for one company.
- get_fii_summary: FII quote, P/VP, 24-month distributions, and computed yield.
- compare_stocks: 2–5 tickers compared across P/E, P/B, ROE, EV/EBITDA, and dividend yield.
- get_quotes: latest quotes for up to 100 symbols.
- get_fundamentals: valuation, profitability, leverage, and yield metrics.
- get_dividends: dividends and JCP preserved as distinct event types.
- get_historical_prices: B3 daily, weekly, or monthly OHLCV.
- get_financial_statements: income, balance-sheet, and cash-flow statements.
- list_stocks: instrument discovery by asset class, sector, or name.
- screen_stocks: server-side fundamental screening.
- get_bulk_quotes: complete active quote universe.
- get_macro_rates: current rate and inflation context.
- get_macro_currency: current PTAX USD/BRL.
- get_macro_indicator: historical macro series.
- get_corporate_actions: splits, bonuses, renames, and ticker lineage.

## Methodology

Full per-field reference: https://bolsix.io/docs/methodology

Statement fields are CVM lines as filed (consolidated when filed, else individual; latest filing version): revenue 3.01, gross_profit 3.03, ebit 3.05, ebitda 3.05 + depreciation from cash-flow lines under 6.01.01, net_income 3.11 (consolidated, including minority shareholders), net_income_parent 3.11.01 (attributable to the parent; empty for individual-only filers and when filed as 0 under a nonzero 3.11, and the ratios then use net_income), total_assets 1, total_liabilities 2.01 + 2.02, equity 2.03 (total), minority_interest 2.03.09, cash 1.01.01, short_term_investments 1.01.02, total_debt 2.01.04 + 2.02.01 (including IFRS 16 leases), operating/investing/financing cash flow 6.01/6.02/6.03.

Ratios: eps = net_income_parent / shares; pe_ratio = market_cap / net_income_parent; book_value = (equity - minority_interest) / shares; pb_ratio = market_cap / (equity - minority_interest); roe = net_income_parent / (equity - minority_interest) at period end; roa = net_income / total_assets; net_debt = total_debt - cash - short_term_investments; enterprise_value = market_cap + net_debt; dividend_yield = dividends + JCP (gross) with record date in the last 365 days / last close. market_cap sums every share class at its own price; units are left out (their shares are already in ON and PN) unless the company lists only units, and a preferred total B3 reports on several classes (PNA, PNB) is counted once, at the most-traded class's price.

Periods: annual (fiscal year), quarterly (one discrete quarter; flow ratios annualized x4), ttm (last twelve months). Use period=ttm when comparing with other sources. Banks: revenue, ebit, ebitda and total_debt are empty; intermediation_revenue, financial_margin, pretax_income and provision_expenses are returned instead.

## Reasoning and tax semantics

JCP (juros sobre capital próprio) and dividends must not be merged. For a Brazilian individual investor, JCP has 15% tax withheld at source while dividends are currently tax-free. When both event types are present, a basic net-yield calculation is:

    net_yield = (total_dividends + total_jcp * 0.85) / current_price

Use the most specific workflow tool that matches the task. Preserve doc_url for filing citations. Preserve statement provenance and as-of dates for point-in-time research. Report data_source and date context when available. Do not present market data as personalized investment advice.