Hosted Ledgers Verwerken Nu Beheerde Price Includes

Laten we eerlijk zijn: je posities zijn al perfect vastgelegd in je ledger. Het zijn de prijzen die je gevangen houden in een cyclus van eindeloos opnieuw intypen.

Die asymmetrie is het oudste, meest frustrerende klusje in plain-text accounting. Je schrijft een aankoop één keer op, en die staat voor altijd vast: 120 NWRB {41.80 USD, 2024-03-12} legt permanent een hoeveelheid, een kostprijs en een datum vast. Niets wat daarna gebeurt, verandert die feiten. Een prijs daarentegen is het tegenovergestelde—hij klopt precies één dag en wordt daarna stilletjes onjuist. Erger nog: hij is op een manier onjuist die geen enkele balanscontrole ooit zal opmerken, want een ledger met verouderde prijzen balanceert nog steeds perfect.

Historisch gezien was de Beancount-manier om hiermee om te gaan: prijzen ophalen met een script en de uitvoer committen. Het werkt, en veel mensen hebben dat geautomatiseerd. Maar uiteindelijk is het nog steeds een script waar je op moet passen, een cron job die je onderhoudt, en een bestand dat je voortdurend moet mergen.

Niet meer. Voor ledgers die gehost worden op beancount.io verwerkt onze engine dit nu native. Deze post behandelt precies wat er net is uitgebracht, wat we bewust niet hebben aangeraakt, en—net zo belangrijk—wat we nog niet hebben gebouwd.

Wat er is uitgebracht​

Een gehoste beancount.io ledger kan nu een include directive bevatten die naar een URL verwijst in plaats van naar een lokaal bestand:

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

Let op: je moet inloggen voordat je die URL bezoekt. Anonieme verzoeken worden doorgestuurd naar de inlogpagina. Deze pagina is Nederlandstalig, dus het voorbeeld quote in euro's — de valuta waarin lezers hier het vaakst hun boeken bijhouden. Zodra je bent geauthenticeerd, open je https://beancount.io/prices/AAPL-EUR en bevestig je dat je standaard price directives ziet. Voeg die regel dan toe aan je gehoste ledger.

Lees je in een andere taal, gebruik dan de gebruikelijke valuta van die taal, en alleen wanneer de catalogus die als quote vermeldt:

• English: USD, https://beancount.io/prices/AAPL-USD
• 中文: CNY, https://beancount.io/prices/AAPL-CNY. Die URL is geen vermeld paar. Het is Databento's niet-aangepaste AAPL-USD close, gekruist met de ECB's USD-CNY.
• 日本語: 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. Bulgaarse boeken die dit jaar zijn geopend, zijn in euro's; de catalogus vermeldt ook BGN als een ouder bestand die nog gebruikt.
• فارسی, Русский, and Українська: de catalogus heeft geen IRR, RUB of UAH, dus er is geen paar om te openen. Kies een quote die wel vermeld staat.

De catalogus op https://beancount.io/prices/ zit achter diezelfde login. AAPL-USD zelf is een directe Databento-quote, geen kruis. Andere tier-1 aandelen werken hetzelfde — verwissel de ticker, behoud de quote-valuta voor je taal. ACME-USD geeft een 404.

Upstream Beancount's include verwacht technisch gezien een bestandsnaam, dus een URL-include is strikt genomen gedrag van de gehoste engine. Het doet zich nooit voor als gewoon Beancount. Dit is precies wat onze engine onder de motorkap doet:

