API gratuita de ações brasileiras: o que dá para fazer com 200 requisições por dia

Por que 200 requisições por dia é mais do que parece

O viés que faz o número parecer baixo vem da comparação com APIs internacionais como Alpha Vantage (25 req/dia no free, mas com cache agressivo na CDN) ou Polygon (5 req/minuto no free, ou seja, ~7.200/dia). O contexto importa. A api b3 grátis da bolsai expõe endpoints com dados já calculados (27 indicadores TTM por ticker, histórico trimestral de 11 anos, dividendos consolidados), o que reduz o número de chamadas necessárias para extrair informação útil. Uma única chamada a /fundamentals/PETR4 entrega o que em outras APIs exigiria entre cinco e dez chamadas separadas.

O outro fator é que dados fundamentalistas não mudam intraday. Indicadores como P/L, ROE e EV/EBITDA só são recalculados quando sai um novo balanço (ITR trimestral, DFP anual), o que acontece de dois a quatro pontos por ano por empresa. Cachear esses dados por 12 ou 24 horas é seguro e reduz o consumo a uma fração do que seria sem cache. O mesmo vale para dados macro: a meta SELIC muda apenas em reuniões do Copom; o IPCA é mensal.

Como o limite funciona na prática

O contador roda em janela de 24 horas, com reset à meia-noite UTC (21h em horário de Brasília). Cada chamada autenticada com X-API-Key consome uma unidade. As respostas vêm com três cabeçalhos HTTP padronizados que permitem monitorar o consumo:

X-RateLimit-Limit:     200
X-RateLimit-Remaining: 187
X-RateLimit-Reset:     1715472000

O campo X-RateLimit-Reset é um timestamp Unix indicando quando o contador zera. Para integrações que precisam priorizar chamadas dentro do orçamento diário, ler esses cabeçalhos a cada resposta basta para evitar surpresas. Quando o limite é atingido, a API responde com status 429 e o cabeçalho Retry-After indicando os segundos a aguardar. Os formatos exatos e exemplos de tratamento estão na documentação completa.

Caso 1: planilha pessoal de portfólio com 50 ativos

O caso mais comum: uma planilha local ou notebook Python que mantém uma carteira pessoal atualizada com cotação de fechamento e indicadores fundamentalistas. Mesmo carteiras agressivas dificilmente passam de 50 ativos. O script abaixo busca cotação e P/L de cada ticker da carteira e salva tudo em um CSV, gastando exatamente 50 requisições por execução diária.

# carteira_diaria.py — roda 1x ao dia, gasta 50 req
import os
import csv
import httpx
from datetime import date

API_KEY = os.getenv("BOLSAI_API_KEY")
BASE = "https://api.usebolsai.com/api/v1"
HEADERS = {"X-API-Key": API_KEY}

carteira = [
    "PETR4", "VALE3", "ITUB4", "BBAS3", "WEGE3",
    "ABEV3", "BBDC4", "B3SA3", "RENT3", "PRIO3",
    # ... até 50 tickers
]

with httpx.Client(headers=HEADERS, timeout=10) as client, \
     open(f"carteira_{date.today()}.csv", "w") as f:
    w = csv.writer(f)
    w.writerow(["ticker", "preco", "pl", "roe"])
    for t in carteira:
        d = client.get(f"{BASE}/fundamentals/{t}").json()
        w.writerow([t, d["current_price"], d["pl"], d["roe"]])

print(f"50 ativos salvos. Restam ~150 req hoje.")

Note que /fundamentals/{ticker} já traz current_price embutido, eliminando a necessidade de uma chamada separada a /stocks/{ticker}/quote. Para quem só quer preço, o endpoint de cotação custa o mesmo (uma requisição), mas vem mais leve. Para fluxos que precisam de séries OHLC históricas, o caminho está em dados históricos de ações na B3.

Caso 2: bot de Telegram com alertas de preço

