Communitygithub.com

bitbankinc/bitbank-lab-cli

從 bitbank 的資產和價格數據,掌握投資組合現況(資產構成、JPY 計價評估值、經出入金調整後的資產走勢)。

bitbank-lab-cli 是什麼?

此技能(Skill)名為「投資組合 Skill」,專用於 bitbank 交易所用戶,能透過 CLI 工具快速掌握其資產組合現況。它會擷取用戶的資產餘額與即時價格,自動計算出各資產的評估值與佔比,並以表格或圖表呈現當前資產構成。此外,它還能利用 `balance-history` 命令取得經出入金調整後的資產走勢圖,讓用戶清楚了解淨值變化的真正原因(是市場波動還是資金進出)。此技能支援 Claude Code、Coder 等 AI Agent,並整合 bitbank 的 Public 與 Private API。它特別強調「不計算浮動損益」,因為缺乏取得成本資訊,若用戶需要估算獲利/虧損,會引導至 tax-report 技能。此技能也內建嚴謹的輸出驗證迴圈,確保金額與比例的正確性,同時提供可選的圖表視覺化功能,但預設為關閉,需用戶明確要求才繪製。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/bitbankinc/bitbank-lab-cli/tree/HEAD/skills/portfolio

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

投資組合 Skill

何時使用

除了代表觸發詞之外,也可由以下對話啟動:

  • 「我想看資產走勢」「確認持有資產的比例」
  • 「資產有減少嗎?」「換算成 JPY 是多少?」
  • 關於持有資產、餘額、損益的各種問題

如何回答「有浮動損益嗎?」

本技能沒有取得成本,因此無法計算浮動損益(取得成本與市價的差)。 遇到此問題時,不要直接推給 tax-report,而是依序回答:

  1. 先顯示目前的評估值與構成(輸出項目 1)
  2. 如果用戶想要,再顯示資產走勢(輸出項目 2),並標示扣除出入金後的增減
  3. 最後說明「要判斷浮動損益需要取得成本,這屬於 tax-report(tax pnl 的參考損益)的職責」

請勿將 調整後增減 稱作浮動損益。 這只是扣除出入金後的評估值增減,並非基於取得成本的損益(即使評估值相同,因買入時間不同,浮動損益也會不同)。

前提:Private API 認證設定

使用 Private API 命令(assets / balance-history)需要設定 API 金鑰 / 密鑰。詳細請參閱 _shared/references/cli-conventions.md 中的「認證」章節。

建議:使用 profile(profiles.json)

bitbank profile add main                    # 僅需註冊一次(secret 會以對話隱藏輸入)
bitbank assets --format=json --machine      # 使用 default profile
bitbank --profile=sub assets --format=json --machine   # 切換至其他帳戶

向後相容:使用環境變數

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

若未設定 API 金鑰: 請引導用戶執行 bitbank profile add <name>,並僅使用 Public API(ticker, candles)進行分析。

分析流程

Step 1: 取得持有資產

bitbank assets --format=json --machine   # 使用 profile 時直接執行
# legacy: set -a; source .env; set +a; bitbank assets --format=json --machine

Step 2: 取得目前價格

一次取得所有 JPY 交易對的 ticker:

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

Step 3: 取得資產走勢(僅在需要輸出項目 2 時)

# 預設為最近 30 天、每日
bitbank balance-history --format=json --machine

# 可指定期間與粒度(--days 與 --since 不可同時使用)
bitbank balance-history --days=365 --granularity=month --format=json --machine
bitbank balance-history --since=1735689600000 --granularity=day --format=json --machine

此命令包含還原、評估、出入金調整等所有步驟。它會從目前餘額反向推算成交與出入金,還原各時間點的持有量,並以當日 1 日 K 線開盤價評估,然後直接回傳結果。 模型不需進行乘法運算(本技能不執行計算)。只需讀取回傳值中的 points / current / flow / change / price_quality / completeness / warnings / note / assumptions 並呈現即可。

Step 4: 輸出

輸出項目 1 由模型根據 Step 1 / 2 的資料計算評估值與比例。 輸出項目 2 則直接呈現 Step 3 的確定值(不進行重新計算)。

輸出項目

1. 目前資產構成

列出持有資產、評估值、比例。

=== 資產構成 ===

總評估值: 2,500,000 JPY

資產  | 持有量   | 評估值      | 比例
JPY  | 500,000 | 500,000    | 20.0%
BTC  | 0.15    | 1,387,500  | 55.5%
ETH  | 2.0     | 612,500    | 24.5%
  • 評估值 = 持有量 × ticker 的 last 價格(JPY 為 1)
  • 比例 = 各資產的評估值 / 總評估值

