Communitygithub.com

bitbankinc/bitbank-lab-cli

Erfasse den aktuellen Stand deines Portfolios auf bitbank: Vermögenszusammensetzung, JPY-Bewertung und Vermögensentwicklung (bereinigt um Ein- und Auszahlungen).

Was ist bitbank-lab-cli?

Dieses Skill bietet eine spezialisierte Portfolio-Übersicht für bitbank-Nutzer. Es konzentriert sich ausschließlich auf die Bewertung der gehaltenen Vermögenswerte und deren Entwicklung. Durch die Ausführung der Private-API-Befehle `bitbank assets` und `bitbank tickers-jpy` werden die aktuellen Bestände und Kurse abgerufen. Für die Vermögensentwicklung wird der Befehl `bitbank balance-history` genutzt, der Kalkulationen wie die Wiederherstellung historischer Bestände und die Bereinigung von Ein-/Auszahlungen automatisch vornimmt. Das Skill berechnet keine realisierten oder unrealisierten Gewinne/Verluste, da ihm die Anschaffungskosten fehlen; für solche Analysen wird auf das Skill `tax-report` verwiesen. Es gibt die Ergebnisse als formatierte Texttabellen (Vermögenszusammensetzung, Entwicklung) und optional als Diagramme (Donut-Chart für die Allokation, Liniendiagramm für die Wertentwicklung) aus. Eine integrierte Validierung überprüft die Konsistenz der berechneten Werte, um Fehler zu vermeiden. Nutzer werden durch einen Assistenten zur Einrichtung ihrer API-Schlüssel geführt, falls diese noch nicht konfiguriert sind.

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

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Skill: Portfolio-Übersicht

Wann verwenden?

Neben den primären Triggern wird das Skill auch durch folgende Äußerungen aktiviert:

  • „Ich möchte die Vermögensentwicklung sehen“ / „Zeig mir die Zusammensetzung meiner Vermögenswerte“
  • „Habe ich Verluste gemacht?“ / „Wie viel ist das in JPY wert?“
  • Allgemeine Fragen zu Beständen, Guthaben und Gewinnen/Verlusten

Antwort auf die Frage „Habe ich unrealisierte Gewinne?“

Da dieses Skill keine Anschaffungskosten kennt, kann es keine unrealisierten Gewinne oder Verluste (Differenz zwischen Anschaffungskosten und aktuellem Marktwert) ausweisen. Bei dieser Frage wird nicht einfach an tax-report verwiesen, sondern in der folgenden Reihenfolge geantwortet:

  1. Aktuelle Bewertung und Zusammensetzung anzeigen (Ausgabepunkt 1)
  2. Falls gewünscht, die Vermögensentwicklung anzeigen (Ausgabepunkt 2) und die Veränderung bereinigt um Ein- und Auszahlungen zeigen
  3. Anschließend darauf hinweisen: „Für die Berechnung unrealisierter Gewinne/Verluste werden die Anschaffungskosten benötigt. Dies ist Aufgabe des tax-report-Skills (siehe tax pnl für Referenzgewinne/-verluste).“

Bezeichne die „bereinigte Veränderung“ nicht als unrealisierten Gewinn/Verlust. Es handelt sich um die Veränderung des Bewertungsbetrags ohne Ein- und Auszahlungen, nicht um einen Gewinn/Verlust auf Basis der Anschaffungskosten (selbst bei gleicher Bewertung variiert der unrealisierte Gewinn/Verlust je nach Kaufzeitpunkt).

Voraussetzung: Authentifizierung für die Private API

Um Private-API-Befehle (assets / balance-history) zu verwenden, muss ein API-Key / Secret konfiguriert sein. Details siehe _shared/references/cli-conventions.md unter „Authentifizierung“.

Empfohlen: Profile (profiles.json)

bitbank profile add main                    # Einmalig registrieren (Secret wird verdeckt per Eingabe eingegeben)
bitbank assets --format=json --machine      # Standard-Profil wird verwendet
bitbank --profile=sub assets --format=json --machine   # Zu einem anderen Konto wechseln

Abwärtskompatibel: Umgebungsvariablen

set -a; source .env; set +a
bitbank assets --format=json --machine

