Pular para conteúdo

Tesouro — Finanças

O Tesouro Nacional brasileiro publica dois tipos muito diferentes de dados:

  • Microdados de renda fixa via Tesouro Direto — preços, yields, operações de compra/venda, estoques, investidores.
  • Agregados fiscais via Resultado do Tesouro Nacional (RTN) — receitas, despesas e resultado primário do Governo Federal.

O ecossistema cobre ambos com pacotes dedicados.

O desafio

Análise de Tesouro Direto encontra três barreiras críticas:

  • Volume e velocidade — arquivos diários com milhões de registros; Pandas estoura memória rapidamente.
  • Complexidade FIFO — calcular retornos para investidores com múltiplas compras e vendas parciais exige controle contábil estrito (matching FIFO de lotes com injeção de cupons).
  • Performance de portfólio — calcular retornos mensais com depósitos, saques e renda de cupom exige metodologia GIPS-compliant (Modified Dietz).

A planilha RTN apresenta outro desafio: 24 abas mensais/trimestrais/anuais em formato wide, com hierarquia de contas que precisa ser normalizada para análise.

Dois stacks: Exploração vs. Produção

Stack 1 — Exploração (tesouro-direto-fetcher SDK + Polars)

Para análise ad-hoc, notebooks Jupyter, modelagem de yield curve, análise de portfólio one-off. Use o downloader assíncrono + readers Polars + analytics direto.

graph LR
    A[CKAN Tesouro Nacional] --> B[tesouro_direto_fetcher.downloader<br/>async + idempotente]
    B --> C[CSVs locais]
    C --> D[tesouro_direto_fetcher.reader / analytics<br/>Polars]

Stack 2 — Produção (Pipeline tesouro-direto-fetcher + Parquet/PostgreSQL)

Para análise diária recorrente: scheduler chama tesouro-direto-fetcher download (idempotente via Last-Modified), converte CSVs para Parquet, persiste em PostgreSQL para consumo BI.

graph LR
    A[CKAN Tesouro] --> B[tesouro-direto-fetcher download<br/>scheduled]
    B --> C[CSVs Parquet]
    C --> D[(PostgreSQL)]
    D --> E[Power BI / Metabase]

Para dados fiscais (RTN), o fluxo é mais simples: rtn-fetcher baixa a planilha mais recente, normaliza para formato longo e exporta para Excel/SQLite.

Pacotes

  • tesouro-direto-fetcher — suíte de engenharia financeira: async fetching com idempotência, processamento Polars (10× vs. Pandas), matching FIFO de lotes com injeção de cupom, retornos Modified Dietz GIPS-compliant. Suporta LTN, NTN-B/F/C, LFT.
  • rtn-fetcher — downloader e normalizador da planilha RTN: 24 abas mensais/trimestrais/anuais (corrente / constante / % do PIB), normalização em formato longo com expansão de hierarquia de contas, CLI de exportação Excel/SQLite.
  • Cálculo de Retornos — guia matemático: YTM, duration, FIFO, Modified Dietz, retornos reais para títulos indexados à inflação.

Princípios em ação

  • Resiliência — tesouro_direto_fetcher.downloader verifica last_modified no CKAN antes de baixar, pulando arquivos atualizados; rtn-fetcher deduplica por timestamp.
  • Performance — async fetching paraleliza até max_concurrency recursos por dataset; readers Polars processam 15M linhas em 0.34s.
  • Reprodutibilidade — Modified Dietz pondera fluxos de caixa pelo timing dentro do mês, garantindo conformidade GIPS auditável; matching FIFO é determinístico (vendas associadas às compras mais antigas).
  • Sem Mágica — algoritmos complexos (FIFO, Modified Dietz) são documentados inline; cupons são injetados explicitamente como fluxo de caixa.

Receitas táticas em Padrões Práticos: Idempotência, Concorrência para I/O, Lazy evaluation.

Tipos de títulos do Tesouro Direto

Código Nome Características
LTN Letras do Tesouro Nacional Prefixados (cupom zero), curto prazo
NTN-B Notas do Tesouro Série B Indexados ao IPCA, cupons semestrais
NTN-F Notas do Tesouro Série F Prefixados com cupons, longo prazo
NTN-C Notas do Tesouro Série C Indexados ao IGP-M (legado)
LFT Letras Financeiras do Tesouro Atrelados à Selic, pós-fixados

Métricas disponíveis por título e data: yield (YTM), preço (% do par), duration modificada, vencimento, juros acumulados, volume em circulação.

Próximos passos

Recursos externos