Selic, IPCA, CDI e IGP-M: séries macroeconômicas do BCB via API

Por que séries macro importam para fintechs e quants

O mercado financeiro brasileiro orbita em torno de meia dúzia de séries macro. Selic ancora o custo do dinheiro e funciona como taxa livre de risco padrão. CDI rege a renda fixa privada, já que CDBs, LCIs, LCAs e fundos DI são contratualmente referenciados nele. IPCA é a inflação oficial e aparece em títulos públicos atrelados ao índice, contratos longos e indexação de aluguéis quando o IGP-M sai de cena. IGP-M historicamente reajustou contratos de aluguel, energia regulada e franquias. TR aparece em poupança, financiamento imobiliário pelo SFH e FGTS. Cada uma resolve um problema específico, e misturá-las gera erros caros.

A fonte primária oficial é o Sistema Gerenciador de Séries Temporais (SGS) do Banco Central do Brasil, que cataloga mais de 30 mil séries identificadas por código numérico. O SGS é gratuito e abrangente, mas tem peculiaridades documentadas adiante. Quem opera em produção costuma intermediar a fonte por uma camada estável, e é exatamente o papel do endpoint /macro da bolsai.

Selic meta vs Selic efetiva: a confusão clássica

A Selic é a taxa básica de juros da economia, mas existe em duas formas distintas que muito desenvolvedor mistura. A Selic meta é o alvo de política monetária definido pelo Comitê de Política Monetária (COPOM) em reuniões a cada 45 dias, vigente até a próxima decisão. A Selic efetiva é a média ponderada das taxas das operações compromissadas de um dia, lastreadas em títulos públicos, apurada e divulgada diariamente pelo BCB. Em regra, a efetiva oscila 0,10 ponto percentual abaixo da meta por conta do desenho dos leilões.

• Selic meta (SGS 432, anualizada base 252): use para mostrar a taxa de referência ao usuário final, em comunicados de política monetária e como taxa livre de risco em modelos de longo prazo.
• Selic efetiva (SGS 11, taxa diária): use para acumular rentabilidade dia útil a dia útil, capitalizar contratos, calcular juros de mora e medir o desempenho de fundos atrelados à Selic over.

Confundir as duas séries gera divergência típica de 5 a 10 pontos-base na taxa anualizada. Em uma carteira de R$10 milhões investidos a 100% do CDI, isso representa R$5.000 a R$10.000 por ano de diferença na projeção. A API da bolsai expõe as duas séries em endpoints separados, eliminando o risco de mistura acidental.

CDI, IPCA, IGP-M e TR: o que cada uma mede

A tabela abaixo resume as séries mais consumidas pelo mercado, com o código SGS correspondente, frequência e uso típico em produtos financeiros. Os três primeiros endpoints estão disponíveis nativamente na API da bolsai; IGP-M e TR ainda passam pelo SGS direto, conforme detalhado mais adiante.

CDI e Selic over caminham juntas, separadas tipicamente por 0,10 ponto percentual, e isso é estrutural. Um banco que precisa fechar a posição de caixa pode tomar dinheiro de outro banco no mercado interbancário (taxa CDI) ou recorrer ao mercado aberto, dando títulos públicos como lastro (taxa Selic). A arbitragem mantém as duas próximas. IPCA mede preços ao consumidor pelo IBGE, com cesta de 13 grupos e divulgação mensal. IGP-M, divulgado pela FGV, pesa atacado, consumidor e construção civil, sendo mais volátil que o IPCA e historicamente correlacionado com o câmbio. TR é uma taxa residual com fórmula complexa, derivada das TBF dos CDBs de grandes bancos, e em ambiente de juro alto fica próxima de zero por força da redutora.

Acessando as séries via API da bolsai

O endpoint /macro/{series_name} aceita os parâmetros start, end e limit e devolve um objeto JSON com o nome da série, o código SGS e o array de pontos ordenado por data. O contrato é uniforme entre séries, o que simplifica funções de fetch genéricas. Para baixar a Selic efetiva diária dos últimos 12 meses em Python:

import requests
import pandas as pd
from datetime import date, timedelta

API_KEY = "sk_sua_chave_aqui"
BASE = "https://api.usebolsai.com/api/v1"
HEADERS = {"X-API-Key": API_KEY}

def fetch_series(name, start=None, end=None, limit=5000):
    params = {"limit": limit}
    if start: params["start"] = start
    if end: params["end"] = end
    r = requests.get(f"{BASE}/macro/{name}", params=params, headers=HEADERS, timeout=15)
    r.raise_for_status()
    df = pd.DataFrame(r.json()["data"])
    df["date"] = pd.to_datetime(df["date"])
    return df.sort_values("date").set_index("date")["value"]