Falls kein API-Key konfiguriert ist: Den Benutzer anleiten, bitbank profile add <name> auszuführen, und Analysen durchführen, die nur mit der Public API (Ticker, Candles) möglich sind.

Analyseablauf

Schritt 1: Abruf der gehaltenen Vermögenswerte

bitbank assets --format=json --machine   # Bei Verwendung eines Profils direkt ausführen
# legacy: set -a; source .env; set +a; bitbank assets --format=json --machine

Schritt 2: Abruf der aktuellen Kurse

Alle JPY-Paar-Ticker auf einmal abrufen:

bitbank tickers-jpy --format=json --machine

Schritt 3: Abruf der Vermögensentwicklung (nur wenn Ausgabepunkt 2 benötigt wird)

# Standard: letzte 30 Tage, täglich
bitbank balance-history --format=json --machine

# Zeitraum und Granularität angeben (--days und --since schließen sich gegenseitig aus)
bitbank balance-history --days=365 --granularity=month --format=json --machine
bitbank balance-history --since=1735689600000 --granularity=day --format=json --machine

Dieser Befehl führt die Wiederherstellung, Bewertung und Bereinigung von Ein-/Auszahlungen vollständig durch. Ausgehend vom aktuellen Guthaben werden Trades und Ein-/Auszahlungen zurückgerechnet, um die Bestände zu jedem Zeitpunkt wiederherzustellen. Diese werden dann mit dem Eröffnungskurs des 1-Tages-Kerzen des jeweiligen Tages bewertet. Das Ergebnis wird zurückgegeben. Das Modell führt keine Berechnungen durch (dieses Skill führt keine Berechnungen durch). Es liest lediglich die zurückgegebenen Felder points, current, flow, change, price_quality, completeness, warnings, note und assumptions und präsentiert sie.

Schritt 4: Ausgabe

Ausgabepunkt 1: Das Modell berechnet die Bewertung und die Anteile aus den Daten von Schritt 1 und 2. Ausgabepunkt 2: Die ermittelten Werte aus Schritt 3 werden direkt präsentiert (keine Neuberechnung).

Ausgabepunkte

1. Aktuelle Vermögenszusammensetzung

Liste der gehaltenen Vermögenswerte, Bewertung und Anteile.

=== Vermögenszusammensetzung ===

Gesamtbewertung: 2.500.000 JPY

Vermögenswert | Bestand    | Bewertung     | Anteil
JPY           | 500.000    | 500.000       | 20,0%
BTC           | 0,15       | 1.387.500     | 55,5%
ETH           | 2,0        | 612.500       | 24,5%
  • Bewertung = Bestand × last-Kurs des Tickers (JPY = 1)
  • Anteil = Bewertung des Vermögenswerts / Gesamtbewertung

2. JPY-basierte Vermögensentwicklung

Das Ergebnis von Schritt 3 (balance-history) wird präsentiert. Die folgende Reihenfolge ist einzuhalten. Die Annahmen dürfen nicht hinter die Tabelle verschoben werden – die Reihenfolge ist spezifikationsgemäß (siehe „Position der Annahmen“ unten).

  1. Annahmen (note / assumptions)
  2. Warnungen (warnings / completeness / price_quality) – falls vorhanden
  3. Aufschlüsselung der Veränderung (change / flow)
  4. Entwicklungstabelle (points + letzter Punkt current)
=== Vermögensentwicklung (2025-08-01 bis 2026-08-11, monatlich) ===

Annahmen (vor der Tabelle lesen):
- Die Bestände zu jedem Zeitpunkt werden durch Rückrechnung von Trades und Ein-/Auszahlungen ausgehend vom aktuellen Guthaben wiederhergestellt. Es handelt sich nicht um eine Momentaufnahme des damaligen Guthabens.
- Die Bewertung erfolgt zum Eröffnungskurs des 1-Tages-Kerzen (UTC-Tagesgrenze). Nicht abrufbare Vermögenswerte werden mit dem aktuellen Kurs ersetzt.
- Nur die letzte Zeile „Aktuell“ basiert auf einer tatsächlichen Messung (ticker last × aktuelles Guthaben. Dies kann Guthaben enthalten, das sich im Auszahlungsprozess befindet, daher kann die Summe von der Gesamtbewertung in Ausgabepunkt 1 abweichen).
- Trades über die Verkaufsstelle (Sofortkauf/-verkauf) erscheinen nicht in der API und werden daher nicht berücksichtigt.

