스킬.잇다
itda-gov/stock-portfolio 정식 v0.9.5

빠른 시작

금융위원회 공공데이터 시세 API로 보유 종목의 평가금액·평가손익·수익률을 순수 산술로 계산하는 가장 간단한 방법입니다.

내 보유종목 평가손익 계산해줘
005930 10주 평단가 28만 원 기준 손익은?
삼성전자 10주 카카오 5주 포트폴리오 평가금액 알려줘

이렇게 보유 종목·수량·평균매입단가를 말하면 스킬이 현재가를 조회해 평가손익을 계산합니다.

처음 사용 시 KO_DATA_API_KEY가 필요합니다. data.go.kr 계정으로 데이터셋 15094808(“금융위원회 주식시세정보”)에 활용신청(자동승인) 후, 작업 폴더 루트의 .env에 KO_DATA_API_KEY=발급받은_Decoding키 한 줄을 추가하세요. (이 키는 itda-gov의 g2b·funding·realestate 스킬과 공유되지만, 15094808 데이터셋에는 별도 활용신청이 필요합니다.)

활용 시나리오

단일 종목 평가손익

--holding TICKER:수량:평균매입단가 형식으로 한 종목의 손익을 계산합니다.

005930 10주 평단가 28만 원 기준 손익은?
python3 scripts/collect_stock_portfolio.py --holding 005930:10:280000

복수 종목 포트폴리오

--holding을 반복해 여러 종목을 한 번에 평가합니다.

삼성전자 10주 카카오 5주 포트폴리오 평가금액 알려줘
python3 scripts/collect_stock_portfolio.py \
  --holding 005930:10:280000 \
  --holding 035720:5:55000

종목명으로 입력 + 테이블 출력

종목코드 대신 종목명을 써도 되고, --format table로 표 형식으로 받을 수 있습니다.

내 보유종목 평가손익 표로 정리해줘
python3 scripts/collect_stock_portfolio.py --holding 삼성전자:10:280000 --format table

출력 옵션

옵션값설명
--holdingTICKER:수량:평균매입단가보유종목 (필수, 반복 가능). TICKER는 6자리 종목코드 또는 종목명
--formatjson (기본)holdings 목록 + 종목별 eval_amount·eval_profit·return_pct·계산 수식 필드 포함 JSON
--formattable사람이 읽기 좋은 표 형식
--api-keyKEYAPI 키 직접 지정 (환경변수 대신)

종목별 결과에는 평가금액(eval_amount = qty × clpr), 매입금액(book_value = qty × avg_cost), 평가손익(eval_profit), 수익률(return_pct), 그리고 계산 과정을 보여주는 formula_eval_amount·formula_eval_profit 수식이 함께 제공됩니다.

팁

  • 보유종목은 저장되지 않습니다: --holding으로 넘긴 보유내역은 계산 후 출력만 하며 로컬 파일·DB에 기록되지 않습니다(P-2 비영구 정책). 매 호출마다 보유내역을 다시 입력해야 합니다.
  • 순수 산술만 수행: 이 스킬은 평가금액·손익·수익률만 계산하며, 리밸런싱·매수/매도·목표 비중 추천은 하지 않습니다(자본시장법 §6).
  • 수익률 예외: 평균매입단가(avg_cost)가 0이면 return_pct는 null로 반환됩니다.
  • 종목명 모호성: TICKER에 종목명을 넣었을 때 복수 후보가 있으면 해당 행만 status: ambiguous로 표시됩니다. 정확한 6자리 종목코드를 쓰면 모호성이 사라집니다.
  • 비실시간 데이터: 현재가는 일 1회 갱신·비실시간(T+1)입니다. 응답의 data_recency로 기준일자를 확인하세요. 모든 출력에 “정보 제공이며 투자자문이 아님, 투자판단·책임은 본인” 디스클레이머가 붙습니다.
  • 403 오류: HTTP 403 Forbidden은 15094808 데이터셋 활용신청 미완료가 원인입니다. data.go.kr에서 활용신청(자동승인)을 완료하세요.
  • 단일 종목 조회·검색·과거 시세는 자매 스킬 stock-quote를 사용하세요.
← 스킬 목록