Gehoste Ledgers Verwerken Nu Beheerde Prijs-Includes

Je posities staan al in het grootboek. Hun prijzen zijn het deel dat je blijft overtypen.

Die asymmetrie is het oudste karwei in plain-text accounting. Een aankoop wordt één keer opgeschreven en is voor altijd waar: 120 NWRB {41.80 USD, 2024-03-12} legt een hoeveelheid, een kostprijs en een datum vast, en niets wat daarna gebeurt verandert ook maar één van die drie. Een prijs is het tegenovergestelde — één dag correct, daarna stilletjes fout, en fout op een manier die geen enkele balanscontrole ooit zal opmerken, want een verouderde prijs balanceert nog steeds perfect. Beancounts eigen antwoord is altijd geweest om ze met een tool op te halen en de output te committen, wat werkt en wat velen hebben geautomatiseerd. Het blijft een script dat je bezit, een cron-regel die je onderhoudt, en een bestand dat je merget.

De beancount.io ledger engine doet die resolutie nu zelf, voor grootboeken die bij ons gehost worden. Deze post gaat over wat er daadwerkelijk is uitgeleverd, wat het bewust niet aanraakt, en — net zo belangrijk — wat er nog niet is gebouwd.

Wat er is uitgeleverd​

Een gehost beancount.io-grootboek kan een include bevatten waarvan het doel een URL is in plaats van een bestandsnaam:

; main.bean, in een gehost beancount.io-grootboek.
;
; De beheerde regel staat met opzet uitgecommentarieerd: upstream `include` neemt een
; bestandsglob, dus dit bestand laadt nog steeds als je het naar je eigen machine kopieert.
; Alleen de gehoste engine verwerkt de URL-vorm.
 
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"

Upstream Beancounts include neemt een bestandsnaam — "the specified path can be an absolute or a relative filename" is de volledige specificatie — dus een URL-include is geen gewone Beancount en doet ook nooit alsof. Het is een gedrag van de gehoste engine, en dit is precies wat de engine ermee doet:

• Het materialiseert de feed als een alleen-lezen virtueel bestand. De URL wordt opgelost via het eigen include-resolutiepad van de engine, precies waar een lokaal bestand zou zijn terechtgekomen, zodat elke directive een echte bronlocatie behoudt. Je bytes worden nooit herschreven. Het bestand dat je schreef blijft het bestand dat je schreef.
• De opgehaalde inhoud wordt gevalideerd als uitsluitend prijzen. price-directives, commentaar, en vier toegestane metadata-sleutels — price-source, price-kind, observed-at en provisional — en niets anders. Alles daarbuiten verwerpt de hele inhoud. Er is geen gedeeltelijke inname, dus een feed kan nooit een transactie in je boeken smokkelen.
• Feeds worden gecached als een onveranderlijke revisie plus een bewegende pointer. Verversen wordt gestuurd door een tijdstempel in plaats van door cache-verval, wat betekent dat een storing upstream je laatste goede revisie niet kan meenemen. Een mislukte verversing vervangt een goede revisie nooit door niets.
• Versheid wordt berekend wanneer het grootboek wordt gelezen, niet opgeslagen: recent, stale, of unavailable, naast de observatietijd die de feed zelf rapporteerde. Een prijs die je niet kunt dateren is een prijs die je niet kunt auditen.
• Beheerde regels zijn alleen-lezen. Bewerken of verwijderen wordt geweigerd met een fout die de beheerde bron noemt, en ze tellen niet mee voor directive-limieten — de feed mag niet het budget van je grootboek opeten.

Alles in die lijst draait binnen de gehoste ledger-service. Niets ervan verandert wat een price-directive betekent: die stelt nog steeds de wisselkoers vast tussen een basiscommodity en een quotecommodity, precies zoals de taalreferentie het definieert. De taak van de engine is alleen om correcte, gedateerde, toerekenbare prijzen vóór de loader te zetten.

Je eigen prijs wint altijd​