Aufschlüsselung der Veränderung:
  Einfache Veränderung      : +150.000 JPY (+6,5%)   Differenz der Bewertung zum Periodenanfang
  Davon Netto-Einzahlung    : +120.000 JPY           Einzahlungen − Auszahlungen (nur Kapitalbewegungen)
  Bereinigte Veränderung    :  +30.000 JPY (+1,3%)   Einfache Veränderung − Netto-Einzahlung
  Auszahlungsgebühren       :      770 JPY           Sind bereits in der bereinigten Veränderung enthalten

Datum         | Bewertung(JPY) | Veränderung zum Vormonat
2025-08-01    |  2.300.000     | -
2025-09-01    |  2.180.000     | -5,2%
...
2026-08-01    |  2.420.000     | +1,7%
Aktuell (gemessen) |  2.450.000     | +1,2%

Darstellungsdisziplin

  • Die einfache Veränderung nicht als Überschrift allein verwenden. Die Angabe „+150.000 ¥“ allein vermittelt nicht, dass davon 120.000 ¥ auf eine Einzahlung zurückzuführen sind. Einfache Veränderung, Netto-Einzahlung und bereinigte Veränderung müssen immer zu dritt ausgegeben werden (der Zweck dieses Punktes ist es, diese drei Werte getrennt voneinander zu zeigen).
  • warnings nicht unterdrücken, sondern vollständig wiedergeben. Nicht zusammenfassen, kürzen oder mit „geringfügig“ versehen. Insbesondere wenn completeness.complete false ist (Verlauf wurde aufgrund des Seitenlimits abgeschnitten / Raster wurde ausgedünnt), muss vor der Tabelle klar gesagt werden „Die wiederhergestellten Werte sind nicht vertrauenswürdig“, und es muss darauf hingewiesen werden, dass die Zahlen als Richtwerte zu betrachten sind.
  • flow.withdrawal_fee_jpy ist die positive Summe der Gebühren. Nicht das Vorzeichen umkehren und als „−770“ ausgeben. Die Auswirkung als Kosten ist bereits in adjusted_change_jpy enthalten, daher nicht doppelt im Detail abziehen.
  • assumptions nicht entfernen. Der Annahmenblock übernimmt note / assumptions aus der Ausgabe direkt. Nicht mit eigenen Worten verkürzen oder Bedingungen weglassen.
  • Wenn price_quality.level nicht complete ist, die fallback_assets namentlich nennen (die historische Bewertung dieser Vermögenswerte wurde durch den aktuellen Kurs ersetzt).
  • Wenn partial: true / meta.truncated im Envelope gesetzt sind, dies ebenfalls melden.

Position der Annahmen (Text unterliegt denselben Verpflichtungen wie die Grafik)

„Es handelt sich um wiederhergestellte Werte; nur der letzte Punkt ist gemessen“ muss vor der Tabelle platziert werden. Die gleiche Verpflichtung zur Kennzeichnung, die der Visualisierungsabschnitt für Diagramme vorsieht, gilt auch für den Text. Eine kleine Anmerkung nach einer 20-zeiligen Tabelle wird behandelt, als gäbe es keine Kennzeichnung (Fehlinterpretationen der alten Implementierung entstanden genau dadurch, dass die Anmerkung nach der Tabelle stand).

Selbstprüfung (Validierungsschleife)

Validierung für Ausgabepunkt 1. Fehler bei den Beträgen wirken sich direkt auf die Anlageentscheidungen des Benutzers aus. Daher sollte die Ausgabe ohne Validierung vermieden werden. Ausgabepunkt 2 sind vom CLI berechnete, endgültige Werte. Nicht neu berechnen und abgleichen (durch das Neuerstellen von Zahlen würde das Prinzip dieses Skills, „keine Berechnungen durchzuführen“, verletzt werden).

  1. Ist die Summe der Bewertungen aller Vermögenswerte = Gesamtbewertung? Bei Abweichung liegt ein Berechnungsfehler vor.
  2. Ergibt die Summe der Anteile 100%? Rundungsfehler (±0,1%) sind akzeptabel, aber größere Abweichungen deuten auf einen Rechenfehler hin.
  3. Ist die Bewertung von JPY = Bestand selbst? Wenn JPY mit einem Ticker-Kurs multipliziert wurde, ist das ein Fehler.
  4. Liegt die Bewertung in einem realistischen Bereich? Wenn z. B. 0,01 BTC mehrere Milliarden Yen ergeben, liegt wahrscheinlich ein Fehler bei der Zahlenkonvertierung vor.

