Vos avoirs sont déjà dans le registre. Ce sont leurs prix que vous ne cessez de ressaisir.
Cette asymétrie est la corvée la plus ancienne de la comptabilité en texte brut. Un achat s'écrit une fois et reste vrai pour toujours : 120 NWRB {41.80 USD, 2024-03-12} enregistre une quantité, un coût et une date, et rien de ce qui se produit ensuite ne modifie aucun des trois. Un prix, c'est l'inverse — exact pendant un jour, puis discrètement faux, et faux d'une manière qu'aucun contrôle de solde ne détectera jamais, parce qu'un prix périmé s'équilibre parfaitement. La réponse de Beancount lui-même a toujours été de les récupérer avec un outil et de commiter le résultat, ce qui fonctionne et que beaucoup de gens ont automatisé. Mais cela reste un script qui vous appartient, une entrée cron que vous maintenez et un fichier que vous fusionnez.
Le moteur de registre beancount.io effectue désormais cette résolution lui-même, pour les registres hébergés chez nous. Cet article porte sur ce qui a réellement été livré, sur ce qu'il ne touche délibérément pas et — tout aussi important — sur ce qui n'est pas encore construit.
Ce qui a été livré
Un registre beancount.io hébergé peut comporter un include dont la cible est une URL au lieu d'un nom de fichier :
; 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 de Beancount en amont prend un nom de fichier — « le chemin spécifié peut être un nom de fichier absolu ou relatif » constitue toute la spécification — donc un include sous forme d'URL n'est pas du Beancount standard et ne prétend jamais l'être. C'est un comportement du moteur hébergé, et voici précisément ce que le moteur en fait :
- Il matérialise le flux sous forme de fichier virtuel en lecture seule. L'URL se résout via le propre chemin de résolution d'include du moteur, exactement là où un fichier local aurait atterri, de sorte que chaque directive conserve un emplacement source réel. Vos octets ne sont jamais réécrits. Le fichier que vous avez écrit reste le fichier que vous avez écrit.
- Le corps récupéré est validé comme étant exclusivement composé de prix. Des directives
price, des commentaires et quatre clés de métadonnées autorisées —price-source,price-kind,observed-atetprovisional— et rien d'autre. Tout ce qui dépasse rejette l'intégralité du corps. Il n'y a pas d'ingestion partielle, donc un flux ne peut jamais faire entrer une transaction en contrebande dans vos livres. - Les flux sont mis en cache sous forme de révision immuable plus un pointeur mobile. Le rafraîchissement est déclenché par un horodatage plutôt que par l'expiration du cache, ce qui signifie qu'une panne en amont ne peut pas emporter votre dernière bonne révision. Un rafraîchissement échoué ne remplace jamais une bonne révision par rien.
- La fraîcheur est calculée au moment de la lecture du registre, et non stockée :
recent,staleouunavailable, aux côtés de l'heure d'observation rapportée par le flux lui-même. Un prix que vous ne pouvez pas dater est un prix que vous ne pouvez pas auditer. - Les entrées gérées sont en lecture seule. Leur modification ou leur suppression est refusée avec une erreur nommant la source gérée, et elles ne sont pas comptées dans les limites de directives — le flux n'est pas autorisé à consommer le budget de votre registre.
Tout ce qui figure dans cette liste s'exécute à l'intérieur du service de registre hébergé. Rien de tout cela ne change ce que signifie une directive price : elle établit toujours le taux d'échange entre une commodity de base et une commodity cotée, exactement comme le définit la référence du langage. Le travail du moteur consiste uniquement à placer des prix corrects, datés et attribuables devant le chargeur.
Votre propre prix l'emporte toujours
C'est la partie qui détermine si un flux est utilisable par quelqu'un qui prend son registre au sérieux, alors elle est énoncée précisément.
Pour la même date et la même paire de commodities — et pour la paire réciproque — un prix que vous avez écrit vous-même l'emporte sur le flux géré, quel que soit l'ordre des includes.
Pas « généralement », et pas « si vous placez votre include en dernier ». La décision de masquage est prise avant que la carte des prix ne soit construite, donc elle ne dépend pas de l'endroit où l'include se trouve dans le fichier. Mettez-le en haut, mettez-le en bas, répartissez-le sur trois fichiers : la réponse est la même.
; 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 est l'émetteur fictif du registre d'exemple plus bas ; le nombre est inventé, ce n'est pas une observation de marché.)
Pourquoi cette règle et pas l'autre : un prix dans votre propre fichier est une décision. Ce peut être le cours de clôture imprimé par votre courtier sur le relevé que vous réconciliez, une cotation contemporaine pour une position peu échangée, ou un chiffre que votre comptable vous a demandé d'utiliser. Un flux ne sait rien de tout cela, et un système qui écrase silencieusement une valeur rédigée par un humain a cessé d'être un registre pour devenir une opinion. Le flux comble les lacunes ; il ne vous corrige pas.
Les prix déplacent la valorisation, et rien d'autre
La seconde assurance est structurelle plutôt qu'un choix de politique, et il vaut la peine de la montrer avec de vrais chiffres plutôt que de l'affirmer. Voici le registre d'exemple crypto — lots datés, staking, minage, positions DeFi, airdrops :
Prenez une entrée de ce registre. Un airdrop de token de gouvernance arrive et est enregistré comme revenu à la juste valeur de marché le jour où il atterrit :
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 USDCes 625,00 $ de revenu, et la base de 12,50 $ par unité attachée au lot, sont désormais des faits concernant le 2024-03-20. Toutes les directives price du registre — gérées, écrites à la main ou totalement absentes — laissent les deux intactes. Les prix modifient la valeur de marché ; ils ne modifient jamais les quantités, la base de coût, les flux de trésorerie, les frais ou les gains réalisés. C'est pourquoi un flux de prix est une chose sûre à accepter comme aide, en premier lieu : le pire qu'un prix erroné puisse faire est de mal rapporter ce que vaut une position aujourd'hui, et il ne peut jamais corrompre le chiffre que vous mettrez sur une déclaration de revenus.
Où un modèle de prix erroné vous induit réellement en erreur
Le registre d'exemple actions et ETF présente la version plus tranchante du même point :
Il contient un fractionnement d'actions 4 pour 1, et le fractionnement est enregistré de la manière correcte — comme un changement de quantité qui préserve la base totale, sans toucher aucun compte de revenu :
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}Les deux côtés totalisent 5 016,00 $. La valeur de marché est inchangée à travers le fractionnement — 120 actions à 62,00 $ la veille, 480 actions à 15,50 $ le lendemain, 7 440,00 $ dans les deux cas — et la date d'acquisition entre les accolades survit, ce qui permet à une vente de ces actions en 2026 de rester à long terme.
L'erreur courante consiste à enregistrer un fractionnement comme un événement de prix et à s'appuyer sur une série « ajustée des fractionnements » pour que la valorisation tombe juste. Cela ne fonctionne que tant que tous les prix que vous voyez ont été ajustés de la même manière. Dès qu'un chiffre non ajusté arrive — une ancienne confirmation, une capture d'écran, une série tierce qui ne retraite rien — la position est valorisée à quatre fois sa valeur, et le nombre d'actions dans le registre ne correspond plus au relevé du courtier, de sorte que l'assertion de fin d'année qui l'aurait détecté ne peut plus se déclencher.
C'est le véritable argument en faveur d'un flux de prix avec une source déclarée, un type déclaré et une heure d'observation visible : non pas la commodité, mais le fait de savoir sous quelle convention le chiffre que vous venez d'importer a été calculé. Le fichier de prix propre au registre d'exemple est délibérément non ajusté et le dit, et ses deux directives à cheval sur le fractionnement sont écrites comme une vérification que vous pouvez contrôler à l'œil.
Une note honnête sur le fait de cliquer dans l'un ou l'autre des embeds : la visionneuse de registres hébergés affiche les soldes des comptes au coût, et n'offre aucun contrôle de valorisation sur la page. Les registres ci-dessus sont là pour vous montrer les registres — les lots, le fractionnement, les ventes de lots spécifiques — et non une valorisation de marché que la visionneuse ne dessine pas actuellement. Les deux sont publics, et les deux peuvent être clonés et exécutés localement.
Ce qui n'est pas encore là
Une entrée de changelog vaut moins que rien si elle vous laisse croire quelque chose qui n'est pas vrai, alors voici l'autre moitié, clairement et sans aucune date attachée à quoi que ce soit.
- Le point de terminaison des prix n'est pas public. Une requête anonyme à
https://beancount.io/prices/<ALIAS>est redirigée vers la page de connexion. Il n'y a pas de catalogue public d'alias. - Donc ce n'est pas quelque chose que vous pouvez coller dans votre propre fichier aujourd'hui. Le moteur résout l'include ; la route qu'il résout n'est pas encore ouverte. Quand elle le sera, cela fera l'objet de sa propre entrée de changelog.
- La CLI locale
beane résout pas les includes sous forme d'URL. Elle lit les fichiers depuis le disque, donc un include sous forme d'URL échoue localement comme un glob de fichier ne correspondant à aucun fichier. La prise en charge par le chargeur dans la CLI est un suivi nommé. - Il n'y a pas de surface d'API. Ni REST, ni GraphQL, ni champ MCP pour les prix gérés.
- Il n'y a pas de surface de tableau de bord. Ni écran de connexion de flux, ni étiquette de fraîcheur dans l'interface ; la fraîcheur calculée par le moteur n'a encore nulle part où être affichée.
- Les snapshots et l'export ne sont pas construits, pas plus qu'un catalogue d'instruments ou un point de terminaison de rafraîchissement manuel.
Ce qui a été livré, c'est la couche moteur : la résolution des includes, la validation, le cache de révisions, la règle de priorité et le calcul de la fraîcheur. C'est la partie sur laquelle tout le reste doit s'appuyer, et c'est la partie la plus difficile à modifier ensuite, ce qui explique qu'elle soit passée en premier.
Où regarder ensuite
Les deux registres ci-dessus font partie de la galerie d'exemples, six modèles élaborés que vous pouvez cloner et exécuter localement — ces deux-ci livrent à dessein des fichiers de prix statiques et versionnés, pour qu'un clone réalisé dans deux ans produise encore le rapport qu'il produit aujourd'hui. Tout le reste de ce que nous livrons atterrit sur le changelog.
Si vous maintenez encore vos prix à jour avec votre propre récupérateur, cela reste la bonne réponse pour un registre local, et la documentation de Beancount sur la récupération des prix ainsi que l'outil maintenu beanprice sont les points de départ.
Gardez la partie ennuyeuse ennuyeuse
La raison pour laquelle les prix valent la peine d'être automatisés, c'est qu'ils sont la seule partie d'un registre en texte brut qui se dégrade toute seule. Beancount.io vous offre une comptabilité en texte brut qui reste la vôtre — auditable, versionnée et jamais réécrite dans votre dos, ce qui est exactement le standard qu'un flux géré devait atteindre avant que nous en livrions un. Commencez gratuitement et gardez vos livres dans des fichiers que vous pouvez lire.
