Communitygithub.com

bitbankinc/bitbank-lab-cli

bitbank의 보유 자산과 가격 데이터로부터 포트폴리오 현황(자산 구성, JPY 기준 평가액, 입출금을 조정한 자산 추이)을 파악합니다.

bitbank-lab-cli란 무엇인가요?

이 스킬은 사용자의 bitbank 거래소 계정에서 보유 자산 목록과 실시간 가격 데이터를 가져와 포트폴리오의 현재 상태를 종합적으로 분석하여 보여줍니다. 사용자가 "포트폴리오 상황을 보여줘", "지금 얼마 있어?", "최근 손익은?" 같은 질문을 하면 즉시 실행되어 자산 구성 비율, 총 평가액, 그리고 입출금 효과를 제거한 순수 자산 증감 추이를 테이블 형태로 제공합니다. CLI 기반의 bitbank-lab-cli 툴을 통해 Private API로 자산 데이터를, Public API로 현재가를 가져오며, balance-history 명령어를 통해 복원된 과거 자산 추이를 계산합니다. 이 스킬은 매수 원가를 알 수 없으므로 평가 손익 계산은 하지 않으며, 필요시 tax-report 스킬로 안내합니다. 시각화가 필요한 경우 도넛 차트와 선 그래프를 선택적으로 생성하여 텍스트 출력을 보완할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/bitbankinc/bitbank-lab-cli/tree/HEAD/skills/portfolio

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

포트폴리오 Skill

언제 사용하나요

대표 트리거 외에도 다음과 같은 발화로 실행됩니다:

  • "자산 추이를 보고 싶어", "보유 자산 비율을 확인해줘"
  • "자산이 줄지 않았어?", "JPY로 환산하면 얼마야?"
  • 보유 자산, 잔고, 손익에 관한 질문 전반

"평가 손익 있어?" 에 대한 답변 방법

본 Skill은 취득 원가를 가지고 있지 않으므로, 평가 손익 (취득 원가와 시가의 차이)은 알 수 없습니다. 이 발화에 대해 tax-report로 바로 넘기지 않고, 다음 순서로 답변합니다:

  1. 현재 평가액과 구성 (출력 항목 1)을 제시합니다.
  2. 원한다면 자산 추이 (출력 항목 2)를 보여주고, 입출금을 제외한 증감을 나타냅니다.
  3. 그 위에 "평가 손익 판단에는 취득 원가가 필요하며, 그것은 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)의 결과를 제시합니다. 다음 순서를 지킵니다. 전제를 표 뒤로 미루지 않습니다 — 순서 자체가 사양입니다 (이유는 아래 "전제의 제시 위치").

  1. 전제 (note / assumptions)
  2. 경고 (warnings / completeness / price_quality) — 있으면
  3. 증감 내역 (change / flow)
  4. 추이 테이블 (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의 "계산하지 않음" 원칙에서 벗어납니다).

  1. 각 자산 평가액 합계 = 총 평가액 인가? 불일치면 계산 누락
  2. 비율 합계가 100% 인가? 반올림 오차 (±0.1%)는 허용하지만, 크게 벗어나면 계산 오류
  3. JPY 평가액 = 보유량 그 자체인가? JPY에 ticker 가격을 곱했다면 오류
  4. 평가액이 현실적인 범위인가? BTC 0.01개로 수십억 엔 등, 자릿수가 명백히 이상하면 수치 변환 오류 가능성

불일치가 있으면 원인을 특정하고 수정한 후 출력합니다.

시각화 (선택 사항)

트리거 규율·실행 환경 해결·출력처·스타일·안전 규율은 _shared/references/visualization-guide.md를 따릅니다. 기본값은 off (사용자가 명시적으로 요청했을 때, 또는 제안에 동의했을 때만 그림). 차트는 텍스트 출력 (자산 구성·자산 추이 테이블) 이후에 그리며, 그 대체로 사용하지 않습니다.

본 Skill의 표준 차트:

차트 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를 올리거나 창을 좁혀 재실행합니다. 고쳐지지 않으면 복원값을 사용하지 않고, 그 점을 사용자에게 전달합니다 (이력이 1건 부족한 것만으로도 과거의 점은 조용히 어긋납니다).
  • 신용 거래·판매소는 추이에 반영되지 않습니다. 신용 체결은 현물 잔고를 움직이지 않으므로 되감기에서 제외되며, 판매소 (즉시 매매) 거래는 API에 나타나지 않습니다. 둘 다 warnings / assumptions에 나오므로 그대로 전달합니다.
  • 출력 항목 1의 총 평가액과 current.value_jpy는 완전히 일치하지 않을 수 있습니다. balance-history는 출금 신청 중 (withdrawing_amount)을 실잔고에 다시 더하기 때문에, 신청 중인 자산이 있으면 그만큼 커집니다. 차이를 "계산 오류"로 보고하지 마세요.
  • API 오류시 _shared/references/bitbank-api-formats.md를 참조하세요.
  • 20001 오류 (인증 실패) → .env 설정을 확인하도록 사용자에게 안내합니다.

관련 스킬