# Investidor B3 — how to use (mcp.ai)

Your consolidated B3 investment portfolio (the central depository): position by asset, net worth, trades, dividends/interest-on-equity and movements, across all brokers in one place. Read-only, D-1 data. Connect your own Área do Investidor account, with consent. Pairs with the Banco MCP (Open Finance), banking in the Banco MCP, investment portfolio here.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_b3?ms=1781684640000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `b3_get_carteira`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/b3`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/b3/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/b3/get/carteira` — Resumo da carteira agrupado por classe de ativo (ações, FIIs, renda fixa, etc.) com valor e percentual de cada grupo.
  - body: { agrupamento?: integer, quantidade?: integer, account?: string }
- `POST https://api.mcp.ai/api/b3/get/evolucao/patrimonial` — Série histórica de evolução do patrimônio na B3.
  - body: { data?: string, ap?: integer, account?: string }
- `POST https://api.mcp.ai/api/b3/get/patrimonio` — Patrimônio total consolidado na B3 (soma de todas as corretoras) numa data. Retorna { valor, data }.
  - body: { data?: string, account?: string }
- `POST https://api.mcp.ai/api/b3/get/perfil` — Cadastro/perfil do investidor (identidade da conta B3 conectada).
  - body: { account?: string }
- `POST https://api.mcp.ai/api/b3/get/posicao` — Posição DETALHADA por ativo numa data: ticker (codigoNegociacao), quantidade, preço de fechamento, valor atualizado, ISIN, instituição. Agrupado por tipo de produto. Paginado.
  - body: { data?: string, pagina?: integer, account?: string }
- `POST https://api.mcp.ai/api/b3/get/ultima/atualizacao` — Data/hora da última carga de dados da B3 (a base é D-1). Use para saber quão fresca está a posição.
  - body: { account?: string }
- `POST https://api.mcp.ai/api/b3/list/accounts` — Lista as contas da Área do Investidor B3 conectadas a este install — id, label.
  - body: { account?: string }
- `POST https://api.mcp.ai/api/b3/list/ativos` — Drill-down nos ativos de UM tipo de produto (informe `codigoProduto`), com valor e percentual de cada ativo do grupo. Para a posição COMPLETA de todos os ativos, use b3_get_posicao.
  - body: { codigoProduto: string, agrupamento?: integer, account?: string }
- `POST https://api.mcp.ai/api/b3/list/instituicoes` — Instituições (corretoras) vinculadas ao investidor na B3.
  - body: { account?: string }
- `POST https://api.mcp.ai/api/b3/list/movimentacao` — Movimentação de ativos (entradas/saídas: transferências, subscrições, bonificações, etc.) num intervalo. Paginado.
  - body: { dataInicio?: string, dataFim?: string, pagina?: integer, account?: string }
- `POST https://api.mcp.ai/api/b3/list/negociacoes` — Negociações (compras/vendas) num intervalo de datas. Paginado por `page`.
  - body: { dataInicio?: string, dataFim?: string, page?: integer, account?: string }
- `POST https://api.mcp.ai/api/b3/list/ofertas/publicas` — Ofertas públicas (IPOs/subscrições) do investidor num intervalo. Paginado por `page`.
  - body: { dataInicio?: string, dataFim?: string, page?: integer, account?: string }
- `POST https://api.mcp.ai/api/b3/list/proventos/a/receber` — Proventos provisionados a receber (dividendos/JCP futuros) numa data de referência.
  - body: { data?: string, pagina?: integer, account?: string }
- `POST https://api.mcp.ai/api/b3/list/proventos/recebidos` — Proventos já recebidos (dividendos/JCP pagos) num intervalo de datas. Paginado.
  - body: { dataInicio?: string, dataFim?: string, page?: integer, account?: string }

## Example prompts
- "What's my total net worth on B3?"
- "Show my position by asset"
- "How much did I receive in dividends in the last 3 months?"

## More
- Page: https://mcp.ai/b3
- Agent spec (llms.txt): https://mcp.ai/b3/llms.txt
- Postman collection: https://mcp.ai/b3/postman.json