2. JPY 計價資產走勢

呈現 Step 3(balance-history)的結果。請遵守以下順序。不要將前提移到表格之後 — 順序本身就是規格的一部分(理由請見下方「前提的顯示位置」)。

  1. 前提(note / assumptions)
  2. 警告(warnings / completeness / price_quality)— 如果有的話
  3. 增減的明細(change / flow)
  4. 走勢表格(points + 最終點 current)
=== 資產走勢(2025-08-01 〜 2026-08-11・月次) ===

前提(請在閱讀表格前先看):
- 各時間點的持有量是從目前餘額反向推算成交與出入金後還原的值,
  並非當時的餘額快照
- 評估採用各時間點的 1 日 K 線開盤價(UTC 日邊界)。無法取得的資產以目前價格代替
- 只有最後一行「目前」是實際測量值(ticker last × 目前餘額。
  包含正在提幣申請中的資產,因此可能與輸出項目 1 的總評估值不一致)
- 販賣所(即時買賣)的交易不會出現在 API 中,因此不納入反映

增減的明細:
  單純增減      : +150,000 JPY (+6.5%)   期初以來的評估值差
  其中純出入金  : +120,000 JPY           入金 − 出金(僅本金移動)
  調整後增減    :  +30,000 JPY (+1.3%)   單純增減 − 純出入金
  提幣手續費    :      770 JPY           上述調整後增減已包含

日期         | 評估值(JPY) | 與前一期的變動
2025-08-01  |  2,300,000 | -
2025-09-01  |  2,180,000 | -5.2%
...
2026-08-01  |  2,420,000 | +1.7%
目前(實際)   |  2,450,000 | +1.2%

呈現紀律

  • 不要只將單純增減作為標題。 如果僅顯示「+150,000 日圓」,將無法傳達其中有 120,000 日是來自入金。必須同時呈現單純增減、純出入金、調整後增減這三項(將這三項分開呈現是本輸出項目的核心目的)
  • 不要隱藏 warnings,必須完整傳達。 不要摘要、省略或加上「影響輕微」。特別是當 completeness.complete 為 false(歷史紀錄因頁數上限被截斷 / 網格被稀疏化)時,必須在表格之前明確聲明「還原值不可靠」,並補充數值僅供參考
  • flow.withdrawal_fee_jpy 是正數的手續費總額。 不要反轉符號顯示為「−770」。作為成本的效果已經內含在 adjusted_change_jpy 中,請勿在明細中重複扣除
  • 不要省略 assumptions。 前提區塊應直接引用輸出的 note / assumptions。不要用自己的話簡短改寫,以免遺漏條件
  • 若 price_quality.level 不是 complete,請指名列出 fallback_assets(該資產的歷史評估值已用目前價格代替)
  • 若 envelope 中有 partial: true / meta.truncated,也需一併報告

前提的顯示位置(文字與圖表有相同的義務)

「這是還原值、僅最終點是實際測量值」必須放在表格之前。 我們對文字部分賦予與可視化章節對圖表相同的義務強度。 在 20 行的表格之後用小字補充,等同於沒有註記 (舊實作的誤讀正是因為註記被放在表格之後)。

自我檢查(Validation Loop)

用於輸出項目 1 的驗證。金額錯誤會直接影響用戶的投資決策,因此應避免未經驗證就輸出。 輸出項目 2 是 CLI 計算的確定值,因此不要重新計算後進行比對(一旦重新計算數字,就偏離了本技能「不計算」的原則)。

  1. 各資產評估值的總和是否等於總評估值? 不一致則表示計算有遺漏
  2. 比例的總和是否為 100%? 可允許四捨五入誤差(±0.1%),但若偏離過大則表示計算錯誤
  3. JPY 的評估值是否等於持有量本身? 若將 JPY 乘以 ticker 價格則為錯誤
  4. 評估值是否在合理範圍內? 若 BTC 0.01 枚價值數十億日圓等明顯異常,則可能是數值轉換錯誤

若發現不一致,請找出原因並修正後再輸出。

可視化(選用)

觸發紀律、執行環境解決、輸出目標、樣式、安全紀律請遵循 _shared/references/visualization-guide.md。預設為關閉(僅在用戶明確要求或同意建議時才繪製)。 圖表應在文字輸出(資產構成、資產走勢表格)之後繪製,不可取代文字輸出。

本技能的標準圖表:

圖表 ID內容主要構成要素
portfolio.allocation資產構成輸出項目 1 的評估值比例的甜甜圈圖(依評估值由大到小排序,包含 JPY 現金,中央顯示總評估值)。標籤預設使用圖例方式,小額部分合併為 Others(詳見下方)。ticker 取得時間顯示在底部。可切換橫條圖版本以進行詳細比較
portfolio.value-historyJPY 計價資產走勢輸出項目 2 的 points(還原值)折線圖,加上最終點 current(實際值)以不同標記顯示。圖中需明確標示 reconstructed from current balances; last point measured 以及期間內的純出入金(flow.net_flow_jpy),避免將入金造成的增加解讀為價格上漲。若 price_quality.level 不是 complete,需標明有資產以目前價格代替評估;若有 warnings,也需附上摘要

圖表專用注意事項:

  • 圖中的金額與比例必須與本文的表格一致(對圖表也適用與 Validation Loop 相同的完整性檢查)
  • allocation 的標籤紀律(預設使用圖例方式):
    • 在圖例中以 BTC 79.8% (47,997 JPY) 格式列出幣種、比例、金額
    • 扇形內的百分比註記僅用於較大的扇形(建議 10% 以上)。 小扇形在圖例中閱讀即可
    • 不使用外部標籤加引導線(小扇形相鄰時標籤會互相干擾。圖例由 matplotlib 自動佈局,結構上不會發生重疊)
  • allocation 的小額合併規則(bitbank 支援超過 40 種幣種,可防止因多幣種、灰塵持有導致圓餅圖破碎):
    • 比例低於 3% 的幣種合併為「Others」(閾值可依用戶指定調整)
    • 即使超過閾值,扇形最多 6 個 + Others(超出的部分依比例從小到大合併至 Others)
    • 在圖例或腳註中註明 Others 的數量、合計比例、主要內容 (例如:Others = XRP、DOGE 及其他 5 種幣種(共 4.2%))
    • JPY(現金)無論比例大小,均作為獨立扇形(現金餘力是重要的判斷依據,不可併入 Others)
    • 所有幣種的完整明細必須保留在文字表格中(圖表不可取代文字)。灰塵審查請使用橫條圖版本(顯示所有幣種)
  • 因包含帳戶資訊(評估值、持有量),分享圖片時請留意。若用戶明確表示可分享,則建議顯示不含絕對金額、僅有比例的版本(請參考 visualization-guide.md 的安全紀律)
  • value-history 的過去點是透過反向推算還原,並非當時的餘額快照,僅最終點是實際測量值。請勿省略圖中的此前提註記以及期間內的純出入金(與本文文字相同的義務,避免僅看圖表就誤解為「增加了」)。當 completeness.complete 為 false 時,也需在圖中標明

易犯錯誤(Gotchas)

  • 金額以字串回傳。 若忘記轉換為數值,會導致字串串接,使評估值完全錯誤。assets 的各欄位、ticker 的價格皆為字串
  • 注意 locked_amount。 掛單中的資產會進入 locked_amount。顯示時請使用 onhand_amount(總量)。若只看 free_amount,將遺漏掛單中的資產
  • JPY 沒有 ticker。 JPY 的「價格」恆為 1。若嘗試透過 ticker 取得會發生錯誤
  • 不要重新計算 balance-history 的值。 將持有量乘以歷史價格來建構走勢是舊實作的方法,對於定期定額帳戶會與實際餘額產生巨大偏差(造成誤讀的原因)。需要走勢時,請務必呼叫此命令
  • --days 與 --since 不可同時使用(同時指定會發生錯誤)。預設為最近 30 天、每日。超過 1 年的區間請使用 --granularity=month(每日會因網格上限而遺漏較舊的資料)
  • 不要默默接受截斷。 若出現 completeness.complete: false / partial: true,請嘗試提高 --max-pages 或縮小區間後重新執行。若仍無法解決,則不使用還原值,並向用戶說明情況(只要缺少一筆歷史紀錄,過去的點就會靜態地偏移)
  • 保證金交易、販賣所不會反映在走勢中。 保證金成交不會變動現貨餘額,因此被排除在還原之外;販賣所(即時買賣)的交易不會出現在 API 中。 兩者皆會出現於 warnings / assumptions,請直接傳達
  • 輸出項目 1 的總評估值與 current.value_jpy 可能不完全一致。 balance-history 會將提幣申請中(withdrawing_amount)加回實際餘額,因此若有申請中的資產,該部分會較大。請勿將此差異回報為「計算錯誤」
  • API 錯誤時請參閱 _shared/references/bitbank-api-formats.md
  • 20001 錯誤(認證失敗) → 請引導用戶檢查 .env 的設定

相關技能