Bei Inkonsistenzen die Ursache identifizieren, korrigieren und dann erst ausgeben.

Visualisierung (Optional)

Trigger-Disziplin, Auflösung der Ausführungsumgebung, Ausgabeziel, Stil und Sicherheitsdisziplin richten sich nach _shared/references/visualization-guide.md. Standardmäßig deaktiviert (nur zeichnen, wenn der Benutzer es explizit anfordert oder einem Vorschlag zustimmt). Diagramme werden nach der Textausgabe (Tabellen für Vermögenszusammensetzung und Vermögensentwicklung) gezeichnet und ersetzen diese nicht.

Standarddiagramme dieses Skills:

Diagramm-IDInhaltHauptbestandteile
portfolio.allocationVermögenszusammensetzungDonut-Chart der Bewertungsanteile aus Ausgabepunkt 1 (absteigend nach Bewertung, inkl. JPY-Bargeld, Gesamtbewertung in der Mitte). Etiketten standardmäßig als Legende, kleine Posten in Others zusammengefasst (Details siehe unten). Abrufzeit des Tickers in der Fußzeile. Umschaltbar zu einer horizontalen Balkenansicht für detaillierte Vergleiche
portfolio.value-historyJPY-basierte VermögensentwicklungLiniendiagramm der points (wiederhergestellte Werte) aus Ausgabepunkt 2 + letzter Punkt current (gemessen) mit separater Markierung. reconstructed from current balances; last point measured und die Netto-Einzahlung (flow.net_flow_jpy) während des Zeitraums deutlich in der Grafik vermerken, um zu verhindern, dass eine Erhöhung durch Einzahlung als Wertsteigerung gelesen wird. Wenn price_quality.level nicht complete ist, darauf hinweisen, dass einige Vermögenswerte mit dem aktuellen Kurs bewertet wurden; wenn warnings vorhanden sind, eine Zusammenfassung dieser ebenfalls anfügen

Diagrammspezifische Hinweise:

  • Die Beträge und Anteile in der Grafik müssen mit den Tabellen im Text übereinstimmen (Die gleiche Konsistenzprüfung wie bei der Validierungsschleife gilt auch für die Grafik)
  • Etiketten-Disziplin für allocation (Legendenformat ist Standard):
    • In der Legende die Werte im Format BTC 79,8% (47.997 JPY) mit Name, Anteil und Betrag auflisten
    • Prozentangaben in den Tortenstücken nur bei großen Stücken (Richtwert ab 10%). Kleine Stücke in der Legende lesen
    • Keine Perimeter-Etiketten mit Ausziehlinien verwenden (bei benachbarten kleinen Stücken kommt es zu Etikettenüberlagerungen. Die Legende wird von matplotlib automatisch platziert, so dass Überschneidungen strukturell vermieden werden)
  • Kleinbetrag-Zusammenfassungsregel für allocation (bitbank unterstützt über 40 Werte, um eine Zersplitterung des JPY durch viele Werte und Staubbestände zu vermeiden):
    • Werte mit einem Anteil unter 3% werden zu „Others“ zusammengefasst (Schwellenwert kann vom Benutzer geändert werden)
    • Auch oberhalb des Schwellenwerts sind maximal 6 Stücke + Others erlaubt (Überschüssige werden aufsteigend nach Größe zu Others hinzugefügt)
    • Die Anzahl, den Gesamtanteil und die wichtigsten Bestandteile von Others in der Legende oder Fußnote angeben (z. B. Others = XRP, DOGE und 5 weitere Werte (insgesamt 4,2%))
    • JPY (Bargeld) bleibt unabhängig vom Anteil ein eigenes Stück (die Bargeldreserve ist ein erstklassiges Entscheidungskriterium und wird nicht in Others gefaltet)
    • Die vollständige Aufschlüsselung aller Werte muss immer in der Texttabelle erhalten bleiben (Diagramme ersetzen den Text nicht). Für die Staubüberprüfung die horizontale Balkenansicht (alle Werte) verwenden
  • Enthält Kontoinformationen (Bewertung, Bestand), daher Vorsicht beim Teilen von Bildern. Wenn der Benutzer ausdrücklich erklärt, dass das Teilen beabsichtigt ist, eine Anzeige nur der Anteile ohne absolute Beträge vorschlagen (siehe Sicherheitsdisziplin in visualization-guide.md)
  • Die historischen Punkte in value-history sind durch Rückrechnung wiederhergestellte Werte und keine damaligen Guthaben-Momentaufnahmen; nur der letzte Punkt ist gemessen. Diese Annahme und die Netto-Einzahlung während des Zeitraums dürfen in der Grafik nicht weggelassen werden (gleiche Verpflichtung wie für den Text. Dadurch wird verhindert, dass jemand, der nur die Grafik sieht, „Es ist gestiegen“ liest). Wenn completeness.complete false ist, dies ebenfalls in der Grafik vermerken

