Portfolio Skill
When to Use
Beyond the representative triggers, this skill is activated by utterances like:
- "I want to see asset trends" / "Check the ratio of my holdings"
- "Has my portfolio decreased?" / "How much is it worth in JPY?"
- General questions about holdings, balances, profits and losses
How to Answer "Is there any unrealized profit?"
This skill does not have the acquisition cost, so it cannot provide unrealized profit/loss (the difference between acquisition cost and market value). For this utterance, do not just redirect to tax-report; respond in the following order:
- Show the current valuation and composition (output item 1)
- If desired, show the asset trend (output item 2) and indicate the increase/decrease excluding deposits/withdrawals
- Then explain, "Determining unrealized profit/loss requires acquisition cost, which is handled by
tax-report(the reference profit/loss intax pnl)."
Do not call adjusted change unrealized profit/loss. That is the change in valuation excluding deposits/withdrawals, not a cost‑basis profit/loss (the same valuation can yield different unrealized profits depending on when assets were bought).
Prerequisites: Private API Authentication Setup
To use private API commands (assets / balance-history), you need API key/secret. See "Authentication" in _shared/references/cli-conventions.md for details.
Recommended: Profile (profiles.json)
bitbank profile add main # Register once (secret is hidden input)
bitbank assets --format=json --machine # Uses default profile
bitbank --profile=sub assets --format=json --machine # Switch to another account
Legacy Compatibility: env vars
set -a; source .env; set +a
bitbank assets --format=json --machine
If API keys are not set: Guide the user to run bitbank profile add <name> and perform analysis using only Public API (ticker, candles).
Analysis Flow
Step 1: Get Holdings
bitbank assets --format=json --machine # Just run when using profile
# legacy: set -a; source .env; set +a; bitbank assets --format=json --machine
Step 2: Get Current Prices
Fetch all JPY pair tickers at once:
bitbank tickers-jpy --format=json --machine
Step 3: Get Asset Trend (only when output item 2 is needed)
# Default is last 30 days, daily
bitbank balance-history --format=json --machine
# Specify period and granularity (--days and --since cannot be used together)
bitbank balance-history --days=365 --granularity=month --format=json --machine
bitbank balance-history --since=1735689600000 --granularity=day --format=json --machine
This command handles reconstruction, valuation, and deposit/withdrawal adjustment all in one. It back‑calculates from the current balance using order and deposit/withdrawal history, reconstructs holdings at each point, and values them at that day's 1‑day candle open. The result is returned ready to use. The model does not perform multiplication (this skill does no calculations). It only reads and presents the returned points / current / flow / change / price_quality / completeness / warnings / note / assumptions.
Step 4: Output
Output item 1 derives the valuation and ratios from Steps 1 and 2. Output item 2 presents the exact values from Step 3 (no recalculation).
Output Items
1. Current Asset Composition
List holdings, valuations, and ratios.
=== Asset Composition ===
Total Valuation: 2,500,000 JPY
Asset | Holdings | Valuation | Ratio
JPY | 500,000 | 500,000 | 20.0%
BTC | 0.15 | 1,387,500 | 55.5%
ETH | 2.0 | 612,500 | 24.5%
- Valuation = Holdings × ticker
lastprice (JPY = 1) - Ratio = Asset valuation / Total valuation
2. JPY‑Denominated Asset Trend
Present the results of Step 3 (balance-history). Maintain the following order. Do not place assumptions after the table — the order itself is a specification (see below for reasoning).
- Assumptions (
note/assumptions) - Warnings (
warnings/completeness/price_quality) — if any - Change breakdown (
change/flow) - Trend table (
points+ final pointcurrent)
=== Asset Trend (2025-08-01 to 2026-08-11, monthly) ===
Assumptions (read before the table):
- Holdings at each point are reconstructed by back‑calculating from the current balance using order and deposit/withdrawal history, not a snapshot of the balance at that time.
- Valuation uses the 1‑day candle open at the UTC day boundary. Assets for which historical prices are unavailable are substituted with the current price.
- The final row "Current" is not a reconstructed value but an actual measurement (ticker last × current holdings. It may include assets in withdrawal processing, so it may not match the total valuation in output item 1).
- Trades on the instant exchange (Tori‑sho) do not appear in the API and are therefore not reflected.
Change Breakdown:
Simple change : +150,000 JPY (+6.5%) Difference in valuation from start
Net deposits/withdrawals: +120,000 JPY Deposits − withdrawals (principal only)
Adjusted change : +30,000 JPY (+1.3%) Simple change − net deposits/withdrawals
Withdrawal fees : 770 JPY Already included in the adjusted change above
Date | Valuation (JPY) | Change from Previous
2025-08-01 | 2,300,000 | -
2025-09-01 | 2,180,000 | -5.2%
...
2026-08-01 | 2,420,000 | +1.7%
Current (measured) | 2,450,000 | +1.2%
Presentation Discipline
- Do not highlight only the simple change. Presenting "+150,000 JPY" alone fails to convey that 120,000 JPY of that is a deposit. Always present all three: simple change, net deposits/withdrawals, and adjusted change (showing these three separately is the very purpose of this item).
- Do not suppress
warnings; convey them in full. Do not summarize, omit, or add remarks like "minor." In particular, whencompleteness.completeisfalse(history truncated due to page limits or grid thinning), state clearly before the table that "the reconstructed values may not be reliable" and treat the numbers as approximate. flow.withdrawal_fee_jpyis a positive total fee. Do not invert the sign and show it as "−770." Its cost effect is already built intoadjusted_change_jpy, so do not subtract it again in the breakdown.- Do not trim
assumptions. The assumptions block should directly reflect the output'snote/assumptions. Do not paraphrase in your own words in a way that omits conditions. - When
price_quality.levelis notcomplete, name the specificfallback_assets(those assets' past valuations are substituted with the current price). - If
partial: true/meta.truncatedappears in the envelope, report that as well.
Location of Assumptions (The text carries the same obligation as a chart)
"Reconstructed values; only the final point is measured" must appear before the table. This obligation applies to the text with the same intensity as the annotation obligation required for charts in the visualization section. Placing a small note after a 20‑line table is equivalent to having no note at all. Misunderstandings in previous implementations arose precisely because the note was placed after the table.
Self‑Validation Loop
Validation for output item 1. Currency errors directly affect user investment decisions, so avoid output without validation. Output item 2 comes from CLI‑computed deterministic values, so do not recalculate or cross‑check (re‑computing numbers would violate this skill's "no calculation" principle).
- Does the sum of each asset’s valuation equal the total valuation? If not, there's a calculation omission.
- Do the ratios sum to 100%? Rounding errors (±0.1%) are acceptable; larger deviations indicate a calculation error.
- Is JPY valuation equal to its holding amount? Multiplying JPY by a ticker price is incorrect.
- Is the valuation within a realistic range? 0.01 BTC valued at billions of yen clearly indicates a number conversion error.
If inconsistencies are found, identify the cause, correct, and then output.
Visualization (Optional)
Adhere to trigger discipline, execution environment resolution, output destination, style, and safety rules in _shared/references/visualization-guide.md. Default is off (only draw when the user explicitly requests it, or upon agreement to a suggestion). Charts are drawn after the text output (asset composition and asset trend tables), not as a replacement.
Standard charts for this skill:
| Chart ID | Content | Main Components |
|---|---|---|
portfolio.allocation | Asset composition | Donut chart of valuation ratios from output item 1 (sorted by valuation descending, includes JPY cash, total valuation in center). Labels default to legend style; small slices aggregated into Others (see below). Footer shows ticker retrieval time. Option to switch to horizontal bar for detailed comparison |
portfolio.value-history | JPY‑denominated asset trend | Line chart of points (reconstructed values) with final point current (measured) marked differently. Clearly state reconstructed from current balances; last point measured and net deposits/withdrawals (flow.net_flow_jpy) in the figure to prevent deposit‑driven increases from being mistaken as price appreciation. If price_quality.level is not complete, note that some assets are valued using current price; if there are warnings, include a summary |
Chart‑specific notes:
- Ensure figures match the corresponding tables in the text (apply the same consistency validation to charts as in the Validation Loop).
allocationlabel discipline (legend style default):- In the legend, list symbol, ratio, and value in the format
BTC 79.8% (47,997 JPY). - In‑slice % annotations only for large slices (~10% or more). Small slices are read from the legend.
- Do not use outer labels with leader lines (they interfere when small slices are adjacent; matplotlib auto‑positions the legend to avoid overlap).
- In the legend, list symbol, ratio, and value in the format
allocationsmall slice aggregation rule (bitbank supports over 40 symbols; prevents fragmentation from many small holdings and dust):- Symbols with a ratio less than 3% are aggregated into "Others" (threshold is adjustable by the user).
- Even if above the threshold, limit slices to maximum 6 + Others (the smallest ones go to Others).
- In the legend or footnote, indicate the count, total ratio, and main constituents of Others (e.g.,
Others = XRP, DOGE and 5 others (total 4.2%)). - JPY (cash) is always an independent slice regardless of ratio (cash power is a primary decision factor, so it must not be folded into Others).
- Always keep the complete breakdown for all symbols in the text table (charts do not replace the text). For dust scrutiny, use the horizontal bar version (full symbol list).
- Contains account information (valuation, holdings), so be careful when sharing images. If the user explicitly states they intend to share, suggest displaying only ratios without absolute amounts (see safety rules in
visualization-guide.md). - Past points in
value-historyare reconstructed by back‑calculation, not snapshots of the balance at that time; only the final point is measured. Do not omit this assumption and the net deposits/withdrawals from the figure's annotation (same obligation as for the text; prevents someone who only looks at the chart from thinking "it increased"). Whencompleteness.completeisfalse, also state that in the figure.
Gotchas
- Amounts are returned as strings. Forgetting to convert to numbers will result in string concatenation, completely breaking the valuation. All fields in
assetsand ticker prices are strings. - Pay attention to
locked_amount. Assets in orders appear inlocked_amount. Useonhand_amount(total amount) for display. Using onlyfree_amountwill omit assets in orders. - JPY has no ticker. JPY's "price" is always 1. Attempting to fetch it via ticker will cause an error.
- Do not reconstruct
balance-historyvalues. Building a trend by multiplying holdings with historical prices is the old implementation method; for accumulation accounts it will differ significantly from actual balances (the root cause of misinterpretation). When a trend is needed, always call this CLI command. --daysand--sincecannot be used together (specifying both will error). Default is last 30 days, daily. For windows exceeding 1 year, use--granularity=month(daily will drop the older side due to the grid limit).- Do not silently pass truncation. If
completeness.complete: false/partial: trueappears, either increase--max-pagesor narrow the window and rerun. If it cannot be fixed, do not use the reconstructed values and inform the user accordingly (even one missing history item silently shifts past points). - Margin trades and instant exchange trades are not reflected in the trend. Margin trades don't move spot balances and are excluded from back‑calculation; instant exchange trades do not appear in the API. Both are noted in
warnings/assumptions— convey them as‑is. - The total valuation in output item 1 and
current.value_jpymay not match exactly.balance-historyadds back assets in withdrawal processing (withdrawing_amount) to the actual balance, so if there are assets under withdrawal, that value will be larger. Do not report this as a "calculation error." - For API errors, refer to
_shared/references/bitbank-api-formats.md. - For error 20001 (authentication failure), guide the user to check the
.envconfiguration.