Communitygithub.com

bitbankinc/bitbank-lab-cli

Consultez la situation actuelle de votre portefeuille (composition des actifs, valeur en JPY, évolution ajustée des dépôts/retraits) à partir des actifs détenus et des données de prix sur bitbank.

Qu'est-ce que bitbank-lab-cli ?

Cette compétence pour agent IA se spécialise dans l'évaluation de portefeuille pour la plateforme d'échange bitbank. Elle récupère les actifs détenus via l'API privée et les tickers de prix publics JPY pour générer deux sorties principales : un aperçu de la composition actuelle (actif, montant, valeur en JPY, pourcentage d'allocation) et un historique de la valeur en JPY, qui reconstruit les soldes passés en déduisant les ordres exécutés et les dépôts/retraits à partir du solde actuel. Contrairement aux compétences de corrélation ou de volatilité, ce skill ne calcule pas de profit/perte latent, car il ne connaît pas le coût d'acquisition ; il redirige plutôt les requêtes de P&L vers une compétence de rapport fiscal. Il exige que l'utilisateur configure une clé API (via la commande `bitbank profile add` ou les variables d'environnement) pour les appels d'API privée, mais peut fonctionner avec des API publiques seules pour des analyses limitées si aucune clé n'est définie. Le skill met l'accent sur les principes de non-recalcul : pour l'historique de la valeur, il présente les résultats exacts fournis par la commande `bitbank balance-history` sans interpolation ni multiplication, et pour l'aperçu actuel, il valide que les valeurs totales et les pourcentages sont cohérents avant de les afficher. Il inclut une visualisation optionnelle via des diagrammes en anneau et des graphiques linéaires, avec des règles strictes concernant les étiquettes (légendaire de préférence), le regroupement des petites participations (seuil de 3 %) et l'affichage des avertissements (intégrité des données, qualité des prix, hypothèses) avant les tableaux. Les plates-formes prises en charge incluent les terminaux prenant en charge les exécutions de commandes CLI et Python (pour la visualisation), et la documentation du skill met en garde contre les pièges courants tels que les valeurs de retour de chaîne, les actifs verrouillés, le traitement spécial JPY et les divergences entre l'évaluation actuelle et l'historique des soldes de secours.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/bitbankinc/bitbank-lab-cli/tree/HEAD/skills/portfolio

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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 :

  1. Affichez la valorisation actuelle et la composition (élément de sortie 1)
  2. Si souhaité, affichez l'évolution des actifs (élément de sortie 2) et montrez la variation hors dépôts/retraits
  3. 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 pnl pour 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 last du 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).

  1. Hypothèses (note / assumptions)
  2. Avertissements (warnings / completeness / price_quality) — s'il y en a
  3. Détail de la variation (change / flow)
  4. Tableau d'évolution (points + point final current)
=== É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, si completeness.complete est false (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_jpy est 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 dans adjusted_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 les note / assumptions de la sortie. Ne les reformulez pas en raccourci pour ne pas omettre des conditions.
  • Si price_quality.level n'est pas complete, citez nommément les fallback_assets (les évaluations passées de ces actifs sont remplacées par le prix actuel).
  • Si partial: true / meta.truncated est 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).

  1. La somme des valeurs d'évaluation de chaque actif est-elle égale à la valeur totale ? Si non, il y a un oubli de calcul
  2. La somme des ratios atteint-elle 100 % ? Tolérez une erreur d'arrondi (±0,1 %), mais un écart important indique une erreur de calcul
  3. 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
  4. 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 graphiqueContenuÉléments principaux
portfolio.allocationComposition du portefeuilleDonut 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 JPYLigne 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)
  • 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-history sont 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 »). Si completeness.complete est false, 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 dans locked_amount. Pour l'affichage, utilisez onhand_amount (quantité totale). Si vous regardez uniquement free_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
  • --days et --since ne 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: true apparaît, augmentez --max-pages ou 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_jpy peuvent ne pas correspondre parfaitement. balance-history ajoute 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

Skills associés