• Het materialiseert de feed als een read-only virtueel bestand. De URL wordt opgelost via het eigen include-resolutiepad van de engine—en landt precies waar een lokaal bestand zou zijn geland—zodat elke directive een echte bronlocatie behoudt. Je originele bytes worden nooit herschreven. Het bestand dat je schreef, blijft het bestand dat je schreef.
• Strikte payload-validatie. De opgehaalde inhoud wordt gevalideerd als price-only. We staan strikt price directives, commentaar en vier specifieke metadata-sleutels toe (price-source, price-kind, observed-at en provisional). Al het andere verwerpt de hele inhoud. Er is geen gedeeltelijke ingest, wat betekent dat een rogue feed nooit een transactie in je boeken kan smokkelen.
• Slimme caching. Feeds worden gecached als een onveranderlijke revisie met een bewegende pointer. Verversingscycli worden aangestuurd door tijdstempels in plaats van cache-expiratie, zodat een upstream-storing je laatste goede revisie niet wist.
• Auditeerbare versheid. Versheid wordt dynamisch berekend wanneer de ledger wordt gelezen (recent, verouderd of niet beschikbaar) samen met de door de feed gerapporteerde observatietijd. Een prijs die je niet kunt dateren, is een prijs die je niet kunt auditen.
• Strikt read-only. Beheerde entries kunnen niet worden bewerkt of verwijderd (een poging daartoe geeft een foutmelding met de bron erbij). Bovendien tellen ze niet mee voor je directive-limieten—we laten feeds niet het budget van je ledger opeten.

Niets hiervan verandert wat een price directive fundamenteel betekent in Beancount. De enige taak van de engine is om correcte, gedateerde en herleidbare prijzen vóór de loader te leggen.

Je eigen prijs wint altijd​

Dit is de dealbreaker voor iedereen die zijn ledger serieus neemt, dus laten we glashelder zijn:

Voor dezelfde datum en hetzelfde commodity-paar (inclusief het omgekeerde paar) wint een prijs die je zelf hebt geschreven altijd van de beheerde feed.

Niet "meestal", en niet "alleen als je je include als laatste zet". Deze shadowing-beslissing vindt plaats voordat de prijsmap wordt opgebouwd, wat betekent dat deze volledig onafhankelijk is van waar de include in je bestand staat. Zet hem bovenaan, zet hem onderaan, of splits hem over drie bestanden—je handgeschreven prijs wint altijd.

De omgekeerde regel is makkelijk te missen maar essentieel. Een feed van AAPL-USD is een prijs van AAPL in USD. Als je met de hand een prijs de andere kant op hebt geschreven — USD in AAPL, zelfde datum — dan wint jouw entry nog steeds van de feed. Hetzelfde geldt voor welke quote je ook hebt geïncludeerd, CNY of JPY inbegrepen.

Waarom deze regel? Omdat een prijs in je eigen bestand een bewuste keuze is. Het kan de exacte close zijn die je broker op een afschrift heeft gedrukt dat je aan het afstemmen bent, een gelijktijdige quote voor een dun verhandeld actief, of een specifiek cijfer dat je accountant eiste. Een feed kent je context niet. Een systeem dat stilletjes een door een mens geschreven cijfer overschrijft, houdt op een ledger te zijn en wordt een mening. De feed is er om gaten te vullen; hij corrigeert je niet.

Prijzen beïnvloeden waardering, en niets anders​

Deze volgende geruststelling is structureel in plaats van een beleidskeuze, en laat zich het beste tonen met echte cijfers. Bekijk onze crypto-voorbeeldledger, met gedateerde lots, staking, DeFi-posities en airdrops:

Laten we één specifieke entry eruit halen. Een governance-token-airdrop komt binnen en wordt geboekt als inkomen tegen fair market value op de dag dat deze 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 onveranderlijke feiten over 2024-03-20. Elke price directive in de ledger—of die nu beheerd, handgeschreven of volledig ontbrekend is—laat beide ongemoeid.

Prijzen veranderen marktwaarde; ze veranderen nooit hoeveelheden, kostprijs, kasstromen, kosten of gerealiseerde winsten. Dit is precies waarom een prijsfeed een veilig hulpmiddel is om op te leunen: het allerergste wat een slechte prijs kan doen, is tijdelijk onjuist weergeven wat een positie vandaag waard is. Het kan nooit de harde cijfers corrumperen die je op je belastingaangifte zet.

Waar een verkeerd prijsmodel je echt misleidt​

De aandelen- en ETF-voorbeeldledger illustreert de scherpere versie van precies dit punt:

Hij bevat een 4-voor-1 aandelensplitsing, op de juiste manier geboekt—als een hoeveelheidswijziging die de totale basis behoudt zonder inkomstenrekeningen 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 gelijk aan $5.016,00. De marktwaarde blijft ongewijzigd over de splitsing ($7.440,00 in beide gevallen), en de verkrijgingsdatum tussen de accolades overleeft—wat ervoor zorgt dat een verkoop van die aandelen in 2026 als long-term wordt geclassificeerd.