start = (date.today() - timedelta(days=365)).isoformat()
selic = fetch_series("selic", start=start)
cdi = fetch_series("cdi", start=start)
ipca = fetch_series("ipca", start=start)

print(f"Selic efetiva (último): {selic.iloc[-1]:.4f}% a.d.")
print(f"CDI (último):           {cdi.iloc[-1]:.4f}% a.d.")
print(f"IPCA (mês mais recente): {ipca.iloc[-1]:.2f}% a.m.")

Os valores de Selic e CDI saem em base diária. Para anualizar com convenção 252 dias úteis, aplica-se (1 + taxa_diaria/100) ** 252 − 1. Em maio de 2026, com Selic over de 0,0459% ao dia, a taxa anualizada equivalente fica em torno de 12,15%, próxima da meta vigente de 12,25%. IPCA já vem mensal e acumula-se pelo produto dos fatores: (1 + ipca_mensal/100).prod() − 1.

IGP-M e TR: enquanto não estão no /macro

IGP-M e TR ainda não fazem parte do catálogo nativo do endpoint /macro, mas estão no roadmap. Enquanto isso, a alternativa é o próprio SGS do BCB, que devolve as séries em JSON pelo endpoint público em api.bcb.gov.br/dados/serie/bcdata.sgs.{codigo}/dados. O exemplo abaixo busca IGP-M (SGS 189) e TR (SGS 226) diretamente, normaliza o formato e mantém a mesma estrutura de DataFrame usada para as demais séries.

import requests
import pandas as pd

SGS_BASE = "https://api.bcb.gov.br/dados/serie/bcdata.sgs"

def fetch_sgs(codigo, ultimos=36):
    url = f"{SGS_BASE}.{codigo}/dados/ultimos/{ultimos}?formato=json"
    r = requests.get(url, timeout=15)
    r.raise_for_status()
    df = pd.DataFrame(r.json())
    df["data"] = pd.to_datetime(df["data"], format="%d/%m/%Y")
    df["valor"] = df["valor"].astype(float)
    return df.sort_values("data").set_index("data")["valor"]

igpm = fetch_sgs(189, ultimos=12)   # IGP-M mensal
tr = fetch_sgs(226, ultimos=12)     # TR diária

igpm_12m = (1 + igpm/100).prod() - 1
print(f"IGP-M acumulado 12m: {igpm_12m*100:.2f}%")
print(f"TR média 12m: {tr.mean():.4f}% a.d.")

A função fetch_sgs trata as duas armadilhas mais comuns do SGS bruto: data no formato dd/MM/yyyy e valor como string. Para janelas mais longas que 10 anos, o SGS retorna HTTP 500 sem mensagem estruturada, e é preciso fatiar o range manualmente. O cliente acaba implementando paginação, retry com backoff e validação de schema, replicando o trabalho que a camada /macro da bolsai já entrega. A inclusão nativa de IGP-M e TR está prevista no roadmap conforme volume de demanda dos usuários Pro.

Caso de uso 1: rentabilidade histórica de CDB pós-fixado (X% do CDI)

CDBs pós-fixados são contratados como percentual do CDI, tipicamente entre 90% (grandes bancos) e 120% (bancos médios e digitais). A rentabilidade bruta de R$1,00 investido entre duas datas é o produto dos fatores diários do CDI, multiplicados pelo percentual contratado. O exemplo abaixo calcula a rentabilidade acumulada de R$10.000 aplicados em três CDBs hipotéticos (95%, 105% e 115% do CDI) ao longo dos últimos 36 meses, com IR de 17,5% sobre o rendimento no resgate.

import requests
import pandas as pd
from datetime import date, timedelta

API_KEY = "sk_sua_chave_aqui"
BASE = "https://api.usebolsai.com/api/v1"
HEADERS = {"X-API-Key": API_KEY}

start = (date.today() - timedelta(days=365*3)).isoformat()
r = requests.get(
    f"{BASE}/macro/cdi",
    params={"start": start, "limit": 5000},
    headers=HEADERS, timeout=15,
)
cdi = pd.DataFrame(r.json()["data"])
cdi["date"] = pd.to_datetime(cdi["date"])
cdi = cdi.sort_values("date").set_index("date")["value"] / 100

CAPITAL = 10000
IR = 0.175  # prazo entre 181 e 720 dias = 17,5%

