API B3: como acessar dados da bolsa de valores do Brasil
Você já tentou integrar dados da bolsa de valores brasileira em um projeto? Se sim, provavelmente descobriu que acessar informações da B3 (Brasil, Bolsa, Balcão) pode ser complicado e caro.
A boa notícia é que existem APIs que simplificam esse processo. Neste guia, você vai aprender a consultar cotações de ações, FIIs, câmbio e índices da B3 com exemplos práticos que funcionam ao copiar e colar.
O que é uma API de dados financeiros?
Uma API (Interface de Programação de Aplicações) de dados financeiros permite que você acesse informações do mercado diretamente no seu código. Em vez de copiar dados manualmente de sites ou planilhas, você faz uma requisição HTTP e recebe os dados em formato estruturado (JSON).
Isso significa que você pode:
- Criar dashboards;
- Automatizar a coleta de cotações;
- Integrar dados financeiros em apps, sites ou planilhas;
- Construir alertas de preço personalizados.
Qual API usar para acessar dados da B3?
A
- 📊 Cotações de ações (PETR4, VALE3, ITUB4...);
- 🏢 FIIs (Fundos Imobiliários);
- 💵 Câmbio (Dólar, Euro, Libra, Bitcoin);
- 📈 Índice Ibovespa;
- 💰 Taxas SELIC e CDI.
Toda a documentação está em português e os dados retornam em JSON, facilitando a integração com qualquer linguagem de programação.
Quanto custa?
O plano gratuito inclui um pacote de requisições diárias, suficiente para projetos pessoais e testes.
Para aplicações em produção, existem
Como começar: passo a passo
1. Crie sua chave de API
Para acessar os dados, você precisa de uma chave de autenticação:
- Acesse console.hgbrasil.com;
- Crie sua conta gratuita (não precisa de cartão de crédito);
- Gere uma chave do tipo "uso exposto" (para aplicações frontend).
2. Faça sua primeira requisição
Com a chave em mãos, você já pode consultar qualquer ativo. Veja o endpoint para buscar a cotação do dólar:
GEThttps://api.hgbrasil.com/finance/stock_price?symbol=USDBRL&key=suachave
Confira a
Exemplo prático: exibindo cotações na página
Vamos criar uma aplicação simples que mostra a cotação do dólar (USDBRL). Você pode adaptar o código para qualquer ação, FII ou moeda disponível.
Estrutura HTML básica
Crie o arquivo index.html com a estrutura da página:
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Cotação do Dólar - B3</title>
</head>
<body>
<h1>Cotação do Dólar</h1>
<pre id="data">Carregando...</pre>
<script src="script.js"></script>
</body>
</html>
Buscando dados da API
Crie o arquivo script.js para fazer a requisição:
// Substitua pela sua chave de API
const API_KEY = 'SUA_CHAVE_AQUI'
// Ticker do ativo (ex: USDBRL, PETR4, VALE3)
const TICKER = 'USDBRL'
// URL da API com parâmetro CORS para funcionar no navegador
const url = `https://api.hgbrasil.com/finance/stock_price?key=${API_KEY}&format=json-cors&symbol=${TICKER}`
fetch(url)
.then((response) => response.json())
.then((data) => {
document.getElementById('data').textContent = JSON.stringify(data, null, 2)
})
.catch((error) => {
console.error('Erro ao acessar a API:', error)
})
format=json-cors na URL. Ele é obrigatório para requisições feitas diretamente do navegador. Saiba mais na Abra o arquivo index.html no navegador e você verá algo assim:
{
"by": "symbol",
"valid_key": true,
"results": {
"USDBRL": {
"kind": "currency",
"symbol": "USDBRL",
"name": "Dólar em Real",
"company_name": null,
"document": null,
"description": null,
"ai_description": null,
"website": null,
"sector": null,
"related": [],
"bookkeeper": null,
"logo": {
"small": "https://assets.hgbrasil.com/finance/companies/small/usdbrl.png",
"big": "https://assets.hgbrasil.com/finance/companies/big/usdbrl.png"
},
"financials": {},
"region": "Brazil/Sao Paulo",
"currency": "BRL",
"market_time": {
"open": "10:00",
"close": "17:30",
"timezone": -3
},
"market_cap": 0,
"price": 5.1653,
"change_percent": -0.2125,
"change_price": -0.01,
"volume": 0,
"updated_at": "2026-02-23 15:23:11"
}
},
"execution_time": 0.01,
"from_cache": true
}
Formatando os dados para exibição
Agora vamos deixar a apresentação mais profissional. Atualize o index.html:
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Cotações B3</title>
<link rel="stylesheet" href="styles.css" />
</head>
<body>
<h1>Cotações da B3</h1>
<!-- Você pode adicionar vários ativos! -->
<div class="asset" data-ticker="USDBRL"></div>
<div class="asset" data-ticker="PETR4"></div>
<script src="script.js"></script>
</body>
</html>
Atualize o script.js para processar múltiplos ativos:
const API_KEY = 'SUA_CHAVE_AQUI'
// Seleciona todos os elementos com a classe .asset
const assets = document.querySelectorAll('.asset')
assets.forEach((element) => {
const ticker = element.dataset.ticker
const url = `https://api.hgbrasil.com/finance/stock_price?key=${API_KEY}&format=json-cors&symbol=${ticker}`
fetch(url)
.then((response) => response.json())
.then((data) => {
const asset = data.results[ticker]
// Formata a variação com sinal + ou -
const variationSign = asset.change_percent >= 0 ? '+' : ''
const variationClass = asset.change_percent >= 0 ? 'positive' : 'negative'
element.innerHTML = `
<div class="asset-header">
<img class="asset-logo" src="${asset.logo.small}" alt="${asset.name}" />
<span class="asset-name">${asset.name}</span>
<span class="asset-symbol">${asset.symbol}</span>
</div>
<div class="asset-price">R$ ${asset.price.toFixed(2).replace('.', ',')}</div>
<div class="asset-variation ${variationClass}">
${variationSign}${asset.change_percent.toFixed(2).replace('.', ',')}%
</div>
<div class="asset-updated">
Atualizado em ${new Date(asset.updated_at).toLocaleString('pt-BR')}
</div>
`
})
.catch((error) => {
element.innerHTML = `<p class="error">Erro ao carregar ${ticker}</p>`
console.error('Erro:', error)
})
})
Adicione estilos no arquivo styles.css:
* {
box-sizing: border-box;
margin: 0;
padding: 0;
}
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
background: #f5f5f5;
padding: 20px;
}
h1 {
margin-bottom: 20px;
color: #333;
}
.asset {
background: white;
border: 1px solid #e0e0e0;
border-radius: 12px;
padding: 16px;
max-width: 280px;
margin-bottom: 16px;
}
.asset-header {
display: flex;
align-items: center;
gap: 10px;
margin-bottom: 12px;
}
.asset-logo {
width: 32px;
height: 32px;
border-radius: 50%;
}
.asset-name {
font-weight: 600;
color: #333;
}
.asset-symbol {
color: #888;
font-size: 14px;
}
.asset-price {
font-size: 28px;
font-weight: 700;
color: #111;
margin-bottom: 4px;
}
.asset-variation {
font-size: 16px;
font-weight: 500;
margin-bottom: 12px;
}
.asset-variation.positive {
color: #16a34a;
}
.asset-variation.negative {
color: #dc2626;
}
.asset-updated {
font-size: 12px;
color: #888;
}
.error {
color: #dc2626;
}
localhost.Exemplo em PHP (backend)
Para aplicações em produção, recomendamos fazer as requisições pelo backend. Isso mantém sua chave de API segura e permite implementar cache para economizar requisições.
<?php
// Substitua pela sua chave de API
$apiKey = 'SUA_CHAVE_AQUI';
$ticker = 'PETR4';
// Faz a requisição para a API
$url = "https://api.hgbrasil.com/finance/stock_price?key={$apiKey}&symbol={$ticker}";
$response = file_get_contents($url);
$data = json_decode($response, true);
// Verifica se a requisição foi bem-sucedida
if (!$data || !isset($data['results'][$ticker])) {
die('Erro ao buscar dados do ativo.');
}
$asset = $data['results'][$ticker];
// Formata a variação
$variation = $asset['change_percent'];
$variationClass = $variation >= 0 ? 'positive' : 'negative';
$variationSign = $variation >= 0 ? '+' : '';
?>
<!DOCTYPE html>
<html lang="pt-BR">
<head>
<meta charset="UTF-8">
<title><?= htmlspecialchars($asset['name']) ?> - Cotação</title>
</head>
<body>
<div class="asset">
<div class="asset-header">
<img src="<?= htmlspecialchars($asset['logo']['small']) ?>" alt="<?= htmlspecialchars($asset['name']) ?>" />
<span><?= htmlspecialchars($asset['name']) ?></span>
<span>(<?= htmlspecialchars($asset['symbol']) ?>)</span>
</div>
<div class="asset-price">
R$ <?= number_format($asset['price'], 2, ',', '.') ?>
</div>
<div class="asset-variation <?= $variationClass ?>">
<?= $variationSign . number_format($variation, 2, ',', '.') ?>%
</div>
<div class="asset-updated">
Atualizado em <?= date('d/m/Y H:i', strtotime($asset['updated_at'])) ?>
</div>
</div>
</body>
</html>
Indo além...
Agora que você sabe como acessar dados da B3, pode expandir seu projeto:
- Consultar múltiplos ativos: Passe vários tickers separados por vírgula (
symbol=PETR4,VALE3,ITUB4); - Monitorar altas e baixas: Use
symbol=get-highousymbol=get-low; - Acessar dados históricos: Disponível nos
; - Implementar cache: Evite requisições desnecessárias armazenando os dados temporariamente.
A