포트폴리오 Skill
언제 사용하나요
대표 트리거 외에도 다음과 같은 발화로 실행됩니다:
- "자산 추이를 보고 싶어", "보유 자산 비율을 확인해줘"
- "자산이 줄지 않았어?", "JPY로 환산하면 얼마야?"
- 보유 자산, 잔고, 손익에 관한 질문 전반
"평가 손익 있어?" 에 대한 답변 방법
본 Skill은 취득 원가를 가지고 있지 않으므로, 평가 손익 (취득 원가와 시가의 차이)은 알 수 없습니다. 이 발화에 대해 tax-report로 바로 넘기지 않고, 다음 순서로 답변합니다:
- 현재 평가액과 구성 (출력 항목 1)을 제시합니다.
- 원한다면 자산 추이 (출력 항목 2)를 보여주고, 입출금을 제외한 증감을 나타냅니다.
- 그 위에 "평가 손익 판단에는 취득 원가가 필요하며, 그것은 tax-report (
tax pnl의 참고 손익) 담당입니다" 라고 안내합니다.
조정 후 증감 을 평가 손익이라고 부르지 않습니다. 그것은 입출금을 제외한 평가액 증감으로, 취득 원가 기반의 손익이 아닙니다 (같은 평가액이라도 언제 샀는지에 따라 평가 손익은 달라집니다).
전제: Private API 인증 설정
Private API 명령어 (assets / balance-history)를 사용하려면 API 키 / 시크릿을 설정해야 합니다. 자세한 내용은 _shared/references/cli-conventions.md 의 "인증"을 참조하세요.
권장: 프로필 (profiles.json)
bitbank profile add main # 한 번만 등록 (시크릿은 대화형으로 숨겨서 입력)
bitbank assets --format=json --machine # default 프로필이 사용됨
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 # 프로필 사용시 그대로 실행
# 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
이 명령어는 복원, 평가, 입출금 조정까지 모두 수행합니다. 현재 잔고에서 체결/입출금을 역산하여 각 시점의 보유를 복원하고, 해당일의 1day 봉 open으로 평가한 결과를 반환합니다. 모델은 곱셈을 수행하지 않습니다 (본 Skill은 계산을 하지 않습니다). 반환값의 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)의 결과를 제시합니다. 다음 순서를 지킵니다. 전제를 표 뒤로 미루지 않습니다 — 순서 자체가 사양입니다 (이유는 아래 "전제의 제시 위치").
- 전제 (
note/assumptions) - 경고 (
warnings/completeness/price_quality) — 있으면 - 증감 내역 (
change/flow) - 추이 테이블 (
points+ 최종점current)
=== 자산 추이 (2025-08-01 ~ 2026-08-11 · 월별) ===
전제 (표보다 먼저 읽음):
- 각 시점의 보유는 현재 잔고에서 체결·입출금을 역산하여 복원한 값으로,
당시의 잔고 스냅샷이 아닙니다.
- 평가는 각 시점의 1day 봉 open (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엔이 입금임을 전달할 수 없습니다. 단순 증감·순 입출금·조정 후 증감은 반드시 3개를 모두 표시합니다 (이 3개를 나누어 보여주는 것이 이 항목의 목적 그 자체입니다).
warnings는 숨기지 않고 전문을 전달합니다. 요약·생략·"경미합니다" 첨언을 하지 않습니다. 특히completeness.complete가false(이력이 페이지 상한으로 잘렸거나 / 그리드를 간추린 경우) 일 때는 표보다 먼저 "복원값을 신뢰할 수 없습니다" 라고 명시하고, 수치는 참고값으로 다룬다는 점을 첨부합니다.flow.withdrawal_fee_jpy는 양수 수수료 합계입니다. 부호를 반전시켜 "−770"처럼 표시하지 않습니다. 비용으로서의 효과는adjusted_change_jpy쪽에 이미 포함되어 있으므로, 내역에서 이중으로 빼지 않습니다.assumptions도 삭제하지 않습니다. 전제 블록은 출력의note/assumptions를 그대로 가져옵니다. 자신의 말로 짧게 바꿔 쓰거나 조건을 누락하지 않습니다.price_quality.level이complete가 아닐 때는fallback_assets를 지목하여 언급합니다 (해당 자산의 과거 평가는 현재 가격으로 대체되었습니다).partial: true/meta.truncated가 envelope에 있으면 그것도 함께 보고합니다.
전제의 제시 위치 (텍스트에도 그림과 같은 의무가 있습니다)
"복원값이며 최종점만 실측이다"라는 점은 표 앞에 둡니다. 시각화 절이 차트에 부과하는 주석 의무와 같은 강도의 의무를 텍스트 쪽에도 부과합니다. 20행 표의 뒤에 작게 첨부하는 것은, 주석이 없는 것과 같은 취급으로 합니다 (구 구현의 오독은 바로 주석이 표 뒤에 있었기 때문에 발생했습니다).
자체 점검 (Validation Loop)
출력 항목 1 용 검증입니다. 금액 오류는 사용자의 투자 판단에 직접 영향을 미치므로, 검증 없이 출력을 피합니다. 출력 항목 2는 CLI가 계산한 확정값이므로 재계산하여 대조하지 않습니다 (숫자를 새로 만든 시점에서 본 Skill의 "계산하지 않음" 원칙에서 벗어납니다).
- 각 자산 평가액 합계 = 총 평가액 인가? 불일치면 계산 누락
- 비율 합계가 100% 인가? 반올림 오차 (±0.1%)는 허용하지만, 크게 벗어나면 계산 오류
- JPY 평가액 = 보유량 그 자체인가? JPY에 ticker 가격을 곱했다면 오류
- 평가액이 현실적인 범위인가? BTC 0.01개로 수십억 엔 등, 자릿수가 명백히 이상하면 수치 변환 오류 가능성
불일치가 있으면 원인을 특정하고 수정한 후 출력합니다.
시각화 (선택 사항)
트리거 규율·실행 환경 해결·출력처·스타일·안전 규율은 _shared/references/visualization-guide.md를 따릅니다. 기본값은 off (사용자가 명시적으로 요청했을 때, 또는 제안에 동의했을 때만 그림). 차트는 텍스트 출력 (자산 구성·자산 추이 테이블) 이후에 그리며, 그 대체로 사용하지 않습니다.
본 Skill의 표준 차트:
| 차트 ID | 내용 | 주요 구성 요소 |
|---|---|---|
portfolio.allocation | 자산 구성 | 출력 항목 1의 평가액 비율 도넛 (평가액 큰 순, JPY 현금 포함, 중앙에 총 평가액). 라벨은 범례 방식이 기본, 소액은 Others로 집계 (모두 아래 참조). ticker 획득 시간을 푸터에. 상세 비교용 가로 막대 버전으로 전환 가능 |
portfolio.value-history | JPY 기준 자산 추이 | 출력 항목 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를 올리거나 창을 좁혀 재실행합니다. 고쳐지지 않으면 복원값을 사용하지 않고, 그 점을 사용자에게 전달합니다 (이력이 1건 부족한 것만으로도 과거의 점은 조용히 어긋납니다). - 신용 거래·판매소는 추이에 반영되지 않습니다. 신용 체결은 현물 잔고를 움직이지 않으므로 되감기에서 제외되며, 판매소 (즉시 매매) 거래는 API에 나타나지 않습니다. 둘 다
warnings/assumptions에 나오므로 그대로 전달합니다. - 출력 항목 1의 총 평가액과
current.value_jpy는 완전히 일치하지 않을 수 있습니다.balance-history는 출금 신청 중 (withdrawing_amount)을 실잔고에 다시 더하기 때문에, 신청 중인 자산이 있으면 그만큼 커집니다. 차이를 "계산 오류"로 보고하지 마세요. - API 오류시
_shared/references/bitbank-api-formats.md를 참조하세요. - 20001 오류 (인증 실패) →
.env설정을 확인하도록 사용자에게 안내합니다.