Um bot de Telegram que monitora ações favoritas e notifica quando o preço cruza um gatilho consome menos do que parece. Verificar quatro vezes por dia (10h, 13h, 16h e após o fechamento) é suficiente para alertas de swing trade. O exemplo mostra a estrutura típica: lista de alertas com preço-alvo, verificação por ticker, notificação via bot.

# bot_alertas.py — chamado pelo cron a cada 4h, gasta 10 req por execução
import os
import httpx

API_KEY = os.getenv("BOLSAI_API_KEY")
TG_TOKEN = os.getenv("TELEGRAM_BOT_TOKEN")
TG_CHAT = os.getenv("TELEGRAM_CHAT_ID")
BASE = "https://api.usebolsai.com/api/v1"

# Cada item: (ticker, condição, preço-alvo)
alertas = [
    ("PETR4", "<", 36.00),
    ("VALE3", ">", 75.00),
    ("BBAS3", "<", 28.00),
    # ... até 10 alertas
]

def notify(msg: str) -> None:
    httpx.post(
        f"https://api.telegram.org/bot{TG_TOKEN}/sendMessage",
        json={"chat_id": TG_CHAT, "text": msg},
    )

with httpx.Client(headers={"X-API-Key": API_KEY}, timeout=10) as c:
    for ticker, op, alvo in alertas:
        preco = c.get(f"{BASE}/stocks/{ticker}/quote").json()["close"]
        if (op == "<" and preco < alvo) or (op == ">" and preco > alvo):
            notify(f"{ticker} cruzou {op} R${alvo:.2f}: R${preco:.2f}")

Mesmo subindo a frequência para uma checagem por hora dentro do pregão (das 10h às 17h, 7 verificações), o gasto fica em 70 requisições por dia, ainda confortavelmente dentro do limite. Quem precisa de alertas verdadeiramente intraday com latência de minutos deve considerar feed dedicado via corretora; a bolsai trabalha com cotação de fechamento e atualização intradiária via cache.

Caso 3: app pessoal de análise fundamentalista semanal

Para quem mantém um app ou notebook que olha um universo amplo de ações apenas para revisão semanal de teses, a distribuição ao longo da semana resolve. Em vez de bater no universo inteiro toda segunda-feira, o script processa ~30 ativos por dia útil. Combinado com cache local em SQLite, isso reduz o consumo médio significativamente, porque a maioria dos indicadores não muda entre execuções consecutivas.

A tabela abaixo mostra três cenários típicos de cadência semanal e o consumo de cada um:

Para acompanhamento dos múltiplos clássicos, o caminho passa por P/L, P/VP, ROE e EV/EBITDA. O guia análise fundamentalista para iniciantes consolida as quatro dimensões em um único framework.

Caso 4: planilha Google Sheets com cache agressivo

O Google Sheets com Apps Script via CacheService é o caso onde 200 req/dia rende mais. Cada fórmula custom (=BOLSAI_QUOTE("PETR4")) consulta o cache antes de chamar a API. Com TTL de 5 a 15 minutos para cotação e 6 horas para fundamentos, uma planilha com 30 tickers raramente passa de 20 requisições diárias mesmo sendo aberta várias vezes ao dia. O passo a passo completo está em Google Sheets com cotações da B3.

A regra prática de cache para o caso geral fica assim: para cotação intradiária, 5 minutos. Para indicadores fundamentalistas, 12 a 24 horas (eles só mudam na publicação de balanços). Para distribuições de FIIs, 24 horas (informes mensais). Para indicadores macro do BCB (SELIC, CDI, IPCA), 1 a 6 horas. Com essa segmentação, mesmo apps com dezenas de telas ativas conseguem se manter no plano gratuito sem perda relevante de frescor de dados.

Caso 5: screener acadêmico para TCC ou pesquisa

Trabalhos acadêmicos, monografias e estudos de viabilidade de estratégias são casos onde o limite de 200 req/dia cobre o ciclo inteiro. O endpoint /screener aceita combinações de filtros com convenções {indicador}_gt e {indicador}_lt, então a primeira chamada já entrega o subconjunto relevante. Em uma sessão típica, o pesquisador roda uma query inicial, abre 20 finalistas para análise fundamentalista detalhada (mais 20 req), e ainda sobra orçamento para refazer o screener com filtros ajustados.

