API de fundos de investimento: cota, carteira e CNPJ

A API de fundos da brapi cobre fundos listados e fundos sem ticker: FIAGRO, FI-Infra, FIF, FIDC, FIP e outras estruturas registradas na CVM. Os FIIs tradicionais ficam em uma seção própria.

O primeiro cuidado é o identificador. symbols serve para fundo que negocia na B3. cnpjs serve para o resto, o que inclui a maioria dos FIDCs e FIPs. Uma chamada a /api/v2/funds/list no começo evita mandar o fundo para o endpoint errado.

Qual endpoint usar

A documentação de fundos tem todos os parâmetros e schemas, com as rotas específicas de FIAGRO, FIDC e FIP separadas.

Descobrir o fundo antes da análise

A listagem aceita símbolo, CNPJ, busca textual, tipo e status, e devolve symbol, cnpj, assetType, nome, classificação e administrador.

curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://brapi.dev/api/v2/funds/list?symbols=JURO11,XPCA11"

Você também pode filtrar uma família inteira:

curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://brapi.dev/api/v2/funds/list?assetType=fiinfra&sortBy=symbol&sortOrder=asc&limit=20"

O final 11 não diz nada. Um código terminado em 11 pode ser FII, FIAGRO, ETF ou FI-Infra. assetType resolve isso com um valor normalizado.

Separar preço de valor patrimonial

O endpoint /api/v2/funds/indicators reúne preço de mercado, patrimônio, ativos, cotistas e valor patrimonial por cota. Cuidado com navPerShare: parece cotação e não é.

O preço sai da negociação. O valor patrimonial sai da conta que o administrador faz com ativos e passivos do fundo. A diferença entre os dois mede ágio ou deságio e nada mais. Cota com deságio pode estar barata ou pode estar com um problema que o mercado já viu.

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['BRAPI_TOKEN']}"}
response = requests.get(
    "https://brapi.dev/api/v2/funds/indicators",
    params={"symbols": "JURO11,XPCA11"},
    headers=headers,
    timeout=30,
)
response.raise_for_status()

for fund in response.json()["funds"]:
    print(fund["symbol"], fund.get("price"), fund.get("navPerShare"))

Confira os campos atuais no schema de indicadores. Trate ausência e null desde o início, porque nem toda família de fundo divulga os mesmos itens.

Montar uma série patrimonial

/api/v2/funds/nav/history aceita startDate, endDate, paginação e ordem, e devolve a coleção history junto com os dados de paginação.

curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://brapi.dev/api/v2/funds/nav/history?symbols=JURO11&startDate=2026-01-01&endDate=2026-06-30&sortOrder=asc"

A frequência vem do documento regulatório. FI e FIF podem ter registro diário. FIDC costuma ser mensal, por classe ou série. Comparar um fundo diário com um mensal sem reamostrar dá uma diferença que é só ruído de frequência.

Essa rota é valor patrimonial, não preço negociado. Para um fundo listado, o preço vem da rota adequada ao tipo do ativo.

Ler perfil e carteira

O perfil mensal mostra distribuição de cotistas, liquidez, concentração e exposição a crédito privado. Consulte com symbols ou cnpjs, recortando por datas ou pedindo uma referenceDate.

A carteira vem de posições oficiais da CVM. Use /api/v2/funds/portfolio?symbols=JURO11 para fundos FI e FIF. O parâmetro include permite pedir seções específicas quando o schema oferecer essa opção.

Mostre sempre a data de referência. O arquivo regulatório chega depois do mês informado, e uma carteira de março publicada em maio continua sendo uma carteira de março.

Algumas posições ficam confidenciais e o fundo informa só o total da categoria. Esse agregado é o dado. Distribuí-lo entre ativos plausíveis é inventar carteira.

Consultar rendimentos

/api/v2/funds/dividends cobre fundos listados que não são FIIs, e separa data de declaração, data com direito, pagamento e valor por cota.

params = {
    "symbols": "XPCA11",
    "startDate": "2026-01-01",
    "sortBy": "paymentDate",
    "sortOrder": "asc",
}
response = requests.get(
    "https://brapi.dev/api/v2/funds/dividends",
    params=params,
    headers=headers,
    timeout=30,
)
response.raise_for_status()

events = response.json()["dividends"]

Resista à tentação de completar datas faltantes com um offset fixo. Administradores seguem calendários próprios e o intervalo entre data-com e pagamento varia bastante. Guarde cada data como veio na fonte.

Fluxo para uma integração

1. Consulte /list e guarde symbol, cnpj e assetType.
2. Escolha uma rota compatível com o tipo encontrado.
3. Guarde referenceDate, requestedAt e o identificador do fundo.
4. Faça paginação até receber todos os registros necessários.
5. Mostre valores nulos sem substituir por zero.

Esse fluxo cobre os dois erros que mais aparecem: misturar preço com patrimônio e juntar registros de meses diferentes na mesma comparação.

Crie sua chave no painel da brapi e teste a consulta com um fundo que você já acompanha.