def simular(percentual):
    fator_diario = 1 + cdi * percentual
    acumulado = fator_diario.cumprod()
    bruto_final = CAPITAL * acumulado.iloc[-1]
    rendimento = bruto_final - CAPITAL
    liquido_final = CAPITAL + rendimento * (1 - IR)
    retorno_anual = (liquido_final / CAPITAL) ** (1/3) - 1
    return bruto_final, liquido_final, retorno_anual

for pct in [0.95, 1.05, 1.15]:
    bruto, liquido, anual = simular(pct)
    print(f"CDB {pct*100:.0f}%CDI  bruto=R${bruto:>9,.2f}  liq=R${liquido:>9,.2f}  retorno a.a.={anual*100:.2f}%")

O cálculo capitaliza dia útil a dia útil usando a série efetiva do CDI, exatamente como o banco emissor faz quando paga o resgate. Cada ponto percentual extra de CDI rende, em três anos, cerca de R$200 a R$400 líquidos em capital de R$10.000, o que justifica buscar emissores menores quando o risco de crédito é coberto pelo FGC (R$250 mil por CPF por instituição). A mesma lógica vale para um backtest de produto: o post sobre backtest de ações em Python usa CDI como taxa livre de risco para calcular Sharpe e Sortino, e o endpoint /macro/cdi é a base canônica para isso.

Caso de uso 2: IPCA acumulado vs inflação implícita

A inflação implícita é a inflação esperada pelo mercado, extraída da diferença entre a taxa pré-fixada (NTN-F ou LTN) e a taxa real (NTN-B) de prazo equivalente. A fórmula correta usa a equação de Fisher: implícita = (1 + taxa_pré) / (1 + taxa_real) − 1. Comparar essa implícita com o IPCA acumulado nos últimos 12 meses revela o gap entre expectativa de mercado e inflação realizada, sinalizando se a curva está cara ou barata em termos de proteção inflacionária.

import requests
import pandas as pd
from datetime import date, timedelta

API_KEY = "sk_sua_chave_aqui"
BASE = "https://api.usebolsai.com/api/v1"
HEADERS = {"X-API-Key": API_KEY}

# 1. IPCA acumulado 12m via API
start = (date.today() - timedelta(days=400)).isoformat()
r = requests.get(f"{BASE}/macro/ipca", params={"start": start, "limit": 24}, headers=HEADERS)
ipca = pd.DataFrame(r.json()["data"])
ipca["value"] = ipca["value"].astype(float) / 100
ipca_12m = (1 + ipca.tail(12)["value"]).prod() - 1

# 2. Inflação implícita: pré 5 anos vs NTN-B 5 anos (taxas do dia)
#    Em produção, busca-se de uma fonte de curva (Anbima, B3 Tesouro Direto).
#    Aqui usamos valores ilustrativos do fechamento de mai/2026.
taxa_pre_5a = 0.1325     # NTN-F 2031, 13,25% a.a.
taxa_real_5a = 0.0680    # NTN-B 2031, IPCA + 6,80%

implicita_5a = (1 + taxa_pre_5a) / (1 + taxa_real_5a) - 1

print(f"IPCA acumulado 12m:      {ipca_12m*100:.2f}%")
print(f"Implícita pré/NTN-B 5a:  {implicita_5a*100:.2f}%")
print(f"Gap (implícita - IPCA):  {(implicita_5a - ipca_12m)*100:+.2f} pp")

Implícita acima do IPCA corrente, como no exemplo, sugere que o mercado precifica expectativa de aceleração da inflação ou prêmio de risco inflacionário relevante na curva. Quando a implícita fica abaixo do IPCA acumulado, o sinal típico é desinflação esperada (ou prêmio de juro real elevado). A leitura combinada com a meta do COPOM e os relatórios trimestrais de inflação do BCB compõe um termômetro útil para alocação entre NTN-B e LTN. O Relatório de Inflação trimestral traz a projeção oficial.

Direto do BCB SGS vs API da bolsai

Toda série citada está disponível gratuitamente no SGS do BCB. A pergunta legítima é: vale a pena usar uma camada intermediária? Para um script ad hoc, scraping pontual ou consulta manual, a resposta é não: basta chamar o SGS diretamente. Para produto em produção, a conta muda. O SGS tem comportamentos peculiares que viram dívida técnica em projetos que dependem dele:

• Datas em dd/MM/yyyy e valores com vírgula decimal, exigindo parse customizado para cada série.
• Limite informal de aproximadamente 10 anos por requisição, devolvendo HTTP 500 sem mensagem estruturada quando excedido.
• Ausência de paginação. Janelas longas exigem fatiar o range manualmente e concatenar respostas.
• Manutenções noturnas e janelas de feriado bancário com resposta 503 ou HTML estático, causando falha silenciosa em cron jobs.
• Certificado SSL e cadeia de intermediários já foram reemitidos sem aviso, derrubando clientes com bundles de CA desatualizados.
• Séries identificadas só por código numérico. Memorizar 432, 11, 433, 12, 189 e 226 (entre milhares de outras) é fonte recorrente de bug.