# Screener de "qualidade barata": ROE alto, P/L razoável, DY decente
import os
import httpx

API_KEY = os.getenv("BOLSAI_API_KEY")
BASE = "https://api.usebolsai.com/api/v1"

params = {
    "roe_gt": 15,             # rentabilidade mínima
    "pl_lt": 12,              # múltiplo razoável
    "dividend_yield_gt": 5,   # DY mínimo
    "sort": "roe",
    "order": "desc",
    "limit": 50,
}
r = httpx.get(f"{BASE}/screener", headers={"X-API-Key": API_KEY}, params=params)
finalistas = r.json()["data"]

# Custo total: 1 requisição para os 50 candidatos
print(f"{len(finalistas)} ações passaram no filtro. Restam 199 req hoje.")

Note o ganho de eficiência: uma única chamada ao screener entrega 22 candidatos pré-filtrados. Comparado a iterar sobre 350 tickers verificando indicador por indicador, o consumo cai de centenas para uma. Quem quer aprofundar no screener encontra padrões completos em screener de ações brasileiras em Python. Para estratégias mais elaboradas que mesclam filtros com backtest, a sequência natural é o post sobre backtest em Python com a API da B3.

Caso 6: notebook de pesquisa quantitativa

Jupyter Notebooks de pesquisa quantitativa têm um perfil de consumo bimodal. No primeiro dia, o usuário faz backfill de séries históricas para 20 a 50 ativos, gastando de 20 a 50 requisições. Depois disso, o trabalho é majoritariamente offline: análise estatística do DataFrame já carregado em memória, backtest sobre os dados em cache, visualização. Refresh diário de cotações para alguns ativos chave consome menos de 10 requisições.

O endpoint /stocks/{ticker}/history?format=csv exporta diretamente para CSV consumível por pandas, o que reduz drasticamente o atrito. Para integrar dados macro (SELIC como taxa livre de risco, IPCA como deflator), os endpoints /macro/selic e /macro/ipca entregam séries completas. O detalhamento dos endpoints macro e exemplos de Sharpe Ratio com base no CDI estão em API para SELIC, CDI e IPCA.

Quando 200 req/dia não basta

Há três cenários onde o plano gratuito fica realmente apertado. Tratá-los com honestidade evita expectativas erradas:

• Dashboards públicos com tráfego. Qualquer painel exposto na internet onde cada visitante dispara várias chamadas atrás do mesmo dado é incompatível com o free tier. Mesmo com cache server-side agressivo, picos de tráfego derrubam o orçamento rapidamente.
• ETL noturno sobre o universo inteiro. Recalcular indicadores de todas as 350+ ações e 400+ FIIs todo dia consome 750+ requisições só para o full sweep. Esse é o caso clássico onde o plano Pro a R$49/mês (10.000 req/dia) faz sentido econômico imediato.
• Trading intradiário ou high-frequency. Cotações a cada minuto durante o pregão de cinco horas consomem 300 chamadas só na primeira hora. Para day trade, o caminho correto não é nem mesmo o plano Pro; é um feed contratado via corretora ou provedor institucional.

Há também um quarto caso menos óbvio: scraping ou redistribuição dos dados para terceiros. Os Termos de Uso restringem republicação massiva sem autorização, e o consumo nesse formato tende a ultrapassar qualquer plano free de qualquer provedor honesto. Para projetos que envolvem servir dados a uma base de usuários externa, o caminho é o plano Pro combinado com revisão do contrato comercial.

Quando migrar para o plano Pro faz sentido

A migração para o plano Pro (R$49/mês, 10.000 requisições por dia) compensa em três pontos de inflexão objetivos. Primeiro, quando o consumo médio passa de 150 req/dia em mais de duas semanas consecutivas, o que indica que o limite vai estourar em algum momento. Segundo, quando o projeto começa a ser usado por outras pessoas além do desenvolvedor original, ainda que de forma privada. Terceiro, quando agentes de IA via servidor MCP entram no fluxo, porque cada turno conversacional do Claude ou Cursor pode disparar de uma a quatro chamadas. O comparativo de planos está em página de preços.

