Vamos encarar os fatos: suas posições já estão perfeitamente registradas no seu ledger. São os preços que mantêm você preso num ciclo de redigitação sem fim.
Essa assimetria é a tarefa mais antiga e mais frustrante da contabilidade em texto puro. Você registra uma compra uma única vez, e ela fica gravada em pedra para sempre: 120 NWRB {41.80 USD, 2024-03-12} trava permanentemente uma quantidade, um custo e uma data. Nada do que acontece depois altera esses fatos. Um preço, no entanto, é exatamente o oposto — ele está correto por exatamente um dia e depois silenciosamente se torna errado. Pior ainda, ele está errado de um jeito que nenhuma verificação de saldo jamais vai detectar, porque um ledger com preços desatualizados ainda fecha perfeitamente.
Historicamente, a forma Beancount de lidar com isso tem sido buscar preços com um script e fazer commit do resultado. Funciona, e muita gente automatizou isso. Mas, no fim do dia, ainda é um script que você precisa vigiar, um cron job que você mantém e um arquivo que você vive fazendo merge.
Chega disso. Para ledgers hospedados no beancount.io, nosso motor agora lida com essa resolução nativamente. Este post cobre exatamente o que acabou de ser lançado, o que deliberadamente evitamos tocar e — igualmente importante — o que ainda não construímos.
O Que Foi Lançado
Um ledger hospedado no beancount.io agora pode carregar uma diretiva include que aponta para uma URL em vez de um nome de arquivo local:
; main.bean, in a hosted beancount.io ledger.
;
; This page is Portuguese, so the quote currency is EUR. On another language of
; this site, use the currency in the list under the fence.
option "title" "Taxable brokerage"
option "operating_currency" "EUR"
; Only the hosted engine resolves the URL form, and upstream `include` takes a
; file glob — so the line is shown commented out here and this file still
; loads if you copy it to your own machine. Uncomment it in a hosted ledger.
; include "https://beancount.io/prices/AAPL-EUR"Atenção: Você precisará fazer login antes de acessar essa URL. Requisições anônimas redirecionam para a página de login. Esta página está em português, então o exemplo cota euros — a moeda em que os leitores daqui costumam manter seus livros. Depois de autenticado, abra https://beancount.io/prices/AAPL-EUR e confirme que você está vendo diretivas price padrão. Então adicione essa linha ao seu ledger hospedado.
Se você lê outro idioma, use a moeda usual daquele idioma, e somente quando o catálogo a listar como cotação:
- English:
USD, https://beancount.io/prices/AAPL-USD - 中文:
CNY, https://beancount.io/prices/AAPL-CNY. Essa URL não é um par listado. É o fechamento não ajustado deAAPL-USDda Databento, cruzado com oUSD-CNYdo BCE. - 日本語:
JPY, https://beancount.io/prices/AAPL-JPY - 한국어:
KRW, https://beancount.io/prices/AAPL-KRW - Deutsch, Français, Español, Italiano, Nederlands, Català, Português, Slovenčina, and Български:
EUR, https://beancount.io/prices/AAPL-EUR. Livros em búlgaro abertos neste ano estão em euros; o catálogo também cotaBGNcaso um arquivo mais antigo ainda use essa moeda. - فارسی, Русский, and Українська: o catálogo não tem
IRR,RUBouUAH, então não há par para abrir. Escolha uma cotação que ele liste.
O catálogo em https://beancount.io/prices/ fica atrás desse mesmo login. O próprio AAPL-USD é uma cotação direta da Databento, não um cruzamento. Outras ações tier-1 funcionam da mesma forma — troque o ticker, mantenha a moeda de cotação para o seu idioma. ACME-USD retorna um 404.
O include do Beancount upstream tecnicamente espera um nome de arquivo, então um include de URL é um comportamento estritamente do motor hospedado. Ele nunca finge ser Beancount puro. Aqui está exatamente o que nosso motor faz por baixo dos panos:
- Ele materializa o feed como um arquivo virtual somente leitura. A URL é resolvida pelo próprio caminho de resolução de include do motor — aterrissando exatamente onde um arquivo local teria aterrissado — então toda diretiva mantém uma localização de origem real. Seus bytes originais nunca são reescritos. O arquivo que você escreveu continua sendo o arquivo que você escreveu.
- Validação estrita do payload. O corpo buscado é validado como somente preços. Permitimos estritamente diretivas
price, comentários e quatro chaves de metadados específicas (price-source,price-kind,observed-ateprovisional). Qualquer outra coisa rejeita o corpo inteiro. Não há ingestão parcial, o que significa que um feed desonesto nunca pode contrabandear uma transação para dentro dos seus livros. - Cache inteligente. Feeds são armazenados em cache como uma revisão imutável com um ponteiro móvel. Os ciclos de atualização são conduzidos por timestamps em vez de expiração de cache, garantindo que uma indisponibilidade upstream não apague sua última revisão boa.
- Frescor auditável. O frescor é calculado dinamicamente quando o ledger é lido (recente, desatualizado ou indisponível) ao lado do horário de observação reportado pelo feed. Um preço que você não consegue datar é um preço que você não consegue auditar.
- Estritamente somente leitura. Entradas gerenciadas não podem ser editadas ou excluídas (tentar fazer isso lança um erro nomeando a origem). Além disso, elas não contam contra seus limites de diretivas — não deixamos feeds consumirem o orçamento do seu ledger.
Nada disso muda o que uma diretiva de preço significa fundamentalmente no Beancount. O único trabalho do motor é colocar preços corretos, datados e atribuíveis na frente do loader.
Seu Próprio Preço Sempre Prevalece
Este é o divisor de águas para qualquer um que leva seu ledger a sério, então vamos ser cristalinos:
Para a mesma data e o mesmo par de commodities (incluindo seu recíproco), um preço que você mesmo escreveu sempre prevalece sobre o feed gerenciado.
Não "geralmente", e não "só se você colocar seu include por último". Essa decisão de sombreamento acontece antes de o mapa de preços ser construído, o que significa que é completamente independente de onde o include está posicionado no seu arquivo. Coloque no topo, coloque no final, ou divida em três arquivos — seu preço escrito à mão sempre prevalece.
A regra do recíproco é fácil de passar despercebida, mas vital. Um feed de AAPL-USD é um preço de AAPL em USD. Se você escreveu à mão um preço no sentido inverso — USD em AAPL, mesma data — sua entrada ainda vence o feed. O mesmo vale para qualquer cotação que você incluiu, seja CNY ou JPY.
Por que essa regra? Porque um preço no seu próprio arquivo é uma decisão consciente. Pode ser o fechamento exato que seu corretor imprimiu num extrato que você está reconciliando, uma cotação contemporânea para um ativo de baixa liquidez, ou um valor específico que seu contador exigiu. Um feed não conhece seu contexto. Um sistema que silenciosamente sobrescreve um número escrito por um humano deixa de ser um ledger e passa a ser uma opinião. O feed está lá para preencher lacunas; ele não corrige você.
Preços Alteram a Avaliação, e Nada Mais
Esta próxima garantia é estrutural em vez de uma escolha de política, e é melhor mostrada com números reais. Dê uma olhada no nosso ledger de exemplo de cripto, com lotes datados, staking, posições DeFi e airdrops:
Vamos extrair uma entrada específica. Um airdrop de token de governança chega e é registrado como receita a valor justo de mercado no dia em que cai:
2024-03-20 * "Uniswap" "Receive UNI governance token airdrop"
Assets:Crypto:Wallet:MetaMask:UNI 50.00 UNI {12.50 USD, 2024-03-20}
Income:Crypto:Airdrops -625.00 USD
Esses $625,00 de receita, e a base de $12,50 por unidade atrelada ao lote, agora são fatos imutáveis sobre 2024-03-20. Toda diretiva de preço no ledger — seja gerenciada, escrita à mão ou totalmente ausente — deixa ambos intactos.
Preços mudam o valor de mercado; eles nunca alteram quantidades, base de custo, fluxos de caixa, taxas ou ganhos realizados. É exatamente por isso que um feed de preços é uma ferramenta segura para se apoiar: o pior absoluto que um preço ruim pode fazer é declarar temporariamente de forma errada quanto uma posição vale hoje. Ele nunca pode corromper os números duros que você vai colocar na sua declaração de imposto.
Onde um Modelo de Preço Errado Realmente te Engana
O ledger de exemplo de ações e ETFs ilustra a versão mais afiada desse mesmo ponto:
Ele contém um desdobramento de ações de 4 para 1, registrado da forma correta — como uma mudança de quantidade que preserva a base total sem tocar em nenhuma conta de resultado:
2025-07-15 * "Broker" "NWRB 4-for-1 share split — quantity change, not income"
Assets:Brokerage:NWRB -120 NWRB {41.80 USD, 2024-03-12}
Assets:Brokerage:NWRB 480 NWRB {10.45 USD, 2024-03-12}
Ambos os lados equivalem a $5.016,00. O valor de mercado permanece inalterado ao longo do desdobramento ($7.440,00 de qualquer forma), e a data de aquisição entre chaves sobrevive — que é o que mantém uma venda dessas ações em 2026 classificada como de longo prazo.
A armadilha comum é registrar um desdobramento como um evento de preço em vez disso, apoiando-se fortemente numa série de preços "ajustada por desdobramento" para fazer a matemática fechar. Isso só funciona enquanto todo preço que você jamais olhar tiver sido ajustado exatamente da mesma forma. No momento em que um valor não ajustado chega ao seu ledger — um recibo antigo de confirmação, um screenshot, ou um feed de terceiros que não reexpressa dados históricos — a posição é de repente avaliada em quatro vezes seu valor real. Pior ainda, a contagem de ações no ledger não corresponde mais ao extrato do seu corretor, o que significa que suas verificações de saldo de fim de ano vão falhar silenciosamente.
Este é o argumento real para depender de um feed de preços com uma origem declarada, um tipo declarado e um horário de observação visível. Não é só sobre conveniência; é sobre saber exatamente qual convenção matemática seus números importados estão usando.
(Uma nota rápida sobre os embeds: o visualizador de ledger hospedado renderiza saldos de contas a custo e atualmente não oferece controles de avaliação na página. Os ledgers acima servem para mostrar a mecânica subjacente — os lotes, o desdobramento, as vendas. Ambos são públicos, e você pode cloná-los e executá-los localmente.)
O Que Ainda Não Está Aqui
Acreditamos que um changelog é pior que inútil se ele promete demais. Então aqui está a verdade sem retoques sobre o que ainda não construímos, sem prazos anexados:
- Autenticação é obrigatória. Requisições anônimas para
https://beancount.io/prices/<ALIAS>vão te jogar numa página de login. - Sem suporte a CLI local. A CLI local
bealê arquivos do disco, o que significa que um include de URL vai falhar localmente como um glob de arquivo não correspondido. Adicionar suporte ao loader na CLI está no nosso roadmap. - Sem superfície de API. Atualmente não temos nenhum campo REST, GraphQL ou MCP para preços gerenciados.
- Sem dashboard de UI. Ainda não há tela de "conectar-um-feed" e nenhum rótulo de frescor na UI. (Os dados de frescor que nosso motor calcula atualmente não têm onde ser exibidos).
- Sem snapshots, exportações ou endpoints de atualização manual.
O que lançamos hoje é estritamente a camada do motor: resolução de include, validação, cache de revisão, regras de precedência e cálculo de frescor. É a infraestrutura fundamental sobre a qual todo o resto precisa se apoiar, que é exatamente por isso que a construímos primeiro.
Onde Olhar a Seguir
Ambos os ledgers incorporados acima fazem parte da nossa galeria de exemplos — seis padrões totalmente trabalhados que você pode clonar e executar localmente. (Ambos intencionalmente vêm com arquivos de preços estáticos, versionados, garantindo que um clone feito daqui a dois anos produza exatamente o mesmo relatório que produz hoje). Todo o resto que lançamos cai diretamente no nosso changelog.
Se você está perfeitamente feliz mantendo os preços atualizados com seu próprio fetcher, continue com ele. Ele continua sendo a melhor resposta para um ledger estritamente local. A própria documentação de busca de preços do Beancount e a ferramenta mantida beanprice são os melhores lugares para começar.
Mantenha a Parte Chata Chata
Vale a pena automatizar preços precisamente porque eles são a única parte de um ledger em texto puro que apodrece com o tempo. O Beancount.io é construído para te dar contabilidade em texto puro que permanece sua — auditável, versionada e nunca reescrita pelas suas costas. Esse era o padrão de base que um feed gerenciado tinha que atender antes de estarmos dispostos a lançá-lo.
Comece gratuitamente, e mantenha seus livros em arquivos que você realmente pode ler.