Dit is het deel dat bepaalt of een feed bruikbaar is voor iemand die zijn grootboek serieus neemt, dus het wordt exact gesteld.

Voor dezelfde datum en hetzelfde commodity-paar — en voor het omgekeerde paar — wint een prijs die je zelf hebt geschreven over de beheerde feed, ongeacht de volgorde van de include.

Niet "meestal", en niet "als je je include achteraan zet". De shadowing-beslissing wordt genomen voordat de prijsmap wordt opgebouwd, dus het hangt niet af van waar de include in het bestand staat. Zet hem bovenaan, zet hem onderaan, splits hem over drie bestanden: het antwoord is hetzelfde.

; include "https://beancount.io/prices/ACME-USD"   ; gehoste-engine-vorm, opnieuw uitgecommentarieerd
 
; Een prijs die je zelf hebt geschreven, voor dezelfde datum en hetzelfde paar.
; Deze wint — boven de include of eronder, het maakt geen verschil.
2026-09-16 price ACME 93.40 USD

(ACME is de fictieve emittent uit het voorbeeldgrootboek verderop; het getal is verzonnen, geen marktobservatie.)

Waarom die regel en niet de andere: een prijs in je eigen bestand is een beslissing. Het kan de slotkoers zijn die je broker afdrukte op het overzicht waartegen je afstemt, een gelijktijdige quote voor een dun verhandelde positie, of een cijfer dat je accountant je vroeg te gebruiken. Een feed weet niets van dat alles, en een systeem dat stilletjes een door een mens opgesteld cijfer overschrijft, is opgehouden een grootboek te zijn en een mening geworden. De feed vult gaten op; hij corrigeert je niet.

Prijzen beïnvloeden de waardering, en niets anders​

De tweede geruststelling is structureel in plaats van een beleidskeuze, en het is de moeite waard om met echte cijfers te tonen in plaats van te beweren. Hier is het crypto-voorbeeldgrootboek — gedateerde lots, staking, mining, DeFi-posities, airdrops:

Neem één regel eruit. Een governance-token-airdrop komt binnen en wordt geboekt als inkomen tegen fair market value op de dag dat hij landt:

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

Die $625,00 aan inkomen, en de basis van $12,50 per eenheid die aan het lot hangt, zijn nu feiten over 2024-03-20. Elke price-directive in het grootboek — beheerd, handgeschreven, of volledig ontbrekend — laat beide ongemoeid. Prijzen veranderen de marktwaarde; ze veranderen nooit hoeveelheden, kostprijsbasis, kasstromen, kosten of gerealiseerde winsten. Daarom is een prijsfeed überhaupt een veilig iets om hulp bij te accepteren: het slechtste wat een verkeerde prijs kan doen is verkeerd rapporteren wat een positie vandaag waard is, en hij kan nooit het cijfer corrumperen dat je op een belastingaangifte zet.

Waar een verkeerd prijsmodel je echt misleidt​

Het aandelen- en ETF-voorbeeldgrootboek maakt de scherpere versie van hetzelfde punt:

Het bevat een 4-op-1 aandelensplitsing, en de splitsing wordt op de juiste manier geboekt — als een hoeveelheidswijziging die de totale basis behoudt, zonder een inkomstenrekening aan te raken:

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}

Beide kanten zijn $5.016,00. De marktwaarde is ongewijzigd over de splitsing — 120 aandelen tegen $62,00 de dag ervoor, 480 aandelen tegen $15,50 de dag erna, $7.440,00 hoe dan ook — en de acquisitiedatum tussen de accolades overleeft, wat een verkoop van die aandelen in 2026 langdurig houdt.

De veelgemaakte fout is om een splitsing te boeken als een prijs-gebeurtenis en te leunen op een "splitsingsgecorrigeerde" reeks om de waardering kloppend te maken. Dat werkt alleen zolang elke prijs die je ooit ziet op dezelfde manier is gecorrigeerd. Op het moment dat een niet-gecorrigeerd cijfer opduikt — een oude bevestiging, een screenshot, een reeks van een derde partij die niets herziet — wordt de positie gewaardeerd op vier keer zijn waarde, en het aandelenaantal in het grootboek komt niet meer overeen met het overzicht van de broker, dus de eindejaarsassertie die het zou hebben opgemerkt, kan niet afgaan.