Quem quer entender as alternativas no mercado antes de migrar pode comparar lado a lado em bolsai vs brapi, ou avaliar o caminho de saída do scraping tradicional em alternativa ao Fundamentus. Para quem trabalha com renda passiva e quer entender a profundidade da cobertura de proventos, como montar carteira de dividendos com Python mostra o ciclo completo de extração.

Perguntas frequentes

200 requisições por dia bastam para uso pessoal?

Sim, na maior parte dos casos. Uma carteira de 50 ativos atualizada uma vez por dia consome 50 requisições. Um bot de Telegram que checa 10 alertas quatro vezes por dia consome 40. Uma planilha Google Sheets com 30 ativos e cache de seis horas roda com menos de 20 requisições diárias. O limite só fica apertado em dashboards multiusuário, ETLs noturnos sobre o universo inteiro e cenários de alta frequência.

Como funciona o limite de 200 requisições por dia?

O contador roda em janela de 24 horas, com reset à meia-noite UTC (21h em horário de Brasília). Cada chamada autenticada consome uma unidade. Respostas vêm com os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset, então é possível monitorar o consumo em tempo real e ajustar a cadência das integrações sem ultrapassar o limite.

Quando 200 requisições por dia não bastam?

Em três cenários objetivos. Dashboards públicos onde o tráfego é imprevisível e cada visitante dispara várias chamadas. Jobs noturnos de ETL que recalculam o universo inteiro de ações ou FIIs diariamente. Estratégias intradiárias que precisam de cotação a cada minuto. Para esses casos, o plano Pro a R$49 por mês libera 10.000 requisições e remove a restrição.

O cache local conta como requisição?

Não. O limite só conta requisições HTTP que efetivamente chegam à API. Cachear respostas em memória, Redis ou SQLite com TTL adequado reduz significativamente o consumo. Indicadores fundamentalistas mudam apenas com a publicação de novos balanços, então um TTL de 12 a 24 horas é suficiente. Cotação intradiária aceita TTLs de cinco a quinze minutos sem perda relevante de precisão.

O servidor MCP usa quotas separadas?

Não. O servidor MCP usa a mesma chave de API e o mesmo limite diário. Cada tool call que o Claude ou Cursor dispara conta como uma requisição. Em fluxos conversacionais típicos, cada turno consome de uma a quatro chamadas dependendo do prompt. Quem usa MCP intensivamente costuma chegar ao limite mais rápido que com integrações batch e tende a migrar para o plano Pro antes do que projetos puramente programáticos. Detalhes em agente de IA com Claude e MCP.

Próximos passos

A api gratuita ações brasileiras da bolsai foi desenhada para que projetos pessoais comecem hoje, sem cartão de crédito, sem trial limitado a 7 dias, sem fricção de cadastro. Cinquenta ativos numa planilha diária custam 50 requisições. Dez alertas no Telegram com quatro checagens custam 40. Um screener acadêmico semanal cabe em menos de 100. O limite de 200 req/dia foi calibrado para esses cenários: o desenvolvedor que quer prototipar uma ideia, o estudante que precisa de dados para o TCC, o investidor pessoa física que monta sua planilha pessoal.

Quando o projeto cresce, o plano Pro a R$49/mês cobre o salto de duas ordens de grandeza no consumo. Mas começar não exige nem isso. O cadastro é feito com login Google, a chave aparece no painel em segundos, e a documentação cobre todos os endpoints com exemplos prontos.

Leia também

Este conteúdo é informativo e voltado a desenvolvedores. Não constitui recomendação de investimento. Os exemplos de carteira, alertas e cenários de uso são ilustrativos. Limites e preços vigentes em maio de 2026 estão sujeitos a alteração; a fonte oficial é a página de preços. A bolsai consolida dados públicos de B3, CVM e BCB e não emite parecer sobre a qualidade dos ativos mencionados.