Els llibres allotjats ara resolen els preus gestionats inclosos

Acceptem-ho: les teves participacions ja estan perfectament registrades al teu llibre. Són els preus els que et mantenen atrapat en un cicle de retranscripció infinita.

Aquesta asimetria és la tasca més antiga i frustrant de la comptabilitat en text pla. Escrius una compra una vegada, i queda fixada per sempre: 120 NWRB {41.80 USD, 2024-03-12} bloqueja permanentment una quantitat, un cost i una data. Res del que passi després canvia aquests fets. Un preu, en canvi, és exactament el contrari: és correcte durant exactament un dia, i després es torna incorrecte en silenci. Pitjor encara, és incorrecte d'una manera que cap comprovació de saldo atraparà mai, perquè un llibre amb preus desactualitzats encara quadra perfectament.

Històricament, la manera de Beancount de gestionar això ha estat obtenir preus amb un script i fer commit de la sortida. Funciona, i molta gent ho ha automatitzat. Però al capdavall, segueix sent un script que has de vigilar, una tasca cron que mantens i un fitxer que fusiones constantment.

S'ha acabat. Per als llibres allotjats a beancount.io, el nostre motor ara gestiona aquesta resolució de manera nativa. Aquest article cobreix exactament què s'acaba de publicar, què hem evitat deliberadament tocar i — igual d'important — què encara no hem construït.

Què s'ha publicat​

Un llibre allotjat de beancount.io ara pot portar una directiva include que apunti a una URL en lloc d'un nom de fitxer local:

; main.bean, in a hosted beancount.io ledger.
;
; This page is Catalan, 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"

Atenció: Haureu d'iniciar sessió abans d'accedir a aquesta URL. Les sol·licituds anònimes redirigeixen a la pàgina d'inici de sessió. Aquesta pàgina és en català, així que l'exemple cotitza en euros — la divisa en què els lectors d'aquí solen portar els llibres més sovint. Un cop autenticat, obre https://beancount.io/prices/AAPL-EUR i confirma que estàs veient directives price estàndard. Aleshores afegeix aquesta línia al teu llibre allotjat.

Si llegeixes una altra llengua, fes servir la divisa habitual d'aquesta llengua, i només quan el catàleg la llisti com a cotització:

• English: USD, https://beancount.io/prices/AAPL-USD
• 中文: CNY, https://beancount.io/prices/AAPL-CNY. Aquesta URL no és un parell llistat. És el tancament no ajustat d'AAPL-USD de Databento, creuat amb l'USD-CNY del 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 i Български: EUR, https://beancount.io/prices/AAPL-EUR. Els llibres búlgars oberts aquest any són en euros; el catàleg també cotitza BGN si un fitxer més antic encara el fa servir.
• فارسی, Русский i Українська: el catàleg no té IRR, RUB ni UAH, així que no hi ha cap parell per obrir. Trieu una cotització que sí que llisti.

El catàleg a https://beancount.io/prices/ també és darrere d'aquest mateix inici de sessió. AAPL-USD en si és una cotització directa de Databento, no un creuament. Altres accions de nivell 1 funcionen de la mateixa manera — canvia el tíquer, mantén la divisa de cotització per a la teva llengua. ACME-USD retorna un 404.

L'include de Beancount upstream tècnicament espera un nom de fitxer, així que una inclusió d'URL és un comportament estricte del motor allotjat. Mai pretén ser Beancount pur. Aquí tens exactament què fa el nostre motor per sota:

• 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 — aterrant exactament on ho faria un fitxer local — de manera que cada directiva conserva una ubicació d'origen real. Els teus bytes originals mai es reescriuen. El fitxer que vas escriure continua sent el fitxer que vas escriure.
• Validació estricta de la càrrega útil. El cos obtingut es valida com a només preus. Permetem estrictament directives price, comentaris i quatre claus de metadades específiques (price-source, price-kind, observed-at i provisional). Qualsevol altra cosa rebutja el cos sencer. No hi ha ingesta parcial, el que significa que un feed maliciós mai pot introduir de contraban una transacció als teus llibres.
• Memòria cau intel·ligent. Els feeds es guarden a la memòria cau com una revisió immutable amb un punter mòbil. Els cicles d'actualització es regeixen per marques de temps en lloc de per la caducitat de la memòria cau, assegurant que una interrupció del proveïdor no esborri la teva última revisió bona.
• Frescor auditable. El frescor es calcula dinàmicament quan es llegeix el llibre (recent, obsolet o no disponible) juntament amb l'hora d'observació reportada pel feed. Un preu que no pots datar és un preu que no pots auditar.
• Estrictament de només lectura. Les entrades gestionades no es poden editar ni eliminar (intentar-ho llança un error que anomena la font). A més, no compten per als teus límits de directives — no deixem que els feeds es mengin el pressupost del teu llibre.

Res d'això canvia què significa fonamentalment una directiva de preus a Beancount. L'única feina del motor és posar preus correctes, datats i atribuïbles davant del carregador.

El teu propi preu sempre guanya​

Aquest és el punt decisiu per a qualsevol que es prengui seriosament el seu llibre, així que siguem cristal·lins:

Per a la mateixa data i el mateix parell de commodities (incloent-hi el seu recíproc), un preu que hagis escrit tu mateix sempre guanya sobre el feed gestionat.

No "normalment", i no "només si poses el teu include al final". Aquesta decisió d'ombra es pren abans que es construeixi el mapa de preus, el que significa que és completament independent d'on se situa l'include al teu fitxer. Posa'l a dalt, posa'l a baix, o divideix-lo entre tres fitxers — el teu preu escrit a mà sempre guanya.

La regla recíproca és fàcil de passar per alt però vital. Un feed d'AAPL-USD és un preu d'AAPL en USD. Si has escrit a mà un preu a l'inrevés — USD en AAPL, mateixa data — la teva entrada encara guanya sobre el feed. El mateix és cert per a qualsevol cotització que hagis inclòs, CNY o JPY incloses.

Per què aquesta regla? Perquè un preu al teu propi fitxer és una decisió conscient. Pot ser el tancament exacte que el teu corredor va imprimir en un extracte que estàs conciliant, una cotització contemporània per a un actiu poc negociat, o una xifra específica que el teu comptable va exigir. Un feed no coneix el teu context. Un sistema que sobreescriu silenciosament una xifra escrita per un humà deixa de ser un llibre i es converteix en una opinió. El feed hi és per omplir buits; no et corregeix.

Els preus mouen la valoració, i res més​

Aquesta següent garantia és estructural més que una elecció de política, i es mostra millor amb xifres reals. Fes una ullada al nostre llibre d'exemple de cripto, amb lots datats, staking, posicions DeFi i airdrops:

Agafem una entrada concreta. Arriba un airdrop de token de governança i es registra com a ingrés a 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 USD
 

Aquests 625,00 $ d'ingrés, i la base de 12,50 $ per unitat adjunta al lot, són ara fets immutables sobre el 2024-03-20. Cada directiva de preus al llibre — ja sigui gestionada, escrita a mà o completament absent — deixa ambdós intactes.

Els preus canvien el valor de mercat; mai alteren quantitats, base de cost, fluxos d'efectiu, comissions o guanys realitzats. Això és exactament per què un feed de preus és una eina segura en què recolzar-se: el pitjor absolut que pot fer un preu dolent és declarar temporalment de manera errònia quant val una posició avui. Mai pot corrompre les xifres dures que posaràs a la teva declaració d'impostos.

On un model de preus equivocat realment et desorienta​

El llibre d'exemple d'accions i ETF il·lustra la versió més nítida d'aquest mateix punt:

Conté un desdoblament d'accions 4-per-1, registrat 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}
 