De veelgemaakte valkuil is om een splitsing te boeken als een prijsgebeurtenis, zwaar leunend op een "split-adjusted" prijsreeks om de wiskunde te laten kloppen. Dat werkt alleen zolang elke prijs die je ooit bekijkt op exact dezelfde manier is aangepast. Op het moment dat een niet-aangepast cijfer je ledger binnenkomt—een oude bevestiging, een screenshot, of een third-party feed die historische cijfers niet herziet—wordt de positie plotseling gewaardeerd op vier keer zijn werkelijke waarde. Erger nog: het aantal aandelen in de ledger komt niet meer overeen met het afschrift van je broker, wat betekent dat je balansasserties aan het einde van het jaar stilletjes falen.

Dit is het echte argument om te vertrouwen op een prijsfeed met een verklaarde bron, een verklaard soort en een zichtbare observatietijd. Het gaat niet alleen om gemak; het gaat erom precies te weten welke wiskundige conventie je geïmporteerde cijfers gebruiken.

(Een korte opmerking over de embeds: de hosted ledger viewer toont rekeningbalansen tegen kostprijs en biedt momenteel geen waarderingsbediening op de pagina. De ledgers hierboven zijn bedoeld om de onderliggende mechanica te tonen—de lots, de splitsing, de verkopen. Beide zijn openbaar, en je kunt ze klonen en lokaal draaien.)

Wat er nog niet is​

Wij vinden een changelog erger dan nutteloos als hij te veel belooft. Dus hier is de onverbloemde waarheid over wat we nog niet hebben gebouwd, zonder bijbehorende tijdlijnen:

• Authenticatie is verplicht. Anonieme verzoeken aan https://beancount.io/prices/<ALIAS> sturen je door naar een inlogpagina.
• Geen lokale CLI-ondersteuning. De lokale bea CLI leest bestanden van schijf, wat betekent dat een URL-include lokaal faalt als een unmatched file glob. Het toevoegen van loader-ondersteuning aan de CLI staat op onze roadmap.
• Geen API-oppervlak. We hebben momenteel geen REST-, GraphQL- of MCP-veld voor beheerde prijzen.
• Geen UI-dashboard. Er is nog geen "connect-a-feed"-scherm en geen versheidslabel in de UI. (De versheidsdata die onze engine berekent, heeft momenteel nergens om te worden weergegeven).
• Geen snapshots, exports of handmatige verversingseindpunten.

Wat we vandaag hebben uitgebracht is strikt de engine-laag: include-resolutie, validatie, revisie-caching, precedentie-regels en versheidsberekening. Het is de fundamentele infrastructuur waar al het andere op moet staan, en daarom hebben we het als eerste gebouwd.

Waar je hierna moet kijken​

Beide ledgers die hierboven zijn ingebed, maken deel uit van onze voorbeeldgalerij—zes volledig uitgewerkte patronen die je kunt klonen en lokaal kunt draaien. (Beide worden bewust geleverd met statische, ingecheckte prijsbestanden, zodat een kloon die twee jaar vanaf nu wordt gemaakt exact hetzelfde rapport oplevert als vandaag). Al het andere dat we uitbrengen, verschijnt direct op onze changelog.

Als je er prima mee bent om prijzen actueel te houden met je eigen fetcher, hou dat vooral vol. Het blijft het beste antwoord voor een strikt lokale ledger. Beancount's eigen documentatie over het ophalen van prijzen en de onderhouden beanprice-tool zijn de beste plekken om te beginnen.

Houd het saaie deel saai​

Prijzen zijn het automatiseren waard, juist omdat ze het enige deel van een plain-text ledger zijn dat na verloop van tijd verrot. Beancount.io is gebouwd om je plain-text accounting te geven die van jou blijft—auditeerbaar, onder versiebeheer, en nooit achter je rug om herschreven. Dat was de basisstandaard waaraan een beheerde feed moest voldoen voordat we bereid waren hem uit te brengen.

Begin gratis, en houd je boeken in bestanden die je daadwerkelijk kunt lezen.