Dit is het echte argument voor een prijsfeed met een verklaarde bron, een verklaard soort, en een zichtbare observatietijd: niet gemak, maar weten onder welke conventie het cijfer dat je net importeerde is berekend. Het prijsbestand van het voorbeeldgrootboek is bewust niet-gecorrigeerd en zegt dat ook, en de twee directives die de splitsing overspannen zijn geschreven als een controle die je met het blote oog kunt verifiëren.

Eén eerlijke opmerking over het klikken in een van beide embeds: de gehoste grootboekviewer toont rekeningbalansen tegen kostprijs, en biedt geen waarderingsknop op de pagina. De grootboeken hierboven staan er om je de grootboeken te tonen — de lots, de splitsing, de specifieke-lot-verkopen — niet een marktwaardering die de viewer momenteel niet tekent. Beide zijn openbaar, en beide kunnen gekloond en lokaal gedraaid worden.

Wat hier nog niet is​

Een changelog-item is minder dan niets waard als het je iets laat geloven dat niet waar is, dus hier is de andere helft, helder en zonder datum ergens aan te hangen.

• Het prijs-eindpunt is niet openbaar. Een anoniem verzoek aan https://beancount.io/prices/<ALIAS> wordt doorgestuurd naar de inlogpagina. Er is geen openbare alias-catalogus.
• Dus dit is niet iets dat je vandaag in je eigen bestand kunt plakken. De engine verwerkt de include; de route die hij verwerkt is nog niet open. Wanneer dat wel zo is, wordt dat een eigen changelog-item.
• De lokale bea CLI verwerkt geen URL-includes. Het leest bestanden van schijf, dus een URL-include faalt lokaal als een bestandsglob die geen bestanden vindt. Loader-ondersteuning in de CLI is een benoemde vervolgstap.
• Er is geen API-oppervlak. Geen REST-, GraphQL- of MCP-veld voor beheerde prijzen.
• Er is geen dashboard-oppervlak. Geen verbind-een-feed-scherm en geen versheidslabel in de UI; de versheid die de engine berekent heeft nog nergens om te worden weergegeven.
• Snapshots en export zijn niet gebouwd, en een instrumentencatalogus of een handmatig verversingseindpunt evenmin.

Wat is uitgeleverd is de engine-laag: de include-resolutie, de validatie, de revisie-cache, de voorrangsregel en de versheidsberekening. Dat is het deel waarop al het andere moet staan, en het is het deel dat het moeilijkst later te veranderen is, en daarom ging het eerst.

Waar je verder moet kijken​

Beide grootboeken hierboven maken deel uit van de voorbeeldgalerij, zes uitgewerkte patronen die je kunt klonen en lokaal kunt draaien — beide leveren met opzet statische, ingecheckte prijsbestanden mee, zodat een kloon die over twee jaar wordt gemaakt nog steeds het rapport oplevert dat hij vandaag oplevert. Al het andere dat we uitleveren verschijnt op de changelog.

Als je je prijzen nog steeds actueel houdt met een eigen fetcher, blijft dat het juiste antwoord voor een lokaal grootboek, en Beancounts eigen documentatie over het ophalen van prijzen plus de onderhouden beanprice-tool zijn waar je moet beginnen.

Houd het saaie deel saai​

De reden dat prijzen het automatiseren waard zijn, is dat ze het enige deel van een plain-text grootboek zijn dat vanzelf vervalt. Beancount.io geeft je plain-text accounting die van jou blijft — auditeerbaar, onder versiebeheer, en nooit achter je rug om herschreven, precies de standaard waaraan een beheerde feed moest voldoen voordat we er een zouden uitleveren. Begin gratis en houd je boeken in bestanden die je kunt lezen.