Tots dos costats sumen 5.016,00 $. El valor de mercat roman inalterat a través del desdoblament (7.440,00 $ en qualsevol cas), i la data d'adquisició entre claus sobreviu — que és el que manté una venda d'aquestes accions el 2026 classificada com a llarg termini.

La trampa habitual és registrar un desdoblament com un esdeveniment de preus en lloc d'això, recolzant-se fortament en una sèrie de preus "ajustada pel desdoblament" per fer que les matemàtiques quadrin. Això només funciona mentre cada preu que mai miris hagi estat ajustat exactament de la mateixa manera. En el moment que una xifra no ajustada arriba al teu llibre — un rebut de confirmació antic, una captura de pantalla o un feed de tercers que no reexpressa els històrics — la posició es valora de sobte a quatre vegades el seu valor real. Pitjor encara, el recompte d'accions al llibre ja no coincideix amb l'extracte del teu corredor, el que significa que les teves afirmacions de saldo de final d'any fallaran silenciosament.

Aquest és l'argument real per confiar en un feed de preus amb una font declarada, un tipus declarat i una hora d'observació visible. No és només una qüestió de conveniència; és qüestió de saber exactament quina convenció matemàtica fan servir els teus números importats.

(Una nota ràpida sobre les incrustacions: el visualitzador de llibres allotjats mostra els saldos dels comptes a cost i actualment no ofereix controls de valoració a la pàgina. Els llibres de dalt volen mostrar la mecànica subjacent — els lots, el desdoblament, les vendes. Tots dos són públics, i pots clonar-los i executar-los localment.)

Què no hi és encara​

Creiem que un changelog és pitjor que inútil si promet massa. Així que aquí tens la veritat sense embellir sobre què no hem construït encara, sense terminis adjunts:

• L'autenticació és obligatòria. Les sol·licituds anònimes a https://beancount.io/prices/<ALIAS> et rebotaran a una pàgina d'inici de sessió.
• Sense suport per a CLI local. La CLI local bea llegeix fitxers del disc, el que significa que una inclusió d'URL fallarà localment com un glob de fitxer no coincident. Afegir suport de carregador a la CLI és a la nostra fulla de ruta.
• Sense superfície d'API. Actualment no tenim cap camp REST, GraphQL o MCP per als preus gestionats.
• Sense tauler d'interface d'usuari. Encara no hi ha cap pantalla de "connecta-un-feed" ni cap etiqueta de frescor a la interfície. (Les dades de frescor que calcula el nostre motor actualment no tenen on mostrar-se).
• Sense instantànies, exportacions ni endpoints d'actualització manual.

El que hem publicat avui és estrictament la capa del motor: resolució d'inclusions, validació, memòria cau de revisions, regles de precedència i càlcul de frescor. És la infraestructura fonamental sobre la qual ha de reposar tota la resta, que és exactament per què la vam construir primer.

On mirar a continuació​

Tots dos llibres incrustats més amunt formen part de la nostra galeria d'exemples — sis patrons completament desenvolupats que pots clonar i executar localment. (Tots dos s'envien intencionadament amb fitxers de preus estàtics i versionats, assegurant que un clon fet d'aquí a dos anys produeixi exactament el mateix informe que avui). Tota la resta que publiquem aterra directament al nostre changelog.

Si estàs perfectament content mantenint els preus actualitzats amb el teu propi obtenidor, continua així. Segueix sent la millor resposta per a un llibre estrictament local. La pròpia documentació d'obtenció de preus de Beancount i l'eina mantinguda beanprice són els millors llocs per començar.

Mantén la part avorrida avorrida​

Els preus val la pena automatitzar-los precisament perquè són l'única part d'un llibre en text pla que es fa malbé amb el temps. Beancount.io està construït per donar-te comptabilitat en text pla que continua sent teva — auditable, controlada per versions i mai reescrita a la teva esquena. Aquest era l'estàndard de referència que un feed gestionat havia de complir abans que estiguéssim disposats a publicar-lo.

Comença gratis, i mantén els teus llibres en fitxers que realment puguis llegir.