# brapi - API de ações da bolsa de valores brasileira
**URL:** https://brapi.dev/
## Sobre a brapi
Acesse o mercado financeiro em poucos segundos. A API mais confiável do Brasil entrega preços históricos (OHLCV), dividendos detalhados e fundamentos completos para seus apps e estratégias financeiras — integrada em minutos.
* **Documentação clara e objetiva**
* **API simples e completa**
* **Fácil de usar, rápida e estável**
---
## Exemplo de Uso (Cotação)
### Requisição
```bash
curl https://brapi.dev/api/quote/PETR4
```
### Resposta
```json
{
"results": [
{
"currency": "BRL",
"marketCap": 406927019658,
"shortName": "PETROBRAS PN EDR N2",
"longName": "Petróleo Brasileiro S.A. - Petrobras",
"regularMarketChange": 0.82,
"regularMarketChangePercent": 2.734,
"regularMarketTime": "2025-05-02T20:07:46.000Z",
"regularMarketPrice": 30.81,
"regularMarketDayHigh": 30.81,
"regularMarketDayRange": "29.97 - 30.81",
"regularMarketDayLow": 29.97,
"regularMarketVolume": 32881800,
"regularMarketPreviousClose": 29.99,
"regularMarketOpen": 30.29,
"fiftyTwoWeekRange": "29.96 - 42.09",
"fiftyTwoWeekLow": 29.96,
"fiftyTwoWeekHigh": 42.09,
"symbol": "PETR4",
"priceEarnings": 10.864275891251454,
"earningsPerShare": 2.8358848,
"logourl": "https://icons.brapi.dev/icons/PETR4.svg"
}
],
"requestedAt": "2025-05-04T01:30:20.521Z",
"took": "8ms"
}
```
---
## Empresas e Parceiros que utilizam
* Banco Banestes
* Toro Investimentos
* Suno Research
* Grupo Primo
* PicPay
* A Supernova
---
## Principais Funcionalidades
### Análise Fundamentalista
Balanços, DREs e múltiplos direto da CVM, sem bagunça ou parsing manual. Balanço Patrimonial, Demonstrativo de Resultados, Fluxo de Caixa, Valor Adicionado, Dados financeiros e Indicadores financeiros.
### Preços Históricos (OHLCV)
Séries completas para backtests e gráficos que impressionam.
### Dividendos Detalhados
Datas com, ex e pagamento — otimize sua renda passiva com dados completos.
### Moedas e Criptomoedas
Taxas de câmbio e preços históricos de criptomoedas atualizados.
### Inflação e Taxa Selic histórica
Dados de inflação, como IPCA e IGP-M, para análises econômicas e financeiras.
---
## Exemplo de Dados Fundamentalistas (WEGE3)
### Requisição
```bash
curl https://brapi.dev/api/quote/WEGE3?modules=balanceSheetHistory,balanceSheetHistoryQuarterly
```
### Resposta (Estrutura de Dados)
```json
{
"symbol": "WEGE3", // Símbolo do ativo
"balanceSheetHistory": [ // Histórico Anual do Balanço Patrimonial
{
"type": "yearly", // Tipo (Periodicidade: Anual)
"endDate": "2024-12-31", // Data de Fim do Período
"cash": 7347599000, // Caixa e Equivalentes de Caixa
"shortTermInvestments": 648477000, // Investimentos de Curto Prazo
"netReceivables": 7394411000, // Contas a Receber Líquidas
"inventory": 9903951000, // Estoques
"otherCurrentAssets": 1109507000, // Outros Ativos Circulantes
"totalCurrentAssets": 27221359000, // Total de Ativos Circulantes
"longTermInvestments": 71808000, // Investimentos de Longo Prazo
"propertyPlantEquipment": 9933659000, // Imobilizado
"otherAssets": 14268342000, // Outros Ativos Não Circulantes
"totalAssets": 41489701000, // Total de Ativos
"accountsPayable": 3778116000, // Contas a Pagar (Fornecedores)
"shortLongTermDebt": 2850956000, // Dívida de Curto Prazo
"longTermDebt": 744281000, // Dívida de Longo Prazo
"otherLiab": 1212384000, // Outros Passivos Não Circulantes
"totalCurrentLiabilities": 15454265000, // Total de Passivos Circulantes
"totalLiab": 41489701000, // Total de Passivos
"commonStock": 7504517000, // Capital Social
"retainedEarnings": null, // Lucros Retidos / Prejuízos Acumulados
"treasuryStock": null, // Ações em Tesouraria
"otherStockholderEquity": -155191000, // Outros Componentes do Patrimônio Líquido
"totalStockholderEquity": 23125217000, // Total do Patrimônio Líquido
"netTangibleAssets": null, // Ativos Tangíveis Líquidos
"goodWill": null, // Goodwill (Ágio)
"intangibleAssets": 2820655000, // Ativos Intangíveis
"deferredLongTermAssetCharges": null, // Encargos Diferidos de Ativos LP
"deferredLongTermLiab": 170520000, // Passivos Fiscais Diferidos LP
"minorityInterest": 920996000, // Participação de Não Controladores
"capitalSurplus": null, // Reservas de Capital
"accountsReceivableFromClients": 7394411000, // Contas a Receber de Clientes
"taxesToRecover": 817414000, // Impostos a Recuperar
"longTermAssets": 14268342000, // Total do Ativo Não Circulante
"longTermRealizableAssets": 1442220000, // Ativo Realizável a Longo Prazo
"longTermDeferredTaxes": 1141821000, // Tributos Diferidos (Ativo Não Circulante)
"shareholdings": 71808000, // Participações Societárias
"otherNonCurrentAssets": 283265000, // Outros Ativos Não Circulantes (detalhe)
"nonCurrentAssets": 20785497000, // Total do Ativo Não Circulante (sinônimo de longTermAssets)
"shareholdersEquity": 23125217000, // Patrimônio Líquido (sinônimo de totalStockholderEquity)
"realizedShareCapital": 7504517000, // Capital Social Realizado (sinônimo de commonStock)
"capitalReserves": -155191000, // Reservas de Capital (sinônimo de capitalSurplus)
"revaluationReserves": 3631000, // Reservas de Reavaliação
"profitReserves": 11466140000, // Reservas de Lucros
"equityValuationAdjustments": 277498000, // Ajustes de Avaliação Patrimonial
"otherComprehensiveResults": 3107626000, // Outros Resultados Abrangentes
"currentLiabilities": 15454265000, // Total do Passivo Circulante (sinônimo de totalCurrentLiabilities)
"socialAndLaborObligations": 728469000, // Obrigações Sociais e Trabalhistas
"providers": 3778116000, // Fornecedores (sinônimo de accountsPayable)
"taxObligations": 799564000, // Obrigações Fiscais (Circulante)
"loansAndFinancing": 2850956000, // Empréstimos e Financiamentos (Circulante)
"loansAndFinancingInNationalCurrency": 6089000, // Empréstimos e Financiamentos (Moeda Nacional)
"loansAndFinancingInForeignCurrency": 2844867000, // Empréstimos e Financiamentos (Moeda Estrangeira)
"otherObligations": 4330000, // Outras Obrigações (Circulante)
"nonCurrentLiabilities": 2910219000, // Total do Passivo Não Circulante
"longTermLoansAndFinancing": 744281000, // Empréstimos e Financiamentos (Não Circulante)
"longTermLoansAndFinancingInNationalCurrency": 248894000, // Empréstimos e Financiamentos LP (Moeda Nacional)
"longTermLoansAndFinancingInForeignCurrency": 495387000, // Empréstimos e Financiamentos LP (Moeda Estrangeira)
"otherLongTermObligations": 1212384000, // Outras Obrigações (Não Circulante)
"longTermProvisions": 783034000, // Provisões (Não Circulante)
"updatedAt": "2024-12-31" // Atualizado Em
}
],
"balanceSheetHistoryQuarterly": [
// Estrutura similar à anual, mas com type: "quarterly"
]
}
```
---
## Casos de Uso
1. **Integração de Dados do Mercado Financeiro:** Conecte cotações, históricos e fundamentos em seus apps, planilhas ou sistemas com nossa API REST.
2. **Análises Históricas e Backtesting:** Acesse séries temporais detalhadas (OHLCV) para backtests precisos.
3. **Dashboards e Aplicações:** Desenvolva rastreadores de portfólio ou plataformas de análise.
4. **Integração com IA (MCP):** Conecte dados financeiros diretamente em assistentes de IA como Cursor, Claude e VS Code via Model Context Protocol.
## Páginas de mercado para agentes
As páginas públicas de mercado também possuem representações canônicas em Markdown:
* **Lista de ativos:** [https://brapi.dev/quotes.md](https://brapi.dev/quotes.md)
* **Ativo individual:** `https://brapi.dev/quote/{TICKER}.md` — por exemplo, [PETR4.md](https://brapi.dev/quote/PETR4.md)
* **Negociação de conteúdo:** envie `Accept: text/markdown` para a URL HTML equivalente.
### Exemplo de Log de Aplicação
```text
[2023-12-15 14:23:45] INFO Iniciando análise de dados históricos.
[2023-12-15 14:23:47] ACTION Obtendo série histórica OHLCV...
[2023-12-15 14:23:50] DECISION Análise de padrões. Confiança: 85%
[2023-12-15 14:23:52] WARNING Anomalia detectada em indicadores.
[2023-12-15 14:23:55] ERROR Backtest concluído. Resultado disponível.
```
---
## Planos e Preços
### Gratuito
**R$ 0/ano**
Ideal para testar a API, projetos pessoais ou acadêmicos.
* Até 15.000 requisições por mês
* Consulta de 1 ativo por requisição
* Dados históricos de cotações dos últimos 3 meses
* Acesso instantâneo com dados atualizados a cada 30 minutos
* Dados Fundamentalistas Profundos (BP, DRE, DFC)
* Histórico Completo de Dividendos
### Startup
**R$ 119,99/mes**
**R$ 1.199,90/ano** (Economize 2 meses no plano anual)
Ideal para desenvolvedores e investidores que precisam de mais profundidade.
* Volume: 150.000 requisições/mês
* Consultas Múltiplas: Até 10 ativos por requisição
* Dados atualizados a cada 15 minutos
* Histórico de Cotações: Último ano completo
* Dados Fundamentalistas Anuais (últimos 5 anos) e DREs anuais
* Dados Fundamentalistas Trimestrais e Histórico Profundo (desde 2009)
### Pro (Mais Popular)
**R$ 139,99/mês**
**R$ 1.399,90/ano** (Economize 2 meses no plano anual)
A escolha definitiva para análises profundas e uso profissional.
* Volume: 500.000 requisições/mês
* Consultas Múltiplas: Até 20 ativos por requisição
* Dados atualizados a cada 5 minutos
* Dados Fundamentalistas Completos (BP, DRE, DFC, DVA desde 2009)
* Histórico de Cotações Extenso: 10+ anos
* Indicadores Financeiros Avançados Prontos (P/L, P/VP, ROE, etc.)
* Suporte Técnico Prioritário Dedicado
---
## Integração
Nossa API REST suporta qualquer linguagem de programação. Exemplos comuns incluem:
* JavaScript
* Java
* Go
* Python
* TypeScript
---
## Blog e Tutoriais Recentes
* **Como Usar a API de Ações Brasileiras com Python: Guia Prático 2025:** Aprenda a integrar a API brapi.dev com Python usando requests, Pandas e Flask.
* **API de Ações Brasileiras com TypeScript e JavaScript:** Guia completo de integração usando fetch, Axios, Next.js e Node.js.
* **Como Importar Cotações da bolsa brasileira no Excel:** Tutorial usando Power Query e VBA.
---
## Informações Legais e Rodapé
**ASL TECNOLOGIA LTDA 2025**
CNPJ: 41.182.041/0001-23
Parceiro Microsoft for Startups
**Fontes de Dados:** CVM, BCB, Tesouro Direto.
**Isenção de Responsabilidade:** A Brapi fornece informações estritamente informativas provenientes de fontes públicas. Não fornecemos orientações de compra ou venda. Não nos responsabilizamos por decisões financeiras tomadas com base nas informações disponibilizadas. Recomendamos consultoria financeira independente.
```
# Comece a usar a API da brapi.dev
URL: /docs.mdx
Guia rápido para começar a usar a API da brapi.dev. Encontre o endpoint certo para cotações, histórico, dividendos, fundamentos, FIIs, câmbio, cripto e indicadores econômicos do mercado financeiro brasileiro.
***
title: 'Comece a usar a API da brapi.dev'
description:
'Guia rápido para começar a usar a API da brapi.dev. Encontre o endpoint certo
para cotações, histórico, dividendos, fundamentos, FIIs, câmbio, cripto e
indicadores econômicos do mercado financeiro brasileiro.'
howToSteps:
* name: 'Obtenha sua chave de API (opcional para teste)'
text: 'Para testar, use as 4 ações gratuitas (PETR4, MGLU3, VALE3, ITUB4) sem token. Para produção, crie uma conta no dashboard para gerar seu token.'
* name: 'Faça sua primeira requisição'
text: 'Execute curl "[https://brapi.dev/api/v2/stocks/quote?symbols=PETR4](https://brapi.dev/api/v2/stocks/quote?symbols=PETR4)" no terminal para testar sem token, ou adicione o header Authorization: Bearer SEU\_TOKEN para acessar todos os ativos.'
* name: 'Receba os dados em JSON'
text: 'A API retorna um JSON com results\[].data contendo preço, variação, volume, market cap e outros campos da cotação.'
howToTools:
* 'Terminal ou linha de comando'
* 'cURL ou cliente HTTP'
* 'Navegador web'
howToSupplies:
* 'Conta brapi.dev (opcional para teste)'
* 'Token de API brapi.dev (opcional para teste)'
***
import { Callout } from 'fumadocs-ui/components/callout';
import { Card, Cards } from 'fumadocs-ui/components/card';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
A **brapi.dev** é uma API REST para dados financeiros brasileiros. Você acessa
ações, FIIs, BDRs, ETFs, índices, criptomoedas, câmbio e indicadores
econômicos em JSON, com dados de fontes como **CVM**, **IBGE** e **Banco Central
do Brasil**.
O objetivo da brapi é ser o jeito mais simples de levar esses dados para
produtos, planilhas, dashboards, robôs, assistentes de IA e sistemas internos.
## Primeira requisição
Você pode testar agora com 4 ações brasileiras populares, sem token ou cadastro:
**PETR4** (Petrobras) • **MGLU3** (Magazine Luiza) • **VALE3** (Vale) •
**ITUB4** (Itaú)
```bash title="Cotação de PETR4"
curl "https://brapi.dev/api/v2/stocks/quote?symbols=PETR4"
```
```bash title="Múltiplas ações"
curl "https://brapi.dev/api/v2/stocks/quote?symbols=PETR4,VALE3,MGLU3"
```
```bash title="Histórico e dividendos"
curl "https://brapi.dev/api/v2/stocks/historical?symbols=PETR4&range=1mo&interval=1d"
curl "https://brapi.dev/api/v2/stocks/dividends?symbols=ITUB4"
```
Essas ações de teste permitem consultar cotação, histórico, dividendos e dados
financeiros para experimentar a API antes de criar uma conta.
#### Teste primeiro, autentique depois
PETR4, MGLU3, VALE3 e ITUB4 funcionam sem token para você testar a API.
Para acessar todos os ativos e usar em produção, crie sua conta e gere um
token no dashboard.
Seu token estará disponível na seção "Chaves de API" do seu
**[Dashboard](/dashboard)** após o login.
#### Use o token no backend
Em produção, envie o token no header `Authorization`:
```bash title="Terminal (cURL) - Produção"
curl --request GET \
--url 'https://brapi.dev/api/v2/stocks/quote?symbols=PETR4' \
--header 'Authorization: Bearer SEU_TOKEN'
```
#### Leia a resposta
A resposta vem em JSON, com um item em `results` para cada ticker solicitado.
```jsonc title="Resposta da API (JSON)"
{
"results": [
{
"requestedSymbol": "PETR4",
"symbol": "PETR4",
"changed": false,
"data": {
"shortName": "PETROBRAS PN",
"longName": "Petróleo Brasileiro S.A. - Petrobras",
"currency": "BRL",
"regularMarketPrice": 38.50,
"regularMarketDayHigh": 39.00,
"regularMarketDayLow": 38.20,
"regularMarketChange": 0.30,
"regularMarketChangePercent": 0.78,
"regularMarketTime": "2026-06-14T17:08:00.000Z",
"marketCap": 503100000000,
"regularMarketVolume": 45678901,
"logourl": "https://icons.brapi.dev/icons/PETR4.svg"
}
}
],
"requestedAt": "2026-06-14T17:08:02.000Z",
"took": 245
}
```
## Encontre o Dado Certo
Use esta tabela para ir direto ao endpoint do dado que você precisa.
| Preciso de | Endpoint | Documentação | Dados principais |
| --------------------------- | -------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------- |
| Buscar e validar tickers B3 | `/api/v2/tickers` | [Tickers disponíveis](/docs/tickers) | Símbolo, nome, tipo, setor e filtros para autocomplete ou screener |
| Cotação atual | `/api/v2/stocks/quote?symbols=PETR4,VALE3` | [Cotação de ações](/docs/acoes/cotacao) | Preço, variação, volume, market cap, faixa do dia, faixa de 52 semanas e logo |
| Histórico de preços | `/api/v2/stocks/historical?symbols=PETR4&range=1y&interval=1d` | [Histórico de ações](/docs/acoes/historico) | Série OHLCV, volume e preço ajustado |
| Dividendos e JCP | `/api/v2/stocks/dividends?symbols=ITUB4` | [Dividendos de ações](/docs/acoes/dividendos) | Dividendos, JCP, bonificações e subscrições de ações |
| Perfil da empresa | `/api/v2/stocks/profile?symbols=PETR4` | [Perfil de ações](/docs/acoes/perfil) | CNPJ, setor, indústria, endereço, site, descrição e logo |
| Múltiplos e estatísticas | `/api/v2/stocks/statistics?symbols=WEGE3&mode=current` | [Estatísticas de ações](/docs/acoes/estatisticas) | P/L, P/VP, beta, dividend yield, EPS, market cap e séries históricas |
| Dados financeiros | `/api/v2/stocks/financial-data?symbols=WEGE3&mode=current` | [Dados financeiros](/docs/acoes/dados-financeiros) | Receita, lucro, EBITDA, margens, dívida e fluxo de caixa livre |
| Balanço patrimonial | `/api/v2/stocks/balance-sheet?symbols=PETR4&period=annual` | [Balanço patrimonial](/docs/acoes/balanco-patrimonial) | Ativos, passivos, patrimônio líquido, caixa e dívida |
| DRE | `/api/v2/stocks/income-statement?symbols=PETR4&period=annual` | [DRE de ações](/docs/acoes/dre) | Receita, custos, lucro bruto, despesas, EBITDA e lucro líquido |
| Fluxo de caixa | `/api/v2/stocks/cash-flow?symbols=PETR4&period=annual` | [Fluxo de caixa](/docs/acoes/fluxo-de-caixa) | Caixa operacional, investimento, financiamento e caixa livre |
| DVA | `/api/v2/stocks/value-added?symbols=PETR4&period=annual` | [Valor adicionado](/docs/acoes/valor-adicionado) | Demonstração de valor adicionado anual ou trimestral |
| Rendimentos de FIIs | `/api/v2/fii/dividends?symbols=MXRF11` | [FIIs](/docs/fiis) | Rendimentos, histórico, relatórios, imóveis e carteira de fundos imobiliários |
## Autenticação
Use o header `Authorization` em código backend e produção. Ele evita expor o
token em URLs, logs e histórico de navegação.
```bash
curl -H "Authorization: Bearer SEU_TOKEN" \
"https://brapi.dev/api/v2/stocks/quote?symbols=PETR4"
```
```bash
curl "https://brapi.dev/api/v2/stocks/quote?symbols=PETR4&token=SEU_TOKEN"
```
O parâmetro `?token=` funciona para ferramentas que não suportam headers
(Google Sheets, Excel Power Query, Notion). Tokens na URL podem aparecer em
histórico do navegador, logs de servidor e ferramentas de analytics.
**Prefira header auth sempre que possível.**
Nunca exponha seu token no código do lado do cliente. Em aplicações web, faça
as chamadas para a API da brapi.dev a partir do seu backend.
## Principais Conceitos
* **URL base:** todas as requisições usam `https://brapi.dev/api`.
* **Símbolos:** endpoints de mercado usam `symbols=PETR4,VALE3` para consultar
um ou mais ativos na mesma chamada.
* **Resposta:** endpoints por ativo retornam `results[]`; o payload principal
fica em `results[].data`.
* **Datas:** use `startDate` e `endDate` no formato `YYYY-MM-DD` quando quiser
controlar a janela de consulta.
* **Períodos contábeis:** fundamentos aceitam `period=annual` ou
`period=quarterly`; alguns endpoints também aceitam `mode=current` ou
`mode=history`.
## Explore Nossos Endpoints
Navegue pelas seções para acessar todos os dados disponíveis.
## SDKs Oficiais
Use nossas bibliotecas oficiais quando quiser integração com tipos, helpers e
tratamento de erros pronto.
## Exemplos Práticos
Veja como buscar os mesmos dados em diferentes ambientes.
```bash title="Cotação, histórico e fundamentos"
curl "https://brapi.dev/api/v2/stocks/quote?symbols=PETR4,VALE3"
curl -H "Authorization: Bearer SEU_TOKEN" \
"https://brapi.dev/api/v2/stocks/historical?symbols=PETR4&range=1y&interval=1d"
curl -H "Authorization: Bearer SEU_TOKEN" \
"https://brapi.dev/api/v2/stocks/income-statement?symbols=PETR4&period=annual"
```
```python title="requests"
import requests
token = "SEU_TOKEN"
response = requests.get(
"https://brapi.dev/api/v2/stocks/quote",
headers={"Authorization": f"Bearer {token}"},
params={"symbols": "PETR4,VALE3"},
)
response.raise_for_status()
data = response.json()
for item in data["results"]:
quote = item["data"]
print(item["symbol"], quote["regularMarketPrice"])
```
```javascript title="fetch"
const response = await fetch(
'https://brapi.dev/api/v2/stocks/quote?symbols=PETR4,VALE3',
{
headers: {
Authorization: `Bearer ${process.env.BRAPI_API_TOKEN}`,
},
},
);
if (!response.ok) {
throw new Error(`Erro HTTP ${response.status}`);
}
const data = await response.json();
for (const item of data.results) {
console.log(item.symbol, item.data.regularMarketPrice);
}
```
## Próximos Passos
* **[Consulte cotações de ações](/docs/acoes/cotacao):** comece com preço atual,
variação e volume.
* **[Monte seu fluxo com tickers](/docs/tickers):** busque símbolos, valide
entradas e descubra cobertura por endpoint.
* **[Veja todos os exemplos](/docs/examples):** aplique a API em planilhas,
backends, sites e integrações.
# Servidor MCP para IAs
URL: /docs/mcp.mdx
Conecte a brapi a qualquer assistente de IA com uma única URL. Funciona com Claude, ChatGPT, Cursor, VS Code, n8n e mais de 100 outros clientes.
***
title: Servidor MCP para IAs
description:
Conecte a brapi a qualquer assistente de IA com uma única URL. Funciona
com Claude, ChatGPT, Cursor, VS Code, n8n e mais de 100 outros clientes.
howToSteps:
* name: 'Crie sua conta'
text: 'Acesse brapi.dev e crie uma conta gratuita.'
* name: 'Adicione o servidor MCP no seu cliente de IA'
text: 'Cole a URL do servidor brapi nas configurações de MCP do seu cliente.'
* name: 'Faça uma pergunta'
text: 'Pergunte sobre cotações, FIIs, câmbio ou indicadores em linguagem natural.'
howToTools:
* 'Cliente de IA com suporte a MCP (Claude, ChatGPT, Cursor, VS Code, n8n, etc.)'
howToSupplies:
* 'Conta brapi.dev (gratuita)'
***
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Callout } from 'fumadocs-ui/components/callout';
import { Card, Cards } from 'fumadocs-ui/components/card';
O servidor MCP da brapi conecta seu assistente de IA aos dados do mercado
financeiro brasileiro. Com uma única URL, sua IA passa a buscar cotações de
ações, FIIs, câmbio, criptomoedas e indicadores econômicos enquanto você
conversa com ela.
## URL do servidor
```text
https://brapi.dev/api/mcp/mcp
```
Essa é a única URL que você precisa. Copie e cole no seu cliente de IA. Na
primeira vez, ele abre o navegador para você fazer login na brapi.
## Configure seu cliente
Rode no terminal:
```bash
claude mcp add --transport http brapi https://brapi.dev/api/mcp/mcp
```
O Claude abre o navegador para você fazer login.
Para verificar a instalação:
```bash
claude mcp list
```
Abra o arquivo de configuração do Claude:
* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
E adicione:
```json
{
"mcpServers": {
"brapi": {
"command": "npx",
"args": ["mcp-remote", "https://brapi.dev/api/mcp/mcp"]
}
}
}
```
Reinicie o Claude. Na primeira pergunta, ele abre o navegador para você fazer
login na brapi.
Rode no terminal para adicionar o servidor:
```bash
codex mcp add brapi --url https://brapi.dev/api/mcp/mcp
```
Em seguida, faça o login com OAuth:
```bash
codex mcp login brapi
```
O Codex abre o navegador para você fazer login na brapi.
Se o Codex disser que não suporta servidores HTTP, abra `~/.codex/config.toml`
e adicione:
```toml
[features]
experimental_use_rmcp_client = true
```
Isso ativa o cliente de MCP HTTP do Codex.
1. Abra **Configurações → Conectores** no ChatGPT
2. Clique em **Adicionar conector personalizado**
3. Cole a URL: `https://brapi.dev/api/mcp/mcp`
4. Faça login na brapi quando o ChatGPT pedir
Conectores personalizados estão disponíveis nos planos pagos do ChatGPT (Plus,
Pro, Business e Enterprise).
Abra `~/.cursor/mcp.json` (global) ou `.cursor/mcp.json` (do projeto) e
adicione:
```json
{
"mcpServers": {
"brapi": {
"command": "npx",
"args": ["mcp-remote", "https://brapi.dev/api/mcp/mcp"]
}
}
}
```
Reinicie o Cursor. Na primeira pergunta, ele abre o navegador para login.
Abra `.vscode/mcp.json` no seu projeto (ou nas configurações do usuário) e
adicione:
```json
{
"mcp": {
"servers": {
"brapi": {
"url": "https://brapi.dev/api/mcp/mcp"
}
}
}
}
```
Você precisa do **VS Code 1.99 ou maior** com a extensão **GitHub Copilot**.
Habilite `chat.mcp.enabled` nas configurações.
1. Adicione um node **AI Agent** no seu workflow
2. Conecte um node **MCP Client Tool**
3. Em **Server URL**, cole: `https://brapi.dev/api/mcp/mcp`
4. Em **Authentication**, escolha **OAuth2**
Pronto para criar automações como alertas de preço, relatórios diários e
notificações no Slack/Discord.
[Documentação oficial do MCP Client Tool no n8n](https://docs.n8n.io/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.mcpclienttool/)
O servidor da brapi funciona com qualquer cliente que suporte MCP, incluindo
**Windsurf**, **Cline**, **Zed**, **Continue**, **Amazon Q**, **Gemini CLI**,
**goose** e mais de 100 outros.
Em qualquer um deles, use a URL:
```text
https://brapi.dev/api/mcp/mcp
```
Se o seu cliente não fizer login automático no navegador, gere um token no
[dashboard da brapi](https://brapi.dev) e use o cabeçalho:
```text
Authorization: Bearer SEU_TOKEN
```
## Exemplos de perguntas
```txt
Qual é a cotação atual da PETR4?
```
```txt
Compare PETR4 e VALE3 no último mês
```
```txt
Liste as 5 ações com maior volume de negociação hoje
```
```txt
Quais FIIs do segmento de logística têm o maior dividend yield?
```
```txt
Mostre os rendimentos pagos pelo MXRF11 nos últimos 12 meses
```
```txt
Qual a taxa SELIC hoje e como ela mudou nos últimos 12 meses?
```
```txt
Compare a evolução do IPCA e IGP-M nos últimos 5 anos
```
```txt
Qual o preço do Bitcoin em reais agora?
```
```txt
Quais são os vencimentos de opções disponíveis para PETR4?
```
```txt
Mostre delta, gamma e volatilidade implícita das opções de PETR4 no próximo vencimento
```
## Ferramentas disponíveis
A IA tem acesso a 69 ferramentas. As 9 primeiras funcionam sem login; as
demais precisam de uma conta brapi.
### Descoberta (sem login)
| Ferramenta | O que faz |
| ----------------------------------- | ----------------------------------------------------- |
| `get_available_stocks` | Lista ações, FIIs, BDRs e índices brasileiros |
| `get_available_currencies` | Lista moedas (USD-BRL, EUR-BRL, etc.) |
| `get_available_cryptocurrencies` | Lista criptomoedas (BTC, ETH, etc.) |
| `get_available_inflation_countries` | Lista países com dados de inflação |
| `get_tickers` | Busca e filtra tickers B3 disponíveis |
| `get_ticker_renames` | Lista renomes conhecidos de tickers |
| `resolve_tickers` | Resolve tickers antigos para o ticker atual |
| `get_ticker_coverage` | Mostra quais endpoints existem para cada ticker |
| `get_macro_series_available` | Lista séries macroeconômicas (Selic, IPCA, CDI, etc.) |
### Ações, câmbio e criptomoedas
| Ferramenta | O que faz |
| ---------------------------- | ------------------------------------------------------- |
| `get_stock_quotes` | Endpoint legado de cotações, módulos e histórico |
| `get_stock_quote` | Snapshot v2: preço, variação, volume, market cap e logo |
| `get_stock_historical` | Histórico OHLCV v2 de ações |
| `get_stock_dividends` | Dividendos e JCP v2 de ações |
| `get_stock_profile` | Perfil cadastral/empresarial v2 |
| `get_stock_statistics` | Estatísticas atuais ou históricas v2 |
| `get_stock_financial_data` | Dados financeiros atuais ou históricos v2 |
| `get_stock_balance_sheet` | Balanço patrimonial anual ou trimestral v2 |
| `get_stock_income_statement` | DRE anual ou trimestral v2 |
| `get_stock_cash_flow` | Fluxo de caixa anual ou trimestral v2 |
| `get_stock_value_added` | Demonstração de valor adicionado v2 |
| `get_currency_rates` | Taxas de câmbio em tempo real |
| `get_crypto_prices` | Preços de criptomoedas |
### Indicadores macroeconômicos
| Ferramenta | O que faz |
| ------------------------- | ------------------------------------------------------ |
| `get_macro_series` | Histórico de séries macro (Selic, IPCA, IGP-M, CDI...) |
| `get_macro_series_latest` | Valor mais recente de cada série macro |
| `get_inflation_data` | Dados de inflação (IPCA, IGPM) |
| `get_prime_rate_data` | Taxa SELIC e histórico |
### Fundos imobiliários (FIIs)
| Ferramenta | O que faz |
| ---------------------------- | -------------------------------------------------------- |
| `get_fii_list` | Lista FIIs com filtros por segmento, setor e mandato |
| `get_fii_indicators` | Indicadores atuais (P/VP, dividend yield, patrimônio...) |
| `get_fii_indicators_history` | Evolução mensal dos indicadores |
| `get_fii_historical` | Histórico diário de preços (OHLCV) |
| `get_fii_properties` | Imóveis físicos, área e vacância consolidada |
| `get_fii_properties_history` | Evolução trimestral de imóveis, área e vacância |
| `get_fii_portfolio` | Composição normalizada: CRIs, FoFs, imóveis e direitos |
| `get_fii_portfolio_history` | Evolução trimestral da composição da carteira |
| `get_fii_reports` | Relatórios mensais da CVM com composição da carteira |
| `get_fii_dividends` | Histórico de rendimentos pagos |
| `get_fii_financials` | Relatórios financeiros DFIN oficiais de FIIs |
| `get_fii_annual_reports` | Informes anuais oficiais de FIIs |
### Fundos brasileiros
| Ferramenta | O que faz |
| ----------------------- | ------------------------------------------------------------ |
| `get_funds_list` | Lista FIIs, FIAGROs, FI-Infra/FIFs, FIDCs e FIPs |
| `get_funds_indicators` | Preço, NAV oficial, P/NAV, patrimônio, ativos e cotistas |
| `get_funds_nav_history` | NAV diário FI/FIF e mensal FIDC com rentabilidade por classe |
| `get_funds_profile` | Perfil mensal CVM FI/FIF: investidores, risco e liquidez |
| `get_funds_dividends` | Dividendos oficiais de FIAGRO, FI-Infra/FIF, FIDC e FIP |
| `get_funds_portfolio` | Carteira CVM CDA agrupada por tipo de ativo |
| `get_fiagro_reports` | Relatórios mensais FIAGRO por símbolo ou CNPJ |
| `get_fiagro_portfolio` | Alocações FIAGRO em seções normalizadas |
| `get_fidc_reports` | Relatórios mensais FIDC, normalmente por CNPJ |
| `get_fidc_portfolio` | Setores, vencimentos, risco, cotas e cotistas de FIDCs |
| `get_fip_reports` | Relatórios FIP trimestrais/quadrimestrais por CNPJ |
### Tesouro Direto
| Ferramenta | O que faz |
| --------------------------------- | ---------------------------------------------------- |
| `get_treasury_list` | Lista títulos com filtros por indexador e vencimento |
| `get_treasury_indicators` | Taxas e preços indicativos atuais |
| `get_treasury_indicators_history` | Histórico diário de taxas e preços |
### Opções
| Ferramenta | O que faz |
| ------------------------------ | ---------------------------------------------- |
| `get_option_expirations` | Vencimentos disponíveis de um ativo |
| `get_option_strikes` | Strikes disponíveis em um vencimento |
| `get_option_chain` | Cadeia de opções de um vencimento |
| `get_option_historical` | Histórico diário de uma série específica |
| `get_option_analytics` | Gregas e volatilidade implícita por vencimento |
| `get_option_analytics_history` | Histórico diário de gregas e IV de uma série |
### Futuros e opções sobre futuros
| Ferramenta | O que faz |
| -------------------------------------- | -------------------------------------------- |
| `get_futures_list` | Lista contratos futuros com filtros |
| `get_futures_quote` | Cotação EOD de contratos futuros |
| `get_futures_specs` | Especificações de contratos futuros |
| `get_futures_historical` | Histórico diário de um contrato futuro |
| `get_futures_term_structure` | Curva de vencimentos de um ativo futuro |
| `get_futures_option_expirations` | Vencimentos de opções sobre futuros |
| `get_futures_option_strikes` | Strikes de opções sobre futuros |
| `get_futures_option_chain` | Cadeia de opções sobre futuros |
| `get_futures_option_historical` | Histórico diário de uma opção sobre futuro |
| `get_futures_option_analytics` | Gregas e IV de opções sobre futuros |
| `get_futures_option_analytics_history` | Histórico diário de gregas e IV de uma série |
## Limites por plano
As consultas via MCP usam o mesmo limite da API REST.
| Plano | Requisições/mês | Ideal para |
| ------------ | --------------- | ---------------------------- |
| **Gratuito** | 15.000 | Testes e projetos pessoais |
| **Startup** | 150.000 | Startups e pequenas empresas |
| **Pro** | 500.000 | Aplicações de alto volume |
[Ver todos os planos](https://brapi.dev/pricing)
## Próximos passos
***
Os dados são fornecidos apenas para fins informativos e não constituem
aconselhamento financeiro. Consulte sempre um profissional qualificado antes
de tomar decisões de investimento.
# Schema OpenAPI
URL: /docs/openapi.mdx
Especificação completa da API brapi em formato OpenAPI 3.0
***
title: 'Schema OpenAPI'
description: 'Especificação completa da API brapi em formato OpenAPI 3.0'
-------------------------------------------------------------------------
import { Button } from '~/components/ui/button'
import { DownloadSimple, Eye } from '@phosphor-icons/react/ssr'
import { OpenApiSchemaBlock } from '~/components/docs/openapi-schema-block';
A especificação completa da API brapi está disponível no formato OpenAPI 3.0
(anteriormente conhecido como Swagger). Esta documentação técnica contém todos
os endpoints, parâmetros, schemas de resposta e exemplos de uso.
## Download e Visualização
Você pode baixar o arquivo JSON da especificação ou visualizar o arquivo JSON
online.
## Schema Completa
Especificação completa da API brapi em formato OpenAPI 3.0 para dados de ações, moedas, criptomoedas, inflação, etc.
## Como usar esta especificação
### 1. **Ferramentas de Desenvolvimento**
* **Swagger UI**: Visualize e teste a API interativamente
* **Postman**: Importe a especificação para criar coleções automaticamente
* **Insomnia**: Gere requisições baseadas na especificação
* **OpenAPI Generator**: Gere SDKs em diversas linguagens
### 2. **Integração em Projetos**
* **Frontend**: Use para gerar tipos TypeScript automaticamente
* **Backend**: Valide requisições e respostas contra o schema
* **Documentação**: Gere documentação automática para sua aplicação
### 3. **Validação e Testes**
* Valide suas requisições contra o schema oficial
* Use para testes automatizados de integração
* Garanta compatibilidade com futuras versões da API
## Informações Técnicas
* **Versão OpenAPI**: 3.0.0
* **Versão da API**: 3.0.0
* **Formato**: JSON
* **Atualização**: Automática a cada deploy
* **Compatibilidade**: Todas as ferramentas que suportam OpenAPI 3.0+
## Próximos Passos
1. **[Comece com a documentação geral](/docs)** para entender os conceitos
básicos
2. **[Explore os endpoints de ações](/docs/acoes)** para ver exemplos práticos
3. **[Veja exemplos de código](/docs/examples)** em diferentes linguagens
4. **[Configure sua conta](/dashboard)** para obter seu token de API
***
*Esta especificação é gerada automaticamente e sempre reflete o estado atual da
API brapi.*
# Listar Criptomoedas
URL: /docs/criptomoedas/available.mdx
Endpoints focados na obtenção de dados sobre Criptomoedas. Inclui consulta de cotações atuais em diversas moedas fiduciárias, dados históricos e listagem de criptomoedas suportadas pela API.
***
title: Listar Criptomoedas
description: >-
Endpoints focados na obtenção de dados sobre Criptomoedas. Inclui consulta de
cotações atuais em diversas moedas fiduciárias, dados históricos e listagem de
criptomoedas suportadas pela API.
full: true
keywords: brapi, api, documentação, criptomoedas
openGraph:
title: Listar Criptomoedas
description: >-
Endpoints focados na obtenção de dados sobre Criptomoedas. Inclui consulta
de cotações atuais em diversas moedas fiduciárias, dados históricos e
listagem de criptomoedas suportadas pela API.
type: website
locale: pt\_BR
lastUpdated: '2025-04-28T01:22:35.254Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/crypto/available
toc:
* depth: 2
title: Listar Todas as Criptomoedas Disponíveis
url: '#listar-todas-as-criptomoedas-disponíveis'
structuredData:
headings:
* content: Listar Todas as Criptomoedas Disponíveis
id: listar-todas-as-criptomoedas-disponíveis
contents:
* content: >-
Obtenha a lista completa de todas as siglas (tickers) de criptomoedas
que a API Brapi suporta para consulta no endpoint `/api/v2/crypto`.
### Funcionalidade:
* Retorna um array `coins` com as siglas.
* Pode ser filtrado usando o parâmetro `search`.
### Autenticação:
Requer token de autenticação via `token` (query) ou `Authorization`
(header).
### Exemplo de Requisição:
**Listar todas as criptomoedas disponíveis:**
```bash
curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto/available"
```
**Buscar criptomoedas cujo ticker contenha 'DOGE':**
```bash
curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/crypto/available?search=DOGE"
```
### Resposta:
A resposta é um objeto JSON com a chave `coins`, contendo um array de
strings com as siglas das criptomoedas (ex: `["BTC", "ETH", "LTC",
"XRP"]`).
heading: listar-todas-as-criptomoedas-disponíveis
***
Endpoints focados na obtenção de dados sobre **Criptomoedas**.
Inclui consulta de cotações atuais em diversas moedas fiduciárias, dados
históricos e listagem de criptomoedas suportadas pela API.
# Cotação de Criptomoedas
URL: /docs/criptomoedas.mdx
Endpoints focados na obtenção de dados sobre Criptomoedas. Inclui consulta de cotações atuais em diversas moedas fiduciárias, dados históricos e listagem de criptomoedas suportadas pela API.
***
title: Cotação de Criptomoedas
description: >-
Endpoints focados na obtenção de dados sobre Criptomoedas. Inclui consulta de
cotações atuais em diversas moedas fiduciárias, dados históricos e listagem de
criptomoedas suportadas pela API.
full: true
keywords: brapi, api, documentação, criptomoedas
openGraph:
title: Cotação de Criptomoedas
description: >-
Endpoints focados na obtenção de dados sobre Criptomoedas. Inclui consulta
de cotações atuais em diversas moedas fiduciárias, dados históricos e
listagem de criptomoedas suportadas pela API.
type: website
locale: pt\_BR
lastUpdated: '2025-04-28T01:22:35.254Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/crypto
toc:
* depth: 2
title: Buscar Cotação Detalhada de Criptomoedas
url: '#buscar-cotação-detalhada-de-criptomoedas'
structuredData:
headings:
* content: Buscar Cotação Detalhada de Criptomoedas
id: buscar-cotação-detalhada-de-criptomoedas
contents:
* content: >-
Obtenha cotações atualizadas e dados históricos para uma ou mais
criptomoedas.
### Funcionalidades:
* **Cotação Múltipla:** Consulte várias criptomoedas em uma única
requisição usando o parâmetro `coin`.
* **Moeda de Referência:** Especifique a moeda fiduciária para a
cotação com `currency` (padrão: BRL).
* **Dados Históricos:** Solicite séries históricas usando `range` e
`interval` (similar ao endpoint de ações).
### Autenticação:
Requer token de autenticação via `token` (query) ou `Authorization`
(header).
### Exemplo de Requisição:
**Cotação de Bitcoin (BTC) e Ethereum (ETH) em Dólar Americano
(USD):**
```bash
curl -X GET
"https://brapi.dev/api/v2/crypto?coin=BTC,ETH¤cy=USD&token=SEU_TOKEN"
```
**Cotação de Cardano (ADA) em Real (BRL) com histórico do último mês
(intervalo diário):**
```bash
curl -X GET
"https://brapi.dev/api/v2/crypto?coin=ADA¤cy=BRL&range=1mo&interval=1d&token=SEU_TOKEN"
```
### Resposta:
A resposta contém um array `coins`, onde cada objeto representa uma
criptomoeda solicitada, incluindo sua cotação atual, dados de mercado
e, opcionalmente, a série histórica (`historicalDataPrice`).
heading: buscar-cotação-detalhada-de-criptomoedas
***
import { Callout } from 'fumadocs-ui/components/callout';
Endpoints focados na obtenção de dados sobre **Criptomoedas**.
Dados agregados de provedores de mercado crypto. Cotações em tempo real para BTC, ETH e 100+ criptoativos em BRL, USD e EUR.
Inclui consulta de cotações atuais em diversas moedas fiduciárias, dados
históricos e listagem de criptomoedas suportadas pela API.
# Dicionário de Campos da API
URL: /docs/dicionario.mdx
Consulte todos os campos disponíveis na API da brapi com nomes em português, descrições detalhadas, fórmulas de cálculo, tipos, unidades e endpoints. Entenda por que alguns campos retornam null.
***
title: Dicionário de Campos da API
description: >-
Consulte todos os campos disponíveis na API da brapi com nomes em português,
descrições detalhadas, fórmulas de cálculo, tipos, unidades e endpoints.
Entenda por que alguns campos retornam null.
full: true
keywords: brapi, api, dicionário, campos, documentação, null, referência
openGraph:
title: Dicionário de Campos da API
description: >-
Consulte todos os campos da API da brapi: nomes em português, descrições,
fórmulas, tipos, unidades e endpoints. Entenda por que campos retornam null.
type: website
locale: pt\_BR
lastUpdated: '2026-05-22T00:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/dictionary
-------------------------
import { Callout } from 'fumadocs-ui/components/callout';
import { Card, Cards } from 'fumadocs-ui/components/card';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
O dicionário é um endpoint **público** (não requer autenticação) que retorna
todos os campos disponíveis na API, com nome em português, descrição detalhada,
fórmula de cálculo, tipo de dado, unidade e em quais endpoints cada campo
aparece.
`GET /api/v2/dictionary` — sem autenticação, sem limites de plano. Ideal para
construir tooltips, labels dinâmicos, documentação automatizada e integrações.
## Como usar
O endpoint aceita dois parâmetros de query opcionais:
| Parâmetro | Descrição | Exemplo |
| ---------- | -------------------------------------------------------------- | -------------------- |
| `search` | Busca textual em key, label, description, category e endpoints | `?search=patrimônio` |
| `category` | Filtra por categoria (case-insensitive) | `?category=fii` |
Ambos podem ser combinados: `?category=balance-sheet&search=ativo`.
## Início rápido
```bash
# Listar todos os campos
curl "https://brapi.dev/api/v2/dictionary"
# Buscar por termo
curl "https://brapi.dev/api/v2/dictionary?search=patrimônio"
# Filtrar por categoria
curl "https://brapi.dev/api/v2/dictionary?category=fii"
# Combinar busca e categoria
curl "https://brapi.dev/api/v2/dictionary?category=balance-sheet&search=ativo"
```
```typescript
const BASE = 'https://brapi.dev/api/v2/dictionary';
// Listar todos os campos
const all = await fetch(BASE).then((r) => r.json());
// Buscar por termo
const search = await fetch(`${BASE}?search=patrimônio`).then((r) => r.json());
// Filtrar por categoria
const fiiFields = await fetch(`${BASE}?category=fii`).then((r) => r.json());
// Gerar labels dinâmicos a partir do dicionário
const labelMap = Object.fromEntries(
all.fields.map((f) => [f.key, f.label]),
);
console.log(labelMap['dividendYield12m']); // "Dividend Yield 12 meses"
```
```python
import requests
BASE = "https://brapi.dev/api/v2/dictionary"
# Listar todos os campos
all_fields = requests.get(BASE).json()
# Buscar por termo
search = requests.get(BASE, params={"search": "patrimônio"}).json()
# Filtrar por categoria
fii_fields = requests.get(BASE, params={"category": "fii"}).json()
# Gerar labels dinâmicos
label_map = {f["key"]: f["label"] for f in all_fields["fields"]}
print(label_map["dividendYield12m"]) # "Dividend Yield 12 meses"
```
## Estrutura de cada entrada
Cada campo retornado contém:
| Campo | Tipo | Descrição |
| ------------- | -------------- | ---------------------------------------------------------------------- |
| `key` | string | Identificador do campo (ex: `dividendYield12m`) |
| `label` | string | Nome em português (ex: "Dividend Yield 12 meses") |
| `description` | string | Descrição detalhada do que o campo representa |
| `calculation` | string \| null | Fórmula de cálculo, quando aplicável |
| `endpoints` | string\[] | Endpoints onde o campo aparece |
| `category` | string | Categoria do campo |
| `type` | string | Tipo de dado: `number`, `string`, `boolean`, `date`, `object`, `array` |
| `unit` | string \| null | Unidade de medida (`%`, `R$`, etc.) |
### Exemplo de resposta
```json
{
"fields": [
{
"key": "dividendYield12m",
"label": "Dividend Yield 12 meses",
"description": "Rendimento de dividendos/rendimentos acumulados dos últimos 12 meses em relação ao preço atual da cota",
"calculation": "(soma dos rendimentos dos últimos 12 meses / preço atual) × 100",
"endpoints": ["/api/v2/fii/indicators", "/api/v2/fii/indicators/history"],
"category": "fii",
"type": "number",
"unit": "%"
}
],
"requestedAt": "2026-05-22T12:00:00.000Z",
"took": 1
}
```
## Categorias disponíveis
Use o parâmetro `category` para filtrar campos por área:
| Categoria | Descrição | Exemplo de endpoint |
| ------------------ | ----------------------------------------------- | ----------------------------------------------------- |
| `quote` | Cotações de ações, FIIs, ETFs, BDRs | `/api/quote/{tickers}` |
| `historical` | Dados históricos OHLCV | `/api/quote/{tickers}` |
| `financial-data` | Dados financeiros (receita, EBITDA, margens) | `/api/quote/{tickers}?modules=financialData` |
| `balance-sheet` | Balanço Patrimonial | `/api/quote/{tickers}?modules=balanceSheetHistory` |
| `income-statement` | Demonstração de Resultado (DRE) | `/api/quote/{tickers}?modules=incomeStatementHistory` |
| `cash-flow` | Demonstração de Fluxo de Caixa (DFC) | `/api/quote/{tickers}?modules=cashflowHistory` |
| `value-added` | Demonstração de Valor Adicionado (DVA) | `/api/quote/{tickers}?modules=valueAddedHistory` |
| `statistics` | Estatísticas-chave (P/L, ROE, Valor de Mercado) | `/api/quote/{tickers}?modules=defaultKeyStatistics` |
| `dividends` | Dividendos e JCP | `/api/quote/{tickers}?dividends=true` |
| `fii` | Indicadores de Fundos Imobiliários | `/api/v2/fii/indicators` |
| `fii-reports` | Relatórios gerenciais mensais da CVM | `/api/v2/fii/reports` |
| `treasury` | Tesouro Direto (taxas e preços) | `/api/v2/treasury/indicators` |
| `crypto` | Criptomoedas | `/api/v2/crypto` |
| `currency` | Taxas de câmbio | `/api/v2/currency` |
| `inflation` | Indicadores de inflação (IPCA, IGPM) | `/api/v2/inflation` |
| `prime-rate` | Taxa SELIC | `/api/v2/prime-rate` |
| `futures` | Contratos futuros B3 | `/api/v2/futures/*` |
| `future-options` | Opções sobre futuros | `/api/v2/futures/options/*` |
### Exemplos por categoria
```bash
# Campos de cotação (preço, variação, volume, etc.)
curl "https://brapi.dev/api/v2/dictionary?category=quote"
# Campos históricos (OHLCV)
curl "https://brapi.dev/api/v2/dictionary?category=historical"
```
```bash
# Balanço Patrimonial
curl "https://brapi.dev/api/v2/dictionary?category=balance-sheet"
# DRE
curl "https://brapi.dev/api/v2/dictionary?category=income-statement"
# Fluxo de Caixa
curl "https://brapi.dev/api/v2/dictionary?category=cash-flow"
# Dados financeiros agregados
curl "https://brapi.dev/api/v2/dictionary?category=financial-data"
```
```bash
# Indicadores de FIIs (P/VP, DY, vacância, etc.)
curl "https://brapi.dev/api/v2/dictionary?category=fii"
# Relatórios CVM de FIIs
curl "https://brapi.dev/api/v2/dictionary?category=fii-reports"
```
```bash
# Campos de Tesouro Direto (taxas, preços indicativos, indexadores)
curl "https://brapi.dev/api/v2/dictionary?category=treasury"
```
```bash
# Campos de dividendos e JCP
curl "https://brapi.dev/api/v2/dictionary?category=dividends"
```
## Casos de uso
* **Labels dinâmicos**: use `label` para exibir nomes em português na sua interface
sem manter uma tabela manual de traduções.
* **Tooltips/descrições**: use `description` para mostrar o que cada campo
significa ao passar o mouse.
* **Fórmulas**: mostre `calculation` para que o usuário entenda como um
indicador é calculado (ex: "Dividend Yield = (rendimentos 12m / preço) × 100").
* **Tipos e unidades**: use `type` e `unit` para formatar valores
automaticamente (ex: `number` + `%` → `12,5%`; `number` + `R$` → `R$ 1.234,56`).
* **Documentação automatizada**: gere páginas de referência a partir do dicionário
para manter sua documentação interna sempre atualizada com a API.
## Por que este campo está null?
Alguns campos retornam `null` em determinadas consultas. Isso é esperado e
acontece por diferentes razões:
### Cobertura por ativo
Nem todo campo se aplica a todo ativo. A brapi consolida dados da CVM, B3 e
BCB, e cada mercado tem um modelo próprio de divulgação. Quando um campo não se
aplica ao ativo ou ao período consultado, ele retorna `null`.
### Diferenças por setor e padrão contábil
Empresas de setores distintos seguem padrões contábeis diferentes. Campos
como `costOfRevenue` (custo da receita) e `grossProfit` (lucro bruto) são
comuns em indústria e comércio, mas **instituições financeiras e bancos**
usam o **Plano Cosif** — seus balanços não separam custo de receita da mesma
forma, então esses campos vêm como `null`.
Exemplos comuns:
| Campos | Quem tem | Quem não tem |
| ----------------------------------- | --------------------------- | ----------------------------------------- |
| `costOfRevenue`, `grossProfit` | Indústria, comércio, varejo | Bancos, seguradoras, holdings financeiras |
| `inventories`, `accountsReceivable` | Comércio, indústria | Bancos, seguradoras |
| `deposits`, `loansNet` | Bancos | Empresas não-financeiras |
### Seguradoras
Seguradoras seguem normas contábeis específicas da SUSEP. Vários campos do
balanço padrão (como `propertyPlantEquipment`) podem vir como `null` porque
a estrutura patrimonial de seguradoras é organizada de forma diferente
(provisões técnicas, sinistros, prêmios).
### Small caps e empresas sem demonstrativos recentes
Empresas de menor porte ou que não enviaram demonstrativos recentes à CVM
podem ter campos fundamentalistas como `null`. Isso é comum em:
* Empresas que acabaram de abrir capital (IPO recente)
* Empresas com demonstrativos atrasados ou em análise na CVM
* Ativos com baixa liquidez e pouca cobertura
### Campos que não se aplicam ao tipo de ativo
Diferentes tipos de ativos têm campos diferentes. Campos que existem para
ações não necessariamente se aplicam a outros tipos:
| Tipo de ativo | Campos que retornam null |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **FIIs** | Campos de balanço patrimonial de empresas (`grossProfit`, `ebitda`, etc.). Use `category=fii` e `category=fii-reports` no dicionário para ver os campos específicos de FIIs. |
| **ETFs** | Campos fundamentalistas (não têm balanço próprio). |
| **BDRs** | Alguns campos fundamentalistas podem estar indisponíveis (dados da empresa estrangeira). |
| **Índices** (ex: ^BVSP) | A maioria dos campos além de cotação e histórico retorna `null`. |
Use o dicionário para descobrir quais campos pertencem a cada categoria e
endpoint. Se um campo aparece no endpoint que você está consultando mas
retorna `null`, provavelmente é uma das situações acima.
## Perguntas frequentes
r.json());
const tooltips = Object.fromEntries(dict.fields.map(f => [f.key, { label: f.label, desc: f.description, unit: f.unit }]));`}
/>
# Balanço Patrimonial
URL: /docs/acoes/balanco-patrimonial.mdx
Histórico anual ou trimestral de balanço patrimonial de ações.
***
title: Balanço Patrimonial
description: Histórico anual ou trimestral de balanço patrimonial de ações.
full: true
keywords: brapi, api, ações, balanço patrimonial, balance sheet, stocks, v2
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/stocks/balance-sheet
-----------------------------------
Use `period=annual` para dados anuais ou `period=quarterly` para dados
trimestrais.
# Cotação de Ações
URL: /docs/acoes/cotacao.mdx
Snapshot de cotação para ações, BDRs, ETFs, FIIs, units e índices B3 usando o padrão composável /api/v2/stocks.
***
title: Cotação de Ações
description: >-
Snapshot de cotação para ações, BDRs, ETFs, FIIs, units e índices B3 usando
o padrão composável /api/v2/stocks.
full: true
keywords: brapi, api, ações, cotação, stocks, quote, v2, b3
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/stocks/quote
---------------------------
Endpoint para buscar apenas o snapshot de cotação de um ou mais tickers.
Use quando você precisa de preço atual, variação, volume, market cap, faixa do
dia, faixa de 52 semanas e logo, sem carregar módulos financeiros, dividendos
ou histórico.
Este endpoint segue o padrão composável: primeiro descubra ou valide o
ticker em `/api/v2/tickers`, depois consulte o dado de mercado específico em
`/api/v2/stocks/quote?symbols=PETR4,VALE3`.
Tickers antigos são resolvidos para o ticker atual quando houver renome
conhecido. A resposta inclui `requestedSymbol`, `symbol` e `changed` para o
cliente saber quando a brapi retornou outro ticker.
# Dados Financeiros de Ações
URL: /docs/acoes/dados-financeiros.mdx
Dados financeiros atuais ou históricos de tickers B3.
***
title: Dados Financeiros de Ações
description: Dados financeiros atuais ou históricos de tickers B3.
full: true
keywords: brapi, api, ações, dados financeiros, financial data, stocks, v2
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/stocks/financial-data
------------------------------------
Use `mode=current` para dados financeiros atuais/TTM. Use `mode=history` com
`period=annual` ou `period=quarterly` para séries históricas.
# Dividendos de Ações
URL: /docs/acoes/dividendos.mdx
Dividendos, JCP e eventos de ações para ativos B3 stock-like no padrão composável /api/v2/stocks.
***
title: Dividendos de Ações
description: >-
Dividendos, JCP e eventos de ações para ativos B3 stock-like no padrão
composável /api/v2/stocks.
full: true
keywords: brapi, api, ações, dividendos, jcp, proventos, stocks, v2, b3
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/stocks/dividends
-------------------------------
Endpoint para buscar dividendos, JCP e eventos de ações de um ou mais
tickers B3 stock-like. Use quando você precisa apenas de proventos, sem
carregar cotação, histórico ou módulos financeiros.
Este endpoint é para ações e instrumentos stock-like. Rendimentos de FIIs
continuam no endpoint dedicado `/api/v2/fii/dividends`, que tem fonte e
semântica próprias para FIIs.
Tickers antigos são resolvidos para o ticker atual quando houver renome
conhecido, e a resposta inclui `requestedSymbol`, `symbol` e `changed`.
# DRE de Ações
URL: /docs/acoes/dre.mdx
Histórico anual ou trimestral da demonstração de resultado.
***
title: DRE de Ações
description: Histórico anual ou trimestral da demonstração de resultado.
full: true
keywords: brapi, api, ações, dre, income statement, stocks, v2
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/stocks/income-statement
--------------------------------------
Use `period=annual` para dados anuais ou `period=quarterly` para dados
trimestrais.
# Estatísticas de Ações
URL: /docs/acoes/estatisticas.mdx
Indicadores estatísticos atuais ou históricos de tickers B3.
***
title: Estatísticas de Ações
description: Indicadores estatísticos atuais ou históricos de tickers B3.
full: true
keywords: brapi, api, ações, estatísticas, statistics, stocks, v2
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/stocks/statistics
--------------------------------
Use `mode=current` para indicadores atuais/TTM. Use `mode=history` com
`period=annual` ou `period=quarterly` para séries históricas.
# Fluxo de Caixa
URL: /docs/acoes/fluxo-de-caixa.mdx
Histórico anual ou trimestral de fluxo de caixa de ações.
***
title: Fluxo de Caixa
description: Histórico anual ou trimestral de fluxo de caixa de ações.
full: true
keywords: brapi, api, ações, fluxo de caixa, cash flow, stocks, v2
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/stocks/cash-flow
-------------------------------
Use `period=annual` para dados anuais ou `period=quarterly` para dados
trimestrais.
# Histórico de Ações
URL: /docs/acoes/historico.mdx
Séries históricas OHLCV para ações, BDRs, ETFs, FIIs, units e índices B3 no padrão composável /api/v2/stocks.
***
title: Histórico de Ações
description: >-
Séries históricas OHLCV para ações, BDRs, ETFs, FIIs, units e índices B3 no
padrão composável /api/v2/stocks.
full: true
keywords: brapi, api, ações, histórico, ohlcv, stocks, historical, v2, b3
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/stocks/historical
--------------------------------
Endpoint para buscar séries históricas OHLCV de um ou mais tickers. Use
quando você precisa de preços no tempo, sem carregar cotação atual, dividendos
ou módulos financeiros.
O endpoint aceita `range`/`interval` ou `startDate`/`endDate`, respeitando os
limites do plano. Tickers antigos são resolvidos para o ticker atual quando
houver renome conhecido, e a resposta inclui `requestedSymbol`, `symbol` e
`changed`.
Para snapshot de cotação, use `/api/v2/stocks/quote`. Para descobrir ou validar
tickers antes da consulta, use `/api/v2/tickers`.
# Cotação, Dividendos e Dados Financeiros
URL: /docs/acoes.mdx
Endpoints para consulta de dados relacionados a ativos negociados na bolsa brasileira, como Ações, Fundos Imobiliários (FIIs), BDRs, ETFs e Índices (ex: IBOVESPA). Permite buscar cotações atuais, dados históricos, informações fundamentalistas (via módulos) e listagens de ativos disponíveis.
***
title: Cotação, Dividendos e Dados Financeiros
description: >-
Endpoints para consulta de dados relacionados a ativos negociados na bolsa brasileira, como
Ações, Fundos Imobiliários (FIIs), BDRs, ETFs e Índices (ex: IBOVESPA).
Permite buscar cotações atuais, dados históricos, informações fundamentalistas
(via módulos) e listagens de ativos disponíveis.
full: true
keywords: brapi, api, documentação, ações
openGraph:
title: Cotação, Dividendos e Dados Financeiros
description: >-
Endpoints para consulta de dados relacionados a ativos negociados na bolsa brasileira,
como Ações, Fundos Imobiliários (FIIs), BDRs, ETFs e Índices (ex: IBOVESPA).
Permite buscar cotações atuais, dados históricos, informações
fundamentalistas (via módulos) e listagens de ativos disponíveis.
type: website
locale: pt\_BR
lastUpdated: '2025-04-28T01:22:35.251Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/quote/{tickers}
toc:
* depth: 2
title: Dados de Ações e Ativos Financeiros
url: '#buscar-cotação-detalhada-de-ativos-financeiros'
structuredData:
headings:
* content: Dados de Ações e Ativos Financeiros
id: buscar-cotação-detalhada-de-ativos-financeiros
contents:
* content: >
Este endpoint é a principal forma de obter informações detalhadas
sobre um ou mais ativos financeiros (ações, FIIs, ETFs, BDRs, índices)
listados na bolsa brasileira, identificados pelos seus respectivos **tickers**.
### Funcionalidades Principais:
* **Cotação Atual:** Retorna o preço mais recente, variação diária,
máximas, mínimas, volume, etc.
* **Dados Históricos:** Permite solicitar séries históricas de
preços usando os parâmetros `range` e `interval`.
* **Dividendos:** Opcionalmente, inclui histórico de dividendos e
JCP com `dividends=true`.
* **Módulos Adicionais:** Permite requisitar conjuntos de dados
financeiros mais aprofundados através do parâmetro `modules` (veja
detalhes abaixo).
### Autenticação:
É **obrigatório** fornecer um token de autenticação válido, seja via
query parameter `token` ou via header `Authorization: Bearer
seu_token`.
### 🧪 Ações de Teste (Sem Autenticação):
Para facilitar o desenvolvimento e teste, as seguintes **4 ações têm
acesso irrestrito** e **não requerem autenticação**:
* **PETR4** (Petrobras PN)
* **MGLU3** (Magazine Luiza ON)
* **VALE3** (Vale ON)
* **ITUB4** (Itaú Unibanco PN)
**Importante:** Você pode consultar essas ações sem token e com acesso
a todos os recursos (históricos, módulos, dividendos). Porém, se
misturar essas ações com outras na mesma requisição, a autenticação
será obrigatória.
### Exemplos de Requisição:
**1. Cotação simples de PETR4 e VALE3 (ações de teste - sem token):**
```bash
curl -X GET "https://brapi.dev/api/quote/PETR4,VALE3"
```
**2. Cotação de MGLU3 com dados históricos do último mês (ação de
teste - sem token):**
```bash
curl -X GET
"https://brapi.dev/api/quote/MGLU3?range=1mo&interval=1d"
```
**3. Cotação de ITUB4 incluindo dividendos e dados fundamentalistas
(ação de teste - sem token):**
```bash
curl -X GET
"https://brapi.dev/api/quote/ITUB4?dividends=true&modules=defaultKeyStatistics,financialData"
```
**4. Cotação de WEGE3 com Resumo da Empresa e Balanço Patrimonial
Anual (via módulos - requer token):**
```bash
curl -X GET
"https://brapi.dev/api/quote/WEGE3?modules=summaryProfile,balanceSheetHistory&token=SEU_TOKEN"
```
**5. Exemplo de requisição mista (requer token):**
```bash
curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/quote/PETR4,BBAS3"
```
*Nota: Como BBAS3 não é uma ação de teste, toda a requisição requer
autenticação, mesmo contendo PETR4.*
### Parâmetro `modules` (Detalhado):
O parâmetro `modules` é extremamente poderoso para enriquecer a
resposta com dados financeiros detalhados. Você pode solicitar um ou
mais módulos, separados por vírgula.
**Módulos Disponíveis:**
* `summaryProfile`: Informações cadastrais da empresa (endereço,
setor, descrição do negócio, website, número de funcionários).
* `balanceSheetHistory`: Histórico **anual** do Balanço Patrimonial.
* `balanceSheetHistoryQuarterly`: Histórico **trimestral** do
Balanço Patrimonial.
* `defaultKeyStatistics`: Principais estatísticas da empresa (Valor
de Mercado, P/L, ROE, Dividend Yield, etc.) - **TTM (Trailing Twelve
Months)**.
* `defaultKeyStatisticsHistory`: Histórico **anual** das Principais
Estatísticas.
* `defaultKeyStatisticsHistoryQuarterly`: Histórico **trimestral**
das Principais Estatísticas.
* `incomeStatementHistory`: Histórico **anual** da Demonstração do
Resultado do Exercício (DRE).
* `incomeStatementHistoryQuarterly`: Histórico **trimestral** da
Demonstração do Resultado do Exercício (DRE).
* `financialData`: Dados financeiros selecionados (Receita, Lucro
Bruto, EBITDA, Dívida Líquida, Fluxo de Caixa Livre, Margens) - **TTM
(Trailing Twelve Months)**.
* `financialDataHistory`: Histórico **anual** dos Dados Financeiros.
* `financialDataHistoryQuarterly`: Histórico **trimestral** dos
Dados Financeiros.
* `valueAddedHistory`: Histórico **anual** da Demonstração do Valor
Adicionado (DVA).
* `valueAddedHistoryQuarterly`: Histórico **trimestral** da
Demonstração do Valor Adicionado (DVA).
* `cashflowHistory`: Histórico **anual** da Demonstração do Fluxo de
Caixa (DFC).
* `cashflowHistoryQuarterly`: Histórico **trimestral** da
Demonstração do Fluxo de Caixa (DFC).
**Exemplo de Uso do `modules`:**
Para obter a cotação de BBDC4 junto com seu DRE trimestral e Fluxo de
Caixa anual:
```bash
curl -X GET
"https://brapi.dev/api/quote/BBDC4?modules=incomeStatementHistoryQuarterly,cashflowHistory&token=SEU_TOKEN"
```
### Resposta:
A resposta é um objeto JSON contendo a chave `results`, que é um
array. Cada elemento do array corresponde a um ticker solicitado e
contém os dados da cotação e os módulos adicionais requisitados.
* **Sucesso (200 OK):** Retorna os dados conforme solicitado.
* **Bad Request (400 Bad Request):** Ocorre se um parâmetro for
inválido (ex: `range=invalid`) ou se a formatação estiver incorreta.
* **Unauthorized (401 Unauthorized):** Token inválido ou ausente.
* **Payment Required (402 Payment Required):** Limite de requisições
do plano atual excedido.
* **Not Found (404 Not Found):** Um ou mais tickers solicitados não
foram encontrados.
heading: buscar-cotação-detalhada-de-ativos-financeiros
***
Endpoints para consulta de dados relacionados a ativos negociados na bolsa brasileira, como
**Ações**, **Fundos Imobiliários (FIIs)**, **BDRs**, **ETFs** e **Índices** (ex:
IBOVESPA).
Permite buscar cotações atuais, dados históricos, informações fundamentalistas
(via módulos) e listagens de ativos disponíveis.
# Cotação de todas as ações
URL: /docs/acoes/list.mdx
Endpoints para consulta de dados relacionados a ativos negociados na bolsa brasileira, como Ações, Fundos Imobiliários (FIIs), BDRs, ETFs e Índices (ex: IBOVESPA). Permite buscar cotações atuais, dados históricos, informações fundamentalistas (via módulos) e listagens de ativos disponíveis.
***
title: Cotação de todas as ações
description: >-
Endpoints para consulta de dados relacionados a ativos negociados na bolsa brasileira, como
Ações, Fundos Imobiliários (FIIs), BDRs, ETFs e Índices (ex: IBOVESPA).
Permite buscar cotações atuais, dados históricos, informações fundamentalistas
(via módulos) e listagens de ativos disponíveis.
full: true
keywords: brapi, api, documentação, ações
openGraph:
title: Cotação de todas as ações
description: >-
Endpoints para consulta de dados relacionados a ativos negociados na bolsa brasileira,
como Ações, Fundos Imobiliários (FIIs), BDRs, ETFs e Índices (ex: IBOVESPA).
Permite buscar cotações atuais, dados históricos, informações
fundamentalistas (via módulos) e listagens de ativos disponíveis.
type: website
locale: pt\_BR
lastUpdated: '2025-04-28T01:22:35.251Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/quote/list
toc:
* depth: 2
title: Cotações de todas as ações, fundos, índices e BDRs
url: '#cotacoes-de-todas-as-acoes-fundos-indices-e-bdrs'
structuredData:
headings:
* content: Listar e Filtrar Cotações de Ativos
id: cotacoes-de-todas-as-acoes-fundos-indices-e-bdrs
contents:
* content: >-
Obtenha uma lista paginada de cotações de diversos ativos (ações,
FIIs, BDRs) negociados na bolsa brasileira, com opções avançadas de busca, filtragem
e ordenação.
### Funcionalidades:
* **Busca por Ticker:** Filtre por parte do ticker usando `search`.
* **Filtragem por Tipo:** Restrinja a lista a `stock`, `fund` (FII)
ou `bdr` com o parâmetro `type`.
* **Filtragem por Setor:** Selecione ativos de um setor específico
usando `sector`.
* **Ordenação:** Ordene os resultados por diversos campos (preço,
variação, volume, etc.) usando `sortBy` e `sortOrder`.
* **Paginação:** Controle o número de resultados por página
(`limit`) e a página desejada (`page`).
### Autenticação:
Requer token de autenticação via `token` (query) ou `Authorization`
(header).
### Exemplo de Requisição:
**Listar as 10 ações do setor Financeiro com maior volume, ordenadas
de forma decrescente:**
```bash
curl -X GET
"https://brapi.dev/api/quote/list?sector=Finance&sortBy=volume&sortOrder=desc&limit=10&page=1&token=SEU_TOKEN"
```
**Buscar por ativos cujo ticker contenha 'ITUB' e ordenar por nome
ascendente:**
```bash
curl -X GET
"https://brapi.dev/api/quote/list?search=ITUB&sortBy=name&sortOrder=asc&token=SEU_TOKEN"
```
### Resposta:
A resposta contém a lista de `stocks` (e `indexes` relevantes),
informações sobre os filtros aplicados, detalhes da paginação
(`currentPage`, `totalPages`, `itemsPerPage`, `totalCount`,
`hasNextPage`) e listas de setores (`availableSectors`) e tipos
(`availableStockTypes`) disponíveis para filtragem.
heading: cotacoes-de-todas-as-acoes-fundos-indices-e-bdrs
***
Endpoints para consulta de dados relacionados a ativos negociados na bolsa brasileira, como
**Ações**, **Fundos Imobiliários (FIIs)**, **BDRs**, **ETFs** e **Índices** (ex:
IBOVESPA).
Permite buscar cotações atuais, dados históricos, informações fundamentalistas
(via módulos) e listagens de ativos disponíveis.
# Migração de /api/quote para /api/v2/stocks
URL: /docs/acoes/migracao-v2.mdx
Guia para migrar integrações do endpoint legado de cotação para endpoints v2 composáveis.
***
title: Migração de /api/quote para /api/v2/stocks
description: Guia para migrar integrações do endpoint legado de cotação para endpoints v2 composáveis.
full: true
keywords: brapi, api, ações, migração, quote, stocks, v2
lang: pt-BR
-----------
O endpoint legado `/api/quote/{tickers}` continua funcionando. Para novas
integrações, prefira os endpoints v2 por preocupação: descoberta de ticker,
cotação, histórico, dividendos e fundamentos ficam separados.
## Fluxo recomendado
1. Use `/api/v2/tickers` para buscar, filtrar e validar símbolos.
2. Use `/api/v2/tickers/resolve` quando o usuário informar um ticker antigo.
3. Use `/api/v2/tickers/renames` para mostrar histórico de mudanças de código.
4. Use `/api/v2/tickers/coverage` para decidir qual endpoint consultar.
5. Chame o endpoint v2 específico para o dado que você precisa.
## Mapeamento de endpoints
| Legado | V2 recomendado |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `/api/quote/list` | `/api/v2/tickers` |
| `/api/quote/PETR4` | `/api/v2/stocks/quote?symbols=PETR4` |
| `/api/quote/PETR4,VALE3` | `/api/v2/stocks/quote?symbols=PETR4,VALE3` |
| `/api/quote/PETR4?range=1y&interval=1d` | `/api/v2/stocks/historical?symbols=PETR4&range=1y&interval=1d` |
| `/api/quote/PETR4?startDate=2024-01-01&endDate=2024-12-31` | `/api/v2/stocks/historical?symbols=PETR4&startDate=2024-01-01&endDate=2024-12-31` |
| `/api/quote/PETR4?dividends=true` | `/api/v2/stocks/dividends?symbols=PETR4` |
Dividendos/rendimentos de FIIs continuam em `/api/v2/fii/dividends`. Não use
`/api/v2/stocks/dividends` para FIIs quando você precisa da semântica dedicada
de rendimentos de fundos imobiliários.
## Diferenças na resposta
Os endpoints v2 mantêm o envelope `{ results, requestedAt, took }`, mas cada
endpoint retorna apenas o dado daquele domínio:
| V2 | Campo principal |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `/api/v2/stocks/quote` | `results[].data.regularMarketPrice`, `results[].data.regularMarketChangePercent`, `results[].data.marketCap` |
| `/api/v2/stocks/historical` | `results[].data.historicalDataPrice` |
| `/api/v2/stocks/dividends` | `results[].data.cashDividends`, `results[].data.stockDividends`, `results[].data.subscriptions` |
| `/api/v2/stocks/profile` | `results[].data` |
| `/api/v2/stocks/statistics` | `results[].data` |
| `/api/v2/stocks/financial-data` | `results[].data` |
| `/api/v2/stocks/balance-sheet` | `results[].data` |
| `/api/v2/stocks/income-statement` | `results[].data` |
| `/api/v2/stocks/cash-flow` | `results[].data` |
| `/api/v2/stocks/value-added` | `results[].data` |
Quando um ticker antigo é resolvido, os itens retornam `requestedSymbol`,
`symbol` e `changed`, permitindo mostrar ao usuário que o código foi atualizado.
## Mapeamento de módulos
| Módulo legado | V2 recomendado |
| -------------------------------------- | --------------------------------------------------------------------------- |
| `summaryProfile` | `/api/v2/stocks/profile?symbols=PETR4` |
| `defaultKeyStatistics` | `/api/v2/stocks/statistics?symbols=PETR4&mode=current` |
| `defaultKeyStatisticsHistory` | `/api/v2/stocks/statistics?symbols=PETR4&mode=history&period=annual` |
| `defaultKeyStatisticsHistoryQuarterly` | `/api/v2/stocks/statistics?symbols=PETR4&mode=history&period=quarterly` |
| `financialData` | `/api/v2/stocks/financial-data?symbols=PETR4&mode=current` |
| `financialDataHistory` | `/api/v2/stocks/financial-data?symbols=PETR4&mode=history&period=annual` |
| `financialDataHistoryQuarterly` | `/api/v2/stocks/financial-data?symbols=PETR4&mode=history&period=quarterly` |
| `balanceSheetHistory` | `/api/v2/stocks/balance-sheet?symbols=PETR4&period=annual` |
| `balanceSheetHistoryQuarterly` | `/api/v2/stocks/balance-sheet?symbols=PETR4&period=quarterly` |
| `incomeStatementHistory` | `/api/v2/stocks/income-statement?symbols=PETR4&period=annual` |
| `incomeStatementHistoryQuarterly` | `/api/v2/stocks/income-statement?symbols=PETR4&period=quarterly` |
| `cashflowHistory` | `/api/v2/stocks/cash-flow?symbols=PETR4&period=annual` |
| `cashflowHistoryQuarterly` | `/api/v2/stocks/cash-flow?symbols=PETR4&period=quarterly` |
| `valueAddedHistory` | `/api/v2/stocks/value-added?symbols=PETR4&period=annual` |
| `valueAddedHistoryQuarterly` | `/api/v2/stocks/value-added?symbols=PETR4&period=quarterly` |
## Compatibilidade
Use `/api/quote/{tickers}` quando você precisa manter uma integração antiga
sem alterar contrato. Use `/api/v2/stocks/*` quando estiver construindo uma
integração nova, um agente de IA, uma tela de produto ou um pipeline em que
cada chamada deve buscar apenas um tipo de dado.
# Perfil de Ações
URL: /docs/acoes/perfil.mdx
Perfil cadastral e empresarial de tickers B3 no padrão /api/v2/stocks.
***
title: Perfil de Ações
description: Perfil cadastral e empresarial de tickers B3 no padrão /api/v2/stocks.
full: true
keywords: brapi, api, ações, perfil, profile, stocks, v2
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/stocks/profile
-----------------------------
Use este endpoint para buscar apenas o perfil do ticker, sem cotação, histórico,
dividendos ou demonstrações financeiras.
# Valor Adicionado
URL: /docs/acoes/valor-adicionado.mdx
Histórico anual ou trimestral da demonstração de valor adicionado.
***
title: Valor Adicionado
description: Histórico anual ou trimestral da demonstração de valor adicionado.
full: true
keywords: brapi, api, ações, valor adicionado, dva, value added, stocks, v2
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/stocks/value-added
---------------------------------
Use `period=annual` para dados anuais ou `period=quarterly` para dados
trimestrais.
# C#
URL: /docs/examples/csharp.mdx
Integre a API brapi.dev em suas aplicações C# usando HttpClient. Exemplos práticos para buscar cotações de ações brasileiras.
***
title: 'C#'
description: >-
Integre a API brapi.dev em suas aplicações C# usando HttpClient. Exemplos
práticos para buscar cotações de ações brasileiras.
full: false
keywords: brapi, api, csharp, dotnet, httpclient, cotações, ações brasileiras
openGraph:
title: Integração C# - brapi.dev
description: Exemplos de integração usando C# e .NET
type: website
locale: pt\_BR
lastUpdated: '2025-10-12T17:30:00.000Z'
lang: pt-BR
howToSteps:
* name: 'Crie um HttpClient'
text: 'Use new HttpClient() com Timeout configurado. Considere reutilizar a instância para evitar esgotamento de sockets.'
* name: 'Faça a requisição GET assíncrona'
text: 'Use await client.GetStringAsync(url) para buscar dados da API brapi.dev de forma assíncrona.'
* name: 'Defina classes para deserialização'
text: 'Crie classes Quote e QuoteResponse com propriedades que mapeiam os campos JSON retornados pela API.'
* name: 'Deserialize o JSON usando System.Text.Json'
text: 'Use JsonSerializer.Deserialize(response) para converter a resposta JSON em objetos C# tipados.'
* name: 'Acesse e exiba os dados'
text: 'Acesse data.Results\[0].RegularMarketPrice para obter o preço e formate com Console.WriteLine($"R$ {price:F2}").'
howToTools:
* '.NET 6+ ou .NET Framework 4.8+'
* 'Visual Studio ou VS Code'
* 'System.Text.Json ou Newtonsoft.Json'
howToSupplies:
* 'Projeto .NET configurado'
* 'Conta brapi.dev'
* 'Token de API brapi.dev'
***
Integre a API brapi.dev em suas aplicações C# usando HttpClient.
## Exemplo Básico
```csharp
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
string token = "SEU_TOKEN";
string ticker = "PETR4";
string url = $"https://brapi.dev/api/quote/{ticker}";
using HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", token);
string response = await client.GetStringAsync(url);
Console.WriteLine(response);
}
}
```
## Com Classes Tipadas
```csharp
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text.Json;
using System.Threading.Tasks;
public class Quote
{
public string Symbol { get; set; }
public string ShortName { get; set; }
public decimal RegularMarketPrice { get; set; }
public decimal RegularMarketChangePercent { get; set; }
public string Currency { get; set; }
}
public class QuoteResponse
{
public Quote[] Results { get; set; }
}
public class BrapiClient
{
private readonly HttpClient _httpClient;
private const string BaseUrl = "https://brapi.dev/api";
public BrapiClient(string token)
{
_httpClient = new HttpClient
{
Timeout = TimeSpan.FromSeconds(10)
};
_httpClient.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", token);
}
public async Task GetQuoteAsync(string ticker)
{
var url = $"{BaseUrl}/quote/{ticker}";
var response = await _httpClient.GetStringAsync(url);
var data = JsonSerializer.Deserialize(response);
return data?.Results?[0];
}
static async Task Main()
{
var client = new BrapiClient("SEU_TOKEN");
var quote = await client.GetQuoteAsync("PETR4");
if (quote != null)
{
Console.WriteLine($"{quote.Symbol}: R$ {quote.RegularMarketPrice:F2}");
}
}
}
```
## Próximos Passos
* Explore [outros exemplos](/docs/examples)
* Veja a [documentação completa](/docs)
# Microsoft Excel
URL: /docs/examples/excel.mdx
Aprenda a importar cotações da bolsa brasileira no Excel usando Power Query e VBA com a API brapi.dev. Inclui exemplos com autenticação por header e query param.
***
title: 'Microsoft Excel'
description: >-
Aprenda a importar cotações da bolsa brasileira no Excel usando Power Query e VBA
com a API brapi.dev. Inclui exemplos com autenticação por header e query param.
full: false
keywords: brapi, api, excel, power query, vba, planilha, cotações, batch
openGraph:
title: Integração com Excel - brapi.dev
description: Importe cotações da bolsa brasileira no Excel usando Power Query e VBA
type: website
locale: pt\_BR
lastUpdated: '2026-05-22T00:00:00.000Z'
lang: pt-BR
howToSteps:
* name: 'Abra o Excel e acesse Dados'
text: 'Abra o Microsoft Excel e vá para a guia Dados na barra de ferramentas.'
* name: 'Conecte-se à API brapi.dev via Web'
text: 'Clique em Obter Dados > De Outras Fontes > Da Web e insira a URL: [https://brapi.dev/api/quote/PETR4?token=SEU\_TOKEN](https://brapi.dev/api/quote/PETR4?token=SEU_TOKEN)'
* name: 'Converta os dados JSON para tabela'
text: 'O Power Query abrirá mostrando os dados JSON. Clique em Converter > Para Tabela e expanda as colunas conforme necessário.'
* name: 'Carregue e atualize os dados'
text: 'Clique em Fechar e Carregar. Para atualizar, clique com botão direito na tabela e selecione Atualizar.'
howToTools:
* 'Microsoft Excel'
* 'Power Query'
howToSupplies:
* 'Conta brapi.dev'
* 'Token de API brapi.dev'
***
Importe cotações automáticas da bolsa brasileira no Microsoft Excel usando Power Query ou VBA.
## Usando Power Query
O Power Query permite importar dados JSON diretamente no Excel sem necessidade de programação.
### Passo a Passo (modo simples)
1. Abra o Excel e vá para a guia **Dados**
2. Clique em **Obter Dados** > **De Outras Fontes** > **Da Web**
3. Insira a URL (o Power Query não suporta headers customizados no modo básico):
```
https://brapi.dev/api/quote/PETR4,VALE3,ITUB4?token=SEU_TOKEN
```
4. Clique em **OK**
5. O Power Query abrirá uma janela mostrando os dados JSON
6. Clique em **Converter** > **Para Tabela**
7. Expanda as colunas conforme necessário
8. Clique em **Fechar e Carregar**
> **Dica**: Passe múltiplos tickers separados por vírgula para buscar todos em uma única requisição. O limite de tickers por requisição varia por plano (Gratuito: 1, Startup: 10, Pro: 20).
### Power Query com Header Auth (avançado)
Para usar o header `Authorization: Bearer` no Power Query, crie uma consulta via o Editor Avançado (**Dados** > **Obter Dados** > **De Outras Fontes** > **Consulta Nula**, depois **Editor Avançado**):
```
let
Token = "SEU_TOKEN",
Tickers = "PETR4,VALE3,ITUB4",
Url = "https://brapi.dev/api/quote/" & Tickers,
Source = Json.Document(
Web.Contents(Url, [
Headers = [
#"Authorization" = "Bearer " & Token
]
])
),
Results = Source[results],
Table = Table.FromList(Results, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
Expanded = Table.ExpandRecordColumn(Table, "Column1", {
"symbol", "shortName", "regularMarketPrice",
"regularMarketChange", "regularMarketChangePercent",
"regularMarketVolume", "marketCap"
})
in
Expanded
```
Este método é mais seguro pois o token não fica visível na URL.
### Atualização Automática
Para atualizar os dados automaticamente:
1. Clique com botão direito na tabela
2. Selecione **Atualizar**
3. Ou configure atualização automática em **Propriedades da Consulta**
## VBA com Header Auth
Se precisar de mais controle, use VBA com autenticação via header:
```vb
Sub GetBrapiQuote()
Dim http As Object
Dim token As String
Dim tickers As String
Dim url As String
token = "SEU_TOKEN"
tickers = "PETR4,VALE3,ITUB4"
url = "https://brapi.dev/api/quote/" & tickers
Set http = CreateObject("MSXML2.XMLHTTP")
http.Open "GET", url, False
http.setRequestHeader "Authorization", "Bearer " & token
http.Send
If http.Status = 200 Then
' Requer biblioteca VBA-JSON para parsing
Dim json As Object
Set json = JsonConverter.ParseJson(http.responseText)
Dim i As Long
i = 1
Dim result As Variant
For Each result In json("results")
Range("A" & i).Value = result("symbol")
Range("B" & i).Value = result("regularMarketPrice")
Range("C" & i).Value = result("regularMarketChangePercent")
i = i + 1
Next result
Else
MsgBox "Erro HTTP " & http.Status & ": " & http.responseText
End If
End Sub
```
> **Nota**: Requer biblioteca [VBA-JSON](https://github.com/VBA-tools/VBA-JSON) para parsing de JSON.
## Autenticação: Header vs Query Param
| Método | Quando usar | Segurança |
| -------------------------------- | -------------------------------------- | --------------------------- |
| `Authorization: Bearer` (header) | VBA, Power Query avançado | Token não aparece na URL |
| `?token=SEU_TOKEN` (query param) | Power Query simples, importação rápida | Token visível na URL e logs |
Para importações simples no Power Query, o `?token=` funciona sem configuração extra. Para VBA e scripts automatizados, prefira o header `Authorization: Bearer`.
## Dicas de Uso
1. **Busque em lote**: Passe múltiplos tickers separados por vírgula (`PETR4,VALE3,ITUB4`) em uma única requisição
2. **Monitore seu uso**: Acompanhe o consumo no [dashboard](https://brapi.dev/dashboard)
3. **Token em célula**: No VBA, considere ler o token de uma célula nomeada (`Range("TokenAPI").Value`) em vez de hardcodar no código
## Próximos Passos
* Veja como usar no [Google Sheets](/docs/examples/google-sheets)
* Explore [outros exemplos](/docs/examples)
* Consulte a [documentação da API](/docs)
# Google Sheets
URL: /docs/examples/google-sheets.mdx
Aprenda a buscar cotações automáticas de ações brasileiras no Google Sheets usando a API brapi.dev. Inclui função em lote (batch) para economizar requisições e evitar limites do Apps Script.
***
title: 'Google Sheets'
description: >-
Aprenda a buscar cotações automáticas de ações brasileiras no Google Sheets usando a API
brapi.dev. Inclui função em lote (batch) para economizar requisições e evitar
limites do Apps Script.
full: false
keywords:
brapi, api, google sheets, planilha, cotações, ETFs, apps script, IMAB11,
WRLD11, automação, batch, lote
openGraph:
title: Integração com Google Sheets - brapi.dev
description: >-
Busque cotações automáticas de ações brasileiras no Google Sheets com a API brapi.dev.
Solução para ETFs brasileiros que não aparecem no Google Finance.
type: website
locale: pt\_BR
lastUpdated: '2026-05-22T00:00:00.000Z'
lang: pt-BR
howToSteps:
* name: 'Obtenha sua chave API'
text: 'Acesse brapi.dev, crie uma conta gratuita e copie seu token API no painel de usuário.'
* name: 'Adicione as funções no Apps Script'
text: 'Abra sua planilha no Google Sheets, vá em Extensões > Apps Script, apague o código existente e cole as funções BRAPI\_PRICE e BRAPI\_BATCH fornecidas. Salve o projeto.'
* name: 'Use a função em lote na sua planilha'
text: 'Liste seus tickers em uma coluna e use =BRAPI\_BATCH(A2:A20; $A$1) para buscar todos os preços em uma única requisição.'
howToTools:
* 'Google Sheets'
* 'Google Apps Script'
* 'Navegador web'
howToSupplies:
* 'Conta brapi.dev gratuita'
* 'Token de API brapi.dev'
* 'Planilha Google Sheets'
***
O Google Sheets é uma ferramenta poderosa para acompanhar seus investimentos de forma automática. Através do Google Apps Script, você pode criar funções personalizadas que buscam cotações diretamente da brapi.dev.
## Por que usar a brapi.dev no Google Sheets?
A função `GOOGLEFINANCE` não funciona para muitos ativos brasileiros, especialmente ETFs como IMAB11, WRLD11, IB5M11 e IRFM11. A integração com a brapi.dev resolve esse problema, oferecendo:
* **Dados confiáveis**: Acesso direto aos dados do mercado brasileiro
* **ETFs brasileiros**: Funciona com todos os ativos brasileiros
* **Atualização automática**: Cotações atualizadas conforme seu plano
* **Uso gratuito**: 15.000 requisições mensais no plano gratuito
## Passo a Passo
### 1. Obtenha sua chave API
1. Acesse [brapi.dev](https://brapi.dev)
2. Crie uma conta gratuita
3. No painel de usuário, copie seu **token API**
### 2. Adicione as funções no Apps Script
1. Abra sua planilha no Google Sheets
2. Clique em **Extensões** > **Apps Script**
3. Apague o código existente e cole o código abaixo:
```javascript
/**
* Busca preços de múltiplos tickers em UMA requisição (recomendado).
* Uso: =BRAPI_BATCH(A2:A20; $A$1)
* @param {Range} tickers - Range com os códigos dos ativos (coluna)
* @param {string} token - Token da API brapi.dev
* @return {number[][]} Coluna com o preço de cada ativo
* @customfunction
*/
function BRAPI_BATCH(tickers, token) {
if (!tickers) return [["Erro: informe tickers"]];
if (token && typeof token === 'object' && token.length) {
token = token[0][0];
}
if (!token) {
var sh = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
token = sh.getRange('A1').getDisplayValue();
}
if (!token) return [["Erro: token brapi.dev ausente"]];
// Monta a lista de tickers a partir do range
var tickerList = [];
for (var i = 0; i < tickers.length; i++) {
var t = String(tickers[i][0] || '').toUpperCase().trim();
if (t) tickerList.push(t);
}
if (tickerList.length === 0) return [["Sem tickers"]];
// Uma única requisição para todos os tickers (separados por vírgula)
var url = 'https://brapi.dev/api/quote/' +
encodeURIComponent(tickerList.join(',')) +
'?token=' + encodeURIComponent(token);
var options = {
muteHttpExceptions: true,
headers: { 'User-Agent': 'GoogleSheets-brapi/1.0' }
};
var response = UrlFetchApp.fetch(url, options);
if (response.getResponseCode() !== 200) {
return tickers.map(function() {
return ["HTTP " + response.getResponseCode()];
});
}
var json = JSON.parse(response.getContentText());
var results = (json && json.results) || [];
// Mapeia símbolo → preço para preservar a ordem do range
var priceMap = {};
for (var j = 0; j < results.length; j++) {
var sym = results[j].symbol;
var price = results[j].regularMarketPrice;
if (price == null) price = results[j].lastPrice;
if (price == null) price = results[j].close;
priceMap[sym] = price != null ? price : null;
}
// Retorna um array 2D na mesma ordem da coluna de entrada
return tickers.map(function(row) {
var key = String(row[0] || '').toUpperCase().trim();
if (!key) return [""];
var val = priceMap[key] != null ? priceMap[key] : priceMap[key + '.SA'];
return [val != null ? val : "Não encontrado"];
});
}
/**
* Busca o preço de UM ticker via brapi.dev (1 requisição por célula).
* Prefira BRAPI_BATCH para economizar requisições.
* Uso: =BRAPI_PRICE("PETR4"; $A$1)
* @param {string} ticker - Código do ativo (ex: "PETR4", "VALE3", "IMAB11")
* @param {string} token - Token da API brapi.dev
* @return {number} Preço atual do ativo
* @customfunction
*/
function BRAPI_PRICE(ticker, token) {
if (!ticker) return "Erro: informe ticker";
if (token && typeof token === 'object' && token.length) {
token = token[0][0];
}
if (!token) {
var sh = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
token = sh.getRange('A1').getDisplayValue();
}
if (!token) return "Erro: token brapi.dev ausente";
ticker = String(ticker).toUpperCase().trim();
var url = 'https://brapi.dev/api/quote/' + encodeURIComponent(ticker) +
'?token=' + encodeURIComponent(token);
var options = {
muteHttpExceptions: true,
headers: { 'User-Agent': 'GoogleSheets-brapi/1.0' }
};
var response = UrlFetchApp.fetch(url, options);
if (response.getResponseCode() !== 200) {
return "HTTP " + response.getResponseCode() + ": " +
response.getContentText().substring(0, 200);
}
var json = JSON.parse(response.getContentText());
var result = (json && json.results && json.results[0]) || null;
if (!result) return "Sem dados retornados";
var price = result.regularMarketPrice;
if (price == null) price = result.lastPrice;
if (price == null) price = result.close;
return price != null ? price : "Preço não encontrado";
}
/**
* Retorna dados completos de um ativo
* Uso: =BRAPI_DATA("PETR4"; $A$1; "symbol")
* @param {string} ticker - Código do ativo
* @param {string} token - Token da API
* @param {string} field - Campo desejado (regularMarketPrice, currency, shortName, etc)
* @return {any} Valor do campo solicitado
* @customfunction
*/
function BRAPI_DATA(ticker, token, field) {
if (!ticker) return "Erro: informe ticker";
if (!field) return "Erro: informe campo";
if (token && typeof token === 'object' && token.length) {
token = token[0][0];
}
if (!token) {
var sh = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
token = sh.getRange('A1').getDisplayValue();
}
if (!token) return "Erro: token ausente";
ticker = String(ticker).toUpperCase().trim();
var url = 'https://brapi.dev/api/quote/' + encodeURIComponent(ticker) +
'?token=' + encodeURIComponent(token);
var options = {
muteHttpExceptions: true,
headers: { 'User-Agent': 'GoogleSheets-brapi/1.0' }
};
var response = UrlFetchApp.fetch(url, options);
if (response.getResponseCode() !== 200) {
return "Erro HTTP " + response.getResponseCode();
}
var json = JSON.parse(response.getContentText());
var result = (json && json.results && json.results[0]) || null;
if (!result) return "Sem dados";
return result[field] || "Campo não encontrado";
}
```
4. Salve o projeto (Ctrl + S ou clique no ícone de disquete)
5. Feche a janela do editor
### 3. Use as funções na sua planilha
1. Na célula **A1**, cole seu token da API brapi.dev
#### Função em lote (recomendado)
Liste os tickers na coluna A (a partir de A2) e use a fórmula em lote:
```
=BRAPI_BATCH(A2:A20; $A$1)
```
Isso busca até 20 tickers em **uma única requisição** à API, economizando sua cota.
#### Função individual
Para buscar um único ativo, use:
```
=BRAPI_PRICE("PETR4"; $A$1)
```
A referência `$A$1` garante que o endereço da célula do token não mude ao arrastar a fórmula.
## Exemplos de Uso
### Ações
```
=BRAPI_PRICE("PETR4"; $A$1) # Petrobras PN
=BRAPI_PRICE("VALE3"; $A$1) # Vale ON
=BRAPI_PRICE("ITUB4"; $A$1) # Itaú Unibanco PN
=BRAPI_PRICE("BBDC4"; $A$1) # Bradesco PN
```
### ETFs de Renda Fixa
```
=BRAPI_PRICE("IMAB11"; $A$1) # ETF IMA-B
=BRAPI_PRICE("IB5M11"; $A$1) # ETF IMA-B 5+
=BRAPI_PRICE("IRFM11"; $A$1) # ETF IRF-M
=BRAPI_PRICE("B5P211"; $A$1) # ETF NTN-B Principal
```
### ETFs Internacionais
```
=BRAPI_PRICE("WRLD11"; $A$1) # ETF Global
=BRAPI_PRICE("IVVB11"; $A$1) # ETF S&P 500
=BRAPI_PRICE("NASD11"; $A$1) # ETF Nasdaq
```
### Índices
```
=BRAPI_PRICE("^BVSP"; $A$1) # Índice Ibovespa
```
### Dados avançados por campo
```
=BRAPI_DATA("PETR4"; $A$1; "regularMarketPrice") # Preço
=BRAPI_DATA("PETR4"; $A$1; "currency") # Moeda
=BRAPI_DATA("PETR4"; $A$1; "shortName") # Nome curto
=BRAPI_DATA("PETR4"; $A$1; "regularMarketChange") # Variação do dia
=BRAPI_DATA("PETR4"; $A$1; "marketCap") # Valor de mercado
```
## Quotas e Limites do Apps Script
O Google Apps Script impõe limites próprios além dos limites da brapi.dev:
| Recurso | Limite (contas gratuitas) |
| -------------------------------- | ------------------------- |
| `UrlFetchApp.fetch` por execução | 50 chamadas |
| `UrlFetchApp.fetch` por dia | 20.000 chamadas |
| Tempo de execução por função | 30 segundos |
**Por isso a função `BRAPI_BATCH` é essencial**: uma planilha com 30 ativos usando `BRAPI_PRICE` faz 30 chamadas `UrlFetchApp.fetch` por atualização; com `BRAPI_BATCH`, faz apenas **1 chamada**.
### Limites da brapi.dev
| Comportamento | O que acontece |
| -------------- | ---------------------------------------------------------------- |
| `HTTP 429` | Você excedeu o rate limit do seu plano. Aguarde ou faça upgrade. |
| `HTTP 401` | Token inválido ou ausente. |
| Plano gratuito | 15.000 requisições/mês |
## Autenticação: `?token=` vs Header
O Google Apps Script suporta headers HTTP via `UrlFetchApp`, porém para funções personalizadas (`@customfunction`) a simplicidade do `?token=` na URL é a abordagem mais prática. Para scripts que rodam no backend (triggers, menus), você pode usar o header:
```javascript
// Em triggers ou menus (NÃO em @customfunction)
var options = {
muteHttpExceptions: true,
headers: {
'Authorization': 'Bearer ' + token,
'User-Agent': 'GoogleSheets-brapi/1.0'
}
};
```
Para código backend e aplicações de produção, o método `Authorization: Bearer` é recomendado por ser mais seguro — tokens na URL podem vazar em logs e histórico.
## Dicas de Uso
1. **Use `BRAPI_BATCH`**: Sempre que possível, busque múltiplos tickers em uma requisição
2. **Atualize com moderação**: Evite recalcular a cada segundo — 2-3 atualizações por dia é suficiente para a maioria dos portfólios
3. **Monitore seu uso**: Acompanhe o consumo no [dashboard](https://brapi.dev/dashboard)
4. **Limite de tickers por requisição varia por plano** (Gratuito: 1, Startup: 10, Pro: 20). Se tiver mais ativos que o limite, divida em blocos
## Monitoramento de Uso
Para uma ideia de consumo:
| Cenário | Requisições/mês |
| ----------------------------------- | ------------------------------ |
| 30 ativos com `BRAPI_BATCH`, 3x/dia | \~90 (30 dias × 3 × 1 req) |
| 30 ativos com `BRAPI_PRICE`, 3x/dia | \~2.700 (30 dias × 3 × 30 req) |
| 50 ativos com `BRAPI_BATCH`, 3x/dia | \~270 (30 dias × 3 × 3 blocos) |
A função em lote reduz o consumo em **\~97%** para portfólios típicos.
## Solução de Problemas
### "Erro: token ausente"
Verifique se o token está na célula A1 ou se está sendo passado corretamente como parâmetro.
### "HTTP 401"
Token inválido. Verifique se copiou o token completo do [painel da brapi.dev](https://brapi.dev/dashboard).
### "HTTP 429"
Limite de requisições excedido. Migre para `BRAPI_BATCH` para reduzir o consumo ou considere o plano pago.
### "Sem dados retornados"
Ticker inválido ou ativo não encontrado. Verifique o código do ativo.
### "Exceeded maximum execution time"
A função está demorando mais de 30 segundos. Reduza o número de tickers por chamada ou verifique sua conexão.
## Próximos Passos
* Veja como usar no [Microsoft Excel](/docs/examples/excel)
* Explore outros [exemplos de integração](/docs/examples)
* Consulte a [documentação da API](/docs)
* Confira os [endpoints disponíveis](/docs/acoes)
# Exemplos de Integração
URL: /docs/examples.mdx
Exemplos práticos de integração com a API brapi.dev em diversas linguagens de programação, plataformas e ferramentas. Inclui código de exemplo para TypeScript, Python, PHP, Java, C#, Google Sheets, Excel, WordPress e aplicações mobile.
***
title: 'Exemplos de Integração'
description: >-
Exemplos práticos de integração com a API brapi.dev em diversas linguagens de
programação, plataformas e ferramentas. Inclui código de exemplo para
TypeScript, Python, PHP, Java, C#, Google Sheets, Excel, WordPress e
aplicações mobile.
full: false
keywords:
brapi, api, documentação, integração, exemplos, código, typescript, python,
php, java, google sheets, excel
openGraph:
title: Exemplos de Integração com brapi.dev
description: >-
Exemplos práticos de integração com a API brapi.dev em diversas linguagens
de programação, plataformas e ferramentas. Inclui código de exemplo para
TypeScript, Python, PHP, Java, C#, Google Sheets, Excel, WordPress e
aplicações mobile.
type: website
locale: pt\_BR
lastUpdated: '2025-10-12T17:30:00.000Z'
lang: pt-BR
-----------
A API da brapi.dev é uma API REST, o que significa que ela pode ser integrada
com praticamente qualquer plataforma ou linguagem de programação. Esta seção
apresenta exemplos concretos de como integrar nossa API em diferentes ambientes.
## Linguagens de Programação
Exemplos de integração em diferentes linguagens:
* [TypeScript/JavaScript](/docs/examples/typescript) - Integração usando fetch e Axios
* [Python](/docs/examples/python) - Usando a biblioteca requests
* [PHP](/docs/examples/php) - Usando cURL
* [Java](/docs/examples/java) - Usando HttpClient (Java 11+)
* [C#](/docs/examples/csharp) - Usando HttpClient
## Planilhas e Ferramentas Sem Código
Integre cotações diretamente em planilhas e ferramentas de produtividade:
* [Google Sheets](/docs/examples/google-sheets) - Função personalizada com Apps Script
* [Microsoft Excel](/docs/examples/excel) - Power Query para importar dados JSON
* [Notion](/docs/examples/notion) - Sincronização automática com Note API Connector
## CMS e Plataformas
Exemplos de integração em sistemas de gerenciamento de conteúdo:
* [WordPress](/docs/examples/wordpress) - Shortcode personalizado para exibir cotações
## Aplicações Mobile
Exemplos para desenvolvimento mobile:
* [React Native](/docs/examples/react-native) - Componente de cotação com hooks
## Começando
Todos os exemplos requerem um token de API. Para obter seu token:
1. Acesse [brapi.dev](https://brapi.dev)
2. Crie uma conta gratuita
3. Copie seu token no painel de usuário
O plano gratuito oferece **15.000 requisições mensais**, suficiente para a maioria dos casos de uso.
## Suporte
Para sugestões de integração com outras plataformas ou linguagens, entre em
contato com nossa equipe de suporte.
# Java
URL: /docs/examples/java.mdx
Integre a API brapi.dev em suas aplicações Java usando HttpClient. Exemplos práticos para buscar cotações de ações brasileiras.
***
title: 'Java'
description: >-
Integre a API brapi.dev em suas aplicações Java usando HttpClient. Exemplos
práticos para buscar cotações de ações brasileiras.
full: false
keywords: brapi, api, java, httpclient, cotações, ações brasileiras
openGraph:
title: Integração Java - brapi.dev
description: Exemplos de integração usando Java 11+ HttpClient
type: website
locale: pt\_BR
lastUpdated: '2025-10-12T17:30:00.000Z'
lang: pt-BR
howToSteps:
* name: 'Crie um HttpClient'
text: 'Use HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build() para criar um cliente HTTP com timeout configurado.'
* name: 'Construa a requisição HTTP'
text: 'Use HttpRequest.newBuilder().uri(URI.create(url)).GET().build() para criar a requisição GET para a API brapi.dev.'
* name: 'Execute a requisição e obtenha a resposta'
text: 'Use client.send(request, HttpResponse.BodyHandlers.ofString()) para executar e obter a resposta como String.'
* name: 'Parse o JSON usando Gson'
text: 'Adicione Gson como dependência e use gson.fromJson(response.body(), QuoteResponse.class) para converter a resposta em objetos Java tipados.'
* name: 'Opcionalmente, integre com Spring Boot'
text: 'Use RestTemplate ou WebClient do Spring com @Cacheable para cache e @Value para injetar o token de configuração.'
howToTools:
* 'Java 11+'
* 'Maven ou Gradle'
* 'Gson ou Jackson'
* 'IDE Java'
howToSupplies:
* 'JDK 11 ou superior'
* 'Conta brapi.dev'
* 'Token de API brapi.dev'
***
Integre a API brapi.dev em suas aplicações Java usando HttpClient (Java 11+).
## Exemplo Básico
```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class BrapiExample {
public static void main(String[] args) throws Exception {
String token = "SEU_TOKEN";
String ticker = "PETR4";
String url = "https://brapi.dev/api/quote/" + ticker;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Authorization", "Bearer " + token)
.GET()
.build();
HttpResponse response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}
```
## Classe Cliente Completa
```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import com.google.gson.Gson;
import com.google.gson.JsonObject;
public class BrapiClient {
private static final String BASE_URL = "https://brapi.dev/api";
private final HttpClient httpClient;
private final String token;
private final Gson gson;
public BrapiClient(String token) {
this.token = token;
this.httpClient = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(10))
.build();
this.gson = new Gson();
}
public QuoteResponse getQuote(String ticker) throws Exception {
String url = String.format("%s/quote/%s", BASE_URL, ticker);
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("Authorization", "Bearer " + token)
.header("User-Agent", "Java BrapiClient/1.0")
.GET()
.build();
HttpResponse response = httpClient.send(request,
HttpResponse.BodyHandlers.ofString());
if (response.statusCode() != 200) {
throw new Exception("HTTP " + response.statusCode());
}
return gson.fromJson(response.body(), QuoteResponse.class);
}
public static class QuoteResponse {
public Quote[] results;
public static class Quote {
public String symbol;
public String shortName;
public double regularMarketPrice;
public double regularMarketChange;
public double regularMarketChangePercent;
public String currency;
}
}
public static void main(String[] args) {
try {
BrapiClient client = new BrapiClient("SEU_TOKEN");
QuoteResponse response = client.getQuote("PETR4");
if (response.results != null && response.results.length > 0) {
QuoteResponse.Quote quote = response.results[0];
System.out.printf("%s: R$ %.2f%n", quote.symbol, quote.regularMarketPrice);
System.out.printf("Variação: %.2f%%%n", quote.regularMarketChangePercent);
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
```
## Spring Boot
```java
// BrapiService.java
package com.example.service;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.cache.annotation.Cacheable;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestTemplate;
@Service
public class BrapiService {
@Value("${brapi.token}")
private String token;
private final RestTemplate restTemplate = new RestTemplate();
private static final String BASE_URL = "https://brapi.dev/api";
@Cacheable(value = "quotes", key = "#ticker")
public QuoteResponse getQuote(String ticker) {
String url = String.format("%s/quote/%s", BASE_URL, ticker);
org.springframework.http.HttpHeaders headers = new org.springframework.http.HttpHeaders();
headers.setBearerAuth(token);
org.springframework.http.HttpEntity entity = new org.springframework.http.HttpEntity<>(headers);
return restTemplate.exchange(url, org.springframework.http.HttpMethod.GET, entity, QuoteResponse.class).getBody();
}
}
// Controller
package com.example.controller;
import com.example.service.BrapiService;
import org.springframework.web.bind.annotation.*;
@RestController
@RequestMapping("/api/stock")
public class StockController {
private final BrapiService brapiService;
public StockController(BrapiService brapiService) {
this.brapiService = brapiService;
}
@GetMapping("/{ticker}")
public QuoteResponse getStock(@PathVariable String ticker) {
return brapiService.getQuote(ticker);
}
}
// application.properties
// brapi.token=SEU_TOKEN
```
## Próximos Passos
* Explore [outros exemplos](/docs/examples)
* Veja a [documentação completa](/docs)
# Notion
URL: /docs/examples/notion.mdx
Sincronize cotações da bolsa brasileira no Notion usando Note API Connector e a API brapi.dev. Importe dados automaticamente sem código.
***
title: 'Notion'
description: >-
Sincronize cotações da bolsa brasileira no Notion usando Note API Connector e a API
brapi.dev. Importe dados automaticamente sem código.
full: false
keywords: brapi, api, notion, note api connector, automação, cotações
openGraph:
title: Integração com Notion - brapi.dev
description: Sincronize cotações da bolsa brasileira no Notion automaticamente
type: website
locale: pt\_BR
lastUpdated: '2025-10-12T17:30:00.000Z'
lang: pt-BR
howToSteps:
* name: 'Acesse o Note API Connector e conecte ao Notion'
text: 'Acesse noteapiconnector.com, clique em Connect with Notion e autorize o acesso ao seu workspace do Notion.'
* name: 'Configure a requisição para a brapi.dev'
text: 'Crie uma nova requisição com URL: [https://brapi.dev/api/quote/PETR4?token=SEU\_TOKEN](https://brapi.dev/api/quote/PETR4?token=SEU_TOKEN) e método GET.'
* name: 'Personalize a saída e configure sincronização'
text: 'Mapeie os campos da resposta JSON para colunas do Notion e configure a frequência de sincronização automática (a cada hora, 5 minutos, etc.).'
* name: 'Visualize seus dados no Notion'
text: 'Seus dados de cotações serão sincronizados automaticamente no Notion, prontos para criar dashboards e acompanhar investimentos.'
howToTools:
* 'Notion'
* 'Note API Connector'
* 'Navegador web'
howToSupplies:
* 'Conta Notion'
* 'Conta brapi.dev'
* 'Token de API brapi.dev'
***
Importe e sincronize dados da brapi.dev diretamente no Notion sem necessidade de código.
## Note API Connector
O [Note API Connector](https://noteapiconnector.com?ref=brapi) permite importar e sincronizar dados da brapi.dev diretamente no Notion. Com ele, você pode:
* 📊 Importar dados de ações e cotações automaticamente
* 🔄 Agendar sincronizações em intervalos personalizados (a cada hora, a cada 5 minutos, etc.)
* 📈 Criar dashboards ao vivo com dados do mercado financeiro brasileiro
* 📌 Manter seu workspace do Notion sempre atualizado com as últimas cotações
## Como Usar
1. Acesse o [Note API Connector](https://noteapiconnector.com?ref=brapi) e clique em **Connect with Notion**
2. Conecte sua conta do Notion e autorize o workspace
3. Configure uma requisição para a brapi.dev usando sua API token:
* **URL**: `https://brapi.dev/api/quote/PETR4?token=SEU_TOKEN`
* **Método**: GET
4. Personalize a saída e configure a sincronização automática
## Configuração Avançada
Para múltiplos ativos, use:
```
https://brapi.dev/api/quote/PETR4,VALE3,ITUB4?token=SEU_TOKEN
```
## Documentação
Para um guia completo de configuração, consulte a [documentação oficial do Note API Connector](https://help.noteapiconnector.com?ref=brapi).
## Próximos Passos
* Veja como usar no [Google Sheets](/docs/examples/google-sheets)
* Explore [outros exemplos](/docs/examples)
# PHP
URL: /docs/examples/php.mdx
Integre a API brapi.dev em suas aplicações PHP usando cURL. Exemplos práticos para buscar cotações de ações brasileiras.
***
title: 'PHP'
description: >-
Integre a API brapi.dev em suas aplicações PHP usando cURL. Exemplos práticos
para buscar cotações de ações brasileiras.
full: false
keywords: brapi, api, php, curl, cotações, ações brasileiras
openGraph:
title: Integração PHP - brapi.dev
description: Exemplos de integração usando PHP e cURL
type: website
locale: pt\_BR
lastUpdated: '2025-10-12T17:30:00.000Z'
lang: pt-BR
howToSteps:
* name: 'Inicialize uma requisição cURL'
text: 'Use curl\_init() com a URL [https://brapi.dev/api/quote/PETR4](https://brapi.dev/api/quote/PETR4), configure CURLOPT\_RETURNTRANSFER como true e adicione o header Authorization: Bearer SEU\_TOKEN via CURLOPT\_HTTPHEADER.'
* name: 'Execute a requisição e obtenha a resposta'
text: 'Execute curl\_exec(), verifique o código HTTP com curl\_getinfo() e feche a conexão com curl\_close().'
* name: 'Parse o JSON e acesse os dados'
text: 'Use json\_decode($response, true) para converter a resposta em array PHP e acesse $data\["results"]\[0]\["regularMarketPrice"].'
* name: 'Implemente tratamento de erros'
text: 'Verifique curl\_error() e o código HTTP para tratar erros de conexão e respostas inválidas adequadamente.'
* name: 'Opcionalmente, integre com WordPress ou Laravel'
text: 'Use wp\_remote\_get() no WordPress com transients para cache, ou Http::get() no Laravel com Cache::remember().'
howToTools:
* 'PHP 7.4+'
* 'cURL'
* 'Editor de código'
howToSupplies:
* 'Servidor com PHP instalado'
* 'Conta brapi.dev'
* 'Token de API brapi.dev'
***
Integre a API brapi.dev em suas aplicações PHP usando cURL ou file\_get\_contents.
## Usando cURL
```php
```
## Com Tratamento de Erros
```php
getMessage()}\n";
}
?>
```
## Classe Cliente
```php
token = $token;
}
public function getQuote($ticker) {
$url = "{$this->baseUrl}/quote/{$ticker}";
return $this->request($url);
}
public function getMultipleQuotes($tickers) {
$tickersParam = implode(',', $tickers);
$url = "{$this->baseUrl}/quote/{$tickersParam}";
return $this->request($url);
}
private function request($url) {
$curl = curl_init($url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_TIMEOUT, 10);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
'User-Agent: PHP BrapiClient/1.0',
"Authorization: Bearer {$this->token}"
]);
$response = curl_exec($curl);
$httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$error = curl_error($curl);
curl_close($curl);
if ($error) {
throw new Exception("Erro cURL: {$error}");
}
if ($httpCode !== 200) {
throw new Exception("HTTP {$httpCode}");
}
return json_decode($response, true);
}
}
// Uso
$client = new BrapiClient('SEU_TOKEN');
try {
$data = $client->getQuote('PETR4');
$quote = $data['results'][0];
echo "{$quote['symbol']}: R$ {$quote['regularMarketPrice']}\n";
} catch (Exception $e) {
echo "Erro: {$e->getMessage()}\n";
}
?>
```
## WordPress Integration
```php
10,
'headers' => [
'Authorization' => "Bearer {$token}",
],
]);
if (is_wp_error($response)) {
return 'Erro ao buscar dados';
}
$body = wp_remote_retrieve_body($response);
$data = json_decode($body, true);
if (isset($data['results'][0]['regularMarketPrice'])) {
$price = $data['results'][0]['regularMarketPrice'];
set_transient($transient_key, $price, 60); // Cache por 60 segundos
return $price;
}
return 'Cotação indisponível';
}
// Shortcode
function brapi_stock_price_shortcode($atts) {
$atts = shortcode_atts([
'ticker' => 'PETR4',
], $atts);
$price = brapi_get_stock_price($atts['ticker']);
if (is_numeric($price)) {
return 'R$ ' . number_format($price, 2, ',', '.');
}
return $price;
}
add_shortcode('brapi_cotacao', 'brapi_stock_price_shortcode');
// Uso no WordPress: [brapi_cotacao ticker="PETR4"]
?>
```
## Laravel
```php
token = config('services.brapi.token');
}
public function getQuote(string $ticker)
{
$cacheKey = "quote_{$ticker}";
return Cache::remember($cacheKey, 60, function () use ($ticker) {
$response = Http::timeout(10)
->withToken($this->token)
->get("{$this->baseUrl}/quote/{$ticker}");
if ($response->failed()) {
throw new \Exception('Failed to fetch quote');
}
return $response->json();
});
}
public function getMultipleQuotes(array $tickers)
{
$tickersParam = implode(',', $tickers);
$response = Http::timeout(10)
->withToken($this->token)
->get("{$this->baseUrl}/quote/{$tickersParam}");
if ($response->failed()) {
throw new \Exception('Failed to fetch quotes');
}
return $response->json();
}
}
// config/services.php
return [
'brapi' => [
'token' => env('BRAPI_TOKEN'),
],
];
// Controller
namespace App\Http\Controllers;
use App\Services\BrapiService;
class StockController extends Controller
{
public function show($ticker, BrapiService $brapi)
{
$data = $brapi->getQuote($ticker);
$quote = $data['results'][0] ?? null;
return view('stock.show', compact('quote'));
}
}
?>
```
## Próximos Passos
* Explore [outros exemplos](/docs/examples)
* Veja a [documentação completa](/docs)
* Confira os [endpoints disponíveis](/docs/acoes)
# Python
URL: /docs/examples/python.mdx
Integre a API brapi.dev em suas aplicações Python usando a biblioteca requests. Exemplos práticos para buscar cotações de ações brasileiras.
***
title: 'Python'
description: >-
Integre a API brapi.dev em suas aplicações Python usando a biblioteca
requests. Exemplos práticos para buscar cotações de ações brasileiras.
full: false
keywords: brapi, api, python, requests, cotações, ações brasileiras
openGraph:
title: Integração Python - brapi.dev
description: Exemplos de integração usando Python e requests
type: website
locale: pt\_BR
lastUpdated: '2025-10-12T17:30:00.000Z'
lang: pt-BR
howToSteps:
* name: 'Escolha sua abordagem: SDK oficial ou requests'
text: 'Recomendamos usar a SDK oficial (pip install brapi) para type hints e retry automático. Se preferir controle manual, use a biblioteca requests.'
* name: 'Configure seu token de API'
text: 'Use python-dotenv para carregar variáveis de ambiente. Crie um arquivo .env com BRAPI\_TOKEN=seu\_token\_aqui.'
* name: 'Faça a requisição para a API'
text: 'Com requests: response = requests.get(url, headers={"Authorization": f"Bearer {token}"}). Parse com response.json().'
* name: 'Parse e use os dados retornados'
text: 'O retorno contém results com lista de cotações. Acesse data\["results"]\[0]\["regularMarketPrice"] para o preço atual.'
* name: 'Integre com Pandas ou Flask'
text: 'Converta os dados para DataFrame com pd.DataFrame(data) para análise. Use Flask ou FastAPI para criar endpoints REST.'
howToTools:
* 'Python 3.7+'
* 'pip'
* 'Editor de código'
howToSupplies:
* 'Conta brapi.dev'
* 'Token de API brapi.dev'
* 'Ambiente Python configurado'
***
Integre a API brapi.dev em suas aplicações Python usando nossa SDK oficial ou biblioteca requests.
## 🎉 SDK Oficial Disponível!
A brapi.dev agora oferece uma **SDK oficial Python 3.8+** que facilita muito a integração:
```bash
pip install brapi
```
**Vantagens da SDK:**
* ✅ Type hints completos
* ✅ Suporte síncrono e assíncrono
* ✅ Tratamento de erros automático
* ✅ Retry inteligente
* ✅ Integração com asyncio e aiohttp
**Exemplo rápido:**
```python
from brapi import Brapi
client = Brapi(api_key="seu_token")
quote = client.quote.retrieve(tickers="PETR4")
print(quote.results[0].regular_market_price)
```
📚 **[Ver documentação completa da SDK](/docs/sdks/python)**
***
## Integração Manual (Sem SDK)
Se preferir usar requests diretamente, veja os exemplos abaixo.
## Por Que Python para Análise Financeira?
```python
import requests
token = 'SEU_TOKEN'
ticker = 'PETR4'
url = f'https://brapi.dev/api/quote/{ticker}'
response = requests.get(url, headers={'Authorization': f'Bearer {token}'})
data = response.json()
print(data)
```
## Com Tratamento de Erros
```python
import requests
from typing import Dict, Optional
def get_quote(ticker: str, token: str) -> Optional[Dict]:
"""
Busca cotação de um ativo brasileiro
Args:
ticker: Código do ativo (ex: 'PETR4')
token: Token da API brapi.dev
Returns:
Dicionário com dados da cotação ou None em caso de erro
"""
url = f'https://brapi.dev/api/quote/{ticker}'
try:
response = requests.get(
url,
headers={'Authorization': f'Bearer {token}'},
timeout=10,
)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
print(f'Erro ao buscar cotação: {e}')
return None
# Uso
token = 'SEU_TOKEN'
data = get_quote('PETR4', token)
if data and 'results' in data:
quote = data['results'][0]
print(f"{quote['symbol']}: R$ {quote['regularMarketPrice']:.2f}")
print(f"Variação: {quote['regularMarketChangePercent']:.2f}%")
```
## Múltiplos Tickers
```python
def get_multiple_quotes(tickers: list[str], token: str) -> Optional[Dict]:
"""Busca cotações de múltiplos ativos"""
tickers_param = ','.join(tickers)
url = f'https://brapi.dev/api/quote/{tickers_param}'
try:
response = requests.get(
url,
headers={'Authorization': f'Bearer {token}'},
timeout=10,
)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
print(f'Erro: {e}')
return None
# Uso
tickers = ['PETR4', 'VALE3', 'ITUB4']
data = get_multiple_quotes(tickers, token)
if data:
for quote in data['results']:
print(f"{quote['symbol']}: R$ {quote['regularMarketPrice']:.2f}")
```
## Classe Cliente
```python
import requests
from typing import Dict, List, Optional
from dataclasses import dataclass
from datetime import datetime
@dataclass
class Quote:
"""Representa uma cotação de ativo"""
symbol: str
short_name: str
regular_market_price: float
regular_market_change: float
regular_market_change_percent: float
currency: str
market_cap: Optional[float] = None
@classmethod
def from_dict(cls, data: Dict) -> 'Quote':
return cls(
symbol=data['symbol'],
short_name=data['shortName'],
regular_market_price=data['regularMarketPrice'],
regular_market_change=data['regularMarketChange'],
regular_market_change_percent=data['regularMarketChangePercent'],
currency=data['currency'],
market_cap=data.get('marketCap')
)
class BrapiClient:
"""Cliente para a API brapi.dev"""
BASE_URL = 'https://brapi.dev/api'
def __init__(self, token: str):
self.token = token
self.session = requests.Session()
self.session.headers.update({
'Authorization': f'Bearer {token}',
'User-Agent': 'Python BrapiClient/1.0',
})
def get_quote(self, ticker: str) -> Optional[Quote]:
"""Busca cotação de um ativo"""
url = f'{self.BASE_URL}/quote/{ticker}'
try:
response = self.session.get(url, timeout=10)
response.raise_for_status()
data = response.json()
if data.get('results'):
return Quote.from_dict(data['results'][0])
return None
except requests.exceptions.RequestException as e:
print(f'Erro ao buscar {ticker}: {e}')
return None
def get_multiple_quotes(self, tickers: List[str]) -> List[Quote]:
"""Busca cotações de múltiplos ativos"""
tickers_param = ','.join(tickers)
url = f'{self.BASE_URL}/quote/{tickers_param}'
try:
response = self.session.get(url, timeout=10)
response.raise_for_status()
data = response.json()
return [Quote.from_dict(item) for item in data.get('results', [])]
except requests.exceptions.RequestException as e:
print(f'Erro ao buscar cotações: {e}')
return []
def __enter__(self):
return self
def __exit__(self, *args):
self.session.close()
# Uso
with BrapiClient('SEU_TOKEN') as client:
# Cotação única
quote = client.get_quote('PETR4')
if quote:
print(f'{quote.symbol}: R$ {quote.regular_market_price:.2f}')
print(f'Variação: {quote.regular_market_change_percent:.2f}%')
# Múltiplas cotações
quotes = client.get_multiple_quotes(['PETR4', 'VALE3', 'ITUB4'])
for quote in quotes:
print(f'{quote.symbol}: R$ {quote.regular_market_price:.2f}')
```
## Salvando em CSV
```python
import csv
from datetime import datetime
def save_quotes_to_csv(tickers: List[str], token: str, filename: str):
"""Salva cotações em arquivo CSV"""
with BrapiClient(token) as client:
quotes = client.get_multiple_quotes(tickers)
if not quotes:
print('Nenhuma cotação obtida')
return
with open(filename, 'w', newline='', encoding='utf-8') as csvfile:
fieldnames = [
'timestamp', 'symbol', 'short_name', 'price',
'change', 'change_percent', 'currency'
]
writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
writer.writeheader()
timestamp = datetime.now().isoformat()
for quote in quotes:
writer.writerow({
'timestamp': timestamp,
'symbol': quote.symbol,
'short_name': quote.short_name,
'price': quote.regular_market_price,
'change': quote.regular_market_change,
'change_percent': quote.regular_market_change_percent,
'currency': quote.currency
})
print(f'Cotações salvas em {filename}')
# Uso
tickers = ['PETR4', 'VALE3', 'ITUB4', 'BBDC4']
save_quotes_to_csv(tickers, 'SEU_TOKEN', 'quotes.csv')
```
## Com Pandas
```python
import pandas as pd
def get_quotes_dataframe(tickers: List[str], token: str) -> pd.DataFrame:
"""Retorna cotações como DataFrame do pandas"""
with BrapiClient(token) as client:
quotes = client.get_multiple_quotes(tickers)
if not quotes:
return pd.DataFrame()
data = [{
'symbol': q.symbol,
'name': q.short_name,
'price': q.regular_market_price,
'change': q.regular_market_change,
'change_percent': q.regular_market_change_percent,
'currency': q.currency,
'market_cap': q.market_cap
} for q in quotes]
return pd.DataFrame(data)
# Uso
df = get_quotes_dataframe(['PETR4', 'VALE3', 'ITUB4'], 'SEU_TOKEN')
print(df)
# Salvar em Excel
df.to_excel('quotes.xlsx', index=False)
```
## Aplicação Flask
```python
from flask import Flask, jsonify
import os
app = Flask(__name__)
BRAPI_TOKEN = os.environ.get('BRAPI_TOKEN')
@app.route('/api/quote/')
def get_quote_api(ticker):
"""Endpoint para buscar cotação"""
with BrapiClient(BRAPI_TOKEN) as client:
quote = client.get_quote(ticker)
if not quote:
return jsonify({'error': 'Quote not found'}), 404
return jsonify({
'symbol': quote.symbol,
'name': quote.short_name,
'price': quote.regular_market_price,
'change_percent': quote.regular_market_change_percent
})
if __name__ == '__main__':
app.run(debug=True)
```
## Boas Práticas
1. **Use variáveis de ambiente** para o token
2. **Implemente timeout** nas requisições
3. **Trate erros** adequadamente
4. **Use sessões** para melhor performance
5. **Feche conexões** quando não precisar mais
## Variáveis de Ambiente
```python
import os
from dotenv import load_dotenv
load_dotenv() # Carrega .env
token = os.environ.get('BRAPI_TOKEN')
if not token:
raise ValueError('BRAPI_TOKEN não configurado')
```
Arquivo `.env`:
```
BRAPI_TOKEN=seu_token_aqui
```
## Próximos Passos
* Explore [outros exemplos](/docs/examples)
* Veja a [documentação completa](/docs)
* Confira os [endpoints disponíveis](/docs/acoes)
# React Native
URL: /docs/examples/react-native.mdx
Integre a API brapi.dev em aplicações React Native. Componentes para exibir cotações de ações brasileiras em apps mobile.
***
title: 'React Native'
description: >-
Integre a API brapi.dev em aplicações React Native. Componentes para exibir
cotações de ações brasileiras em apps mobile.
full: false
keywords: brapi, api, react native, mobile, cotações, hooks
openGraph:
title: Integração React Native - brapi.dev
description: Componentes React Native para cotações da bolsa brasileira
type: website
locale: pt\_BR
lastUpdated: '2025-10-12T17:30:00.000Z'
lang: pt-BR
howToSteps:
* name: 'Crie um componente de cotação'
text: 'Crie um componente StockPrice que recebe ticker como prop e usa useState para gerenciar preço, loading e erro.'
* name: 'Implemente useEffect para buscar dados'
text: 'Use useEffect com fetch para chamar [https://brapi.dev/api/quote/\{ticker}](https://brapi.dev/api/quote/\{ticker}) com header Authorization: Bearer SEU\_TOKEN e atualizar o estado com os dados retornados.'
* name: 'Adicione tratamento de loading e erro'
text: 'Renderize ActivityIndicator durante loading e mensagem de erro quando houver falha na requisição.'
* name: 'Estilize o componente com StyleSheet'
text: 'Use StyleSheet.create para definir estilos do card, incluindo cores para variação positiva (verde) e negativa (vermelho).'
* name: 'Opcionalmente, crie um custom hook useBrapiQuote'
text: 'Extraia a lógica de fetch para um hook reutilizável que retorna { data, loading, error } para uso em múltiplos componentes.'
howToTools:
* 'React Native'
* 'Expo ou React Native CLI'
* 'Editor de código'
howToSupplies:
* 'Projeto React Native configurado'
* 'Conta brapi.dev'
* 'Token de API brapi.dev'
***
Integre a API brapi.dev em suas aplicações React Native.
## Componente Básico
```javascript
import React, { useState, useEffect } from 'react';
import { View, Text, StyleSheet, ActivityIndicator } from 'react-native';
const StockPrice = ({ ticker }) => {
const [price, setPrice] = useState(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);
useEffect(() => {
const token = 'SEU_TOKEN';
const fetchPrice = async () => {
try {
const response = await fetch(
`https://brapi.dev/api/quote/${ticker}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
if (!response.ok) {
throw new Error('Erro ao buscar cotação');
}
const data = await response.json();
setPrice(data.results[0]);
} catch (error) {
setError(error.message);
} finally {
setLoading(false);
}
};
fetchPrice();
}, [ticker]);
if (loading) {
return (
);
}
if (error) {
return (
{error}
);
}
if (!price) return null;
const isPositive = price.regularMarketChangePercent > 0;
return (
{price.symbol}
{price.shortName}
R$ {price.regularMarketPrice.toFixed(2)}
{isPositive ? '+' : ''}{price.regularMarketChangePercent.toFixed(2)}%
);
};
const styles = StyleSheet.create({
container: {
padding: 16,
backgroundColor: '#ffffff',
borderRadius: 12,
marginBottom: 12,
shadowColor: '#000',
shadowOffset: { width: 0, height: 2 },
shadowOpacity: 0.1,
shadowRadius: 4,
elevation: 3,
},
ticker: {
fontSize: 18,
fontWeight: 'bold',
color: '#333',
},
name: {
fontSize: 14,
color: '#666',
marginTop: 4,
},
price: {
fontSize: 24,
fontWeight: 'bold',
color: '#000',
marginTop: 8,
},
change: {
fontSize: 16,
fontWeight: '600',
marginTop: 4,
},
positive: {
color: '#10b981',
},
negative: {
color: '#ef4444',
},
error: {
color: '#ef4444',
fontSize: 14,
},
});
export default StockPrice;
```
## Com Custom Hook
```javascript
import { useState, useEffect } from 'react';
const useBrapiQuote = (ticker, token) => {
const [data, setData] = useState(null);
const [loading, setLoading] = useState(true);
const [error, setError] = useState(null);
useEffect(() => {
let isMounted = true;
const fetchQuote = async () => {
try {
const response = await fetch(
`https://brapi.dev/api/quote/${ticker}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
if (!response.ok) {
throw new Error(`HTTP ${response.status}`);
}
const json = await response.json();
if (isMounted) {
setData(json.results[0]);
setError(null);
}
} catch (err) {
if (isMounted) {
setError(err.message);
setData(null);
}
} finally {
if (isMounted) {
setLoading(false);
}
}
};
fetchQuote();
return () => {
isMounted = false;
};
}, [ticker, token]);
return { data, loading, error };
};
// Uso
const StockCard = ({ ticker }) => {
const { data, loading, error } = useBrapiQuote(ticker, 'SEU_TOKEN');
if (loading) return ;
if (error) return Erro: {error};
if (!data) return null;
return (
{data.symbol}: R$ {data.regularMarketPrice.toFixed(2)}
);
};
```
## Lista de Cotações
```javascript
import React from 'react';
import { FlatList, View } from 'react-native';
const StockList = () => {
const tickers = ['PETR4', 'VALE3', 'ITUB4', 'BBDC4', 'MGLU3'];
return (
item}
renderItem={({ item }) => }
contentContainerStyle={{ padding: 16 }}
/>
);
};
```
## Próximos Passos
* Veja exemplos em [TypeScript](/docs/examples/typescript)
* Explore [outros exemplos](/docs/examples)
# TypeScript / JavaScript
URL: /docs/examples/typescript.mdx
Exemplos de integração da API brapi.dev usando TypeScript e JavaScript com fetch nativo e Axios. Aprenda a buscar cotações de ações brasileiras em aplicações web e Node.js.
***
title: 'TypeScript / JavaScript'
description: >-
Exemplos de integração da API brapi.dev usando TypeScript e JavaScript com
fetch nativo e Axios. Aprenda a buscar cotações de ações brasileiras em aplicações
web e Node.js.
full: false
keywords:
brapi, api, typescript, javascript, fetch, axios, node.js, web
openGraph:
title: Integração TypeScript/JavaScript - brapi.dev
description: >-
Exemplos práticos de integração com fetch e Axios para buscar cotações da bolsa brasileira
type: website
locale: pt\_BR
lastUpdated: '2025-10-12T17:30:00.000Z'
lang: pt-BR
howToSteps:
* name: 'Escolha sua abordagem: SDK oficial ou fetch/Axios'
text: 'Recomendamos usar a SDK oficial (npm install brapi) para tipos completos e retry automático. Se preferir controle manual, use fetch nativo ou Axios.'
* name: 'Configure seu token de API'
text: 'Armazene seu token em variáveis de ambiente (process.env.BRAPI\_TOKEN). Nunca exponha o token no código frontend.'
* name: 'Faça a requisição para a API'
text: 'Com fetch: await fetch(url, { headers: { Authorization: `Bearer ${token}` } }). Com Axios: await axios.get(url, { headers: { Authorization: `Bearer ${token}` } }).'
* name: 'Parse e use os dados retornados'
text: 'O retorno contém results com array de cotações. Acesse data.results\[0].regularMarketPrice para o preço atual.'
* name: 'Implemente cache e tratamento de erros'
text: 'Use try/catch para erros de rede. Implemente cache (ex: Next.js revalidate, SWR, Map) para economizar requisições.'
howToTools:
* 'Node.js ou navegador moderno'
* 'npm, yarn ou bun'
* 'Editor de código'
howToSupplies:
* 'Conta brapi.dev'
* 'Token de API brapi.dev'
* 'Projeto JavaScript/TypeScript'
***
Integre a API brapi.dev em suas aplicações TypeScript e JavaScript usando nossa SDK oficial ou fetch/Axios.
## 🎉 SDK Oficial Disponível!
A brapi.dev agora oferece uma **SDK oficial TypeScript/JavaScript** que facilita muito a integração:
```bash
npm install brapi
```
**Vantagens da SDK:**
* ✅ Tipos TypeScript completos com IntelliSense
* ✅ Tratamento de erros automático
* ✅ Retry inteligente em falhas
* ✅ Suporte a Node.js e navegador
**Exemplo rápido:**
```typescript
const client = new Brapi({
apiKey: process.env.BRAPI_API_KEY,
});
const quote = await client.quote.retrieve('PETR4');
console.log(quote.results[0].regularMarketPrice);
```
📚 **[Ver documentação completa da SDK](/docs/sdks/typescript)**
***
## Integração Manual (Sem SDK)
Se preferir fazer requisições HTTP diretamente, veja os exemplos abaixo.
## Usando Fetch (Nativo)
O fetch é nativo em navegadores modernos e Node.js 18+, sem necessidade de bibliotecas externas.
### Exemplo Básico
```typescript
const fetchQuote = async () => {
const token = 'SEU_TOKEN';
const ticker = 'PETR4';
const response = await fetch(
`https://brapi.dev/api/quote/${ticker}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
const data = await response.json();
console.log(data);
};
fetchQuote();
```
### Com Tratamento de Erros
```typescript
interface QuoteResult {
results: Array<{
symbol: string;
shortName: string;
regularMarketPrice: number;
regularMarketChange: number;
regularMarketChangePercent: number;
currency: string;
}>;
}
const fetchQuote = async (ticker: string): Promise => {
const token = process.env.BRAPI_TOKEN || 'SEU_TOKEN';
try {
const response = await fetch(
`https://brapi.dev/api/quote/${ticker}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data: QuoteResult = await response.json();
return data;
} catch (error) {
console.error('Erro ao buscar cotação:', error);
return null;
}
};
// Uso
fetchQuote('PETR4').then(data => {
if (data && data.results[0]) {
const quote = data.results[0];
console.log(`${quote.symbol}: R$ ${quote.regularMarketPrice}`);
}
});
```
### Múltiplos Tickers
```typescript
const fetchMultipleQuotes = async (tickers: string[]) => {
const token = 'SEU_TOKEN';
const tickersParam = tickers.join(',');
const response = await fetch(
`https://brapi.dev/api/quote/${tickersParam}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
const data = await response.json();
return data.results;
};
// Uso
fetchMultipleQuotes(['PETR4', 'VALE3', 'ITUB4']).then(quotes => {
quotes.forEach(quote => {
console.log(`${quote.symbol}: R$ ${quote.regularMarketPrice}`);
});
});
```
## Usando Axios
Axios é uma biblioteca popular para fazer requisições HTTP, com sintaxe mais simples e recursos adicionais.
### Instalação
```bash
npm install axios
# ou
yarn add axios
# ou
bun add axios
```
### Exemplo Básico
```typescript
const token = 'SEU_TOKEN';
const ticker = 'PETR4';
const url = `https://brapi.dev/api/quote/${ticker}`;
async function fetchQuote() {
try {
const response = await axios.get(url, {
headers: { 'Authorization': `Bearer ${token}` },
});
console.log(response.data);
} catch (error) {
console.error('Erro ao buscar cotação:', error);
}
}
fetchQuote();
```
### Com TypeScript e Interface
```typescript
interface BrapiQuoteResponse {
results: Array<{
symbol: string;
shortName: string;
longName: string;
currency: string;
regularMarketPrice: number;
regularMarketDayHigh: number;
regularMarketDayLow: number;
regularMarketVolume: number;
regularMarketChange: number;
regularMarketChangePercent: number;
regularMarketTime: string;
marketCap: number;
fiftyTwoWeekLow: number;
fiftyTwoWeekHigh: number;
}>;
requestedAt: string;
took: string;
}
class BrapiClient {
private baseUrl = 'https://brapi.dev/api';
private token: string;
constructor(token: string) {
this.token = token;
}
async getQuote(ticker: string): Promise {
try {
const response = await axios.get(
`${this.baseUrl}/quote/${ticker}`,
{
headers: { 'Authorization': `Bearer ${this.token}` },
}
);
return response.data;
} catch (error) {
if (axios.isAxiosError(error)) {
const axiosError = error as AxiosError;
throw new Error(
`Erro na API: ${axiosError.response?.status} - ${axiosError.message}`
);
}
throw error;
}
}
async getMultipleQuotes(tickers: string[]): Promise {
const tickersParam = tickers.join(',');
return this.getQuote(tickersParam);
}
}
// Uso
const client = new BrapiClient(process.env.BRAPI_TOKEN!);
client.getQuote('PETR4').then(data => {
const quote = data.results[0];
console.log(`${quote.symbol}: R$ ${quote.regularMarketPrice}`);
console.log(`Variação: ${quote.regularMarketChangePercent.toFixed(2)}%`);
});
```
## Exemplo Next.js (App Router)
### Server Component
```typescript
// app/stock/[ticker]/page.tsx
interface QuoteData {
results: Array<{
symbol: string;
shortName: string;
regularMarketPrice: number;
regularMarketChangePercent: number;
}>;
}
async function getQuote(ticker: string): Promise {
const token = process.env.BRAPI_TOKEN;
const res = await fetch(
`https://brapi.dev/api/quote/${ticker}`,
{
headers: { 'Authorization': `Bearer ${token}` },
next: { revalidate: 60 },
}
);
if (!res.ok) {
throw new Error('Failed to fetch quote');
}
return res.json();
}
export default async function StockPage({
params,
}: {
params: { ticker: string };
}) {
const data = await getQuote(params.ticker);
const quote = data.results[0];
return (
);
}
```
### Client Component com SWR
```typescript
'use client';
const fetcher = (url: string) => fetch(url).then(r => r.json());
export function StockQuote({ ticker }: { ticker: string }) {
const { data, error, isLoading } = useSWR(
`/api/quote/${ticker}`,
fetcher,
{ refreshInterval: 60000 } // Atualiza a cada 60 segundos
);
if (error) return ;
if (isLoading) return ;
const quote = data.results[0];
return (
);
}
```
### API Route
```typescript
// app/api/quote/[ticker]/route.ts
export async function GET(
request: Request,
{ params }: { params: { ticker: string } }
) {
const token = process.env.BRAPI_TOKEN;
try {
const response = await fetch(
`https://brapi.dev/api/quote/${params.ticker}`,
{ headers: { 'Authorization': `Bearer ${token}` } }
);
if (!response.ok) {
return NextResponse.json(
{ error: 'Failed to fetch quote' },
{ status: response.status }
);
}
const data = await response.json();
return NextResponse.json(data);
} catch (error) {
return NextResponse.json(
{ error: 'Internal server error' },
{ status: 500 }
);
}
}
```
## Node.js com Cache
```typescript
class BrapiService {
private cache = new Map();
private cacheDuration = 60000; // 60 segundos
constructor(private token: string) {}
async getQuote(ticker: string) {
const cached = this.cache.get(ticker);
const now = Date.now();
if (cached && now - cached.timestamp < this.cacheDuration) {
return cached.data;
}
const response = await axios.get(
`https://brapi.dev/api/quote/${ticker}`,
{ headers: { 'Authorization': `Bearer ${this.token}` } }
);
this.cache.set(ticker, {
data: response.data,
timestamp: now
});
return response.data;
}
}
// Uso
const service = new BrapiService(process.env.BRAPI_TOKEN!);
const data = await service.getQuote('PETR4');
```
## Boas Práticas
1. **Armazene o token em variáveis de ambiente**: Nunca exponha o token no código
2. **Implemente cache**: Evite requisições desnecessárias
3. **Trate erros adequadamente**: Sempre use try/catch ou .catch()
4. **Use tipos TypeScript**: Aproveite a tipagem para melhor DX
5. **Respeite os limites**: Monitore o uso de requisições
## Próximos Passos
* Veja exemplos em [outras linguagens](/docs/examples)
* Explore a [documentação completa da API](/docs)
* Confira os [endpoints disponíveis](/docs/acoes)
# WordPress
URL: /docs/examples/wordpress.mdx
Integre cotações da bolsa brasileira no WordPress usando shortcodes e a API brapi.dev. Exiba preços de ações em posts e páginas.
***
title: 'WordPress'
description: >-
Integre cotações da bolsa brasileira no WordPress usando shortcodes e a API brapi.dev.
Exiba preços de ações em posts e páginas.
full: false
keywords: brapi, api, wordpress, shortcode, php, cotações
openGraph:
title: Integração WordPress - brapi.dev
description: Exiba cotações da bolsa brasileira no WordPress com shortcodes
type: website
locale: pt\_BR
lastUpdated: '2025-10-12T17:30:00.000Z'
lang: pt-BR
howToSteps:
* name: 'Adicione o código ao functions.php'
text: 'Acesse o arquivo functions.php do seu tema WordPress (ou crie um plugin personalizado) e cole o código da função brapi\_get\_stock\_price e brapi\_stock\_price\_shortcode fornecidos.'
* name: 'Configure seu token da API'
text: 'Substitua SEU\_TOKEN no código pelo token que você obteve em brapi.dev. Você pode também armazenar o token usando get\_option para maior segurança.'
* name: 'Use o shortcode em posts e páginas'
text: 'Em qualquer post ou página, insira o shortcode \[brapi\_cotacao ticker="PETR4"] para exibir a cotação do ativo desejado.'
* name: 'Opcionalmente, crie um bloco Gutenberg'
text: 'Para uma experiência mais integrada, registre um bloco customizado usando register\_block\_type para permitir inserir cotações diretamente no editor de blocos.'
howToTools:
* 'WordPress'
* 'Editor de código ou FTP'
* 'Navegador web'
howToSupplies:
* 'Conta brapi.dev'
* 'Token de API brapi.dev'
* 'Tema WordPress com functions.php'
***
Integre cotações da bolsa brasileira no WordPress usando shortcodes personalizados.
## Implementação
Adicione este código ao arquivo `functions.php` do seu tema ou em um plugin personalizado:
```php
10,
'headers' => ['Authorization' => "Bearer {$token}"],
]);
if (is_wp_error($response)) {
return 'Erro ao buscar dados';
}
$body = wp_remote_retrieve_body($response);
$data = json_decode($body, true);
if (isset($data['results'][0]['regularMarketPrice'])) {
$price = $data['results'][0]['regularMarketPrice'];
set_transient($transient_key, $price, 60);
return $price;
}
return 'Cotação indisponível';
}
function brapi_stock_price_shortcode($atts) {
$atts = shortcode_atts([
'ticker' => 'PETR4',
], $atts);
$price = brapi_get_stock_price($atts['ticker']);
if (is_numeric($price)) {
return 'R$ ' . number_format($price, 2, ',', '.');
}
return $price;
}
add_shortcode('brapi_cotacao', 'brapi_stock_price_shortcode');
?>
```
## Uso no WordPress
Use o shortcode em posts e páginas:
```
[brapi_cotacao ticker="PETR4"]
```
Exemplos:
```
[brapi_cotacao ticker="VALE3"]
[brapi_cotacao ticker="ITUB4"]
[brapi_cotacao ticker="IMAB11"]
```
## Com Widget Gutenberg
Para criar um bloco customizado:
```php
'brapi-block',
'render_callback' => 'brapi_render_block'
]);
}
add_action('init', 'brapi_register_block');
function brapi_render_block($attributes) {
$ticker = $attributes['ticker'] ?? 'PETR4';
return brapi_stock_price_shortcode(['ticker' => $ticker]);
}
?>
```
## Próximos Passos
* Veja exemplos em [PHP](/docs/examples/php)
* Explore [outros exemplos](/docs/examples)
# Histórico da Carteira de FIIs
URL: /docs/fiis/carteira-historico.mdx
Acompanhe a evolução trimestral da composição normalizada da carteira dos FIIs.
***
title: Histórico da Carteira de FIIs
description: >-
Acompanhe a evolução trimestral da composição normalizada da carteira dos
FIIs.
full: true
keywords: brapi, api, fii, carteira, portfolio, histórico, trimestral, composição
openGraph:
title: Histórico da Carteira de FIIs
description: Série trimestral compacta de composição de carteira dos FIIs.
type: website
locale: pt\_BR
lastUpdated: '2026-05-30T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/fii/portfolio/history
structuredData:
headings: \[]
contents:
* content: >-
Retorna a série trimestral de resumos de composição de carteira dos FIIs.
***
import { Callout } from 'fumadocs-ui/components/callout';
Use este endpoint para acompanhar a evolução da carteira dos FIIs por trimestre.
A resposta é compacta: cada item em `history[]` traz `summary` e `allocations`,
sem as listas detalhadas de CRIs, cotas, imóveis, terrenos e direitos.
Para abrir os itens de um trimestre específico, use
[`/api/v2/fii/portfolio`](/docs/fiis/carteira) com `referenceDate`.
Sandbox sem token: `symbols=HGLG11` e `symbols=MXRF11`. Para todos os FIIs,
use um token Pro.
## Quando usar
* **Composição ao longo do tempo:** use `history[].allocations`.
* **Valor declarado:** use `history[].summary.declaredValue`.
* **FIIs de papel e FoFs:** acompanhe `financialAssets.declaredValue`.
* **Retificações:** use `allVersions=true` para ver versões anteriores do informe.
# Carteira de FIIs
URL: /docs/fiis/carteira.mdx
Consulte a composição normalizada da carteira dos FIIs: CRIs, cotas de outros FIIs, imóveis, direitos e terrenos.
***
title: Carteira de FIIs
description: >-
Consulte a composição normalizada da carteira dos FIIs: CRIs, cotas de outros
FIIs, imóveis, direitos e terrenos.
full: true
keywords: brapi, api, fii, carteira, portfolio, fof, cri, cotas de fii, cvm
openGraph:
title: Carteira de FIIs
description: Carteira normalizada de FIIs para FoFs, FIIs de papel e análise de composição.
type: website
locale: pt\_BR
lastUpdated: '2026-05-30T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/fii/portfolio
structuredData:
headings: \[]
contents:
* content: >-
Retorna a composição normalizada da carteira de FIIs agrupada por fundo.
***
import { Callout } from 'fumadocs-ui/components/callout';
Use este endpoint para responder “o que este FII possui?”. A resposta vem
agrupada por FII, com `summary`, `allocations`, `financialAssets`,
`fundHoldings`, `properties`, `lands` e `rights`.
Para imóveis físicos e vacância, prefira [`/api/v2/fii/properties`](/docs/fiis/imoveis).
Este endpoint é melhor para FoFs, FIIs de papel, CRIs e composição geral.
Sandbox sem token: `symbols=HGLG11` e `symbols=MXRF11`. Para todos os FIIs,
use um token Pro.
## Quando usar
* **FoFs:** use `fundHoldings` para ver cotas de outros FIIs.
* **FIIs de papel:** use `financialAssets` para CRIs, emissores e valores.
* **Carteiras híbridas:** use `allocations` para entender a composição.
* **Auditoria:** use `referenceDate` para travar um trimestre específico.
* **Evolução trimestral:** use [`/api/v2/fii/portfolio/history`](/docs/fiis/carteira-historico).
# Dividendos de FIIs
URL: /docs/fiis/dividendos.mdx
Consulte o histórico de dividendos e rendimentos de Fundos Imobiliários, com filtros de data e ordenação.
***
title: Dividendos de FIIs
description: >-
Consulte o histórico de dividendos e rendimentos de Fundos Imobiliários,
com filtros de data e ordenação.
full: true
keywords: brapi, api, fii, dividendos, rendimentos, amortização
openGraph:
title: Dividendos de FIIs
description: >-
Histórico de dividendos e rendimentos de Fundos Imobiliários.
type: website
locale: pt\_BR
lastUpdated: '2026-04-25T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/fii/dividends
structuredData:
headings: \[]
contents:
* content: >-
Retorna o histórico de dividendos e rendimentos de FIIs, incluindo
rendimentos mensais e amortizações, com filtros de data.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna o histórico de dividendos (rendimentos e amortizações) de um ou mais
FIIs. Use `startDate` e `endDate` para delimitar o período e `sortOrder` para
controlar a direção.
Aceita até **20 símbolos** separados por vírgula.
**Plano mínimo: Pro.** No sandbox sem token, aceita apenas `symbols=MXRF11`
e/ou `HGLG11`.
# Financeiros de FIIs
URL: /docs/fiis/financeiros.mdx
Relatórios DFIN oficiais de FIIs por símbolo ou CNPJ.
***
title: Financeiros de FIIs
description: Relatórios DFIN oficiais de FIIs por símbolo ou CNPJ.
full: true
keywords: brapi, FII, DFIN, financeiro, CVM
openGraph:
title: Financeiros de FIIs
description: Dados financeiros DFIN oficiais para FIIs.
type: website
locale: pt\_BR
lastUpdated: '2026-06-14T00:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/fii/financials
-----------------------------
Consulta relatórios DFIN de FIIs por símbolo, CNPJ, ano ou período.
# Cotações Históricas de FIIs
URL: /docs/fiis/historico.mdx
Consulte cotações históricas OHLCV diárias de Fundos Imobiliários para gráficos de preço e backtests.
***
title: Cotações Históricas de FIIs
description: >-
Consulte cotações históricas OHLCV diárias de Fundos Imobiliários para
gráficos de preço e backtests.
full: true
keywords: brapi, api, fii, cotações, histórico, OHLCV
openGraph:
title: Cotações Históricas de FIIs
description: >-
Cotações históricas OHLCV diárias de Fundos Imobiliários.
type: website
locale: pt\_BR
lastUpdated: '2026-04-25T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/fii/historical
structuredData:
headings: \[]
contents:
* content: >-
Retorna cotações históricas OHLCV diárias de FIIs, com filtros por
data e ordenação. Ideal para gráficos de preço e backtests.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna cotações históricas OHLCV (abertura, máxima, mínima, fechamento,
volume) diárias de um ou mais FIIs. Use `startDate` e `endDate` para delimitar
o período (padrão: últimos 12 meses).
Aceita até **20 símbolos** separados por vírgula. Cada símbolo retorna sua
própria série temporal.
**Plano mínimo: Pro.** No sandbox sem token, aceita apenas `symbols=MXRF11`
e/ou `HGLG11`.
# Histórico de Imóveis e Vacância
URL: /docs/fiis/imoveis-historico.mdx
Acompanhe a evolução trimestral de imóveis, área e vacância consolidada dos FIIs.
***
title: Histórico de Imóveis e Vacância
description: >-
Acompanhe a evolução trimestral de imóveis, área e vacância consolidada dos
FIIs.
full: true
keywords: brapi, api, fii, imóveis, vacância, histórico, trimestral
openGraph:
title: Histórico de Imóveis e Vacância
description: Série trimestral compacta de imóveis, área e vacância de FIIs.
type: website
locale: pt\_BR
lastUpdated: '2026-05-30T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/fii/properties/history
structuredData:
headings: \[]
contents:
* content: >-
Retorna a série trimestral de resumos de imóveis e vacância dos FIIs.
***
import { Callout } from 'fumadocs-ui/components/callout';
Use este endpoint para montar gráficos de vacância, área total e quantidade de
imóveis ao longo dos trimestres. A resposta é compacta: cada item em `history[]`
traz `symbol`, `referenceDate`, `version` e `summary`, sem a lista completa de
imóveis.
Para inspecionar os imóveis de um trimestre específico, use
[`/api/v2/fii/properties`](/docs/fiis/imoveis) com `referenceDate`.
Sandbox sem token: `symbols=HGLG11` e `symbols=MXRF11`. Para todos os FIIs,
use um token Pro.
## Quando usar
* **Gráfico de vacância:** use `history[].summary.vacancyRate`.
* **Evolução de área:** use `history[].summary.totalArea`.
* **Mudança de carteira física:** compare `history[].summary.count`.
* **Retificações:** use `allVersions=true` para ver versões anteriores do informe.
# Imóveis e Vacância de FIIs
URL: /docs/fiis/imoveis.mdx
Consulte imóveis físicos de FIIs com área, endereço, vacância, inadimplência e participação na receita.
***
title: Imóveis e Vacância de FIIs
description: >-
Consulte imóveis físicos de FIIs com área, endereço, vacância, inadimplência e
participação na receita.
full: true
keywords: brapi, api, fii, imóveis, vacância, tijolo, galpões, shoppings
openGraph:
title: Imóveis e Vacância de FIIs
description: Endpoint simples para analisar imóveis físicos e vacância de FIIs.
type: website
locale: pt\_BR
lastUpdated: '2026-05-30T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/fii/properties
structuredData:
headings: \[]
contents:
* content: >-
Retorna imóveis físicos de FIIs com vacância consolidada e item a item.
***
import { Callout } from 'fumadocs-ui/components/callout';
Use este endpoint para analisar FIIs de tijolo. A vacância aparece em primeiro
plano: `summary.vacancyRate` é ponderada por área quando possível, e cada imóvel
vem em `properties[]` com `area`, `address`, `propertyClass`, `unitCount`,
`vacancyRate`, `delinquencyRate` e `revenueShare`.
Campos de taxa como `vacancyRate`, `delinquencyRate` e `revenueShare` são
razões decimais. Exemplo: `0.0328` significa `3,28%`.
Sandbox sem token: `symbols=HGLG11` e `symbols=MXRF11`. Para todos os FIIs,
use um token Pro.
## Quando usar
* **Vacância:** use `summary.vacancyRate` para a taxa consolidada.
* **Concentração física:** compare `properties[].area`.
* **Risco operacional:** combine `vacancyRate`, `delinquencyRate` e `revenueShare`.
* **Trimestre específico:** use `referenceDate=YYYY-MM-DD`.
* **Evolução trimestral:** use [`/api/v2/fii/properties/history`](/docs/fiis/imoveis-historico).
* **Ordenação:** use `sortBy=revenueShare|area|vacancyRate|name` e `sortOrder=asc|desc`.
# Fundos Imobiliários (FIIs)
URL: /docs/fiis.mdx
Guia prático para integrar dados de FIIs na brapi: indicadores, relatórios CVM, dividendos, cotações históricas e listagem com filtros.
***
title: Fundos Imobiliários (FIIs)
description: >-
Guia prático para integrar dados de FIIs na brapi: indicadores, relatórios
CVM, dividendos, cotações históricas e listagem com filtros.
full: true
keywords: brapi, api, fii, fundos imobiliários, indicadores, dividendos, relatórios
openGraph:
title: Fundos Imobiliários (FIIs)
description: >-
Guia prático para integrar dados de FIIs na brapi, com fluxo recomendado
e exemplos de uso.
type: website
locale: pt\_BR
lastUpdated: '2026-04-25T12:00:00.000Z'
lang: pt-BR
-----------
import { Callout } from 'fumadocs-ui/components/callout';
import { Card, Cards } from 'fumadocs-ui/components/card';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
Use a API de FIIs para criar screeners, dashboards, análises de dividendos e
fluxos de due diligence para fundos imobiliários brasileiros.
O fluxo mais comum é:
1. descobrir FIIs com **listagem e filtros**
2. consultar **indicadores atuais** como P/VP, DY e patrimônio
3. acompanhar **histórico de preço, indicadores e dividendos**
4. abrir **relatórios CVM, imóveis, vacância e carteira**
Indicadores fundamentalistas, relatórios CVM, carteira normalizada, imóveis e
vacância, histórico de dividendos/rendimentos, e cotações OHLCV diárias.
Cotações básicas de FIIs (preço, variação) estão disponíveis em todos os
planos via `/api/quote/MXRF11`. Os endpoints `/api/v2/fii/*` documentados
aqui trazem **dados detalhados** e são exclusivos do plano **Pro**.
## Cobertura e frequência
* **Indicadores:** atualizados diariamente após o fechamento do pregão.
* **Relatórios CVM:** importados mensalmente conforme publicação pela CVM.
* **Carteira e imóveis:** importados dos informes trimestrais da CVM.
* **Dividendos:** consolidados a partir dos relatórios mensais.
* **Cotações históricas:** OHLCV diário, mesmo formato dos demais ativos.
* **Fuso horário:** `America/Sao_Paulo`. Campos de data em respostas seguem
formato ISO 8601 ou timestamp Unix.
* **Formato de datas em query params:** `YYYY-MM-DD`.
## Acesso por plano
Dados detalhados de FIIs fazem parte do plano **Pro**. O sandbox permite
experimentação sem token para **MXRF11** e **HGLG11**.
| Plano | Acesso a FIIs detalhados |
| ------------------- | ---------------------------------- |
| Sandbox (sem token) | MXRF11 e HGLG11 |
| Free | Cotações básicas via `/api/quote/` |
| Startup | Cotações básicas via `/api/quote/` |
| **Pro** | **Todos os FIIs detalhados** |
## Termos que você vai ver
* **Segmento (`segmentType`):** classificação patrimonial do FII — `papel`,
`tijolo`, `hibrido` ou `fof` (fundo de fundos).
* **Segmento de atuação (`segmentoAtuacao`):** setor do mercado imobiliário.
Ex.: `Logística`, `Shoppings`, `Lajes Corporativas`, `Títulos e Val. Mob.`.
* **Tipo de gestão (`tipoGestao`):** `Ativa` ou `Definida` (passiva).
* **Mandato (`mandate`):** perfil de investimento — `Renda`, `Ganho de Capital`
ou `Híbrido`.
* **P/VP (`priceToNav`):** preço de mercado dividido pelo valor patrimonial
por cota. Abaixo de 1 indica desconto.
* **Dividend Yield (`dividendYield12m`):** rendimento dos últimos 12 meses em
relação ao preço atual.
* **Vacância:** percentual de imóveis desocupados (relevante para FIIs de
tijolo).
* **Relatório gerencial:** documento mensal enviado à CVM com composição
patrimonial, rentabilidade e dados operacionais.
## Início rápido
Exemplo do fluxo `listagem → indicadores → dividendos` usando os tickers do
sandbox.
```bash
# 1) Busque um FII disponível no sandbox
curl "https://brapi.dev/api/v2/fii/list?symbols=MXRF11&limit=5"
# 2) Consulte indicadores de um FII específico
curl "https://brapi.dev/api/v2/fii/indicators?symbols=MXRF11"
# 3) Veja o histórico de dividendos
curl "https://brapi.dev/api/v2/fii/dividends?symbols=MXRF11"
```
```typescript
const BASE = 'https://brapi.dev/api/v2/fii';
const token = process.env.BRAPI_TOKEN; // opcional para MXRF11/HGLG11 no sandbox
const headers = token ? { Authorization: `Bearer ${token}` } : undefined;
// 1) Listagem com ticker do sandbox
const list = await fetch(
`${BASE}/list?symbols=MXRF11&limit=5`,
{ headers },
).then((r) => r.json());
// 2) Indicadores atuais
const indicators = await fetch(
`${BASE}/indicators?symbols=MXRF11,HGLG11`,
{ headers },
).then((r) => r.json());
// 3) Histórico de dividendos
const dividends = await fetch(
`${BASE}/dividends?symbols=MXRF11`,
{ headers },
).then((r) => r.json());
console.log({ list, indicators, dividends });
```
```python
import os
import requests
BASE = "https://brapi.dev/api/v2/fii"
token = os.getenv("BRAPI_TOKEN") # opcional para MXRF11/HGLG11 no sandbox
headers = {"Authorization": f"Bearer {token}"} if token else {}
# 1) Listagem com ticker do sandbox
fii_list = requests.get(
f"{BASE}/list",
params={"symbols": "MXRF11", "limit": 5},
headers=headers,
).json()
# 2) Indicadores atuais
indicators = requests.get(
f"{BASE}/indicators",
params={"symbols": "MXRF11,HGLG11"},
headers=headers,
).json()
# 3) Histórico de dividendos
dividends = requests.get(
f"{BASE}/dividends",
params={"symbols": "MXRF11"},
headers=headers,
).json()
print(fii_list, indicators, dividends)
```
## Fluxo recomendado
#### Descubra os FIIs disponíveis
Comece em [`/api/v2/fii/list`](/docs/fiis/listagem) para explorar FIIs com
filtros por segmento, setor de atuação, tipo de gestão e mandato.
#### Consulte os indicadores atuais
Use [`/api/v2/fii/indicators`](/docs/fiis/indicadores) para ver P/VP,
dividend yield, patrimônio, número de cotistas e dados do administrador.
#### Acompanhe a evolução dos indicadores
Use [`/api/v2/fii/indicators/history`](/docs/fiis/indicadores-historico)
para montar gráficos de evolução mensal de P/VP, DY, patrimônio e outros
indicadores.
#### Consulte cotações históricas
Use [`/api/v2/fii/historical`](/docs/fiis/historico) para obter OHLCV
diário. Ideal para gráficos de preço e backtests.
#### Acesse os relatórios da CVM
Use [`/api/v2/fii/reports`](/docs/fiis/relatorios) para consultar os
relatórios gerenciais mensais com composição patrimonial, rentabilidade
e dados operacionais.
#### Analise imóveis e vacância
Use [`/api/v2/fii/properties`](/docs/fiis/imoveis) para consultar imóveis
físicos, área, endereço, vacância e participação na receita.
#### Acompanhe vacância no tempo
Use [`/api/v2/fii/properties/history`](/docs/fiis/imoveis-historico) para
gráficos trimestrais de vacância, área total e quantidade de imóveis.
#### Abra a composição da carteira
Use [`/api/v2/fii/portfolio`](/docs/fiis/carteira) para consultar ativos,
cotas de outros FIIs, CRIs, imóveis, direitos e terrenos.
#### Acompanhe composição no tempo
Use [`/api/v2/fii/portfolio/history`](/docs/fiis/carteira-historico) para
ver a evolução trimestral de alocações e valor declarado.
#### Consulte o histórico de dividendos
Use [`/api/v2/fii/dividends`](/docs/fiis/dividendos) para ver rendimentos
e amortizações pagos ao longo do tempo.
## Casos de uso mais comuns
* **Tela de screening de FIIs:** `list` com filtros → exibir indicadores
* **Dashboard de acompanhamento:** `indicators` para dados atuais + `indicators/history` para evolução
* **Análise de dividendos:** `dividends` para histórico de rendimentos
* **Gráfico de preço:** `historical` para OHLCV diário
* **Due diligence:** `reports` para relatórios CVM + `indicators` para snapshot atual
* **Vacância de FIIs de tijolo:** `properties` para imóveis físicos e `properties/history` para evolução trimestral
* **Carteira detalhada:** `portfolio` para FoFs, CRIs e composição normalizada; `portfolio/history` para evolução de alocação
* **Comparação entre FIIs:** `indicators` com múltiplos symbols (até 20 por request)
## Quando você pode pular etapas
* Se você **já sabe o ticker**, pode ir direto para `indicators`, `historical`,
`dividends`, `reports`, `properties`, `properties/history`, `portfolio` ou
`portfolio/history`.
* Se você quer **só listar e filtrar**, use `list` sem precisar dos outros endpoints.
* Se você quer **só dividendos**, pode ir direto para `dividends` com o ticker.
## Perguntas frequentes
## Receitas prontas
Guias e tutoriais publicados no blog com código pronto para copiar:
## Sandbox sem token
Para facilitar a experimentação, os endpoints de FIIs por símbolo aceitam
consultas no sandbox sem token, restritas a **MXRF11** e **HGLG11**:
* `GET /api/v2/fii/list`: requer token Pro para listar todos os FIIs; sem token,
funciona apenas com `symbols=MXRF11` e/ou `symbols=HGLG11`.
* `GET /api/v2/fii/indicators`, `/indicators/history`, `/historical`,
`/reports`, `/properties`, `/properties/history`, `/portfolio`,
`/portfolio/history` e `/dividends`: funcionam sem token apenas com `symbols`
contendo exclusivamente MXRF11 e/ou HGLG11.
Para qualquer outro FII, é necessário autenticar com um token do plano Pro.
## Endpoints
# Indicadores Históricos de FIIs
URL: /docs/fiis/indicadores-historico.mdx
Acompanhe a evolução mensal dos indicadores de FIIs: P/VP, dividend yield, patrimônio e mais, com filtros de data e ordenação.
***
title: Indicadores Históricos de FIIs
description: >-
Acompanhe a evolução mensal dos indicadores de FIIs: P/VP, dividend yield,
patrimônio e mais, com filtros de data e ordenação.
full: true
keywords: brapi, api, fii, indicadores, histórico, evolução mensal
openGraph:
title: Indicadores Históricos de FIIs
description: >-
Série temporal mensal dos indicadores fundamentalistas de FIIs.
type: website
locale: pt\_BR
lastUpdated: '2026-04-25T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/fii/indicators/history
structuredData:
headings: \[]
contents:
* content: >-
Retorna a série histórica mensal dos indicadores de FIIs, com
filtros por data e ordenação. Ideal para gráficos de evolução.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna a série histórica mensal dos indicadores de FIIs. Use `startDate` e
`endDate` para delimitar o período e `sortOrder` para controlar a direção
(padrão: mais recente primeiro).
Ideal para montar gráficos de evolução de P/VP, dividend yield, patrimônio
e outros indicadores ao longo dos meses. Dados disponíveis a partir de
**setembro de 2016**.
**Plano mínimo: Pro.** No sandbox sem token, aceita apenas `symbols=MXRF11`
e/ou `HGLG11`.
# Indicadores de FIIs
URL: /docs/fiis/indicadores.mdx
Consulte indicadores fundamentalistas atuais de FIIs: P/VP, dividend yield, patrimônio, cotistas e dados do administrador.
***
title: Indicadores de FIIs
description: >-
Consulte indicadores fundamentalistas atuais de FIIs: P/VP, dividend yield,
patrimônio, cotistas e dados do administrador.
full: true
keywords: brapi, api, fii, indicadores, P/VP, dividend yield
openGraph:
title: Indicadores de FIIs
description: >-
Consulte indicadores fundamentalistas atuais de Fundos Imobiliários.
type: website
locale: pt\_BR
lastUpdated: '2026-04-25T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/fii/indicators
structuredData:
headings: \[]
contents:
* content: >-
Retorna indicadores fundamentalistas atuais de FIIs, incluindo
P/VP, dividend yield, patrimônio líquido, número de cotistas e
informações do administrador.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna indicadores fundamentalistas atuais de um ou mais FIIs. Inclui P/VP,
dividend yield (1 mês e 12 meses), patrimônio líquido, total de ativos,
número de cotistas, cotas emitidas e dados do administrador (nome, CNPJ,
contato).
Aceita até **20 símbolos** separados por vírgula. Para acompanhar a evolução
desses indicadores ao longo do tempo, use
[Indicadores Históricos](/docs/fiis/indicadores-historico).
**Plano mínimo: Pro.** No sandbox sem token, aceita apenas `symbols=MXRF11`
e/ou `HGLG11`.
# Informes Anuais de FIIs
URL: /docs/fiis/informes-anuais.mdx
Informes anuais oficiais de FIIs por símbolo ou CNPJ.
***
title: Informes Anuais de FIIs
description: Informes anuais oficiais de FIIs por símbolo ou CNPJ.
full: true
keywords: brapi, FII, informe anual, CVM
openGraph:
title: Informes Anuais de FIIs
description: Informes anuais oficiais para FIIs.
type: website
locale: pt\_BR
lastUpdated: '2026-06-14T00:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/fii/annual-reports
---------------------------------
Consulta informes anuais de FIIs por símbolo, CNPJ, ano ou período.
# Listagem de FIIs
URL: /docs/fiis/listagem.mdx
Liste e filtre Fundos Imobiliários por símbolos, CNPJs, segmento, setor de atuação, tipo de gestão e mandato, com paginação e ordenação.
***
title: Listagem de FIIs
description: >-
Liste e filtre Fundos Imobiliários por símbolos, CNPJs, segmento, setor de
atuação, tipo de gestão e mandato, com paginação e ordenação.
full: true
keywords: brapi, api, fii, fundos imobiliários, listagem, filtro
openGraph:
title: Listagem de FIIs
description: >-
Liste e filtre Fundos Imobiliários com indicadores resumidos.
type: website
locale: pt\_BR
lastUpdated: '2026-04-25T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/fii/list
structuredData:
headings: \[]
contents:
* content: >-
Retorna uma lista paginada de FIIs com indicadores resumidos,
filtros por símbolos, segmento, setor, gestão e mandato, e busca
textual.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna uma lista paginada de FIIs com indicadores resumidos. Use filtros para
refinar por segmento (`papel`, `tijolo`, `híbrido`, `fof`), setor de atuação,
tipo de gestão, mandato, símbolos específicos e CNPJs. Suporta busca textual
pelo nome, ticker ou CNPJ.
Ideal como ponto de partida para telas de screening ou seleção de FIIs.
Veja o fluxo completo em [Fundos Imobiliários](/docs/fiis).
Para FIAGRO, FI-Infra/FIF, FIDC e FIP, use a seção
[Fundos](/docs/fundos). Por exemplo, `JURO11` é FI-Infra/FIF e deve ser
consultado em `/api/v2/funds/list?symbols=JURO11`, não como FII.
**Plano mínimo: Pro.** A listagem completa requer token. Para testar sem token,
use `symbols=MXRF11` e/ou `symbols=HGLG11`, por exemplo
`/api/v2/fii/list?symbols=HGLG11`.
# Relatórios CVM de FIIs
URL: /docs/fiis/relatorios.mdx
Acesse os relatórios gerenciais mensais de FIIs enviados à CVM, com composição patrimonial, rentabilidade e dados operacionais.
***
title: Relatórios CVM de FIIs
description: >-
Acesse os relatórios gerenciais mensais de FIIs enviados à CVM, com
composição patrimonial, rentabilidade e dados operacionais.
full: true
keywords: brapi, api, fii, relatórios, CVM, gerencial mensal
openGraph:
title: Relatórios CVM de FIIs
description: >-
Relatórios gerenciais mensais de FIIs com composição patrimonial e
rentabilidade.
type: website
locale: pt\_BR
lastUpdated: '2026-04-25T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/fii/reports
structuredData:
headings: \[]
contents:
* content: >-
Retorna os relatórios gerenciais mensais de FIIs enviados à CVM,
com composição patrimonial, taxas, rentabilidade e passivos.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna os relatórios gerenciais mensais de FIIs conforme enviados à CVM.
Inclui composição patrimonial (CRI, LCI, imóveis, títulos públicos, cotas
de outros FIIs), taxas de administração, rentabilidade mensal, dividend yield
e passivos.
Use `allVersions=true` para incluir versões retificadas dos relatórios.
Suporta paginação via `page` e `limit`, e ordenação via `sortBy` e
`sortOrder`.
**Plano mínimo: Pro.** No sandbox sem token, aceita apenas `symbols=MXRF11`
e/ou `HGLG11`.
# Carteira de Fundos
URL: /docs/fundos/carteira.mdx
Posições oficiais CVM CDA agrupadas por tipo de ativo.
***
title: Carteira de Fundos
description: Posições oficiais CVM CDA agrupadas por tipo de ativo.
full: true
keywords: brapi, fundos, carteira, CDA, holdings, JURO11
openGraph:
title: Carteira de Fundos
description: Carteira CVM CDA agrupada em títulos públicos, cotas, crédito e outros.
type: website
locale: pt\_BR
lastUpdated: '2026-06-14T00:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/funds/portfolio
------------------------------
Retorna a carteira do fundo agrupada por tipo de ativo, como títulos públicos,
cotas de fundos, crédito, ativos listados, recebíveis e obrigações. Posições
confidenciais aparecem como agregados. Informações adicionais de cada posição
ficam em `details`, com nomes padronizados pela brapi.
# Dividendos
URL: /docs/fundos/dividendos.mdx
Eventos oficiais de dividendos para FIAGRO, FI-Infra/FIF, FIDC e FIP listados.
***
title: Dividendos
description: Eventos oficiais de dividendos para FIAGRO, FI-Infra/FIF, FIDC e FIP listados.
full: true
keywords: brapi, fundos, dividendos, rendimentos, FIAGRO, FI-Infra, FIDC, FIP
openGraph:
title: Dividendos de Fundos
description: Datas e valores oficiais de dividendos de fundos listados não-FII.
type: website
locale: pt\_BR
lastUpdated: '2026-06-26T00:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/funds/dividends
------------------------------
Consulte dividendos de fundos listados não-FII, como FIAGRO, FI-Infra/FIF,
FIDC e FIP, com datas, valor por cota e rótulo do evento.
# Carteira FIAGRO
URL: /docs/fundos/fiagro-carteira.mdx
Alocações FIAGRO agrupadas por crédito agro, passivos e cotistas.
***
title: Carteira FIAGRO
description: Alocações FIAGRO agrupadas por crédito agro, passivos e cotistas.
full: true
keywords: brapi, FIAGRO, carteira, CRA, CPR, FIDC, FII
openGraph:
title: Carteira FIAGRO
description: Alocações FIAGRO normalizadas a partir dos relatórios mensais.
type: website
locale: pt\_BR
lastUpdated: '2026-06-14T00:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/funds/fiagro/portfolio
-------------------------------------
Retorna a carteira FIAGRO do mês selecionado em seções como resumo, alocações,
passivos e investidores.
# Relatórios FIAGRO
URL: /docs/fundos/fiagro-relatorios.mdx
Relatórios mensais FIAGRO da CVM por símbolo ou CNPJ.
***
title: Relatórios FIAGRO
description: Relatórios mensais FIAGRO da CVM por símbolo ou CNPJ.
full: true
keywords: brapi, FIAGRO, relatórios, CVM, XPCA11, CRAA11
openGraph:
title: Relatórios FIAGRO
description: Dados mensais FIAGRO com patrimônio, valor da cota, cotistas e rendimento.
type: website
locale: pt\_BR
lastUpdated: '2026-06-14T00:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/funds/fiagro/reports
-----------------------------------
Consulta relatórios mensais FIAGRO com patrimônio, valor patrimonial por cota,
cotistas, rendimento e campos de
agro/crédito.
# Carteira FIDC
URL: /docs/fundos/fidc-carteira.mdx
Setores, vencimentos, inadimplência, risco, cotas e cotistas.
***
title: Carteira FIDC
description: Setores, vencimentos, inadimplência, risco, cotas e cotistas.
full: true
keywords: brapi, FIDC, carteira, risco, cotas, inadimplência
openGraph:
title: Carteira FIDC
description: Seções agrupadas do relatório mensal FIDC.
type: website
locale: pt\_BR
lastUpdated: '2026-06-14T00:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/funds/fidc/portfolio
-----------------------------------
Retorna a carteira FIDC em seções prontas para análise de crédito estruturado:
setores, vencimentos, inadimplência, risco, cotas, cotistas e cedentes.
# Relatórios FIDC
URL: /docs/fundos/fidc-relatorios.mdx
Relatórios mensais FIDC CVM por CNPJ e símbolo quando houver mapeamento.
***
title: Relatórios FIDC
description: Relatórios mensais FIDC CVM por CNPJ e símbolo quando houver mapeamento.
full: true
keywords: brapi, FIDC, relatórios, CVM, crédito estruturado
openGraph:
title: Relatórios FIDC
description: Dados mensais FIDC com ativos, carteira, PL e administrador.
type: website
locale: pt\_BR
lastUpdated: '2026-06-14T00:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/funds/fidc/reports
---------------------------------
Use `cnpjs` como identificador principal para FIDCs. `symbols` também funciona
quando o fundo tem ticker mapeado na base da brapi.
# Relatórios FIP
URL: /docs/fundos/fip-relatorios.mdx
Relatórios estruturados FIP trimestrais e quadrimestrais da CVM.
***
title: Relatórios FIP
description: Relatórios estruturados FIP trimestrais e quadrimestrais da CVM.
full: true
keywords: brapi, FIP, relatórios, trimestral, quadrimestral
openGraph:
title: Relatórios FIP
description: Relatórios FIP por CNPJ e tipo de documento.
type: website
locale: pt\_BR
lastUpdated: '2026-06-14T00:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/funds/fip/reports
--------------------------------
Consulta relatórios FIP por CNPJ, com suporte a `reportType=trimestral` ou
`reportType=quadrimestral`. `symbols` também funciona quando o fundo tem ticker
mapeado na base da brapi. A resposta organiza capital, cotas, classe e
composição de investidores em campos prontos para uso.
# Fundos
URL: /docs/fundos.mdx
Descubra e consulte fundos brasileiros listados e estruturados: FIIs, FIAGROs, FI-Infra/FIFs, FIDCs e FIPs.
***
title: Fundos
description: >-
Descubra e consulte fundos brasileiros listados e estruturados: FIIs,
FIAGROs, FI-Infra/FIFs, FIDCs e FIPs.
full: true
keywords: brapi, fundos, FIAGRO, FI-Infra, FIF, FIDC, FIP, CNPJ
openGraph:
title: Fundos
description: Identidade, indicadores, valor da cota, carteira e relatórios de fundos brasileiros.
type: website
locale: pt\_BR
lastUpdated: '2026-06-14T00:00:00.000Z'
lang: pt-BR
-----------
import { Callout } from 'fumadocs-ui/components/callout';
import { Cards, Card } from 'fumadocs-ui/components/card';
Use `/api/v2/funds/*` para consultar fundos brasileiros fora do fluxo de ações:
FIAGROs, FI-Infra/FIFs, FIDCs, FIPs e outros fundos estruturados. A API aceita
`symbols` para fundos listados e `cnpjs` para fundos em que o CNPJ é o melhor
identificador.
Para FIIs tradicionais, use `/api/v2/fii/*`. Para FIAGRO, FI-Infra/FIF, FIDC
e FIP, use os endpoints desta seção.
Identidade canônica por símbolo, CNPJ, ISIN e tipo de fundo.
Preço de mercado, valor patrimonial por cota, patrimônio, ativos e cotistas.
Série diária oficial CVM FI/FIF, separada do preço de mercado.
Posições CVM CDA agrupadas em seções úteis.
Eventos oficiais com datas exatas para fundos listados não-FII.
## Fluxo recomendado
Comece pela listagem para resolver símbolo, CNPJ e tipo de fundo. Depois use o
endpoint específico para indicadores, valor da cota, carteira ou relatórios.
```bash
curl -H "Authorization: Bearer SEU_TOKEN" \
"https://brapi.dev/api/v2/funds/list?symbols=JURO11,XPCA11"
curl -H "Authorization: Bearer SEU_TOKEN" \
"https://brapi.dev/api/v2/funds/indicators?symbols=JURO11"
curl -H "Authorization: Bearer SEU_TOKEN" \
"https://brapi.dev/api/v2/funds/fiagro/reports?symbols=XPCA11&startDate=2026-01-01"
```
* Use `/api/v2/funds/list` para descobrir se o ativo é FII, FIAGRO, FI-Infra/FIF, FIDC ou FIP.
* Use `/api/v2/funds/indicators` e `/api/v2/funds/nav/history` para FI-Infra/FIF, onde valor patrimonial por cota e preço de mercado são dados diferentes.
* Use `/api/v2/funds/dividends` quando precisar de rendimentos/amortizações oficiais de FIAGRO, FI-Infra/FIF, FIDC ou FIP listados com data-com/ex e data de pagamento.
* Para FIDCs, `/api/v2/funds/nav/history?cnpjs=...` retorna valor da cota e rentabilidade mensal por classe ou série.
* Use endpoints específicos como `/api/v2/funds/fiagro/reports`, `/api/v2/funds/fidc/reports` e `/api/v2/funds/fip/reports` para relatórios CVM.
* Use `/api/v2/fii/*` quando o produto é um FII tradicional e você precisa de imóveis, vacância, informes mensais, DFIN, informes anuais ou dividendos.
# Indicadores de Fundos
URL: /docs/fundos/indicadores.mdx
Consulte preço, valor patrimonial por cota, patrimônio, ativos e cotistas.
***
title: Indicadores de Fundos
description: Consulte preço, valor patrimonial por cota, patrimônio, ativos e cotistas.
full: true
keywords: brapi, fundos, indicadores, valor patrimonial, preço, JURO11
openGraph:
title: Indicadores de Fundos
description: Indicadores atuais para FIIs, FIAGROs e FI-Infra/FIFs.
type: website
locale: pt\_BR
lastUpdated: '2026-06-14T00:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/funds/indicators
-------------------------------
Retorna indicadores atuais como preço de mercado, valor patrimonial por cota,
relação entre preço e valor patrimonial, patrimônio, ativos e cotistas. O preço
de mercado e o valor patrimonial por cota (`navPerShare`) são campos separados.
# Listagem de Fundos
URL: /docs/fundos/listagem.mdx
Liste fundos por símbolo, CNPJ, busca textual, tipo e status.
***
title: Listagem de Fundos
description: Liste fundos por símbolo, CNPJ, busca textual, tipo e status.
full: true
keywords: brapi, fundos, listagem, FIAGRO, FI-Infra, FIDC, FIP
openGraph:
title: Listagem de Fundos
description: Descubra FIIs, FIAGROs, FI-Infra/FIFs, FIDCs e FIPs.
type: website
locale: pt\_BR
lastUpdated: '2026-06-14T00:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/funds/list
-------------------------
import { Callout } from 'fumadocs-ui/components/callout';
Lista fundos brasileiros com `symbol`, `cnpj`, `assetType`, nomes,
classificações CVM/B3, administradores e indicadores atuais.
Use `/api/v2/funds/list?symbols=JURO11` para consultar um fundo listado,
`/api/v2/funds/list?assetType=fiagro` para filtrar FIAGROs e `cnpjs` para
fundos sem ticker B3.
# Histórico do Valor da Cota
URL: /docs/fundos/nav-historico.mdx
Série diária ou mensal do valor patrimonial por cota, patrimônio, ativos, cotistas e rentabilidade.
***
title: Histórico do Valor da Cota
description: Série diária ou mensal do valor patrimonial por cota, patrimônio, ativos, cotistas e rentabilidade.
full: true
keywords: brapi, fundos, valor da cota, valor patrimonial, histórico, FI-Infra, FIF
openGraph:
title: Histórico do Valor da Cota
description: Histórico do valor patrimonial por cota separado do preço de mercado.
type: website
locale: pt\_BR
lastUpdated: '2026-06-14T00:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/funds/nav/history
--------------------------------
Use este endpoint para acompanhar o valor patrimonial por cota, o patrimônio,
os ativos e o número de cotistas ao longo do tempo. FI/FIF retornam informes
diários. FIDCs retornam informes mensais por classe ou série, com a
rentabilidade mensal oficial da CVM em `monthlyReturn`. Para preços negociados
no mercado, use os endpoints de histórico de preços.
# Perfil de Fundos
URL: /docs/fundos/perfil.mdx
Perfil mensal CVM FI/FIF com investidores, risco e liquidez.
***
title: Perfil de Fundos
description: Perfil mensal CVM FI/FIF com investidores, risco e liquidez.
full: true
keywords: brapi, fundos, perfil, risco, liquidez, cotistas
openGraph:
title: Perfil de Fundos
description: Perfil mensal CVM FI/FIF em seções normalizadas.
type: website
locale: pt\_BR
lastUpdated: '2026-06-14T00:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/funds/profile
----------------------------
Retorna o perfil mensal do fundo em seções prontas para uso: distribuição de
cotistas, risco, liquidez, concentração e exposição a crédito privado.
# Cotação de Futuros
URL: /docs/futuros/cotacao.mdx
Cotação do dia (fim do pregão) para um ou mais contratos: OHLC, preço de ajuste, taxa de ajuste (DI/DAP), volume e número de negócios.
***
title: Cotação de Futuros
description: >-
Cotação do dia (fim do pregão) para um ou mais contratos: OHLC, preço de
ajuste, taxa de ajuste (DI/DAP), volume e número de negócios.
full: true
keywords: brapi, api, futuros, cotação, EOD, ajuste, settlement
openGraph:
title: Cotação de Futuros
description: >-
Cotação do dia para um ou mais contratos futuros.
type: website
locale: pt\_BR
lastUpdated: '2026-05-21T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/futures/quote
structuredData:
headings: \[]
contents:
* content: >-
Cotação do dia para um ou mais contratos futuros, com OHLC, preço
de ajuste, taxa de ajuste, volume e número de negócios.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna a cotação do dia para os contratos pedidos, até **20 por
requisição**. Cada cotação tem:
* **OHLC** (`open`, `high`, `low`, `close`, `average`). Em contratos com
pouca negociação, OHLC pode vir `null`, mas o ajuste segue preenchido.
* **Preço de ajuste** (`settlement`): o preço oficial do dia.
* **Taxa de ajuste** (`settlementRate`): só vem em DI e DAP.
* **`oscillationPct`**: variação % em relação ao dia anterior.
* **Volume**: `trades` (negócios), `volume` (contratos), `financialVolume`
(em reais).
Em DI e DAP, `close` vem em taxa (%a.a.) e `settlement` em reais. Veja
`quotationType` na resposta para saber a unidade.
**Plano Pro.** Sem token, aceita só `symbols=` começando com `WIN` ou
`WDO`.
# Curva de Vencimentos
URL: /docs/futuros/curva-de-vencimentos.mdx
Todos os contratos do mesmo ativo, com o último ajuste por vencimento. Útil para curva de juros do DI, contratos de commodities ou mini Ibov.
***
title: Curva de Vencimentos
description: >-
Todos os contratos do mesmo ativo, com o último ajuste por vencimento.
Útil para curva de juros do DI, contratos de commodities ou mini Ibov.
full: true
keywords: brapi, api, futuros, curva, term structure, vencimento, DI, contango
openGraph:
title: Curva de Vencimentos de Futuros
description: >-
Todos os contratos do mesmo ativo com o último ajuste por vencimento.
type: website
locale: pt\_BR
lastUpdated: '2026-05-21T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/futures/term-structure
structuredData:
headings: \[]
contents:
* content: >-
Todos os contratos do mesmo ativo, com o último ajuste por
vencimento. Útil para curva de juros, contratos de commodities
ou mini Ibov.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna **todos os contratos do mesmo ativo**, ordenados pelo vencimento
mais próximo. Cada contrato vem com a cotação do último pregão.
Bons usos:
* **Curva de juros do DI:** `asset=DI1` traz todos os vencimentos com a
taxa de ajuste (`settlementRate`) por mês.
* **Curva do mini Ibov:** `asset=WIN` mostra como o mercado precifica o
índice para datas futuras.
* **Preço de commodities ao longo do tempo:** `asset=BGI` (boi), `ICF`
(café), `CCM` (milho) ou `SJC` (soja).
Em contratos cotados em taxa (DI, DAP), use `close` e `settlementRate`
para a curva de juros. Em contratos em preço (WIN, BGI etc.), use
`close` ou `settlement`.
**Plano Pro.** Sem token, aceita só `asset=WIN` ou `asset=WDO`.
# Especificações de Futuros
URL: /docs/futuros/especificacoes.mdx
Dados do contrato (vencimento, multiplicador, lote, ISIN, CFI), sem preço.
***
title: Especificações de Futuros
description: >-
Dados do contrato (vencimento, multiplicador, lote, ISIN, CFI), sem preço.
full: true
keywords: brapi, api, futuros, especificações, multiplicador, lote, ISIN
openGraph:
title: Especificações de Futuros
description: >-
Dados do contrato, sem preço.
type: website
locale: pt\_BR
lastUpdated: '2026-05-21T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/futures/specs
structuredData:
headings: \[]
contents:
* content: >-
Dados do contrato (vencimento, multiplicador, lote, ISIN, CFI),
sem preço.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna só os **dados do contrato** — sem preço, volume ou ajuste. Use
quando precisar só das características fixas (multiplicador, lote,
vencimento).
Campos:
* `contractMultiplier`: quanto vale cada ponto. Ex.: `WIN = 0,2`,
`WDO = 10`, `BGI = 330`.
* `allocationRoundLot`: tamanho do lote (quase sempre `1`).
* `expirationDate`, `firstTradeDate`, `lastTradeDate`: datas do contrato.
* `quotationType`: `price` (maioria) ou `rate` (DI, DAP).
* `isin`, `cficCode`: códigos padronizados.
* `deliveryType`, `exerciseType`, `tradingCurrency`: regras de liquidação.
* `companyName`: emissor, quando existir.
Para a cotação do dia, use
[`/api/v2/futures/quote`](/docs/futuros/cotacao).
**Plano Pro.** Sem token, aceita só `symbols=` começando com `WIN` ou
`WDO`.
# Histórico de Futuros
URL: /docs/futuros/historico.mdx
Série diária de um contrato futuro: OHLC, preço de ajuste, taxa de ajuste (DI/DAP), variação e volume. Pronto para gráfico ou backtest.
***
title: Histórico de Futuros
description: >-
Série diária de um contrato futuro: OHLC, preço de ajuste, taxa de ajuste
(DI/DAP), variação e volume. Pronto para gráfico ou backtest.
full: true
keywords: brapi, api, futuros, histórico, OHLC, ajuste, settlement, backtest
openGraph:
title: Histórico de Futuros
description: >-
Série diária de um contrato futuro, pronta para gráfico ou backtest.
type: website
locale: pt\_BR
lastUpdated: '2026-05-21T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/futures/historical
structuredData:
headings: \[]
contents:
* content: >-
Série diária de um contrato futuro identificado por `symbol`,
pronta para gráfico ou backtest.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna a série diária de um contrato, pelo `symbol`. Para vários
contratos de uma vez, use
[`/api/v2/futures/quote`](/docs/futuros/cotacao) (até 20).
Cada dia traz:
* **OHLC** (`open`, `high`, `low`, `close`, `average`).
* **Preço de ajuste** (`settlement`): o preço oficial do dia.
* **Taxa de ajuste** (`settlementRate`): só em DI e DAP.
* **`referencePrice`**: preço de referência oficial.
* **`oscillationPct`**: variação % do dia anterior.
* **Volume**: `trades`, `volume` (contratos), `financialVolume` (em reais).
Em DI e DAP, `close` vem em taxa (%a.a.) e `settlement` em reais. Veja
`quotationType` no nível do contrato — vale para a série toda.
O campo `open` vem `null` em futuros — o arquivo do fim do dia não
publica abertura. Em contratos com pouca negociação, OHLC pode vir todo
`null`; nesses dias, `settlement` ainda vem preenchido.
**Plano Pro.** Sem token, aceita só `symbol` começando com `WIN` ou
`WDO`.
# Futuros
URL: /docs/futuros.mdx
Como usar a API de futuros da brapi (mini Ibov, mini Dolar, DI, boi, café, milho, soja). Veja os termos, o passo a passo e qual endpoint usar.
***
title: Futuros
description: >-
Como usar a API de futuros da brapi (mini Ibov, mini Dolar, DI, boi, café,
milho, soja). Veja os termos, o passo a passo e qual endpoint usar.
full: true
keywords: brapi, api, futuros, mini Ibovespa, mini Dolar, WIN, WDO, BGI, DI1, ICF, CCM, SJC, ajuste, settlement
openGraph:
title: Futuros
description: >-
Como usar a API de futuros da brapi, com passo a passo e exemplos.
type: website
locale: pt\_BR
lastUpdated: '2026-05-21T12:00:00.000Z'
lang: pt-BR
-----------
import { Callout } from 'fumadocs-ui/components/callout';
import { Card, Cards } from 'fumadocs-ui/components/card';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
Use a API de futuros para consultar contratos listados na B3, montar curvas de
vencimento, buscar preço de ajuste e baixar histórico diário.
O caminho normal é:
1. escolha o **ativo** (ex.: `WIN`, `BGI`, `DI1`)
2. liste os **contratos** ou veja a **curva de vencimentos**
3. pegue a **cotação** ou as **especificações** de um contrato
4. baixe o **histórico** do contrato
Dados EOD após o fechamento do pregão: abertura, máxima, mínima, fechamento,
preço de ajuste, variação do dia, negócios, contratos e volume financeiro.
Para DI e DAP, a resposta também traz a taxa de ajuste.
## Cobertura e atualização
* **Histórico:** cerca de **1 ano**, atualizado todo dia após o pregão.
* **Quando atualiza:** **após as 19h** (horário de Brasília). Antes disso,
você vê os dados do pregão anterior.
* **Contratos:** mini Ibov (`WIN`), Ibov (`IND`), mini dólar (`WDO`),
dólar (`DOL`), DI (`DI1`), boi (`BGI`), café (`ICF`), milho (`CCM`),
soja (`SJC`) e outros.
* **Fuso horário:** `America/Sao_Paulo`. Em histórico de preços, `date` é um
número (Unix em segundos) com a data do fechamento. Em analytics de opções,
`date` vem em `YYYY-MM-DD`.
* **Datas em parâmetros:** use `YYYY-MM-DD`.
## Acesso
Futuros estão no plano **Pro**. Sem token, dá para testar com **WIN** (mini
Ibov) e **WDO** (mini Dolar).
| Plano | Acesso |
| ------------------- | ---------------------- |
| Sem token (sandbox) | WIN e WDO |
| Free | Não incluso |
| Startup | Não incluso |
| **Pro** | **Todos os contratos** |
## Termos
* **Ativo (`underlyingAsset` ou `asset`):** o código de 2 a 4 letras do
produto, sem mês ou ano. Ex.: `WIN`, `WDO`, `BGI`, `DI1`.
* **Contrato (`symbol`):** o código que o mercado negocia. Formato:
**`{ATIVO}{LETRA_MÊS}{ANO}`**. Ex.: `WINM26` = mini Ibov com vencimento em
junho de 2026.
* **Vencimento (`expirationDate`):** data em que o contrato termina, no
formato `YYYY-MM-DD`.
* **Preço de ajuste (`settlement`):** o preço oficial do dia, divulgado no
fim do pregão. Vem sempre preenchido, mesmo em dias sem negócio.
* **Taxa de ajuste (`settlementRate`):** só vem em contratos de juros
(DI, DAP). É a taxa anual (`%a.a.`) do ajuste.
* **Multiplicador (`contractMultiplier`):** quanto vale cada ponto.
Ex.: `WIN = 0,2`, `WDO = 10`, `BGI = 330` (arrobas), `DI1 = 1`.
* **Lote (`allocationRoundLot`):** tamanho do lote. Quase sempre `1`.
* **Tipo de cotação (`quotationType`):** `price` para a maioria,
`rate` para juros (DI, DAP). Veja abaixo.
## Contratos em taxa vs em preço
A maioria dos futuros é cotada em **preço**. O número em `close`, `high`,
`low` e `settlement` é o preço direto (pontos para WIN, reais para BGI etc.).
Os futuros de juros (`DI1`, `DI`, `DAP`) são cotados em **taxa anual**
(`%a.a.`):
* `close`, `high`, `low`, `average` vêm em **%a.a.** (ex.: `14.075` =
14,075% a.a.).
* `settlement` vem em **reais** (preço unitário, ex.: `92179.44`).
* `settlementRate` vem em **%a.a.** (ex.: `14.059`).
O campo `quotationType` (`"price"` ou `"rate"`) na resposta diz qual
unidade usar.
Para o preço oficial do dia, **use sempre `settlement`**. O `close`
(último negócio) pode vir vazio em contratos com pouca negociação.
## Como ler o `symbol`
Padrão: **`{ATIVO}{LETRA_MÊS}{ANO}`**.
* **Ativo:** 2 a 4 letras (`WIN`, `WDO`, `BGI`, `DI1`).
* **Letra do mês:** uma letra para cada mês.
| Mês | Letra | Mês | Letra |
| --------- | ----- | -------- | ----- |
| Janeiro | F | Julho | N |
| Fevereiro | G | Agosto | Q |
| Março | H | Setembro | U |
| Abril | J | Outubro | V |
| Maio | K | Novembro | X |
| Junho | M | Dezembro | Z |
* **Ano:** dois últimos dígitos.
Exemplos:
* `WINM26` → mini Ibov, junho de 2026.
* `DI1F27` → DI, janeiro de 2027.
* `BGIK26` → boi gordo, maio de 2026.
## Comece rápido
Exemplo do fluxo `curva → cotação → histórico` para o mini Ibov.
```bash
# 1) Curva de vencimentos do mini Ibov
curl "https://brapi.dev/api/v2/futures/term-structure?asset=WIN"
# 2) Cotação do contrato
curl "https://brapi.dev/api/v2/futures/quote?symbols=WINM26"
# 3) Histórico dos últimos 12 meses
curl "https://brapi.dev/api/v2/futures/historical?symbol=WINM26"
```
```typescript
const BASE = 'https://brapi.dev/api/v2/futures';
const token = process.env.BRAPI_TOKEN; // opcional para WIN/WDO no sandbox
const headers = token ? { Authorization: `Bearer ${token}` } : undefined;
// 1) Curva
const curve = await fetch(`${BASE}/term-structure?asset=WIN`, {
headers,
}).then((r) => r.json());
// 2) Contrato mais próximo do vencimento
const front = curve.contracts[0];
const quote = await fetch(`${BASE}/quote?symbols=${front.symbol}`, {
headers,
}).then((r) => r.json());
// 3) Histórico
const history = await fetch(
`${BASE}/historical?symbol=${front.symbol}`,
{ headers },
).then((r) => r.json());
console.log(history);
```
```python
import os
import requests
BASE = "https://brapi.dev/api/v2/futures"
token = os.getenv("BRAPI_TOKEN") # opcional para WIN/WDO no sandbox
headers = {"Authorization": f"Bearer {token}"} if token else {}
# 1) Curva
curve = requests.get(
f"{BASE}/term-structure", params={"asset": "WIN"}, headers=headers
).json()
front = curve["contracts"][0]
# 2) Cotação
quote = requests.get(
f"{BASE}/quote", params={"symbols": front["symbol"]}, headers=headers
).json()
# 3) Histórico
history = requests.get(
f"{BASE}/historical", params={"symbol": front["symbol"]}, headers=headers
).json()
print(history)
```
## Passo a passo
#### Liste os contratos
Use [`/api/v2/futures/list`](/docs/futuros/lista) para ver o que existe,
ou [`/api/v2/futures/term-structure`](/docs/futuros/curva-de-vencimentos)
para ver todos os vencimentos de um ativo.
#### Pegue cotação ou especificações
Use [`/api/v2/futures/quote`](/docs/futuros/cotacao) para a cotação do
dia de até 20 contratos, ou
[`/api/v2/futures/specs`](/docs/futuros/especificacoes) para os dados do
contrato (multiplicador, lote, vencimento, ISIN).
#### Histórico
Use [`/api/v2/futures/historical`](/docs/futuros/historico) com `symbol`
para a série diária do contrato.
#### Opções sobre o contrato
Para opções sobre futuros (boi, café, milho, soja), veja
[Opções sobre Futuros](/docs/futuros/opcoes).
## Casos comuns
* **Painel de futuros:** `list → quote`
* **Curva de juros do DI:** `term-structure?asset=DI1`
* **Curva do mini Ibov:** `term-structure?asset=WIN`
* **Backtest de boi:** `term-structure?asset=BGI → historical`
* **Margem e ajuste do dia:** `quote` (use `settlement` e `settlementRate`)
## Perguntas frequentes
## Sandbox sem token
Para testar sem token, os endpoints aceitam só estes ativos:
* `/list`, `/term-structure`: `asset=WIN` ou `asset=WDO`.
* `/quote`, `/specs`: `symbols=` com `WIN` ou `WDO`.
* `/historical`: `symbol` com `WIN` ou `WDO`.
* `/options/expirations`, `/options/strikes`, `/options/chain`:
`underlying=BGI`.
* `/options/historical`: `symbol` com `BGI`.
Para outros ativos, use um token do plano Pro.
## Endpoints
# Listar Contratos Futuros
URL: /docs/futuros/lista.mdx
Lista de contratos futuros disponíveis, com filtros por ativo, segmento e contratos vencidos.
***
title: Listar Contratos Futuros
description: >-
Lista de contratos futuros disponíveis, com filtros por ativo, segmento e
contratos vencidos.
full: true
keywords: brapi, api, futuros, listar, contratos, WIN, WDO, BGI, DI1
openGraph:
title: Listar Contratos Futuros
description: >-
Lista de contratos futuros disponíveis, com filtros.
type: website
locale: pt\_BR
lastUpdated: '2026-05-21T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/futures/list
structuredData:
headings: \[]
contents:
* content: >-
Lista de contratos futuros disponíveis, com filtros por ativo,
segmento e contratos vencidos.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna a lista de contratos futuros. Use os filtros para limitar a um
ativo (ex.: `asset=BGI`) ou a um segmento (ex.: `segment=agribusiness`).
Cada item traz os **dados do contrato** (sem preço): símbolo, ativo,
vencimento, multiplicador, lote, ISIN, CFI. Para a cotação do dia, use
[`/api/v2/futures/quote`](/docs/futuros/cotacao). Para a curva inteira de
um ativo, use
[`/api/v2/futures/term-structure`](/docs/futuros/curva-de-vencimentos).
**Plano Pro.** Sem token, aceita só `asset=WIN` ou `asset=WDO`.
# Séries Macroeconômicas Disponíveis
URL: /docs/macro/available.mdx
Lista das séries macroeconômicas disponíveis com slugs, aliases, unidade, frequência e descrição. Aceita busca textual via `q` e filtro por categoria.
***
title: Séries Macroeconômicas Disponíveis
description: >-
Lista das séries macroeconômicas disponíveis com slugs, aliases, unidade,
frequência e descrição. Aceita busca textual via `q` e filtro por categoria.
full: true
keywords: brapi, api, macroeconomia, indicadores, disponíveis, slugs, busca
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/macro/available
------------------------------
Endpoint **público**. Retorna metadados das séries disponíveis (slug, nome,
unidade, frequência, categoria). Use os slugs em
[`/api/v2/macro`](/docs/macro) e
[`/api/v2/macro/latest`](/docs/macro/latest).
### Filtros opcionais
* `q` — busca textual em slug, alias, nome e descrição (case-insensitive,
substring). Quando informado, os resultados vêm ordenados por relevância
(slug > alias > nome > descrição).
* `category` — filtra por categoria (ex: `interestRate`, `inflation`,
`monetary`, `activity`, `labor`, `external`).
Os filtros podem ser combinados.
# Macroeconomia
URL: /docs/macro.mdx
Endpoint composable para acessar séries temporais de indicadores macroeconômicos do Brasil — Selic, IPCA, IGP-M, agregados monetários, atividade e mercado de trabalho.
***
title: Macroeconomia
description: >-
Endpoint composable para acessar séries temporais de indicadores
macroeconômicos do Brasil — Selic, IPCA, IGP-M, agregados monetários,
atividade e mercado de trabalho.
full: true
keywords: brapi, api, macroeconomia, indicadores econômicos, selic, ipca, igpm
openGraph:
title: Macroeconomia — brapi
description: >-
Séries temporais de indicadores macroeconômicos brasileiros — Selic,
IPCA, IGP-M e outros — em uma única requisição.
type: website
locale: pt\_BR
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/macro
--------------------
Acesse séries temporais de indicadores macroeconômicos brasileiros usando
slugs estáveis. Compatível com **múltiplas séries** em uma única requisição
via parâmetro `symbols` (ex: `symbols=selic,ipca,igpm`).
Use [`/api/v2/macro/available`](/docs/macro/available) para descobrir todos
os slugs disponíveis (com busca textual opcional via `q`).
# Macroeconomia — Última Observação
URL: /docs/macro/latest.mdx
Snapshot do valor mais recente de cada série macroeconômica solicitada. Ideal para dashboards que mostram apenas o valor corrente de Selic, IPCA, etc.
***
title: Macroeconomia — Última Observação
description: >-
Snapshot do valor mais recente de cada série macroeconômica solicitada.
Ideal para dashboards que mostram apenas o valor corrente de Selic, IPCA,
etc.
full: true
keywords: brapi, api, macroeconomia, selic, ipca, latest
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/macro/latest
---------------------------
Retorna apenas a observação mais recente para cada série solicitada.
# Listar Moedas
URL: /docs/moedas/available.mdx
Endpoints para consulta de Moedas Fiduciárias. Atualmente, focado na listagem das moedas disponíveis para conversão ou consulta de taxas de câmbio (embora o endpoint de cotação de moedas não esteja detalhado aqui, a listagem está disponível).
***
title: Listar Moedas
description: >-
Endpoints para consulta de Moedas Fiduciárias. Atualmente, focado na listagem
das moedas disponíveis para conversão ou consulta de taxas de câmbio (embora o
endpoint de cotação de moedas não esteja detalhado aqui, a listagem está
disponível).
full: true
keywords: brapi, api, documentação, moedas
openGraph:
title: Listar Moedas
description: >-
Endpoints para consulta de Moedas Fiduciárias. Atualmente, focado na
listagem das moedas disponíveis para conversão ou consulta de taxas de
câmbio (embora o endpoint de cotação de moedas não esteja detalhado aqui, a
listagem está disponível).
type: website
locale: pt\_BR
lastUpdated: '2025-04-28T01:22:35.254Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/currency/available
toc:
* depth: 2
title: Listar Todas as Moedas Fiduciárias Disponíveis
url: '#listar-todas-as-moedas-fiduciárias-disponíveis'
structuredData:
headings:
* content: Listar Todas as Moedas Fiduciárias Disponíveis
id: listar-todas-as-moedas-fiduciárias-disponíveis
contents:
* content: >-
Obtenha a lista completa de todas as moedas fiduciárias suportadas
pela API, geralmente utilizadas no parâmetro `currency` de outros
endpoints (como o de criptomoedas) ou para futuras funcionalidades de
conversão.
### Funcionalidade:
* Retorna um array `currencies` com os nomes das moedas.
* Pode ser filtrado usando o parâmetro `search`.
### Autenticação:
Requer token de autenticação via `token` (query) ou `Authorization`
(header).
### Exemplo de Requisição:
**Listar todas as moedas disponíveis:**
```bash
curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency/available"
```
**Buscar moedas cujo nome contenha 'Euro':**
```bash
curl -H "Authorization: Bearer SEU_TOKEN" "https://brapi.dev/api/v2/currency/available?search=Euro"
```
### Resposta:
A resposta é um objeto JSON com a chave `currencies`, contendo um
array de objetos. Cada objeto possui uma chave `currency` com o nome
completo da moeda (ex: `"Dólar Americano/Real Brasileiro"`). **Nota:**
O formato do nome pode indicar um par de moedas, dependendo do
contexto interno da API.
heading: listar-todas-as-moedas-fiduciárias-disponíveis
***
Endpoints para consulta de **Moedas Fiduciárias**.
Atualmente, focado na listagem das moedas disponíveis para conversão ou consulta
de taxas de câmbio (embora o endpoint de cotação de moedas não esteja detalhado
aqui, a listagem está disponível).
# Histórico de Moedas
URL: /docs/moedas/historico.mdx
Série histórica diária de cotações PTAX para pares de moedas em BRL — USD, EUR, GBP, JPY, CHF, CAD, AUD, DKK, NOK, SEK contra o real.
***
title: Histórico de Moedas
description: >-
Série histórica diária de cotações PTAX para pares de moedas em BRL —
USD, EUR, GBP, JPY, CHF, CAD, AUD, DKK, NOK, SEK contra o real.
full: true
keywords: brapi, api, moedas, ptax, histórico, dolar, euro, libra
openGraph:
title: Histórico de Moedas — brapi
description: >-
Série histórica diária de cotações PTAX para pares de moedas em BRL.
type: website
locale: pt\_BR
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/currency/historical
----------------------------------
Retorna a série histórica diária da cotação PTAX de venda para um ou mais
pares contra o real. Ideal para back-testing, gráficos de longo prazo e
análise de risco cambial.
# Cotação de Moedas
URL: /docs/moedas.mdx
Endpoints para consulta de Moedas Fiduciárias. Atualmente, focado na listagem das moedas disponíveis para conversão ou consulta de taxas de câmbio.
***
title: Cotação de Moedas
description: >-
Endpoints para consulta de Moedas Fiduciárias. Atualmente, focado na listagem
das moedas disponíveis para conversão ou consulta de taxas de câmbio.
full: true
keywords: brapi, api, documentação, moedas
openGraph:
title: Cotação de Moedas
description: >-
Endpoints para consulta de Moedas Fiduciárias. Atualmente, focado na
listagem das moedas disponíveis para conversão ou consulta de taxas de
câmbio.
type: website
locale: pt\_BR
lastUpdated: '2025-04-28T01:22:35.254Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/currency
toc:
* depth: 2
title: Listar Todas as Moedas Fiduciárias Disponíveis
url: '#listar-todas-as-moedas-fiduciárias-disponíveis'
structuredData:
headings:
* content: Listar Todas as Moedas Fiduciárias Disponíveis
id: listar-todas-as-moedas-fiduciárias-disponíveis
contents:
* content: >-
Obtenha cotações atualizadas para um ou mais pares de moedas
fiduciárias (ex: USD-BRL, EUR-USD).
### Funcionalidades:
* **Cotação Múltipla:** Consulte vários pares de moedas em uma única
requisição usando o parâmetro `currency`. \* **Dados Retornados:**
Inclui nome do par, preços de compra (bid) e venda (ask), variação,
máximas e mínimas, e timestamp da atualização.
### Parâmetros:
* **`currency` (Obrigatório):** Uma lista de pares de moedas
separados por vírgula, no formato `MOEDA_ORIGEM-MOEDA_DESTINO` (ex:
`USD-BRL`, `EUR-USD`). Consulte os pares disponíveis em
[`/api/v2/currency/available`](#/Moedas/getAvailableCurrencies).
* **`token` (Obrigatório):** Seu token de autenticação.
### Autenticação:
Requer token de autenticação válido via `token` (query) ou
`Authorization` (header).
### Estrutura da Resposta (200 OK):
A resposta bem-sucedida (`CurrencyResponse`) contém um array
`currency`. Cada objeto dentro deste array (`CurrencyQuote`)
representa um par solicitado e inclui: \* `fromCurrency`: Sigla da
moeda de origem. \* `toCurrency`: Sigla da moeda de destino.
* `name`: Nome descritivo do par. \* `high`, `low`: Preços máximo e
mínimo do período recente. \* `bidVariation`, `percentageChange`:
Variação absoluta e percentual. \* `bidPrice`, `askPrice`: Preços de
compra e venda atuais. \* `updatedAtTimestamp`, `updatedAtDate`:
Timestamps da última atualização.
````json {
\"currency\":
[
{
\"fromCurrency\": \"USD\",
\"toCurrency\":
\"BRL\",
\"name\": \"Dólar Americano/Real
Brasileiro\",
\"high\": \"5.22\",
\"low\":
\"5.162\",
\"bidVariation\":
\"0.0454\",
\"percentageChange\":
\"0.88\",
\"bidPrice\": \"5.2097\",
\"askPrice\":
\"5.2127\",
\"updatedAtTimestamp\":
\"1696601423\",
\"updatedAtDate\": \"2023-10-06
11:10:23\"
},
{
\"fromCurrency\":
\"EUR\",
\"toCurrency\": \"USD\",
\"name\": \"Euro/Dólar
Americano\",
\"high\": \"1.0568\",
\"low\":
\"1.0482\",
\"bidVariation\":
\"-0.0037\",
\"percentageChange\":
\"-0.35\",
\"bidPrice\": \"1.051\",
\"askPrice\":
\"1.0511\",
\"updatedAtTimestamp\":
\"1696601456\",
\"updatedAtDate\": \"2023-10-06
11:10:56\"
}
]
} ```
heading: listar-todas-as-moedas-fiduciárias-disponíveis
````
***
import { Callout } from 'fumadocs-ui/components/callout';
Endpoints para consulta de **Moedas Fiduciárias**.
Taxas de câmbio do **BCB** e provedores forex. USD, EUR, GBP e 50+ pares com atualização em tempo real.
Atualmente, focado na listagem das moedas disponíveis para conversão ou consulta
de taxas de câmbio.
# Histórico de Gregas e IV de Opções
URL: /docs/opcoes/analytics-historico.mdx
Consulte a série temporal EOD de volatilidade implícita e gregas calculadas para uma opção específica.
***
title: Histórico de Gregas e IV de Opções
description: >-
Consulte a série temporal EOD de volatilidade implícita e gregas calculadas
para uma opção específica.
full: true
keywords: brapi, api, opções, histórico, gregas, volatilidade implícita
openGraph:
title: Histórico de Gregas e IV de Opções
description: >-
Série temporal EOD de volatilidade implícita e gregas calculadas para uma
opção específica.
type: website
locale: pt\_BR
lastUpdated: '2026-06-01T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/options/analytics/history
structuredData:
headings: \[]
contents:
* content: >-
Retorna a série temporal EOD de IV e gregas calculadas para uma
opção específica.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna uma série temporal diária com volatilidade implícita, delta, gamma,
theta, vega e rho para uma opção específica.
Use este endpoint quando você já sabe o `symbol` e o `expirationDate` da série.
Se o mesmo `symbol` existir mais de uma vez no vencimento, informe também
`strike`.
**Plano mínimo: Pro.** No sandbox sem token, aceita apenas símbolos que
começam com `PETR`.
# Gregas e IV de Opções
URL: /docs/opcoes/analytics.mdx
Consulte volatilidade implícita e gregas EOD calculadas para séries de opções de um vencimento.
***
title: Gregas e IV de Opções
description: >-
Consulte volatilidade implícita e gregas EOD calculadas para séries de
opções de um vencimento.
full: true
keywords: brapi, api, opções, gregas, delta, gamma, theta, vega, rho, volatilidade implícita
openGraph:
title: Gregas e IV de Opções
description: >-
Consulte volatilidade implícita e gregas EOD calculadas para opções.
type: website
locale: pt\_BR
lastUpdated: '2026-06-01T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/options/analytics
structuredData:
headings: \[]
contents:
* content: >-
Retorna volatilidade implícita e gregas EOD calculadas para séries
de opções de um vencimento.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna volatilidade implícita e gregas EOD para as séries de um vencimento,
com filtros por `side`, `minStrike` e `maxStrike`.
Os cálculos usam preços EOD observados. Quando faltam dados suficientes, os
campos calculados ficam `null` e `nullReason` explica o motivo.
**Plano mínimo: Pro.** No sandbox sem token, aceita apenas `underlying=PETR4`.
`dividendYield` considera apenas dividendos já anunciados até a data de
cálculo. A API não usa dividendos futuros estimados como proxy.
# Histórico de uma Série de Opção
URL: /docs/opcoes/historico.mdx
Consulte o histórico diário de uma série de opção por símbolo e vencimento, com resposta simples e pronta para gráfico ou backtest.
***
title: Histórico de uma Série de Opção
description: >-
Consulte o histórico diário de uma série de opção por símbolo e vencimento,
com resposta simples e pronta para gráfico ou backtest.
full: true
keywords: brapi, api, opções, histórico, série
openGraph:
title: Histórico de uma Série de Opção
description: >-
Consulte o histórico diário de uma série de opção por símbolo e
vencimento.
type: website
locale: pt\_BR
lastUpdated: '2026-04-22T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/options/historical
structuredData:
headings: \[]
contents:
* content: >-
Retorna o histórico diário EOD de uma única série de opção,
identificada por símbolo e vencimento. Pronto para gráfico ou
backtest.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna o histórico diário EOD de uma única série de opção, identificada por
`symbol` e `expirationDate`. Informe também `strike` quando o mesmo símbolo
aparecer mais de uma vez no mesmo vencimento.
Normalmente você descobre a série primeiro em
[Séries Negociadas](/docs/opcoes/series) e só depois chama este endpoint. Foi
desenhado para **uma série por requisição**, para manter a integração simples
e evitar ambiguidades.
**Plano mínimo: Pro.** No sandbox sem token, aceita apenas `symbol` começando
com `PETR` (opções do subjacente PETR4).
# Opções
URL: /docs/opcoes.mdx
Guia simples para integrar opções na brapi: entenda os termos principais, o fluxo recomendado e qual endpoint usar em cada caso.
***
title: Opções
description: >-
Guia simples para integrar opções na brapi: entenda os termos principais, o
fluxo recomendado e qual endpoint usar em cada caso.
full: true
keywords: brapi, api, opções, vencimento, strike, série
openGraph:
title: Opções
description: >-
Guia simples para integrar opções na brapi, com fluxo recomendado e
exemplos de uso.
type: website
locale: pt\_BR
lastUpdated: '2026-04-22T12:00:00.000Z'
lang: pt-BR
-----------
import { Callout } from 'fumadocs-ui/components/callout';
import { Card, Cards } from 'fumadocs-ui/components/card';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
Use a API de opções para montar telas de cadeia, acompanhar séries negociadas,
consultar histórico EOD e adicionar gregas/volatilidade implícita ao seu
produto.
O fluxo mais comum é:
1. escolher o **ativo subjacente**
2. descobrir os **vencimentos**
3. ver os **preços de exercício**
4. listar as **séries negociadas**
5. consultar **gregas e volatilidade implícita**
6. pegar o **histórico** de uma série específica
Esta seção cobre opções sobre **ações, ETFs e índices** (PETR4, VALE3,
BOVA11, IBOV, etc.). Para opções sobre **futuros** (boi gordo, café,
milho, soja e similares), veja
[Opções sobre Futuros](/docs/futuros/opcoes).
A API entrega dados **EOD**: abertura, máxima, mínima, média, fechamento,
bid, ask, negócios, volume, volume financeiro, gregas e volatilidade implícita.
O arquivo diário é processado após o fechamento do pregão.
## Cobertura e frequência
* **Histórico:** a partir de **2009**, com consolidação diária após o fechamento.
* **Atualização:** o arquivo EOD é processado **após \~19h de Brasília** (BRT/BRT-3).
Até lá, o "último pregão disponível" corresponde ao pregão anterior.
* **Contratos cobertos:** opções de ações, ETFs e índices (ex.: IBOV) listados
na bolsa brasileira.
* **Fuso horário:** todas as datas estão em `America/Sao_Paulo`. Em respostas
de preços/histórico, `date` é timestamp Unix em segundos; em respostas de
analytics, `date` vem em `YYYY-MM-DD`.
* **Formato de datas em query params:** `YYYY-MM-DD`.
## Acesso por plano
Opções fazem parte do plano **Pro**. O sandbox abaixo permite experimentação
sem token para **PETR4**.
| Plano | Acesso a opções |
| ------------------- | ------------------- |
| Sandbox (sem token) | PETR4 |
| Free | Não incluso |
| Startup | Não incluso |
| **Pro** | **Todos os ativos** |
## Termos que você vai ver
* **Ativo subjacente:** a ação, ETF ou índice da opção. Ex.: `PETR4`.
* **Vencimento (`expirationDate`):** a data em que a opção vence.
Ex.: `2026-05-15`.
* **Preço de exercício / strike:** preço combinado na opção. Ex.: `34`.
* **Série:** a combinação prática que o mercado negocia. Na resposta da API,
aparece como `symbol`, `expirationDate`, `side` e `strike`.
* **`symbol`:** o ticker da série (ex.: `PETRE370`), composto pelo ativo
subjacente + letra do mês/tipo + identificador do strike (veja abaixo).
* **Opção de compra (`call`):** direito de **comprar** o ativo subjacente.
* **Opção de venda (`put`):** direito de **vender** o ativo subjacente.
* **Titular:** quem compra a opção. Paga o prêmio e exerce o direito se for
vantajoso.
* **Lançador:** quem vende a opção. Recebe o prêmio e assume a obrigação.
* **Prêmio:** preço pago/recebido pela opção. É o que aparece como `close`,
`bid`, `ask` no histórico.
* **Opção americana:** pode ser exercida a qualquer momento até o vencimento
(padrão de opções de ações).
* **Opção europeia:** só pode ser exercida no vencimento (padrão de opções
de índice, como IBOV).
## Formato do `symbol`
O ticker de uma série segue o padrão da bolsa brasileira:
**`{ATIVO}{LETRA_MÊS}{ID_STRIKE}`**.
* **Ativo:** as 4 letras do subjacente (ex.: `PETR`).
* **Letra do mês + tipo:**
* `A–L` para **calls** (A = janeiro, B = fevereiro, ..., L = dezembro).
* `M–X` para **puts** (M = janeiro, N = fevereiro, ..., X = dezembro).
* **ID do strike:** número de 1 a 3 dígitos atribuído pela bolsa para aquele
strike no vencimento.
Exemplos:
* `PETRE370` → **PETR4**, **call** (`E` = maio), strike mapeado como `370`.
* `PETRQ28` → **PETR4**, **put** (`Q` = maio), strike mapeado como `28`.
O ID do strike **não é o valor em reais**. Para saber o strike em reais,
use `/api/v2/options/chain` ou `/api/v2/options/strikes`.
## Início rápido
Exemplo do fluxo `vencimentos → séries negociadas → histórico` para opções de
**PETR4**. Funciona no sandbox sem token.
```bash
# 1) Descubra os vencimentos disponíveis
curl "https://brapi.dev/api/v2/options/expirations?underlying=PETR4"
# 2) Liste as séries negociadas em um vencimento
curl "https://brapi.dev/api/v2/options/chain?underlying=PETR4&expirationDate=2026-05-15"
# 3) Consulte o histórico de uma série específica
curl "https://brapi.dev/api/v2/options/historical?symbol=PETRE370&expirationDate=2026-05-15"
```
```typescript
const BASE = 'https://brapi.dev/api/v2/options';
const token = process.env.BRAPI_TOKEN; // dispensável para PETR4 no sandbox
const headers = token ? { Authorization: `Bearer ${token}` } : undefined;
// 1) Vencimentos
const expirations = await fetch(
`${BASE}/expirations?underlying=PETR4`,
{ headers },
).then((r) => r.json());
const nextExpiration = expirations.expirations[0];
// 2) Séries negociadas no vencimento
const chain = await fetch(
`${BASE}/chain?underlying=PETR4&expirationDate=${nextExpiration}`,
{ headers },
).then((r) => r.json());
// 3) Histórico da série ATM mais próxima
const firstSeries = chain.series[0];
const history = await fetch(
`${BASE}/historical?symbol=${firstSeries.symbol}&expirationDate=${firstSeries.expirationDate}`,
{ headers },
).then((r) => r.json());
console.log(history);
```
```python
import os
import requests
BASE = "https://brapi.dev/api/v2/options"
token = os.getenv("BRAPI_TOKEN") # dispensável para PETR4 no sandbox
headers = {"Authorization": f"Bearer {token}"} if token else {}
# 1) Vencimentos
expirations = requests.get(
f"{BASE}/expirations", params={"underlying": "PETR4"}, headers=headers
).json()
next_exp = expirations["expirations"][0]
# 2) Séries negociadas no vencimento
chain = requests.get(
f"{BASE}/chain",
params={"underlying": "PETR4", "expirationDate": next_exp},
headers=headers,
).json()
# 3) Histórico da primeira série
first_series = chain["series"][0]
history = requests.get(
f"{BASE}/historical",
params={"symbol": first_series["symbol"], "expirationDate": first_series["expirationDate"]},
headers=headers,
).json()
print(history)
```
## Fluxo recomendado
#### Descubra os vencimentos
Comece em [`/api/v2/options/expirations`](/docs/opcoes/vencimentos) quando
você só sabe o ativo, como `PETR4`, e ainda não sabe qual vencimento usar.
#### Descubra os preços de exercício
Depois de escolher o vencimento, use
[`/api/v2/options/strikes`](/docs/opcoes/precos-de-exercicio) para saber
quais strikes existem naquele vencimento.
#### Liste as séries negociadas
Use [`/api/v2/options/chain`](/docs/opcoes/series) para montar a tela que a
maioria das pessoas espera ver: séries negociadas por vencimento, com preço
e volume.
#### Busque o histórico de uma série
Quando você já sabe qual série quer acompanhar, use
[`/api/v2/options/historical`](/docs/opcoes/historico) com `symbol` e
`expirationDate`. Se precisar, informe também `strike`.
#### Consulte gregas e IV
Use [`/api/v2/options/analytics`](/docs/opcoes/analytics) para a foto EOD
de um vencimento, ou
[`/api/v2/options/analytics/history`](/docs/opcoes/analytics-historico)
para a série temporal de uma opção específica.
## Casos de uso mais comuns
* **Tela simples de opções no seu app:** `expirations -> chain`
* **Filtro por strike:** `expirations -> strikes -> chain`
* **Gregas e volatilidade implícita por vencimento:** `expirations -> analytics`
* **Gráfico de uma opção específica:** `chain -> historical`
* **Backtest ou persistência diária:** escolher a série via `chain` e depois
buscar o histórico em `historical` e `analytics/history`
## Quando você pode pular etapas
* Se você **já sabe o vencimento**, pode ir direto para `strikes` ou `chain`.
* Se você **já sabe a série**, pode ir direto para `historical`.
* Se você quer só montar uma tela simples por vencimento, pode **pular
`strikes`** e ir direto para `chain`.
## Perguntas frequentes
## Receitas prontas
Guias e tutoriais publicados no blog com código pronto para copiar:
## Próximas melhorias
O foco atual é histórico EOD, cadeia, strikes, vencimentos, gregas e IV. As
próximas frentes em avaliação são:
* Snapshots intraday durante o pregão.
* Interesse em aberto por série.
Pedidos de clientes ajudam a definir a ordem dessas entregas.
## Sandbox sem token
Para facilitar a experimentação, todos os endpoints de opções aceitam
consultas no sandbox sem token, restritas a opções de **PETR4**:
* `GET /api/v2/options/expirations`, `/strikes` e `/chain`: apenas com
`underlying=PETR4`.
* `GET /api/v2/options/analytics`: apenas com `underlying=PETR4`.
* `GET /api/v2/options/historical`: apenas com `symbol` começando com `PETR`
(ou seja, opções do subjacente PETR4).
* `GET /api/v2/options/analytics/history`: apenas com `symbol` começando com
`PETR`.
Para qualquer outro ativo, é necessário autenticar com um token do plano Pro.
## Endpoints
# Preços de Exercício de Opções
URL: /docs/opcoes/precos-de-exercicio.mdx
Liste os preços de exercício disponíveis para um vencimento de opções, com filtro opcional por compra (call) ou venda (put).
***
title: Preços de Exercício de Opções
description: >-
Liste os preços de exercício disponíveis para um vencimento de opções, com
filtro opcional por compra (call) ou venda (put).
full: true
keywords: brapi, api, opções, strike, preço de exercício
openGraph:
title: Preços de Exercício de Opções
description: >-
Liste os preços de exercício disponíveis para um vencimento de opções.
type: website
locale: pt\_BR
lastUpdated: '2026-04-22T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/options/strikes
structuredData:
headings: \[]
contents:
* content: >-
Retorna os strikes disponíveis em um vencimento específico, a partir
das séries negociadas. Útil para montar um seletor de strike antes
de consultar as séries negociadas.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna os strikes disponíveis em um vencimento específico, a partir das
séries negociadas. Use `side=call` ou `side=put` para filtrar por tipo de
opção.
Se você não precisa desta etapa intermediária, pode ir direto para
[Séries Negociadas](/docs/opcoes/series) e filtrar por faixa de strike com
`minStrike` e `maxStrike`.
**Plano mínimo: Pro.** No sandbox sem token, aceita apenas `underlying=PETR4`.
# Séries Negociadas de Opções
URL: /docs/opcoes/series.mdx
Consulte as séries negociadas de opções para um vencimento específico, com preço, volume e filtros por compra/venda e faixa de strike.
***
title: Séries Negociadas de Opções
description: >-
Consulte as séries negociadas de opções para um vencimento específico, com
preço, volume e filtros por compra/venda e faixa de strike.
full: true
keywords: brapi, api, opções, séries, vencimento
openGraph:
title: Séries Negociadas de Opções
description: >-
Consulte as séries negociadas de opções para um vencimento específico.
type: website
locale: pt\_BR
lastUpdated: '2026-04-22T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/options/chain
structuredData:
headings: \[]
contents:
* content: >-
Retorna as séries negociadas de um vencimento com metadados do
contrato e OHLCV do último pregão disponível até a data pedida.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna as séries negociadas de um vencimento com metadados do contrato
(`symbol`, `side`, `strike`, `expirationDate`) e OHLCV do último pregão
disponível até a data pedida. Este é o endpoint principal para montar uma
tela de opções por vencimento.
Apesar do caminho ser `/chain`, na documentação chamamos isso de **séries
negociadas**, porque esse nome faz mais sentido para o público brasileiro.
**Plano mínimo: Pro.** No sandbox sem token, aceita apenas `underlying=PETR4`.
# Vencimentos de Opções
URL: /docs/opcoes/vencimentos.mdx
Liste os vencimentos disponíveis de opções por ativo subjacente, de um jeito simples para descobrir qual série consultar depois.
***
title: Vencimentos de Opções
description: >-
Liste os vencimentos disponíveis de opções por ativo subjacente, de um jeito
simples para descobrir qual série consultar depois.
full: true
keywords: brapi, api, opções, vencimentos
openGraph:
title: Vencimentos de Opções
description: >-
Liste os vencimentos disponíveis de opções por ativo subjacente.
type: website
locale: pt\_BR
lastUpdated: '2026-04-22T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/options/expirations
structuredData:
headings: \[]
contents:
* content: >-
Retorna os vencimentos de opções disponíveis para um ativo
subjacente, como `PETR4`. Use como primeiro passo antes de consultar
strikes ou séries negociadas.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna os vencimentos de opções disponíveis para um ativo subjacente (ação,
ETF ou índice). Por padrão, mostra apenas vencimentos futuros — envie
`includeExpired=true` para incluir vencimentos passados.
Use este endpoint como ponto de partida quando você ainda não sabe qual
vencimento consultar. Veja o fluxo completo em
[Opções](/docs/opcoes).
**Plano mínimo: Pro.** No sandbox sem token, aceita apenas `underlying=PETR4`.
# SDKs Oficiais
URL: /docs/sdks.mdx
SDKs oficiais da brapi.dev para TypeScript/JavaScript e Python. Integre a API da bolsa brasileira com tipos, retry automático e erros específicos.
***
title: 'SDKs Oficiais'
description: >-
SDKs oficiais da brapi.dev para TypeScript/JavaScript e Python. Integre a API
da bolsa brasileira com tipos, retry automático e erros específicos.
full: false
keywords:
brapi, sdk, typescript, python, npm, pypi, api client, developer tools
openGraph:
title: SDKs Oficiais - brapi.dev
description: >-
Bibliotecas oficiais para integração rápida e tipada com a API da bolsa brasileira
type: website
locale: pt\_BR
lastUpdated: '2025-10-12T20:10:00.000Z'
lang: pt-BR
-----------
Use as SDKs oficiais quando quiser chamar a brapi com tipos, retry e tratamento
de erros já configurados. Elas são úteis para backends, scripts, dashboards e
integrações que consultam a API com frequência.
## Por que usar as SDKs?
### Requisição HTTP manual
```typescript
const response = await fetch("https://brapi.dev/api/quote/PETR4", {
headers: { Authorization: `Bearer ${token}` },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
const price = data.results[0].regularMarketPrice; // sem tipos gerados
```
### Com SDK
```typescript
const quote = await client.quote.retrieve('PETR4');
const price = quote.results[0].regularMarketPrice; // tipado pelo SDK
```
As SDKs reduzem boilerplate e deixam explícitos os casos importantes:
* tipos para autocomplete e validação no editor
* retry configurável
* erros específicos por status
* clientes síncronos ou assíncronos, dependendo da linguagem
* mesma autenticação da API REST
***
## SDKs disponíveis
### TypeScript / JavaScript
SDK oficial para TypeScript e JavaScript com suporte a Node.js e navegador.
#### Instalação
```bash
npm install brapi
# ou
yarn add brapi
# ou
pnpm add brapi
# ou
bun add brapi
```
#### Exemplo rápido
```typescript
import Brapi from 'brapi';
const client = new Brapi({
apiKey: process.env.BRAPI_API_KEY,
});
const quote = await client.quote.retrieve('PETR4');
console.log(quote.results[0].regularMarketPrice);
```
#### Características
* Tipos TypeScript
* Suporte a Node.js e navegador
* Bundle tree-shakeable
* Integração com Next.js, Express e outros frameworks
* Retry automático configurável
**Links:**
* [Documentação TypeScript](/docs/sdks/typescript)
* [Pacote no npm](https://www.npmjs.com/package/brapi)
* [Repositório no GitHub](https://github.com/brapi-dev/brapi-typescript)
***
### Python
SDK oficial para Python 3.8+ com suporte síncrono e assíncrono.
#### Instalação
```bash
pip install brapi
# Com suporte a aiohttp (opcional, melhor performance)
pip install brapi[aiohttp]
```
#### Exemplo rápido (síncrono)
```python
from brapi import Brapi
client = Brapi(api_key="seu_token")
quote = client.quote.retrieve(tickers="PETR4")
print(quote.results[0].regular_market_price)
```
#### Exemplo rápido (assíncrono)
```python
import asyncio
from brapi import AsyncBrapi
async def main():
async with AsyncBrapi(api_key="seu_token") as client:
quote = await client.quote.retrieve(tickers="PETR4")
print(quote.results[0].regular_market_price)
asyncio.run(main())
```
#### Características
* Type hints
* Cliente síncrono e assíncrono
* httpx com suporte a HTTP/2
* Integração com Flask, FastAPI e Pandas
* Context managers
**Links:**
* [Documentação Python](/docs/sdks/python)
* [Pacote no PyPI](https://pypi.org/project/brapi/)
* [Repositório no GitHub](https://github.com/brapi-dev/brapi-python)
***
## Comparação
| Feature | TypeScript/JS | Python |
| ---------------- | ------------- | ---------- |
| Tipos | TypeScript | Type hints |
| Autocomplete IDE | Sim | Sim |
| Sync/Async | Async | Ambos |
| Retry automático | Sim | Sim |
| Erros tipados | Sim | Sim |
| HTTP/2 | Sim | Sim |
| Bundle size | Pequeno | N/A |
| Python 3.8+ | N/A | Sim |
| Node.js/Browser | Sim | N/A |
***
## Casos de Uso
### 1. Aplicações Web
**Next.js / React:**
```typescript
import Brapi from 'brapi';
// Server Component
const client = new Brapi({ apiKey: process.env.BRAPI_API_KEY });
const quote = await client.quote.retrieve('PETR4');
```
**FastAPI / Flask:**
```python
from fastapi import FastAPI
from brapi import AsyncBrapi
app = FastAPI()
client = AsyncBrapi(api_key="seu_token")
@app.get("/quote/{ticker}")
async def get_quote(ticker: str):
quote = await client.quote.retrieve(tickers=ticker)
return quote.results[0]
```
### 2. Análise de Dados
**Python com Pandas:**
```python
import pandas as pd
from brapi import Brapi
client = Brapi(api_key="seu_token")
# Buscar múltiplas cotações
tickers = "PETR4,VALE3,ITUB4"
quote = client.quote.retrieve(tickers=tickers)
# Converter para DataFrame
df = pd.DataFrame([
{
'symbol': r.symbol,
'price': r.regular_market_price,
'change': r.regular_market_change_percent
}
for r in quote.results
])
print(df)
```
### 3. Scripts e Automação
**Monitoramento de Preços:**
```python
from brapi import Brapi
import time
client = Brapi(api_key="seu_token")
while True:
quote = client.quote.retrieve(tickers="PETR4")
price = quote.results[0].regular_market_price
print(f"PETR4: R$ {price:.2f}")
time.sleep(60) # Atualiza a cada minuto
```
### 4. APIs e Microsserviços
**Express.js API:**
```typescript
import express from 'express';
import Brapi from 'brapi';
const app = express();
const client = new Brapi({ apiKey: process.env.BRAPI_API_KEY });
app.get('/api/quote/:ticker', async (req, res) => {
try {
const quote = await client.quote.retrieve(req.params.ticker);
res.json(quote);
} catch (error) {
res.status(500).json({ error: error.message });
}
});
app.listen(3000);
```
### 5. Dashboards e Visualizações
**TypeScript com Chart.js:**
```typescript
const client = new Brapi({ apiKey: process.env.BRAPI_API_KEY });
async function updateChart() {
const quote = await client.quote.retrieve('PETR4,VALE3,ITUB4');
const labels = quote.results.map(r => r.symbol);
const prices = quote.results.map(r => r.regularMarketPrice);
// Atualizar gráfico com os dados
chart.data.labels = labels;
chart.data.datasets[0].data = prices;
chart.update();
}
```
***
## Recursos suportados
Ambas as SDKs suportam todos os endpoints da API:
### Mercado Brasileiro
* **Cotações** - ações, ETFs, FIIs e BDRs
* **Dados fundamentalistas** - balanços, DRE e indicadores
* **Dividendos** - histórico de proventos
* **Histórico** - preços históricos
### Criptomoedas
* **Preços** - Bitcoin, Ethereum e outros criptoativos
* **Lista de moedas disponíveis**
### Indicadores Econômicos
* **Inflação** - IPCA, IGP-M e outros índices
* **Taxa de juros** - SELIC e CDI
* **Câmbio** - USD, EUR e outras moedas
***
## Tratamento de erros
Ambas as SDKs lançam exceções específicas por tipo de erro:
### TypeScript
```typescript
import Brapi from 'brapi';
try {
const quote = await client.quote.retrieve('INVALID');
} catch (error) {
if (error instanceof Brapi.NotFoundError) {
console.log('Ticker não encontrado');
} else if (error instanceof Brapi.RateLimitError) {
console.log('Limite de requisições atingido');
} else if (error instanceof Brapi.AuthenticationError) {
console.log('Token inválido');
}
}
```
### Python
```python
from brapi import Brapi, NotFoundError, RateLimitError
try:
quote = client.quote.retrieve(tickers="INVALID")
except NotFoundError:
print("Ticker não encontrado")
except RateLimitError:
print("Limite de requisições atingido")
```
***
## Configuração avançada
### Retry automático
```typescript
// TypeScript
const client = new Brapi({
apiKey: process.env.BRAPI_API_KEY,
maxRetries: 3, // Tenta até 3 vezes
});
```
```python
# Python
client = Brapi(
api_key="seu_token",
max_retries=3, # Tenta até 3 vezes
)
```
### Timeouts
```typescript
// TypeScript
const client = new Brapi({
apiKey: process.env.BRAPI_API_KEY,
timeout: 10000, // 10 segundos
});
```
```python
# Python
client = Brapi(
api_key="seu_token",
timeout=10.0, # 10 segundos
)
```
***
## Como as SDKs são mantidas
As SDKs são geradas com [Stainless](https://www.stainless.com/) a partir da
especificação da API. Isso mantém tipos, métodos e documentação inline alinhados
com os endpoints publicados.
* Tipos gerados a partir da especificação
* Documentação inline nos clientes
* Testes automáticos nos repositórios das SDKs
***
## Começar a usar
Escolha a SDK da sua linguagem:
### TypeScript / JavaScript
```bash
npm install brapi
```
**[Ver documentação TypeScript](/docs/sdks/typescript)**
**Links:**
* [Pacote no npm](https://www.npmjs.com/package/brapi)
* [Repositório no GitHub](https://github.com/brapi-dev/brapi-typescript)
***
### Python
```bash
pip install brapi
```
**[Ver documentação Python](/docs/sdks/python)**
**Links:**
* [Pacote no PyPI](https://pypi.org/project/brapi/)
* [Repositório no GitHub](https://github.com/brapi-dev/brapi-python)
***
## Futuras SDKs
Estamos trabalhando em SDKs para:
* **Go** - em desenvolvimento
* **PHP** - planejado
* **Java** - planejado
* **Ruby** - planejado
Sugestões de SDKs podem ser enviadas pelo [GitHub](https://github.com/brapi-dev).
***
## Suporte e comunidade
* [GitHub Discussions](https://github.com/brapi-dev)
* [Reportar bug](https://github.com/brapi-dev)
* [Email de suporte](mailto:contato@brapi.dev)
* [Documentação da API](/docs)
***
## Open Source
As SDKs são **open source** e licenciadas sob MIT.
* [GitHub](https://github.com/brapi-dev)
* [Contribuir](https://github.com/brapi-dev)
* [Changelog](https://github.com/brapi-dev)
# SDK Python
URL: /docs/sdks/python.mdx
SDK oficial Python da brapi.dev. Biblioteca completa com type hints, suporte síncrono e assíncrono, integração com asyncio e aiohttp, tratamento de erros automático.
***
title: 'SDK Python'
description: >-
SDK oficial Python da brapi.dev. Biblioteca completa com type hints, suporte
síncrono e assíncrono, integração com asyncio e aiohttp, tratamento de erros
automático.
full: false
keywords:
brapi, sdk, python, pip, api client, asyncio, httpx
openGraph:
title: SDK Python - brapi.dev
description: >-
SDK oficial Python com type hints e suporte síncrono e assíncrono
type: website
locale: pt\_BR
lastUpdated: '2025-10-12T20:00:00.000Z'
lang: pt-BR
howToSteps:
* name: 'Instale a SDK via pip'
text: 'Execute pip install brapi no terminal. Para melhor performance async, use pip install brapi\[aiohttp].'
* name: 'Configure a variável de ambiente com seu token'
text: 'Crie um arquivo .env com BRAPI\_API\_KEY=seu\_token\_aqui e use python-dotenv para carregar: from dotenv import load\_dotenv; load\_dotenv().'
* name: 'Importe e inicialize o cliente Brapi'
text: 'No seu código Python, importe com from brapi import Brapi e crie uma instância: client = Brapi(api\_key=os.environ.get("BRAPI\_API\_KEY")).'
* name: 'Busque cotações com o cliente síncrono ou assíncrono'
text: 'Use quote = client.quote.retrieve(tickers="PETR4") para síncrono, ou await client.quote.retrieve(tickers="PETR4") com AsyncBrapi para async.'
* name: 'Trate erros usando as exceções tipadas'
text: 'Importe exceções como NotFoundError, RateLimitError e use try/except para tratamento específico de cada tipo de erro.'
howToTools:
* 'Python 3.8+'
* 'pip'
* 'Editor de código'
howToSupplies:
* 'Conta brapi.dev'
* 'Token de API brapi.dev'
* 'Ambiente Python configurado'
***
SDK oficial da brapi.dev para Python 3.8+, oferecendo acesso conveniente à API REST com type hints completos e suporte síncrono e assíncrono.
## Características
* ✅ **Type hints completos** - Autocomplete e validação no IDE
* ✅ **Python 3.8+** - Compatível com versões modernas
* ✅ **Sync e Async** - Cliente síncrono e assíncrono
* ✅ **Powered by httpx** - HTTP/2 e connection pooling
* ✅ **Suporte aiohttp** - Performance assíncrona otimizada
* ✅ **Tratamento de erros** - Exceções tipadas e descritivas
* ✅ **Retry automático** - Tratamento inteligente de falhas
* ✅ **Gerado com Stainless** - Sempre atualizado com a API
## Instalação
```bash
pip install brapi
```
Com suporte a aiohttp (opcional, para melhor performance async):
```bash
pip install brapi[aiohttp]
```
## Início Rápido
### Cliente Síncrono
```python
import os
from brapi import Brapi
client = Brapi(
api_key=os.environ.get("BRAPI_API_KEY"),
)
# Buscar cotação
quote = client.quote.retrieve(tickers="PETR4")
print(quote.results[0].regular_market_price)
# Múltiplas ações
quotes = client.quote.retrieve(tickers="PETR4,VALE3,ITUB4")
for stock in quotes.results:
print(f"{stock.symbol}: R$ {stock.regular_market_price}")
```
### Cliente Assíncrono
```python
import os
import asyncio
from brapi import AsyncBrapi
client = AsyncBrapi(
api_key=os.environ.get("BRAPI_API_KEY"),
)
async def main():
quote = await client.quote.retrieve(tickers="PETR4")
print(quote.results[0].regular_market_price)
asyncio.run(main())
```
## Configuração
### Variáveis de Ambiente
Recomendamos usar `python-dotenv` para gerenciar variáveis de ambiente:
```bash
pip install python-dotenv
```
Crie um arquivo `.env`:
```bash
BRAPI_API_KEY=seu_token_aqui
```
No seu código:
```python
import os
from dotenv import load_dotenv
from brapi import Brapi
load_dotenv()
client = Brapi(
api_key=os.environ.get("BRAPI_API_KEY"),
)
```
### Opções do Cliente
```python
client = Brapi(
api_key="seu_token",
environment="production", # 'production' ou 'sandbox'
max_retries=2, # Número de tentativas (padrão: 2)
timeout=60.0, # Timeout em segundos (padrão: 60)
)
```
## Exemplos de Uso
### Cotações
```python
# Cotação única
quote = client.quote.retrieve(tickers="PETR4")
stock = quote.results[0]
print(f"Símbolo: {stock.symbol}")
print(f"Nome: {stock.short_name}")
print(f"Preço: R$ {stock.regular_market_price}")
print(f"Variação: {stock.regular_market_change_percent}%")
# Com módulos adicionais
quote_with_data = client.quote.retrieve(
tickers="PETR4",
modules="summaryProfile,balanceSheetHistory"
)
```
### Lista de Ações
```python
# Todas as ações disponíveis
stocks = client.quote.list()
for stock in stocks.stocks:
print(f"{stock.stock}: {stock.name} ({stock.type})")
# Com paginação
stocks_page = client.quote.list(page=1, limit=50)
```
### Criptomoedas
```python
# Cotação de cripto
crypto = client.crypto.retrieve(coin="BTC")
print(f"Bitcoin: ${crypto.currency}")
# Lista de criptos disponíveis
cryptos = client.crypto.available()
for coin in cryptos.coins:
print(f"{coin.coin}: {coin.name}")
```
### Moedas
```python
# Cotação de moeda
currency = client.currency.retrieve(currency="USD-BRL")
print(f"Dólar: R$ {currency.ask}")
# Lista de moedas disponíveis
currencies = client.currency.available()
```
### Inflação
```python
# Dados de inflação do Brasil
inflation = client.inflation.retrieve(country="brazil")
print(f"IPCA: {inflation.IPCA}")
# Países disponíveis
countries = client.inflation.available()
```
### Taxa de Juros
```python
# Taxa SELIC
selic = client.prime_rate.retrieve(country="brazil")
print(f"SELIC: {selic.value}%")
# Países disponíveis
countries = client.prime_rate.available()
```
## Cliente Assíncrono
### Com httpx (padrão)
```python
import asyncio
from brapi import AsyncBrapi
async def main():
client = AsyncBrapi(api_key="seu_token")
# Todas as operações usam await
quote = await client.quote.retrieve(tickers="PETR4")
print(quote.results[0].regular_market_price)
# Não esqueça de fechar o cliente
await client.close()
asyncio.run(main())
```
### Com Context Manager
```python
import asyncio
from brapi import AsyncBrapi
async def main():
async with AsyncBrapi(api_key="seu_token") as client:
quote = await client.quote.retrieve(tickers="PETR4")
print(quote.results[0].regular_market_price)
# Cliente fechado automaticamente
asyncio.run(main())
```
### Com aiohttp (melhor performance)
```python
import asyncio
from brapi import AsyncBrapi, DefaultAioHttpClient
async def main():
async with AsyncBrapi(
api_key="seu_token",
http_client=DefaultAioHttpClient(),
) as client:
quote = await client.quote.retrieve(tickers="PETR4")
print(quote.results[0].regular_market_price)
asyncio.run(main())
```
### Requisições Concorrentes
```python
import asyncio
from brapi import AsyncBrapi
async def get_multiple_quotes():
async with AsyncBrapi(api_key="seu_token") as client:
# Buscar várias cotações em paralelo
tasks = [
client.quote.retrieve(tickers="PETR4"),
client.quote.retrieve(tickers="VALE3"),
client.quote.retrieve(tickers="ITUB4"),
]
results = await asyncio.gather(*tasks)
for quote in results:
stock = quote.results[0]
print(f"{stock.symbol}: R$ {stock.regular_market_price}")
asyncio.run(get_multiple_quotes())
```
## Tratamento de Erros
```python
from brapi import Brapi
from brapi import (
APIError,
BadRequestError,
AuthenticationError,
NotFoundError,
RateLimitError,
)
client = Brapi(api_key="seu_token")
try:
quote = client.quote.retrieve(tickers="INVALID")
except NotFoundError as e:
print(f"Ticker não encontrado: {e}")
except RateLimitError as e:
print(f"Limite de requisições: {e}")
except AuthenticationError as e:
print(f"Token inválido: {e}")
except APIError as e:
print(f"Erro na API: {e}")
```
### Tipos de Exceção
| Exception | Status | Descrição |
| -------------------------- | ------ | ---------------------- |
| `BadRequestError` | 400 | Requisição inválida |
| `AuthenticationError` | 401 | Token inválido |
| `PermissionDeniedError` | 403 | Sem permissão |
| `NotFoundError` | 404 | Recurso não encontrado |
| `UnprocessableEntityError` | 422 | Dados inválidos |
| `RateLimitError` | 429 | Limite de requisições |
| `InternalServerError` | 5xx | Erro no servidor |
| `APIConnectionError` | N/A | Erro de conexão |
## Integração com Flask
```python
from flask import Flask, jsonify
from brapi import Brapi
app = Flask(__name__)
client = Brapi(api_key="seu_token")
@app.route('/api/quote/')
def get_quote(ticker):
try:
quote = client.quote.retrieve(tickers=ticker)
return jsonify({
'symbol': quote.results[0].symbol,
'price': quote.results[0].regular_market_price,
})
except NotFoundError:
return jsonify({'error': 'Ticker not found'}), 404
if __name__ == '__main__':
app.run()
```
## Integração com FastAPI
```python
from fastapi import FastAPI, HTTPException
from brapi import AsyncBrapi, NotFoundError
app = FastAPI()
client = AsyncBrapi(api_key="seu_token")
@app.get("/api/quote/{ticker}")
async def get_quote(ticker: str):
try:
quote = await client.quote.retrieve(tickers=ticker)
return {
'symbol': quote.results[0].symbol,
'price': quote.results[0].regular_market_price,
}
except NotFoundError:
raise HTTPException(status_code=404, detail="Ticker not found")
@app.on_event("shutdown")
async def shutdown():
await client.close()
```
## Integração com Pandas
```python
import pandas as pd
from brapi import Brapi
client = Brapi(api_key="seu_token")
def get_quotes_dataframe(tickers: list[str]) -> pd.DataFrame:
"""Retorna cotações como DataFrame"""
tickers_str = ','.join(tickers)
quote = client.quote.retrieve(tickers=tickers_str)
data = []
for stock in quote.results:
data.append({
'symbol': stock.symbol,
'name': stock.short_name,
'price': stock.regular_market_price,
'change_percent': stock.regular_market_change_percent,
})
return pd.DataFrame(data)
# Uso
df = get_quotes_dataframe(['PETR4', 'VALE3', 'ITUB4'])
print(df)
# Salvar em Excel
df.to_excel('cotacoes.xlsx', index=False)
```
## Timeouts
```python
# Timeout global
client = Brapi(
api_key="seu_token",
timeout=10.0, # 10 segundos
)
# Timeout por requisição
quote = client.quote.retrieve(
tickers="PETR4",
timeout=5.0, # 5 segundos
)
```
## Retry Automático
```python
# Configurar retries
client = Brapi(
api_key="seu_token",
max_retries=3, # Tenta até 3 vezes
)
# Desabilitar retries
client = Brapi(
api_key="seu_token",
max_retries=0, # Sem retry
)
```
## Type Hints
A SDK inclui type hints completos para todas as operações:
```python
from brapi import Brapi
from brapi.types import QuoteRetrieveResponse
client: Brapi = Brapi(api_key="seu_token")
# Type checking automático
quote: QuoteRetrieveResponse = client.quote.retrieve(tickers="PETR4")
# Autocomplete no IDE
price: float = quote.results[0].regular_market_price
```
## Boas Práticas
### 1. Reutilize o Cliente
```python
# ✅ Bom - Crie uma instância e reutilize
from brapi import Brapi
client = Brapi(api_key="seu_token")
def get_quote(ticker):
return client.quote.retrieve(tickers=ticker)
# ❌ Ruim - Criar nova instância a cada uso
def get_quote(ticker):
client = Brapi(api_key="seu_token") # Não faça isso
return client.quote.retrieve(tickers=ticker)
```
### 2. Use Variáveis de Ambiente
```python
# ✅ Bom
import os
from brapi import Brapi
client = Brapi(api_key=os.environ.get("BRAPI_API_KEY"))
# ❌ Ruim - Nunca hardcode o token
client = Brapi(api_key="meu-token-secreto") # Não faça isso!
```
### 3. Use Context Manager com Async
```python
# ✅ Bom
async with AsyncBrapi(api_key="seu_token") as client:
quote = await client.quote.retrieve(tickers="PETR4")
# Cliente fechado automaticamente
# ❌ Ruim
client = AsyncBrapi(api_key="seu_token")
quote = await client.quote.retrieve(tickers="PETR4")
# Esqueceu de fechar!
```
## Links Úteis
* 📦 [Pacote PyPI](https://pypi.org/project/brapi/)
* 🔧 [Repositório GitHub](https://github.com/brapi-dev/brapi-python)
* 📚 [Documentação Completa da API](/docs)
* 🐛 [Reportar Bug](https://github.com/brapi-dev/brapi-python/issues)
## Suporte
Precisa de ajuda? Entre em contato:
* 💬 [Abra uma issue](https://github.com/brapi-dev/brapi-python/issues)
* 📧 [Suporte por email](mailto:contato@brapi.dev)
* 📖 [Documentação completa](/docs)
## Contribuindo
Contribuições são bem-vindas! Veja o [guia de contribuição](https://github.com/brapi-dev/brapi-python/blob/main/CONTRIBUTING.md).
## Licença
MIT License - veja [LICENSE](https://github.com/brapi-dev/brapi-python/blob/main/LICENSE) para detalhes.
# SDK TypeScript/JavaScript
URL: /docs/sdks/typescript.mdx
SDK oficial TypeScript/JavaScript da brapi.dev. Biblioteca completa com tipos TypeScript, suporte a Node.js e navegador, tratamento de erros automático e retry inteligente.
***
title: 'SDK TypeScript/JavaScript'
description: >-
SDK oficial TypeScript/JavaScript da brapi.dev. Biblioteca completa com tipos
TypeScript, suporte a Node.js e navegador, tratamento de erros automático e
retry inteligente.
full: false
keywords:
brapi, sdk, typescript, javascript, npm, api client, node.js
openGraph:
title: SDK TypeScript/JavaScript - brapi.dev
description: >-
SDK oficial TypeScript/JavaScript com tipos completos e suporte a async/await
type: website
locale: pt\_BR
lastUpdated: '2025-10-12T20:00:00.000Z'
lang: pt-BR
howToSteps:
* name: 'Instale a SDK via npm, yarn ou bun'
text: 'Execute npm install brapi (ou yarn add brapi, bun add brapi) no terminal do seu projeto para instalar a SDK oficial.'
* name: 'Configure a variável de ambiente com seu token'
text: 'Crie um arquivo .env e adicione BRAPI\_API\_KEY=seu\_token\_aqui. Nunca exponha o token diretamente no código.'
* name: 'Importe e inicialize o cliente Brapi'
text: 'No seu código TypeScript/JavaScript, importe com import Brapi from "brapi" e crie uma instância: const client = new Brapi({ apiKey: process.env.BRAPI\_API\_KEY }).'
* name: 'Busque cotações usando async/await'
text: 'Use const quote = await client.quote.retrieve("PETR4") para obter cotações. O resultado já vem tipado com IntelliSense completo.'
* name: 'Trate erros usando as exceções tipadas'
text: 'Envolva as chamadas em try/catch e verifique tipos de erro como Brapi.NotFoundError, Brapi.RateLimitError para tratamento específico.'
howToTools:
* 'Node.js'
* 'npm, yarn, pnpm ou bun'
* 'Editor de código (VS Code recomendado)'
howToSupplies:
* 'Conta brapi.dev'
* 'Token de API brapi.dev'
* 'Projeto Node.js ou TypeScript'
***
SDK oficial da brapi.dev para TypeScript e JavaScript, oferecendo acesso conveniente à API REST com tipos completos e suporte a async/await.
## Características
* ✅ **Tipos TypeScript completos** - IntelliSense e autocomplete
* ✅ **Suporte a Node.js e Browser** - Funciona em qualquer ambiente
* ✅ **Async/Await nativo** - API moderna e fácil de usar
* ✅ **Retry automático** - Tratamento inteligente de falhas
* ✅ **Tratamento de erros** - Erros tipados e descritivos
* ✅ **Tree-shakeable** - Bundle otimizado
* ✅ **Gerado com Stainless** - Sempre atualizado com a API
## Instalação
```bash
npm install brapi
# ou
yarn add brapi
# ou
pnpm add brapi
# ou
bun add brapi
```
## Início Rápido
### JavaScript
```javascript
const client = new Brapi({
apiKey: process.env.BRAPI_API_KEY,
});
// Buscar cotação de uma ação
const quote = await client.quote.retrieve('PETR4');
console.log(quote.results[0].regularMarketPrice);
// Buscar múltiplas ações
const quotes = await client.quote.retrieve('PETR4,VALE3,ITUB4');
console.log(quotes.results);
```
### TypeScript
```typescript
const client = new Brapi({
apiKey: process.env.BRAPI_API_KEY,
});
// Tipos automáticos!
const quote: Brapi.QuoteRetrieveResponse = await client.quote.retrieve('PETR4');
// IntelliSense completo
const price = quote.results[0].regularMarketPrice;
const change = quote.results[0].regularMarketChangePercent;
```
## Configuração
### Variáveis de Ambiente
Crie um arquivo `.env`:
```bash
BRAPI_API_KEY=seu_token_aqui
```
### Opções do Cliente
```typescript
const client = new Brapi({
apiKey: process.env.BRAPI_API_KEY, // Obrigatório
environment: 'production', // 'production' ou 'sandbox'
maxRetries: 2, // Número de tentativas (padrão: 2)
timeout: 60000, // Timeout em ms (padrão: 60000)
});
```
## Exemplos de Uso
### Cotações
```typescript
// Cotação única
const quote = await client.quote.retrieve('PETR4');
// Múltiplas cotações
const quotes = await client.quote.retrieve('PETR4,VALE3,ITUB4');
// Com parâmetros adicionais
const quoteWithModules = await client.quote.retrieve('PETR4', {
modules: 'summaryProfile,balanceSheetHistory',
});
// Resultado
console.log(quote.results[0]);
// {
// symbol: 'PETR4',
// shortName: 'PETROBRAS PN',
// regularMarketPrice: 38.45,
// regularMarketChangePercent: 2.15,
// currency: 'BRL',
// ...
// }
```
### Lista de Ações
```typescript
// Listar todas as ações disponíveis
const stocks = await client.quote.list();
// Com paginação
const stocksPage = await client.quote.list({
page: 1,
limit: 50,
});
console.log(stocks.stocks);
// [
// { stock: 'PETR4', name: 'Petrobras PN', type: 'stock' },
// { stock: 'VALE3', name: 'Vale ON', type: 'stock' },
// ...
// ]
```
### Criptomoedas
```typescript
// Cotação de cripto
const crypto = await client.crypto.retrieve('BTC');
// Lista de criptos disponíveis
const cryptos = await client.crypto.available();
```
### Moedas
```typescript
// Cotação de moeda
const currency = await client.currency.retrieve('USD-BRL');
// Lista de moedas disponíveis
const currencies = await client.currency.available();
```
### Inflação
```typescript
// Dados de inflação
const inflation = await client.inflation.retrieve('IPCA');
// Países disponíveis
const countries = await client.inflation.available();
```
### Taxa de Juros
```typescript
// Taxa SELIC
const selic = await client.primeRate.retrieve('SELIC');
// Países disponíveis
const countries = await client.primeRate.available();
```
## Tratamento de Erros
A SDK lança erros tipados para facilitar o tratamento:
```typescript
try {
const quote = await client.quote.retrieve('INVALID');
} catch (error) {
if (error instanceof Brapi.APIError) {
console.log(error.status); // Código HTTP (ex: 404)
console.log(error.name); // Nome do erro (ex: 'NotFoundError')
console.log(error.message); // Mensagem descritiva
console.log(error.headers); // Headers da resposta
}
}
```
### Tipos de Erro
| Status Code | Error Type | Descrição |
| ----------- | -------------------------- | ---------------------- |
| 400 | `BadRequestError` | Requisição inválida |
| 401 | `AuthenticationError` | Token inválido |
| 403 | `PermissionDeniedError` | Sem permissão |
| 404 | `NotFoundError` | Recurso não encontrado |
| 422 | `UnprocessableEntityError` | Dados inválidos |
| 429 | `RateLimitError` | Limite de requisições |
| >=500 | `InternalServerError` | Erro no servidor |
| N/A | `APIConnectionError` | Erro de conexão |
## Retry Automático
A SDK tenta automaticamente 2 vezes em caso de falha:
```typescript
// Configurar retries
const client = new Brapi({
apiKey: process.env.BRAPI_API_KEY,
maxRetries: 3, // Tenta até 3 vezes
});
// Desabilitar retries
const client = new Brapi({
apiKey: process.env.BRAPI_API_KEY,
maxRetries: 0, // Sem retry
});
```
Erros automaticamente retriados:
* Erros de conexão
* 408 Request Timeout
* 409 Conflict
* 429 Rate Limit
* Erros 5xx (servidor)
## Uso em Next.js
### Server Component
```typescript
// app/stock/[ticker]/page.tsx
const client = new Brapi({
apiKey: process.env.BRAPI_API_KEY,
});
export default async function StockPage({
params,
}: {
params: { ticker: string };
}) {
const quote = await client.quote.retrieve(params.ticker);
const stock = quote.results[0];
return (
);
}
```
### API Route
```typescript
// app/api/quote/[ticker]/route.ts
const client = new Brapi({
apiKey: process.env.BRAPI_API_KEY,
});
export async function GET(
request: Request,
{ params }: { params: { ticker: string } }
) {
try {
const quote = await client.quote.retrieve(params.ticker);
return NextResponse.json(quote);
} catch (error) {
if (error instanceof Brapi.NotFoundError) {
return NextResponse.json(
{ error: 'Ticker not found' },
{ status: 404 }
);
}
throw error;
}
}
```
### Client Component com SWR
```typescript
'use client';
const fetcher = (url: string) => fetch(url).then(r => r.json());
export function StockQuote({ ticker }: { ticker: string }) {
const { data, error } = useSWR(`/api/quote/${ticker}`, fetcher);
if (error) return ;
if (!data) return ;
const stock = data.results[0];
return ;
}
```
## Uso com Express
```typescript
const app = express();
const client = new Brapi({
apiKey: process.env.BRAPI_API_KEY,
});
app.get('/api/quote/:ticker', async (req, res) => {
try {
const quote = await client.quote.retrieve(req.params.ticker);
res.json(quote);
} catch (error) {
if (error instanceof Brapi.NotFoundError) {
res.status(404).json({ error: 'Ticker not found' });
} else {
res.status(500).json({ error: 'Internal server error' });
}
}
});
app.listen(3000);
```
## Timeouts
```typescript
// Timeout global
const client = new Brapi({
apiKey: process.env.BRAPI_API_KEY,
timeout: 10000, // 10 segundos
});
// Timeout por requisição
const quote = await client.quote.retrieve('PETR4', {
timeout: 5000, // 5 segundos
});
```
## Tipos Disponíveis
A SDK exporta todos os tipos necessários:
```typescript
import type {
QuoteRetrieveResponse,
QuoteListResponse,
CryptoRetrieveResponse,
CurrencyRetrieveResponse,
InflationRetrieveResponse,
} from 'brapi';
```
## Boas Práticas
### 1. Reutilize a Instância do Cliente
```typescript
// ✅ Bom - Crie uma instância e reutilize
export const brapiClient = new Brapi({
apiKey: process.env.BRAPI_API_KEY,
});
// ❌ Ruim - Criar nova instância a cada uso
function getQuote() {
const client = new Brapi({ apiKey: '...' }); // Não faça isso
}
```
### 2. Use Variáveis de Ambiente
```typescript
// ✅ Bom
const client = new Brapi({
apiKey: process.env.BRAPI_API_KEY,
});
// ❌ Ruim - Nunca hardcode o token
const client = new Brapi({
apiKey: 'meu-token-secreto', // Não faça isso!
});
```
### 3. Trate Erros Adequadamente
```typescript
// ✅ Bom
try {
const quote = await client.quote.retrieve('PETR4');
} catch (error) {
if (error instanceof Brapi.RateLimitError) {
// Trate limite de requisições
} else if (error instanceof Brapi.NotFoundError) {
// Trate ticker não encontrado
}
}
```
## Links Úteis
* 📦 [Pacote NPM](https://www.npmjs.com/package/brapi)
* 🔧 [Repositório GitHub](https://github.com/brapi-dev/brapi-typescript)
* 📚 [Documentação Completa da API](/docs)
* 🐛 [Reportar Bug](https://github.com/brapi-dev/brapi-typescript/issues)
## Suporte
Precisa de ajuda? Entre em contato:
* 💬 [Abra uma issue](https://github.com/brapi-dev/brapi-typescript/issues)
* 📧 [Suporte por email](mailto:contato@brapi.dev)
* 📖 [Documentação completa](/docs)
## Contribuindo
Contribuições são bem-vindas! Veja o [guia de contribuição](https://github.com/brapi-dev/brapi-typescript/blob/main/CONTRIBUTING.md).
## Licença
MIT License - veja [LICENSE](https://github.com/brapi-dev/brapi-typescript/blob/main/LICENSE) para detalhes.
# Tesouro Direto
URL: /docs/tesouro-direto.mdx
Guia para integrar dados de títulos públicos do Tesouro Direto na brapi: listagem, indicadores atuais e histórico diário de taxas e preços.
***
title: Tesouro Direto
description: >-
Guia para integrar dados de títulos públicos do Tesouro Direto na brapi:
listagem, indicadores atuais e histórico diário de taxas e preços.
full: true
keywords: brapi, api, tesouro direto, renda fixa, tesouro selic, tesouro ipca, prefixado
openGraph:
title: Tesouro Direto — brapi
description: >-
Integre taxas e preços indicativos de títulos públicos do Tesouro Direto
com endpoints REST da brapi.
type: website
locale: pt\_BR
lastUpdated: '2026-05-16T12:00:00.000Z'
lang: pt-BR
-----------
import { Callout } from 'fumadocs-ui/components/callout';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
A API de Tesouro Direto entrega a primeira camada de dados de renda fixa da
brapi:
1. **listar** os títulos atualmente ofertados
2. consultar **taxas e preços atuais** por símbolo
3. acompanhar o **histórico diário** de taxas e preços
Taxas indicativas de compra/venda, preços unitários, vencimento, indexador,
tipo de cupom e histórico diário desde 2005, conforme disponibilidade da
fonte pública.
Títulos do Tesouro Direto usam `symbol` em formato slug minúsculo, como
`tesouro-selic-01032031`. Não use tickers de bolsa ou códigos internos de
fontes externas.
## Cobertura e frequência
* **Títulos cobertos:** Tesouro Selic, Prefixado, IPCA+, IGP-M histórico,
Renda+ e Educa+ quando presentes no arquivo público.
* **Atualização:** diária, conforme publicação da base do Tesouro Direto.
* **Histórico:** série diária de taxas e preços desde 2005.
* **Datas:** parâmetros em `YYYY-MM-DD`; respostas em `YYYY-MM-DD`.
* **Fonte externa:** a resposta nunca expõe URLs, IDs de dataset ou IDs de
recurso upstream. Use apenas os símbolos públicos da brapi.
## Acesso por plano
Tesouro Direto detalhado faz parte do plano **Pro**. O sandbox permite
experimentação sem token para três títulos:
* `tesouro-selic-01032031`
* `tesouro-prefixado-com-juros-semestrais-01012037`
* `tesouro-ipca-com-juros-semestrais-15082060`
| Plano | Acesso ao Tesouro Direto |
| ------------------- | ---------------------------------- |
| Sandbox (sem token) | ✅ Apenas os 3 títulos sandbox |
| Free | ❌ |
| Startup | ❌ |
| **Pro** | **✅ Todos os títulos disponíveis** |
## Campos principais
* **`symbol`:** slug público do título, composto pelo nome normalizado e data de
vencimento (`DDMMAAAA`).
* **`bondType`:** nome público do título, como `Tesouro Selic` ou
`Tesouro IPCA+ com Juros Semestrais`.
* **`indexer`:** `selic`, `prefixado`, `ipca` ou `igpm`.
* **`couponType`:** `zero` para títulos sem cupom periódico, `semestral` para
títulos com juros semestrais.
* **`buyRate` / `sellRate`:** taxa indicativa em `% a.a.`. Em Tesouro Selic, é
spread sobre a Selic; em Prefixado, rendimento nominal; em IPCA, rendimento
real acima do IPCA.
* **`rateInfo`:** metadados que explicam como interpretar `buyRate` e
`sellRate` para aquele indexador (`spreadOverSelic`,
`nominalAnnualRate`, `realAnnualRateOverIpca` ou
`realAnnualRateOverIgpm`).
* **`buyPrice` / `sellPrice` / `basePrice`:** preços unitários indicativos em
reais.
* **`durationDays`:** dias corridos entre a data-base e o vencimento.
## Início rápido
```bash
# 1) Liste títulos Selic atualmente ofertados
curl "https://brapi.dev/api/v2/treasury/list?indexer=selic"
# 2) Consulte indicadores atuais de títulos específicos
curl "https://brapi.dev/api/v2/treasury/indicators?symbols=tesouro-selic-01032031"
# 3) Consulte o histórico diário de taxas e preços
curl "https://brapi.dev/api/v2/treasury/indicators/history?symbols=tesouro-selic-01032031&startDate=2026-05-01&endDate=2026-05-15"
```
```typescript
const BASE = 'https://brapi.dev/api/v2/treasury';
const token = process.env.BRAPI_TOKEN;
const headers = token ? { Authorization: `Bearer ${token}` } : undefined;
const list = await fetch(`${BASE}/list?indexer=selic`, { headers })
.then((r) => r.json());
const indicators = await fetch(
`${BASE}/indicators?symbols=tesouro-selic-01032031`,
{ headers },
).then((r) => r.json());
const history = await fetch(
`${BASE}/indicators/history?symbols=tesouro-selic-01032031&startDate=2026-05-01&endDate=2026-05-15`,
{ headers },
).then((r) => r.json());
console.log({ list, indicators, history });
```
```python
import os
import requests
BASE = "https://brapi.dev/api/v2/treasury"
token = os.getenv("BRAPI_TOKEN")
headers = {"Authorization": f"Bearer {token}"} if token else {}
listagem = requests.get(
f"{BASE}/list",
params={"indexer": "selic"},
headers=headers,
).json()
indicadores = requests.get(
f"{BASE}/indicators",
params={"symbols": "tesouro-selic-01032031"},
headers=headers,
).json()
historico = requests.get(
f"{BASE}/indicators/history",
params={
"symbols": "tesouro-selic-01032031",
"startDate": "2026-05-01",
"endDate": "2026-05-15",
},
headers=headers,
).json()
print(listagem, indicadores, historico)
```
## Fluxo recomendado
#### Descubra os títulos disponíveis
Comece em [`/api/v2/treasury/list`](/docs/tesouro-direto/listagem) para
listar a oferta atual e filtrar por indexador ou tipo de cupom.
#### Consulte o snapshot atual
Use [`/api/v2/treasury/indicators`](/docs/tesouro-direto/indicadores) para
buscar taxas e preços atuais de até 20 títulos por requisição.
#### Monte gráficos históricos
Use [`/api/v2/treasury/indicators/history`](/docs/tesouro-direto/indicadores-historico)
para obter séries diárias de taxas e preços por título.
## Casos de uso comuns
* **Comparador de títulos públicos:** `list` com filtro por indexador.
* **Dashboard de renda fixa:** `indicators` para snapshot atual.
* **Gráfico de marcação a mercado:** `indicators/history` com `buyPrice`,
`sellPrice` e `basePrice`.
* **Análise de curva de juros:** combinar títulos Prefixados e IPCA+ por
vencimento.
# Histórico de Indicadores do Tesouro Direto
URL: /docs/tesouro-direto/indicadores-historico.mdx
Consulte a série diária de taxas e preços indicativos para títulos do Tesouro Direto, com filtro de datas e ordenação.
***
title: Histórico de Indicadores do Tesouro Direto
description: >-
Consulte a série diária de taxas e preços indicativos para títulos do Tesouro
Direto, com filtro de datas e ordenação.
full: true
keywords: brapi, api, tesouro direto, histórico, taxa histórica, preço histórico
openGraph:
title: Histórico de Indicadores do Tesouro Direto — brapi
description: Série diária de taxas e preços de títulos do Tesouro Direto.
type: website
locale: pt\_BR
lastUpdated: '2026-05-16T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/treasury/indicators/history
------------------------------------------
import { Callout } from 'fumadocs-ui/components/callout';
Retorna a série diária de taxas e preços por título, agrupada por `symbol`.
Quando `startDate` e `endDate` são omitidos, a API usa os últimos 12 meses.
Use esta rota para gráficos de marcação a mercado, análise de taxa por
vencimento e acompanhamento de movimentos da curva de juros.
Cada série inclui `rateInfo`, com a unidade e a descrição de como interpretar
`buyRate` e `sellRate` para o indexador daquele título.
**Plano mínimo: Pro.** No sandbox sem token, todos os símbolos da requisição
precisam estar na lista de sandbox.
# Indicadores do Tesouro Direto
URL: /docs/tesouro-direto/indicadores.mdx
Consulte o snapshot atual de taxas, preços, vencimento, indexador e tipo de cupom para títulos do Tesouro Direto.
***
title: Indicadores do Tesouro Direto
description: >-
Consulte o snapshot atual de taxas, preços, vencimento, indexador e tipo de
cupom para títulos do Tesouro Direto.
full: true
keywords: brapi, api, tesouro direto, indicadores, taxa compra, taxa venda, preço unitário
openGraph:
title: Indicadores do Tesouro Direto — brapi
description: Consulte taxas e preços atuais de títulos públicos do Tesouro Direto.
type: website
locale: pt\_BR
lastUpdated: '2026-05-16T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/treasury/indicators
----------------------------------
import { Callout } from 'fumadocs-ui/components/callout';
Retorna o snapshot mais recente de cada título solicitado via `symbols`.
Você pode enviar até 20 símbolos por requisição, separados por vírgula.
Símbolos desconhecidos são omitidos de `results`, sem erro por símbolo.
**Plano mínimo: Pro.** No sandbox sem token, todos os símbolos da requisição
precisam estar na lista de sandbox.
As taxas vêm em `% a.a.`. Para Tesouro Selic, `buyRate` e `sellRate` são
spreads sobre a Selic; para Prefixado são taxas nominais; para IPCA+ são
taxas reais acima do IPCA. A resposta inclui `rateInfo` para tornar essa
interpretação explícita por título.
# Listagem do Tesouro Direto
URL: /docs/tesouro-direto/listagem.mdx
Liste títulos públicos atualmente ofertados pelo Tesouro Direto, com filtros por indexador, tipo de cupom, busca, paginação e ordenação.
***
title: Listagem do Tesouro Direto
description: >-
Liste títulos públicos atualmente ofertados pelo Tesouro Direto, com filtros
por indexador, tipo de cupom, busca, paginação e ordenação.
full: true
keywords: brapi, api, tesouro direto, listagem, renda fixa, títulos públicos
openGraph:
title: Listagem do Tesouro Direto — brapi
description: Liste e filtre títulos do Tesouro Direto com taxas e preços atuais.
type: website
locale: pt\_BR
lastUpdated: '2026-05-16T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/treasury/list
----------------------------
import { Callout } from 'fumadocs-ui/components/callout';
Retorna uma lista paginada dos títulos do Tesouro Direto atualmente ofertados,
com taxas e preços indicativos mais recentes. Cada item inclui `rateInfo`, que
explica se as taxas são spread sobre Selic, taxa nominal ou taxa real acima do
índice de inflação.
Use esta rota como ponto de descoberta para encontrar os `symbols` públicos que
serão usados nos endpoints de indicadores e histórico.
**Plano mínimo: Pro.** No sandbox sem token, use `search` com um dos símbolos
liberados: `tesouro-selic-01032031`,
`tesouro-prefixado-com-juros-semestrais-01012037` ou
`tesouro-ipca-com-juros-semestrais-15082060`.
# Cobertura por Ticker
URL: /docs/tickers/cobertura.mdx
Descubra quais superfícies de dados da brapi estão disponíveis para cada ticker e quais endpoints usar em seguida.
***
title: Cobertura por Ticker
description: >-
Descubra quais superfícies de dados da brapi estão disponíveis para cada
ticker e quais endpoints usar em seguida.
full: true
keywords: brapi, api, tickers, cobertura, disponibilidade, endpoints
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/tickers/coverage
-------------------------------
Endpoint **público** para verificar o que a brapi consegue consultar para cada
ticker B3.
Use quando sua integração precisa decidir o próximo passo automaticamente:
cotação, histórico, dividendos de ações, rendimentos de FIIs, indicadores de
FIIs, relatórios ou endpoints de carteira e imóveis.
A resposta é por símbolo. Um ticker desconhecido não derruba a chamada inteira:
ele retorna `status: "unknown"` com recomendações de busca. Tickers antigos são
resolvidos antes da checagem e retornam `status: "renamed"` quando houver
mapeamento conhecido.
Este endpoint não retorna os dados de mercado em si. Ele informa quais endpoints
usar.
# Tickers Disponíveis
URL: /docs/tickers.mdx
Descubra, filtre e valide tickers B3 disponíveis na brapi usando o padrão v2. Ideal para busca, autocomplete, screeners e seleção de símbolos antes de consultar dados de mercado.
***
title: Tickers Disponíveis
description: >-
Descubra, filtre e valide tickers B3 disponíveis na brapi usando o padrão
v2. Ideal para busca, autocomplete, screeners e seleção de símbolos antes de
consultar dados de mercado.
full: true
keywords: brapi, api, tickers, ações, fiis, etfs, bdrs, b3, símbolos
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/tickers
----------------------
Endpoint **público** para descoberta de tickers B3. Use antes dos endpoints de
dados de mercado para encontrar o símbolo correto, montar autocomplete, validar
entradas de usuário ou construir telas de screening.
O catálogo cobre instrumentos B3 em formato de ticker: ações, FIIs, ETFs, BDRs,
units e índices. Opções, futuros, Tesouro Direto, cripto, câmbio e séries macro
têm endpoints próprios.
Para dados por preocupação, use endpoints específicos, como `/api/v2/fii/*` ou
`/api/v2/stocks/*`. O endpoint legado `/api/quote/list`
continua funcionando, mas novas integrações devem preferir este formato v2.
## Fluxo recomendado
1. Use `/api/v2/tickers` para buscar e filtrar símbolos disponíveis.
2. Use `/api/v2/tickers/resolve` se o usuário informou um ticker antigo.
3. Use `/api/v2/tickers/renames` para mostrar o histórico de mudança de código.
4. Use `/api/v2/tickers/coverage` para descobrir quais endpoints fazem sentido
para cada símbolo antes de buscar dados de mercado.
# Renomes de Tickers
URL: /docs/tickers/renomes.mdx
Consulte mudanças conhecidas de código de negociação na B3, incluindo ticker antigo, ticker atual canônico e data efetiva.
***
title: Renomes de Tickers
description: >-
Consulte mudanças conhecidas de código de negociação na B3, incluindo ticker
antigo, ticker atual canônico e data efetiva.
full: true
keywords: brapi, api, tickers, renomes, ticker antigo, b3
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/tickers/renames
------------------------------
Endpoint **público** para consultar renomes conhecidos de tickers B3.
Use quando um usuário informa um código antigo, quando você precisa exibir o
histórico de mudança de ticker, ou quando quer explicar por que uma busca por
um símbolo antigo deve apontar para outro ativo.
Filtros úteis:
* `symbols` filtra eventos envolvendo qualquer ticker informado.
* `search` busca em ticker antigo, novo ou canônico.
* `startDate` e `endDate` limitam pela data efetiva do renome, usando o formato
`YYYY-MM-DD`.
Para normalizar uma lista antes de consultar dados, use
[`/api/v2/tickers/resolve`](/docs/tickers/resolver).
# Resolver Tickers Antigos
URL: /docs/tickers/resolver.mdx
Normalize tickers antigos para o ticker atual recomendado antes de consultar dados de mercado.
***
title: Resolver Tickers Antigos
description: >-
Normalize tickers antigos para o ticker atual recomendado antes de consultar
dados de mercado.
full: true
keywords: brapi, api, tickers, resolver, normalizar ticker, ticker antigo
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/tickers/resolve
------------------------------
Endpoint **público** para resolver tickers antigos.
Informe até 20 símbolos em `symbols`. A resposta preserva a ordem dos tickers
informados e retorna:
* `requestedSymbol`: ticker enviado pelo usuário.
* `symbol`: ticker atual recomendado.
* `changed`: se houve normalização.
* `status`: `renamed` quando o ticker consta no catálogo de renomes, `active`
quando foi mantido sem alteração.
* `effectiveDate`: data efetiva do renome, quando existir.
Use este endpoint antes de chamar dados de mercado quando sua aplicação aceita
entrada livre de usuário, planilhas antigas, carteiras importadas ou bases com
histórico de símbolos.
# Histórico de Gregas e IV de Opções sobre Futuros
URL: /docs/futuros/opcoes/analytics-historico.mdx
Consulte a série temporal EOD de volatilidade implícita e gregas calculadas para uma opção sobre futuro específica.
***
title: Histórico de Gregas e IV de Opções sobre Futuros
description: >-
Consulte a série temporal EOD de volatilidade implícita e gregas calculadas
para uma opção sobre futuro específica.
full: true
keywords: brapi, api, opções sobre futuros, histórico, gregas, volatilidade implícita
openGraph:
title: Histórico de Gregas e IV de Opções sobre Futuros
description: >-
Série temporal EOD de volatilidade implícita e gregas calculadas para uma
opção sobre futuro específica.
type: website
locale: pt\_BR
lastUpdated: '2026-06-01T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/futures/options/analytics/history
structuredData:
headings: \[]
contents:
* content: >-
Retorna a série temporal EOD de IV e gregas calculadas para uma
opção sobre futuro específica.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna uma série temporal diária com volatilidade implícita, delta, gamma,
theta, vega e rho para uma opção sobre futuro específica.
Use este endpoint quando você já sabe o `symbol` da série.
**Plano mínimo: Pro.** No sandbox sem token, aceita apenas símbolos que
começam com `BGI`.
# Gregas e IV de Opções sobre Futuros
URL: /docs/futuros/opcoes/analytics.mdx
Consulte volatilidade implícita e gregas EOD calculadas para opções sobre futuros por vencimento.
***
title: Gregas e IV de Opções sobre Futuros
description: >-
Consulte volatilidade implícita e gregas EOD calculadas para opções sobre
futuros por vencimento.
full: true
keywords: brapi, api, opções sobre futuros, gregas, volatilidade implícita, BGI, ICF
openGraph:
title: Gregas e IV de Opções sobre Futuros
description: >-
Consulte volatilidade implícita e gregas EOD calculadas para opções sobre
futuros.
type: website
locale: pt\_BR
lastUpdated: '2026-06-01T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/futures/options/analytics
structuredData:
headings: \[]
contents:
* content: >-
Retorna volatilidade implícita e gregas EOD calculadas para opções
sobre futuros de um vencimento.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna volatilidade implícita e gregas EOD para opções sobre futuros de um
vencimento, com filtros por `side`, `minStrike` e `maxStrike`.
Opções europeias sobre futuros usam Black-76. Opções americanas usam uma
aproximação binomial sobre futuros. Quando faltam dados suficientes, os campos
calculados ficam `null` e `nullReason` explica o motivo.
**Plano mínimo: Pro.** No sandbox sem token, aceita apenas `underlying=BGI`.
Quando não há fechamento negociado, algumas séries podem usar
`referencePrice` como entrada. Nesses casos, `priceSource` vem como
`referencePrice` e `confidence` tende a ser menor.
# Histórico de Opções sobre Futuros
URL: /docs/futuros/opcoes/historico.mdx
Série diária de uma opção sobre futuro: OHLC, preço de referência e volume. Pronto para gráfico ou backtest.
***
title: Histórico de Opções sobre Futuros
description: >-
Série diária de uma opção sobre futuro: OHLC, preço de referência e
volume. Pronto para gráfico ou backtest.
full: true
keywords: brapi, api, opções sobre futuros, histórico, OHLC, backtest
openGraph:
title: Histórico de Opções sobre Futuros
description: >-
Série diária de uma opção sobre futuro.
type: website
locale: pt\_BR
lastUpdated: '2026-05-21T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/futures/options/historical
structuredData:
headings: \[]
contents:
* content: >-
Série diária de uma opção sobre futuro identificada por símbolo,
pronta para gráfico ou backtest.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna a série diária de uma opção sobre futuro, pelo `symbol`
(ex.: `BGIK26C034300`).
O normal é descobrir a série em
[Cadeia](/docs/futuros/opcoes/series) e depois chamar este endpoint. Ele
aceita **uma série por vez**.
A resposta tem:
* **Dados completos do contrato** — strike, optionStyle, multiplier, lote,
ISIN etc.
* **Série diária com negócio** — OHLC, referencePrice, oscillationPct,
trades, volume, financialVolume.
A maioria das séries longe do preço atual negocia pouco — sua resposta
pode ter só alguns dias. Para acompanhar todo dia, escolha a série mais
próxima do preço atual.
**Plano Pro.** Sem token, aceita só `symbol` começando com `BGI`.
# Opções sobre Futuros
URL: /docs/futuros/opcoes.mdx
Como usar a API de opções sobre futuros (boi, café, milho, soja e outros). Veja os termos, o passo a passo e qual endpoint usar.
***
title: Opções sobre Futuros
description: >-
Como usar a API de opções sobre futuros (boi, café, milho, soja e outros).
Veja os termos, o passo a passo e qual endpoint usar.
full: true
keywords: brapi, api, opções sobre futuros, BGI, ICF, CCM, SJC, calls, puts, vencimento, strike
openGraph:
title: Opções sobre Futuros
description: >-
Como usar a API de opções sobre futuros, com passo a passo e exemplos.
type: website
locale: pt\_BR
lastUpdated: '2026-05-21T12:00:00.000Z'
lang: pt-BR
-----------
import { Callout } from 'fumadocs-ui/components/callout';
import { Card, Cards } from 'fumadocs-ui/components/card';
import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
Use esta API para consultar opções cujo ativo-base é um contrato futuro. Ela é
útil para telas de cadeia, histórico EOD, gregas e volatilidade implícita de
commodities e futuros financeiros.
Na bolsa brasileira, os principais ativos são:
* **Boi gordo** (`BGI`)
* **Café arábica** (`ICF`)
* **Milho** (`CCM`)
* **Soja** (`SJC`)
* Outros menores: `CNL`, `D11`–`D17` (DI), `ETH`, `GLD`, `ISP`, `SOY`.
Esta seção é para opções **sobre futuros**. Para opções de **ações,
ETFs e índices** (PETR4, VALE3, BOVA11 etc.), veja
[Opções](/docs/opcoes).
A API entrega vencimentos, strikes, cadeia de opções, histórico EOD,
volatilidade implícita e gregas calculadas para opções europeias e americanas.
## Cobertura e atualização
* **Histórico:** cerca de **1 ano**, atualizado após o pregão.
* **Quando atualiza:** **após as 19h** (horário de Brasília).
* **Contratos:** opções listadas sobre futuros (commodities e financeiros).
* **Analytics:** volatilidade implícita e gregas EOD calculadas para opções
europeias (Black-76) e americanas (aproximação binomial).
* **Fuso horário:** `America/Sao_Paulo`. Em respostas de preços/histórico,
`date` é um número (Unix em segundos); em respostas de analytics, `date` vem
em `YYYY-MM-DD`.
## Termos
* **Ativo (`underlyingAsset`):** o código do **futuro** que serve de base
(ex.: `BGI`, `ICF`).
* **Código da opção (`symbol`):** padrão do mercado
`{ATIVO}{LETRA_MÊS_FUTURO}{ANO}{C|P}{STRIKE×100}`. Ex.:
`BGIH27C028550` = call sobre BGI, vencimento março/2027, strike
R$ 285,50.
* **Estilo (`optionStyle`):** `american` (pode exercer a qualquer momento)
ou `european` (só no vencimento). Opções sobre commodities são quase
sempre **american**.
* **Tipo (`optionType`):** `call` (compra) ou `put` (venda).
* **Strike (`strike`):** preço combinado, em reais.
* **Multiplicador (`contractMultiplier`):** vem do futuro. Ex.: opções de
boi têm multiplicador `330` (arrobas).
* **Lote (`allocationRoundLot`):** quase sempre `1`.
* **Exercício automático (`automaticExercise`):** se `true`, a opção é
exercida sozinha no vencimento quando vale a pena.
## Acesso
Opções sobre futuros estão no plano **Pro**, junto com os futuros.
| Plano | Acesso |
| ------------------- | ------------------- |
| Sem token (sandbox) | BGI (boi gordo) |
| Free | Não incluso |
| Startup | Não incluso |
| **Pro** | **Todos os ativos** |
## Comece rápido
Exemplo do fluxo `vencimentos → cadeia → histórico` para opções de **boi
gordo (BGI)**. Funciona no sandbox sem token.
```bash
# 1) Vencimentos disponíveis
curl "https://brapi.dev/api/v2/futures/options/expirations?underlying=BGI"
# 2) Cadeia (calls + puts) de um vencimento
curl "https://brapi.dev/api/v2/futures/options/chain?underlying=BGI&expirationDate=2026-05-29"
# 3) Histórico de uma série
curl "https://brapi.dev/api/v2/futures/options/historical?symbol=BGIK26C034300"
```
```typescript
const BASE = 'https://brapi.dev/api/v2/futures/options';
const token = process.env.BRAPI_TOKEN; // opcional para BGI no sandbox
const headers = token ? { Authorization: `Bearer ${token}` } : undefined;
// 1) Vencimentos
const exps = await fetch(`${BASE}/expirations?underlying=BGI`, {
headers,
}).then((r) => r.json());
const nextExp = exps.expirations[0];
// 2) Cadeia
const chain = await fetch(
`${BASE}/chain?underlying=BGI&expirationDate=${nextExp}`,
{ headers },
).then((r) => r.json());
// 3) Histórico da série mais próxima do preço
const atm = chain.series[0];
const history = await fetch(
`${BASE}/historical?symbol=${atm.symbol}`,
{ headers },
).then((r) => r.json());
console.log(history);
```
```python
import os
import requests
BASE = "https://brapi.dev/api/v2/futures/options"
token = os.getenv("BRAPI_TOKEN") # opcional para BGI no sandbox
headers = {"Authorization": f"Bearer {token}"} if token else {}
# 1) Vencimentos
exps = requests.get(
f"{BASE}/expirations", params={"underlying": "BGI"}, headers=headers
).json()
next_exp = exps["expirations"][0]
# 2) Cadeia
chain = requests.get(
f"{BASE}/chain",
params={"underlying": "BGI", "expirationDate": next_exp},
headers=headers,
).json()
# 3) Histórico
atm = chain["series"][0]
history = requests.get(
f"{BASE}/historical", params={"symbol": atm["symbol"]}, headers=headers
).json()
print(history)
```
## Passo a passo
#### Vencimentos
Comece em
[`/api/v2/futures/options/expirations`](/docs/futuros/opcoes/vencimentos)
com o ativo do subjacente (ex.: `BGI`, `ICF`).
#### Strikes
Use
[`/api/v2/futures/options/strikes`](/docs/futuros/opcoes/precos-de-exercicio)
para ver os strikes do vencimento. Filtre por `side=call` ou
`side=put`.
#### Cadeia
Use [`/api/v2/futures/options/chain`](/docs/futuros/opcoes/series) para
todas as séries do vencimento, com último preço.
#### Gregas e IV
Use
[`/api/v2/futures/options/analytics`](/docs/futuros/opcoes/analytics)
para a foto EOD de um vencimento, ou
[`/api/v2/futures/options/analytics/history`](/docs/futuros/opcoes/analytics-historico)
para a série temporal de uma opção específica.
#### Histórico
Quando souber a série, use
[`/api/v2/futures/options/historical`](/docs/futuros/opcoes/historico).
## Casos comuns
* **Tela de opções de commodity:** `expirations → chain`
* **Filtro por faixa de strike:** `chain?minStrike=X&maxStrike=Y`
* **Gregas e volatilidade implícita por vencimento:** `expirations → analytics`
* **Backtest de boi/café/milho/soja:** `chain` para escolher a série,
depois `historical` e `analytics/history`.
## Perguntas frequentes
## Endpoints
# Strikes de Opções sobre Futuros
URL: /docs/futuros/opcoes/precos-de-exercicio.mdx
Strikes disponíveis para opções sobre um futuro num vencimento, com filtro por call/put.
***
title: Strikes de Opções sobre Futuros
description: >-
Strikes disponíveis para opções sobre um futuro num vencimento, com
filtro por call/put.
full: true
keywords: brapi, api, opções sobre futuros, strikes, preço de exercício
openGraph:
title: Strikes de Opções sobre Futuros
description: >-
Strikes disponíveis para opções sobre um futuro.
type: website
locale: pt\_BR
lastUpdated: '2026-05-21T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/futures/options/strikes
structuredData:
headings: \[]
contents:
* content: >-
Strikes disponíveis para opções sobre um futuro num vencimento.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna a lista de strikes do vencimento, para o ativo pedido. Filtre por
`side=call` ou `side=put` se precisar.
Use este endpoint quando quiser ver a faixa de strikes antes de chamar a
[cadeia](/docs/futuros/opcoes/series) — assim dá para limitar a cadeia
com `minStrike` e `maxStrike`.
**Plano Pro.** Sem token, aceita só `underlying=BGI`.
# Cadeia de Opções sobre Futuros
URL: /docs/futuros/opcoes/series.mdx
Cadeia (calls + puts) de opções sobre um futuro num vencimento, com preço, volume, estilo e multiplicador.
***
title: Cadeia de Opções sobre Futuros
description: >-
Cadeia (calls + puts) de opções sobre um futuro num vencimento, com
preço, volume, estilo e multiplicador.
full: true
keywords: brapi, api, opções sobre futuros, cadeia, chain, calls, puts, série
openGraph:
title: Cadeia de Opções sobre Futuros
description: >-
Cadeia (calls + puts) de opções sobre um futuro num vencimento.
type: website
locale: pt\_BR
lastUpdated: '2026-05-21T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/futures/options/chain
structuredData:
headings: \[]
contents:
* content: >-
Cadeia (calls e puts) de opções sobre um futuro num vencimento,
com o último preço.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna todas as séries (calls e puts) do vencimento, com o último preço
até a data pedida.
Cada série tem:
* **Dados do contrato:** `symbol`, `optionType` (call/put), `optionStyle`
(american/european), `strike`, `expirationDate`, `contractMultiplier`,
`allocationRoundLot`, `automaticExercise`.
* **Cotação do dia:** OHLC, `referencePrice`, `oscillationPct`, `trades`,
`volume`, `financialVolume`.
Filtros opcionais: `side=call|put`, `minStrike`, `maxStrike`.
A maioria das séries longe do preço atual tem pouca negociação. `close`
pode vir `null` em muitas linhas — o `referencePrice` pode estar
preenchido mesmo sem negócio.
**Plano Pro.** Sem token, aceita só `underlying=BGI`.
# Vencimentos de Opções sobre Futuros
URL: /docs/futuros/opcoes/vencimentos.mdx
Vencimentos disponíveis para opções sobre um futuro (boi, café, milho, soja e outros).
***
title: Vencimentos de Opções sobre Futuros
description: >-
Vencimentos disponíveis para opções sobre um futuro (boi, café, milho,
soja e outros).
full: true
keywords: brapi, api, opções sobre futuros, vencimentos, BGI, ICF, CCM, SJC
openGraph:
title: Vencimentos de Opções sobre Futuros
description: >-
Vencimentos disponíveis para opções sobre um futuro.
type: website
locale: pt\_BR
lastUpdated: '2026-05-21T12:00:00.000Z'
lang: pt-BR
\_openapi:
method: GET
route: /api/v2/futures/options/expirations
structuredData:
headings: \[]
contents:
* content: >-
Vencimentos disponíveis para opções sobre um futuro.
***
import { Callout } from 'fumadocs-ui/components/callout';
Retorna a lista de vencimentos das opções de um ativo. Use `underlying`
com o código do **futuro** (ex.: `BGI`, `ICF`, `CCM`, `SJC`).
Os vencimentos das opções **nem sempre coincidem** com os do futuro — cada
opção tem seu próprio calendário.
**Plano Pro.** Sem token, aceita só `underlying=BGI` (boi gordo).