Gotchas (Fallstricke)

  • Beträge werden als Zeichenketten zurückgegeben. Wenn die Umwandlung in Zahlen vergessen wird, kommt es zu einer Zeichenkettenverkettung, und die Bewertung wird vollständig zerstört. Alle Felder von assets und die Tickerkurse sind Zeichenketten.
  • Achtung vor locked_amount. Vermögenswerte in offenen Orders landen in locked_amount. Für die Anzeige onhand_amount (Gesamtmenge) verwenden. Wenn nur free_amount betrachtet wird, verschwinden die in Orders gebundenen Vermögenswerte.
  • JPY hat keinen Ticker. Der „Kurs“ von JPY ist immer 1. Der Versuch, ihn über den Ticker abzurufen, führt zu einem Fehler.
  • Die Werte von balance-history nicht neu berechnen. Das Multiplizieren von Beständen mit historischen Kursen, um eine Entwicklung zu konstruieren, ist die Vorgehensweise der alten Implementierung und führt bei Sparplänen zu großen Abweichungen vom tatsächlichen Guthaben (Ursache von Fehlinterpretationen). Wenn eine Entwicklung benötigt wird, immer diesen Befehl aufrufen.
  • --days und --since schließen sich gegenseitig aus (gleichzeitige Angabe führt zu einem Fehler). Standard ist die letzten 30 Tage, täglich. Für Fenster über 1 Jahr --granularity=month verwenden (täglich würde aufgrund des Rasterlimits die ältere Seite abschneiden).
  • Kein stillschweigendes Hinnehmen von Abschneidungen. Wenn completeness.complete: false / partial: true erscheint, --max-pages erhöhen oder das Fenster verkleinern und erneut ausführen. Wenn es sich nicht beheben lässt, die wiederhergestellten Werte nicht verwenden und den Benutzer darüber informieren (bereits das Fehlen eines einzigen Verlaufseintrags verschiebt die historischen Punkte leise).
  • Margin-Handel und Verkaufsstelle werden nicht in der Entwicklung abgebildet. Margingeschäfte bewegen das Spot-Guthaben nicht und sind daher von der Rückrechnung ausgeschlossen; Trades über die Verkaufsstelle (Sofortkauf/-verkauf) erscheinen nicht in der API. Beides erscheint in warnings / assumptions und wird so weitergegeben.
  • Die Gesamtbewertung von Ausgabepunkt 1 und current.value_jpy können unterschiedlich sein. balance-history addiert das sich in der Auszahlung befindliche Guthaben (withdrawing_amount) zum tatsächlichen Guthaben, daher ist der Wert bei vorhandenem Auszahlungsguthaben entsprechend höher. Dies nicht als „Rechenfehler“ melden.
  • Bei API-Fehlern siehe _shared/references/bitbank-api-formats.md
  • Fehler 20001 (Authentifizierungsfehler) → Den Benutzer anweisen, die Einstellungen in .env zu überprüfen.

Verwandte Skills