Seus ativos já estão no ledger. Seus preços são a parte que você fica redigitando.
Essa assimetria é a tarefa mais antiga da contabilidade em texto puro. Uma compra é escrita uma vez e permanece verdadeira para sempre: 120 NWRB {41.80 USD, 2024-03-12} registra uma quantidade, um custo e uma data, e nada que aconteça depois altera nenhum dos três. Um preço é o oposto — correto por um dia, depois silenciosamente errado, e errado de uma forma que nenhuma verificação de saldo jamais vai capturar, porque um preço desatualizado ainda balanceia perfeitamente. A resposta do próprio Beancount sempre foi buscá-los com uma ferramenta e commitar a saída, o que funciona e o que muitas pessoas já automatizaram. Ainda é um script que você mantém, uma entrada de cron que você cuida e um arquivo que você faz merge.
A ledger engine do beancount.io agora faz essa resolução sozinha, para ledgers hospedados conosco. Este post é sobre o que de fato foi entregue, o que ela deliberadamente não toca e — igualmente importante — o que ainda não está construído.
O que foi entregue
Um ledger beancount.io hospedado pode carregar um include cujo alvo é uma URL em vez de um nome de arquivo:
; main.bean, in a hosted beancount.io ledger.
;
; The managed line is shown commented out on purpose: upstream `include` takes a
; file glob, so this file still loads if you copy it to your own machine. Only
; the hosted engine resolves the URL form.
option "title" "Taxable brokerage"
option "operating_currency" "USD"
include "accounts.bean"
; include "https://beancount.io/prices/ACME-USD"
include "transactions/purchases.bean"
include "transactions/sales.bean"O include do Beancount upstream aceita um nome de arquivo — "o caminho especificado pode ser um nome de arquivo absoluto ou relativo" é toda a especificação — então um include de URL não é Beancount puro e nunca finge ser. É um comportamento da engine hospedada, e aqui está precisamente o que a engine faz com ele:
- Ela materializa o feed como um arquivo virtual somente leitura. A URL resolve através do próprio caminho de resolução de includes da engine, exatamente onde um arquivo local teria caído, então cada diretiva mantém uma localização de origem real. Seus bytes nunca são reescritos. O arquivo que você escreveu permanece o arquivo que você escreveu.
- O corpo buscado é validado como somente preços. Diretivas
price, comentários e quatro chaves de metadados permitidas —price-source,price-kind,observed-ateprovisional— e nada mais. Qualquer coisa além disso rejeita o corpo inteiro. Não há ingestão parcial, então um feed nunca pode contrabandear uma transação para dentro dos seus livros. - Feeds são cacheados como uma revisão imutável mais um ponteiro móvel. A atualização é guiada por um timestamp em vez de por expiração de cache, o que significa que uma indisponibilidade upstream não pode levar junto sua última revisão boa. Uma atualização falha nunca substitui uma revisão boa por nada.
- A atualidade é calculada quando o ledger é lido, não armazenada:
recent,staleouunavailable, junto com o horário de observação que o próprio feed reportou. Um preço que você não consegue datar é um preço que você não consegue auditar. - Entradas gerenciadas são somente leitura. Editar ou excluir uma delas é recusado com um erro que nomeia a fonte gerenciada, e elas não contam contra limites de diretivas — o feed não tem permissão para consumir o orçamento do seu ledger.
Tudo nessa lista roda dentro do serviço de ledger hospedado. Nada disso muda o que uma diretiva price significa: ela ainda estabelece a taxa de câmbio entre uma commodity base e uma commodity de cotação, exatamente como a referência da linguagem a define. O trabalho da engine é apenas colocar preços corretos, datados e atribuíveis diante do loader.
Seu próprio preço sempre prevalece
Esta é a parte que decide se um feed é utilizável por alguém que leva seu ledger a sério, então ela é declarada com exatidão.
Para a mesma data e o mesmo par de commodities — e para o par recíproco — um preço que você mesmo escreveu prevalece sobre o feed gerenciado, independentemente da ordem do include.
Não "geralmente", e não "se você colocar seu include por último". A decisão de sombreamento é tomada antes que o mapa de preços seja construído, então não depende de onde o include está no arquivo. Mova-o para o topo, mova-o para o fim, divida-o entre três arquivos: a resposta é a mesma.
; include "https://beancount.io/prices/ACME-USD" ; hosted-engine form, again shown commented
; A price you wrote yourself, for the same date and pair.
; This one wins — above the include or below it, it makes no difference.
2026-09-16 price ACME 93.40 USD(ACME é o emissor fictício do ledger de exemplo mais abaixo; o número é inventado, não uma observação de mercado.)
Por que essa regra e não a outra: um preço no seu próprio arquivo é uma decisão. Pode ser o fechamento que seu corretor imprimiu no extrato com o qual você está reconciliando, uma cotação contemporânea para uma posição de baixa liquidez, ou um valor que seu contador pediu que você usasse. Um feed não sabe nada disso, e um sistema que sobrescreve silenciosamente um valor escrito por um humano deixou de ser um ledger e passou a ser uma opinião. O feed preenche lacunas; ele não corrige você.
Preços movem a avaliação, e nada mais
A segunda garantia é estrutural em vez de uma escolha de política, e vale a pena mostrá-la com números reais em vez de afirmá-la. Aqui está o ledger de exemplo de cripto — lotes datados, staking, mineração, posições DeFi, airdrops:
Pegue uma entrada dele. Um airdrop de token de governança chega e é registrado como receita pelo 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 USDEsses $625,00 de receita, e a base de $12,50 por unidade atrelada ao lote, agora são fatos sobre 2024-03-20. Todas as diretivas de preço no ledger — gerenciadas, escritas à mão, ou totalmente ausentes — deixam ambos intactos. Preços mudam o valor de mercado; eles nunca mudam quantidades, base de custo, fluxos de caixa, taxas ou ganhos realizados. É por isso que um feed de preços é uma coisa segura de se aceitar ajuda em primeiro lugar: o pior que um preço errado pode fazer é reportar incorretamente quanto vale uma posição hoje, e ele nunca pode corromper o número que você vai colocar na declaração de imposto.
Onde um modelo de preço errado realmente te engana
O ledger de exemplo de ações e ETFs apresenta a versão mais afiada do mesmo ponto:
Ele contém um desdobramento de ações de 4 para 1, e o desdobramento é registrado da forma correta — como uma mudança de quantidade que preserva a base total, sem tocar em nenhuma conta de receita:
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 são $5.016,00. O valor de mercado não muda ao longo do desdobramento — 120 ações a $62,00 no dia anterior, 480 ações a $15,50 no dia seguinte, $7.440,00 de qualquer forma — e a data de aquisição entre chaves sobrevive, o que é o que mantém uma venda de 2026 dessas ações como de longo prazo.
O erro comum é registrar um desdobramento como um evento de preço em vez disso e se apoiar em uma série "ajustada por desdobramento" para fazer a avaliação sair certa. Isso funciona apenas enquanto todo preço que você jamais vê tiver sido ajustado da mesma forma. No momento em que um valor não ajustado chega — uma confirmação antiga, um print de tela, uma série de terceiros que não reexpressa nada — a posição é avaliada em quatro vezes o seu valor, e a contagem de ações no ledger não corresponde mais ao extrato do corretor, então a asserção de fim de ano que teria capturado isso não pode disparar.
Este é o verdadeiro argumento para um feed de preços com uma fonte declarada, um tipo declarado e um horário de observação visível: não conveniência, mas saber sob qual convenção o número que você acabou de importar foi calculado. O próprio arquivo de preços do ledger de exemplo é deliberadamente não ajustado e diz isso, e suas duas diretivas que cruzam o desdobramento são escritas como uma verificação que você pode conferir a olho.
Uma nota honesta sobre clicar em qualquer um dos embeds: o visualizador de ledger hospedado renderiza saldos de contas pelo custo, e não oferece nenhum controle de avaliação na página. Os ledgers acima estão lá para mostrar os ledgers — os lotes, o desdobramento, as vendas de lotes específicos — não uma avaliação de mercado que o visualizador atualmente não desenha. Ambos são públicos, e ambos podem ser clonados e executados localmente.
O que ainda não está aqui
Uma entrada de changelog vale menos que nada se ela deixa você acreditar em algo que não é verdade, então aqui está a outra metade, claramente e sem data atrelada a nada disso.
- O endpoint de preços não é público. Uma requisição anônima para
https://beancount.io/prices/<ALIAS>é redirecionada para a página de login. Não há catálogo público de aliases. - Então isto não é algo que você possa colar no seu próprio arquivo hoje. A engine resolve o include; a rota que ela resolve ainda não está aberta. Quando estiver, isso será sua própria entrada de changelog.
- A CLI local
beanão resolve includes de URL. Ela lê arquivos do disco, então um include de URL falha localmente como um glob de arquivo que não corresponde a nenhum arquivo. Suporte do loader na CLI é um follow-up nomeado. - Não há superfície de API. Nenhum campo REST, GraphQL ou MCP para preços gerenciados.
- Não há superfície de dashboard. Nenhuma tela de conectar um feed e nenhum rótulo de atualidade na UI; a atualidade que a engine calcula não tem onde ser exibida ainda.
- Snapshots e exportação não estão construídos, e nem um catálogo de instrumentos nem um endpoint de atualização manual.
O que foi entregue é a camada da engine: a resolução de include, a validação, o cache de revisões, a regra de precedência e o cálculo de atualidade. Essa é a parte sobre a qual todo o resto tem que se apoiar, e é a parte mais difícil de mudar depois, razão pela qual ela veio primeiro.
Onde olhar em seguida
Ambos os ledgers acima fazem parte da galeria de exemplos, seis padrões trabalhados que você pode clonar e executar localmente — esses dois trazem arquivos de preços estáticos e versionados de propósito, então um clone feito daqui a dois anos ainda produz o relatório que produz hoje. Todo o resto que entregamos aparece no changelog.
Se você ainda mantém preços atualizados com um buscador próprio, essa continua sendo a resposta certa para um ledger local, e a própria documentação de busca de preços do Beancount mais a ferramenta mantida beanprice são o ponto de partida.
Mantenha a parte chata chata
A razão pela qual preços valem a pena automatizar é que eles são a única parte de um ledger em texto puro que decai sozinha. O Beancount.io te dá contabilidade em texto puro que continua sendo sua — auditável, versionada e nunca reescrita pelas suas costas, que é exatamente o padrão que um feed gerenciado teve que atender antes de entregarmos um. Comece de graça e mantenha seus livros em arquivos que você pode ler.
