Les teves participacions ja són al llibre. Els seus preus són la part que no deixes de reescriure.
Aquesta asimetria és la feina més antiga de la comptabilitat en text pla. Una compra s'escriu una vegada i és certa per sempre: 120 NWRB {41.80 USD, 2024-03-12} registra una quantitat, un cost i una data, i res del que passi després canvia cap dels tres. Un preu és el contrari — correcte durant un dia, després silenciosament incorrecte, i incorrecte d'una manera que cap comprovació de saldo atraparà mai, perquè un preu obsolet encara quadra perfectament. La resposta pròpia de Beancount sempre ha estat obtenir-los amb una eina i fer commit de la sortida, cosa que funciona i que molta gent ha automatitzat. Encara és un script que és teu, una entrada de cron que mantens i un fitxer que fusiones.
El motor de llibres de beancount.io ara fa aquesta resolució ell mateix, per als llibres allotjats amb nosaltres. Aquest article tracta sobre què s'ha publicat realment, què no toca deliberadament i — igual d'important — què encara no s'ha construït.
Què s'ha publicat
Un llibre allotjat de beancount.io pot portar una inclusió el destí de la qual és una URL en lloc d'un nom de fitxer:
; 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"L'include del Beancount original pren un nom de fitxer — "el camí especificat pot ser un nom de fitxer absolut o relatiu" és tota l'especificació — així que una inclusió d'URL no és Beancount pur i mai pretén ser-ho. És un comportament del motor allotjat, i aquí tens exactament què fa el motor amb això:
- Materialitza el feed com un fitxer virtual de només lectura. La URL es resol a través del propi camí de resolució d'inclusions del motor, exactament on hauria anat a parar un fitxer local, de manera que cada directiva conserva una ubicació d'origen real. Els teus bytes mai es reescriuen. El fitxer que vas escriure continua sent el fitxer que vas escriure.
- El cos obtingut es valida com a només preus. Directives
price, comentaris i quatre claus de metadades permeses —price-source,price-kind,observed-atiprovisional— i res més. Qualsevol cosa més enllà d'això rebutja el cos sencer. No hi ha ingesta parcial, així que un feed mai pot colar una transacció als teus llibres. - Els feeds es cachegen com una revisió immutable més un punter mòbil. L'actualització es dirigeix per una marca de temps en lloc de per l'expiració de la caché, cosa que significa que una interrupció del proveïdor no es pot endur la teva última revisió bona. Una actualització fallida mai substitueix una revisió bona per res.
- La frescor es calcula quan es llegeix el llibre, no s'emmagatzema:
recent,staleounavailable, juntament amb el temps d'observació que el propi feed ha reportat. Un preu que no pots datar és un preu que no pots auditar. - Les entrades gestionades són de només lectura. Editar-ne o eliminar-ne una es rebutja amb un error que nomena la font gestionada, i no compten contra els límits de directives — no es permet que el feed consumeixi el pressupost del teu llibre.
Tot el que hi ha en aquesta llista s'executa dins del servei de llibres allotjats. Res d'això canvia què significa una directiva price: encara estableix la taxa de canvi entre una mercaderia base i una mercaderia de cotització, exactament com ho defineix la referència del llenguatge. La feina del motor és només posar davant del carregador preus correctes, datats i atribuïbles.
El teu propi preu sempre guanya
Aquesta és la part que decideix si un feed és utilitzable per algú que es pren seriosament el seu llibre, així que s'enuncia exactament.
Per a la mateixa data i el mateix parell de mercaderies — i per al parell recíproc — un preu que hagis escrit tu mateix guanya sobre el feed gestionat, independentment de l'ordre d'inclusió.
No "normalment", i no "si poses la teva inclusió al final". La decisió d'ombrejat es pren abans que es construeixi el mapa de preus, així que no depèn d'on es troba la inclusió al fitxer. Mou-la a dalt, mou-la a baix, divideix-la entre tres fitxers: la resposta és la mateixa.
; 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 és l'emissor fictici del llibre d'exemple més avall; el número és inventat, no una observació de mercat.)
Per què aquesta regla i no l'altra: un preu al teu propi fitxer és una decisió. Pot ser el tancament que el teu broker va imprimir a l'extracte contra el qual estàs conciliant, una cotització contemporània per a una posició poc negociada, o una xifra que el teu comptable et va demanar que utilitzessis. Un feed no sap res de tot això, i un sistema que sobreescriu silenciosament una xifra escrita per un humà ha deixat de ser un llibre i ha començat a ser una opinió. El feed omple buits; no et corregeix.
Els preus mouen la valoració, i res més
La segona tranquil·litat és estructural més que una elecció de política, i val la pena mostrar-la amb números reals en lloc d'afirmar-la. Aquí tens el llibre d'exemple de criptomonedes — lots datats, staking, mineria, posicions DeFi, airdrops:
Pren una entrada d'aquí. Arriba un airdrop de token de governança i es registra com a ingrés al valor de mercat raonable el dia que aterra:
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 USDAquests $625.00 d'ingrés, i la base de $12.50 per unitat adjunta al lot, són ara fets sobre el 2024-03-20. Cada directiva de preu del llibre — gestionada, escrita a mà o completament absent — deixa ambdós intactes. Els preus canvien el valor de mercat; mai canvien quantitats, base de cost, fluxos d'efectiu, comissions o guanys realitzats. Que és per què un feed de preus és una cosa segura d'acceptar ajuda: el pitjor que pot fer un preu incorrecte és informar malament quant val una posició avui, i mai pot corrompre el número que posaràs en una declaració d'impostos.
On un model de preus incorrecte et desorienta realment
El llibre d'exemple d'accions i ETF mostra la versió més punyent del mateix punt:
Conté un desdoblament d'accions 4-per-1, i el desdoblament es registra de la manera correcta — com un canvi de quantitat que preserva la base total, sense tocar cap compte d'ingressos:
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}Els dos costats són $5,016.00. El valor de mercat no canvia amb el desdoblament — 120 accions a $62.00 el dia abans, 480 accions a $15.50 el dia després, $7,440.00 en tots dos casos — i la data d'adquisició entre claus sobreviu, que és el que manté a llarg termini una venda d'aquestes accions el 2026.
L'error comú és registrar un desdoblament com un esdeveniment de preu i recolzar-se en una sèrie "ajustada pel desdoblament" perquè la valoració surti correcta. Això funciona només mentre cada preu que vegis mai hagi estat ajustat de la mateixa manera. En el moment que arriba una xifra no ajustada — una confirmació antiga, una captura de pantalla, una sèrie de tercers que no reexpressa res — la posició es valora al quadruple del seu valor, i el recompte d'accions del llibre ja no coincideix amb l'extracte del broker, així que l'asserció de fi d'any que ho hauria atrapat no es pot activar.
Aquest és l'argument real a favor d'un feed de preus amb una font declarada, un tipus declarat i un temps d'observació visible: no la conveniència, sinó saber sota quina convenció s'ha calculat el número que acabes d'importar. El propi fitxer de preus del llibre d'exemple és deliberadament no ajustat i ho diu, i les seves dues directives que travessen el desdoblament estan escrites com una comprovació que pots verificar a ull.
Una nota honesta sobre fer clic a qualsevol dels dos incrustats: el visor de llibres allotjats mostra els saldos dels comptes a cost, i no ofereix cap control de valoració a la pàgina. Els llibres de dalt hi són per mostrar-te els llibres — els lots, el desdoblament, les vendes de lots específics — no una valoració de mercat que el visor actualment no dibuixa. Tots dos són públics, i tots dos es poden clonar i executar localment.
Què encara no hi és
Una entrada de changelog val menys que res si et deixa creure una cosa que no és certa, així que aquí tens l'altra meitat, clarament i sense cap data adjunta a res d'això.
- L'endpoint de preus no és públic. Una petició anònima a
https://beancount.io/prices/<ALIAS>es redirigeix a la pàgina d'inici de sessió. No hi ha cap catàleg públic d'àlies. - Així que això no és una cosa que puguis enganxar al teu propi fitxer avui. El motor resol la inclusió; la ruta que resol encara no és oberta. Quan ho sigui, això serà la seva pròpia entrada de changelog.
- La CLI local
beano resol inclusions d'URL. Llegeix fitxers del disc, així que una inclusió d'URL falla localment com un glob de fitxers que no coincideix amb cap fitxer. El suport del carregador a la CLI és un seguiment nomenat. - No hi ha superfície d'API. Cap camp REST, GraphQL o MCP per a preus gestionats.
- No hi ha superfície de tauler. Cap pantalla de connecta-un-feed i cap etiqueta de frescor a la interfície; la frescor que calcula el motor encara no té on mostrar-se.
- Les instantànies i l'exportació no estan construïdes, i tampoc ho està un catàleg d'instruments ni un endpoint d'actualització manual.
El que s'ha publicat és la capa del motor: la resolució d'inclusions, la validació, la caché de revisions, la regla de precedència i el càlcul de frescor. Aquesta és la part sobre la qual ha de sostenir-se tota la resta, i és la part més difícil de canviar després, que és per què va anar primer.
On mirar a continuació
Tots dos llibres de dalt formen part de la galeria d'exemples, sis patrons treballats que pots clonar i executar localment — tots dos envien fitxers de preus estàtics i versionats deliberadament, així que un clon fet d'aquí a dos anys encara produeix l'informe que produeix avui. Tota la resta que publiquem aterra al changelog.
Si encara mantens els preus actualitzats amb un obtenidor propi, aquesta continua sent la resposta correcta per a un llibre local, i la pròpia documentació d'obtenció de preus de Beancount més l'eina mantinguda beanprice són on començar.
Mantén la part avorrida avorrida
La raó per la qual els preus val la pena automatitzar-los és que són l'única part d'un llibre en text pla que es degrada per si sola. Beancount.io et dona comptabilitat en text pla que continua sent teva — auditable, controlada per versions i mai reescrita a la teva esquena, que és exactament l'estàndard que un feed gestionat havia de complir abans que publiquem un. Comença gratis i mantén els teus llibres en fitxers que pots llegir.
