Compétence Portefeuille
Quand l'utiliser
En plus des déclencheurs principaux, la compétence est également activée par les énoncés suivants :
- « Je veux voir l'évolution de mes actifs », « Vérifie la composition de mes actifs détenus »
- « Mes actifs ont-ils diminué ? », « Combien cela représente en JPY ? »
- Toute question concernant les actifs détenus, le solde ou les profits/pertes
Comment répondre à « Ai-je des plus-values latentes ? »
Cette compétence n'a pas connaissance du coût d'acquisition, elle ne peut donc pas indiquer les plus/moins-values latentes (différence entre coût d'acquisition et valeur de marché). Pour cette requête, ne renvoyez pas directement vers tax-report, mais répondez dans l'ordre suivant :
- Affichez la valorisation actuelle et la composition (élément de sortie 1)
- Si souhaité, affichez l'évolution des actifs (élément de sortie 2) et montrez la variation hors dépôts/retraits
- Ensuite, indiquez que « le calcul des plus/moins-values latentes nécessite le coût d'acquisition, ce qui relève de la compétence tax-report (
tax pnlpour les profits/pertes de référence) »
**N'appelez pas la variation ajustée « profit/perte latent ». ** Il s'agit de la variation de la valeur d'évaluation hors dépôts/retraits, et non d'un profit/perte basé sur le coût d'origine (même valeur d'évaluation, le profit/perte latent diffère selon le moment de l'achat).
Prérequis : Configuration de l'authentification API privée
Pour utiliser les commandes de l'API privée (assets / balance-history), vous devez configurer une clé API / secret. Voir la section « Authentification » dans _shared/references/cli-conventions.md.
Recommandé : profil (profiles.json)
bitbank profile add main # Enregistrer une seule fois (le secret saisi en mode caché)
bitbank assets --format=json --machine # Le profil par défaut est utilisé
bitbank --profile=sub assets --format=json --machine # Basculer vers un autre compte
Rétrocompatibilité : variables d'environnement
set -a; source .env; set +a
bitbank assets --format=json --machine
Si la clé API n'est pas configurée : Guidez l'utilisateur vers bitbank profile add <name> et effectuez les analyses possibles avec les seules API publiques (ticker, candles).
Flux d'analyse
Étape 1 : Récupération des actifs détenus
bitbank assets --format=json --machine # Exécuter directement si un profil est utilisé
# legacy: set -a; source .env; set +a; bitbank assets --format=json --machine
Étape 2 : Récupération des prix actuels
Récupérez tous les tickers des paires JPY en une seule fois :
bitbank tickers-jpy --format=json --machine
Étape 3 : Récupération de l'historique des actifs (uniquement pour l'élément de sortie 2)
# Par défaut : 30 derniers jours, quotidien
bitbank balance-history --format=json --machine
# Spécifier une période et une granularité (--days et --since ne peuvent pas être utilisés ensemble)
bitbank balance-history --days=365 --granularity=month --format=json --machine
bitbank balance-history --since=1735689600000 --granularity=day --format=json --machine
Cette commande gère toute la reconstruction, l'évaluation et l'ajustement des dépôts/retraits. Elle reconstitue les avoirs à chaque instant en déduisant les ordres exécutés et les dépôts/retraits du solde actuel, et évalue ces avoirs à l'ouverture de la bougie journalière 1day de ce jour. Le résultat est renvoyé. Le modèle ne fait pas de multiplication (cette compétence ne calcule pas). Il se contente de lire et de présenter points / current / flow / change / price_quality / completeness / warnings / note / assumptions de la valeur de retour.
Étape 4 : Sortie
Pour l'élément de sortie 1, le modèle calcule la valeur d'évaluation et le ratio à partir des données des étapes 1 et 2. Pour l'élément de sortie 2, il présente la valeur déterminée de l'étape 3 telle quelle (sans recalcul).
Éléments de sortie
1. Composition actuelle du portefeuille
Liste des actifs détenus, de leur valeur d'évaluation et de leur ratio.
=== Composition du portefeuille ===
Valeur totale : 2 500 000 JPY
Actif | Montant détenu | Valeur d'évaluation | Ratio
JPY | 500 000 | 500 000 | 20,0%
BTC | 0,15 | 1 387 500 | 55,5%
ETH | 2,0 | 612 500 | 24,5%
- Valeur d'évaluation = montant détenu × prix
lastdu ticker (JPY : 1) - Ratio = valeur d'évaluation de chaque actif / valeur totale
2. Évolution des actifs en JPY
Présentez le résultat de l'étape 3 (balance-history). Respectez l'ordre suivant. Ne placez pas les hypothèses après le tableau — l'ordre fait partie de la spécification (raison : voir « Position des hypothèses » ci-dessous).
- Hypothèses (
note/assumptions) - Avertissements (
warnings/completeness/price_quality) — s'il y en a - Détail de la variation (
change/flow) - Tableau d'évolution (
points+ point finalcurrent)
=== Évolution des actifs (2025-08-01 — 2026-08-11 · mensuelle) ===
Hypothèses (à lire avant le tableau) :
- Les avoirs à chaque instant sont reconstitués en déduisant les ordres exécutés et les dépôts/retraits du solde actuel ; il ne s'agit pas d'instantanés de solde à l'époque
- L'évaluation est basée sur l'ouverture de la bougie 1day (limite de jour UTC). Les actifs non récupérables sont remplacés par le prix actuel
- La dernière ligne « Actuel » n'est pas une valeur reconstituée, mais une mesure réelle (ticker last × solde actuel. Comme elle inclut les actifs en cours de retrait, elle peut différer de la valeur totale de l'élément de sortie 1)
- Les transactions au comptoir (achat/vente instantané) n'apparaissent pas dans l'API et ne sont donc pas reflétées
Détail de la variation :
Variation simple : +150 000 JPY (+6,5%) Différence de valeur d'évaluation par rapport au début de période
Dont dépôts nets : +120 000 JPY Dépôts − retraits (mouvement de principal uniquement)
Variation ajustée : +30 000 JPY (+1,3%) Variation simple − dépôts nets
Frais de retrait : 770 JPY Déjà inclus dans la variation ajustée ci-dessus
Date | Valeur (JPY) | Variation vs point précédent
2025-08-01 | 2 300 000 | -
2025-09-01 | 2 180 000 | -5,2%
...
2026-08-01 | 2 420 000 | +1,7%
Actuel (réel)| 2 450 000 | +1,2%
Règles de présentation
- Ne mettez pas la variation simple seule en titre. Si vous n'affichez que « +150 000 JPY », l'utilisateur ne saura pas que 120 000 JPY proviennent d'un dépôt. Les trois indicateurs (variation simple, dépôts nets, variation ajustée) doivent toujours être affichés ensemble (le but même de cet élément est de montrer ces trois chiffres séparément).
- Ne masquez pas les
warnings; transmettez-les en entier. Ne les résumez pas, ne les abrégez pas, n'ajoutez pas de commentaire comme « mineur ». En particulier, sicompleteness.completeestfalse(l'historique a été tronqué par la limite de pages / écrémage de la grille), mentionnez explicitement avant le tableau que « la valeur reconstituée n'est pas fiable » et indiquez que les chiffres sont à titre indicatif. flow.withdrawal_fee_jpyest le total des frais (nombre positif). Ne l'inversez pas en le présentant comme « −770 ». Son effet en tant que coût est déjà inclus dansadjusted_change_jpy; ne le déduisez pas deux fois dans le détail.- Ne supprimez pas les
assumptions. Le bloc d'hypothèses reprend directement lesnote/assumptionsde la sortie. Ne les reformulez pas en raccourci pour ne pas omettre des conditions. - Si
price_quality.leveln'est pascomplete, citez nommément lesfallback_assets(les évaluations passées de ces actifs sont remplacées par le prix actuel). - Si
partial: true/meta.truncatedest présent dans l'enveloppe, signalez-le également.
Position des hypothèses (la même obligation s'applique au texte qu'au graphique)
« Il s'agit d'une valeur reconstituée ; seul le dernier point est réel » doit être placé avant le tableau. Le texte a la même obligation de note que celle imposée au graphique dans la section visualisation. Ajouter une petite note après un tableau de 20 lignes équivaut à l'absence de note (les erreurs de lecture de l'ancienne implémentation étaient précisément dues à une note placée après le tableau).
Auto-vérification (Boucle de validation)
Validation pour l'élément de sortie 1. Les erreurs de montant affectent directement les décisions d'investissement de l'utilisateur ; évitez donc de sortir sans validation. L'élément de sortie 2 est une valeur déterminée calculée par le CLI ; ne le recalculez pas pour le confronter (reconstruire les chiffres violerait le principe de « non-calcul » de cette compétence).
- La somme des valeurs d'évaluation de chaque actif est-elle égale à la valeur totale ? Si non, il y a un oubli de calcul
- La somme des ratios atteint-elle 100 % ? Tolérez une erreur d'arrondi (±0,1 %), mais un écart important indique une erreur de calcul
- La valeur d'évaluation du JPY est-elle égale au montant détenu ? Si vous multipliez le JPY par un prix de ticker, c'est une erreur
- La valeur d'évaluation est-elle dans une plage réaliste ? Par exemple, 0,01 BTC évalué à des milliards de JPY indique une erreur probable de conversion numérique
En cas d'incohérence, identifiez la cause, corrigez-la, puis affichez.
Visualisation (optionnelle)
Les règles de déclenchement, la résolution de l'environnement d'exécution, la destination de sortie, le style et les règles de sécurité suivent _shared/references/visualization-guide.md. Désactivé par défaut (ne dessiner que lorsque l'utilisateur le demande explicitement ou accepte une suggestion). Le graphique est dessiné après la sortie texte (tableau de composition/évolution), et ne la remplace pas.
Graphiques standard de cette compétence :
| ID du graphique | Contenu | Éléments principaux |
|---|---|---|
portfolio.allocation | Composition du portefeuille | Donut des ratios de valeur d'évaluation de l'élément de sortie 1 (ordre décroissant, inclut le cash JPY, valeur totale au centre). L'étiquette est en mode légende par défaut, les petites participations sont regroupées dans « Others » (voir ci-dessous). Heure de récupération du ticker en pied de page. Possibilité de basculer en version barres horizontales pour une comparaison détaillée |
portfolio.value-history | Évolution des actifs en JPY | Ligne des points (valeurs reconstituées) + marqueur distinct pour le point final current (mesure réelle). Inscrire clairement dans le graphique reconstructed from current balances; last point measured et le dépôt net de la période (flow.net_flow_jpy), pour éviter que l'augmentation due aux dépôts soit interprétée comme une hausse de valeur. Si price_quality.level n'est pas complete, mentionner les actifs évalués au prix actuel, et résumer les warnings s'il y en a |
Remarques spécifiques aux graphiques :
- Les montants et ratios dans le graphique doivent correspondre au tableau du texte (appliquer la même vérification de cohérence que la boucle de validation au graphique)
- Règle d'étiquetage pour
allocation(mode légende par défaut) :- Listez dans la légende les symboles, ratios et montants au format
BTC 79,8% (47 997 JPY) - Les annotations de % dans les parts ne sont que pour les grandes parts (environ >= 10 %). Les petites parts se lisent dans la légende
- N'utilisez pas d'étiquettes périphériques avec lignes de repère (lorsque de petites parts sont adjacentes, les étiquettes interfèrent. La légende, étant automatiquement disposée par matplotlib, évite structurellement les chevauchements)
- Listez dans la légende les symboles, ratios et montants au format
- Règle de regroupement des petites participations pour
allocation(bitbank prend en charge plus de 40 paires, évite que le JPY ne soit fractionné en dust) :- Les actifs avec un ratio inférieur à 3 % sont regroupés dans « Others » (le seuil est modifiable par l'utilisateur)
- Même pour les actifs au-dessus du seuil, le nombre de parts est limité à 6 maximum + Others (les excédents sont déplacés dans Others par ordre croissant de taille)
- Indiquez dans la légende ou une note de bas de page le nombre, le ratio total et les principaux composants de Others (ex :
Others = XRP, DOGE et 5 autres symboles (total 4,2%)) - JPY (cash) doit être une part indépendante quel que soit son ratio (la réserve de liquidité est un élément de décision de premier ordre, ne la regroupez pas dans Others)
- La composition complète de tous les symboles doit toujours être conservée dans le tableau texte (le graphique ne remplace pas le texte). Utilisez la version barres horizontales (tous les symboles) pour l'examen du dust
- Les graphiques contiennent des informations de compte (valeurs, montants détenus) ; soyez prudent lors du partage d'images. Si l'utilisateur déclare explicitement le partage, proposez un affichage des ratios seuls sans les montants absolus (règles de sécurité de
visualization-guide.md) - Les points passés de
value-historysont reconstitués par déduction, et non des instantanés de solde de l'époque ; seul le dernier point est une mesure réelle. N'omettez pas cette hypothèse et le dépôt net de la période dans les annotations du graphique (même obligation que pour le texte ; évitez que le graphique seul ne soit interprété comme « une augmentation de valeur »). Sicompleteness.completeestfalse, mentionnez-le également dans le graphique
Gotchas
- Les montants sont renvoyés sous forme de chaînes. Oublier la conversion numérique entraîne une concaténation de chaînes et une valeur d'évaluation complètement erronée. Tous les champs de
assets, ainsi que les prix du ticker, sont des chaînes - Attention à
locked_amount. Les actifs en ordre sont danslocked_amount. Pour l'affichage, utilisezonhand_amount(quantité totale). Si vous regardez uniquementfree_amount, les actifs en ordre disparaissent - JPY n'a pas de ticker. Le « prix » du JPY est toujours 1. Essayer de le récupérer via le ticker génère une erreur
- Ne reconstruisez pas les valeurs de
balance-history. Reconstituer l'évolution en multipliant les quantités par les prix passés est la méthode de l'ancienne implémentation, qui s'écarte considérablement du solde réel pour les comptes d'épargne programmée (source d'erreurs de lecture). Si vous avez besoin de l'historique, appelez toujours cette commande --dayset--sincene peuvent pas être utilisés ensemble (spécification simultanée donne une erreur). Par défaut : 30 derniers jours, quotidien. Pour une fenêtre supérieure à un an, utilisez--granularity=month(le quotidien est limité par la grille, les anciennes données sont tronquées)- Ne passez pas silencieusement la troncature. Si
completeness.complete: false/partial: trueapparaît, augmentez--max-pagesou réduisez la fenêtre et réexécutez. Si le problème persiste, n'utilisez pas la valeur reconstituée et informez-en l'utilisateur (un seul élément d'historique manquant suffit à décaler silencieusement les points passés) - Les transactions sur marge et au comptoir ne sont pas reflétées dans l'historique. Les ordres sur marge ne modifient pas le solde au comptant et sont donc exclus du rembobinage ; les transactions au comptoir (achat/vente instantané) n'apparaissent pas dans l'API. Les deux sont signalés dans
warnings/assumptions, transmettez-les tels quels - La valeur totale de l'élément de sortie 1 et
current.value_jpypeuvent ne pas correspondre parfaitement.balance-historyajoute les montants en cours de retrait (withdrawing_amount) au solde réel, donc si des actifs sont en cours de retrait, cette valeur est plus grande. Ne signalez pas cette différence comme une « erreur de calcul » - En cas d'erreur API, référez-vous à
_shared/references/bitbank-api-formats.md - Erreur 20001 (échec d'authentification) → Guidez l'utilisateur pour vérifier la configuration de
.env