A camada /macro da bolsai resolve esses pontos com um contrato REST estável: nomes legíveis (selic, cdi, ipca), datas em ISO 8601, valores como float, paginação implícita até 5000 pontos, cache Redis de 5 minutos e SLA contratual. O plano gratuito (200 reqs/dia) cobre o uso de protótipo; o plano Pro (10 mil reqs/dia, R$29/mês) sustenta a operação de uma fintech média sem necessidade de cache local. A comparação de APIs gratuitas para a B3 detalha o ecossistema e os tradeoffs.

Para integração mais ampla, a mesma chave API libera as séries macro e os endpoints de ações, fundamentos, dividendos e FIIs. Quem está construindo um comparador de renda fixa pode, na mesma chamada, buscar CDI atual e o último dividend yield de FIIs comparáveis pela tabela de Dividend Yield via API. A documentação completa fica em /docs.

Perguntas frequentes

Qual a diferença entre Selic meta e Selic efetiva?

A Selic meta é o alvo de política monetária definido pelo COPOM a cada 45 dias. A Selic efetiva é a média ponderada das operações compromissadas de um dia, lastreadas em títulos públicos, apurada diariamente. Em regra, a efetiva oscila 0,10 ponto percentual abaixo da meta. Pela API da bolsai, GET /macro/selic_target retorna a meta (SGS 432) e GET /macro/selic retorna a efetiva diária (SGS 11).

Por que o CDI é a referência da renda fixa privada?

O CDI (Certificado de Depósito Interbancário) é a taxa média das operações de empréstimo entre bancos com prazo de um dia, calculada pela B3. Como reflete o custo real de funding dos bancos, virou benchmark padrão para CDBs, LCIs, LCAs, debêntures e fundos DI. CDBs pós-fixados costumam ser ofertados como percentual do CDI, por exemplo 100% ou 110% do CDI.

IGP-M e TR estão disponíveis na API da bolsai?

Ainda não. As séries nativamente expostas são Selic meta (SGS 432), Selic efetiva (SGS 11), IPCA (SGS 433), CDI (SGS 12) e dólar PTAX (SGS 1). IGP-M (SGS 189) e TR (SGS 226) podem ser consumidos diretamente do BCB SGS enquanto não fazem parte do catálogo nativo, com a inclusão prevista no roadmap conforme demanda.

Por que usar a API da bolsai se o BCB SGS é gratuito?

O BCB SGS é a fonte primária e funciona bem para scripts pontuais. Em produção surgem dores recorrentes: limite informal de 10 anos por requisição, ausência de paginação, datas no formato dd/MM/yyyy, valores com vírgula decimal, falhas em janelas de manutenção e instabilidade em feriados. A API da bolsai normaliza formato, gerencia janelas longas, mantém cache de 5 minutos e fornece uptime previsível, removendo a necessidade de wrapper customizado.

Como calcular a inflação implícita em Python?

A inflação implícita é a diferença entre a taxa pré de um título público pré-fixado (LTN ou NTN-F) e a taxa real de uma NTN-B de prazo equivalente. A fórmula correta usa a equação de Fisher: implícita = (1 + taxa_pré) / (1 + taxa_real) − 1. Comparar essa implícita com o IPCA acumulado em 12 meses, obtido via GET /macro/ipca, revela se o mercado precifica inflação acima ou abaixo do realizado, sinal útil para gestão de carteira de renda fixa.

Próximos passos

Acessar séries do BCB via API REST normalizada elimina três classes de dívida técnica: parse de formato, gestão de janelas longas e tolerância a instabilidade da fonte primária. As cinco séries cobertas neste guia (Selic meta, Selic efetiva, CDI, IPCA, IGP-M e TR) dão conta de calculadoras de renda fixa, comparadores de produto, dashboards econômicos e modelos de valuation. Quem precisa também de dados de ações encontra na mesma chave API os endpoints fundamentalistas descritos no guia de alternativas ao Fundamentus e o screener de ações brasileiras.

Leia também

Conteúdo educativo, não constitui recomendação de investimento. Dados macroeconômicos referenciados em maio de 2026; taxas e séries SGS estão sujeitas a atualização e correção pelo Banco Central. Decisões de alocação dependem de objetivo, horizonte e tolerância a risco do investidor.