English · 한국어

Home Assistant에서 한국·미국 주식, 환율, 암호화폐, OpenDart 공시까지 모두 네이티브 sensor로. 무료 API만 사용, 증권사 계정 연동 없음, 음성 비서 지원.

Releases

• ☕ 거실 패널에서 코스피·내 종목·환율·비트코인 한눈에
• 📉 보유 종목이 평단가 대비 ±5% 움직이면 자동 알림
• ⏱️ "지난 30분 동안 ±2% 움직였다" 같은 단기 변동률 트리거
• 🗣️ "헤이 구글, 삼성전자 얼마야?" 음성 질의
• 🔔 OpenDart 신규 공시 푸시 (카테고리별 필터)
• 📊 장 마감 직후 일일 요약 자동 발송

모두 무료 API (yfinance + OpenDart 무료 키), 증권사 계정 X.

• Home Assistant + HACS 설치

1. HACS → ⋮ → 사용자 정의 저장소
2. URL: https://github.com/redchupa/kr_finance_kit / Type: Integration → 추가

1. HACS에서 KR Finance Kit 검색 → 다운로드
2. HA 완전 재시작 (Reload 아닌 Restart)

설정 → 기기 및 서비스 → + 통합 추가 → "KR Finance Kit"

각 필드의 라벨 뒤 콜론(:)에 그대로 복사·붙여넣기 가능한 예시가 미리 보입니다.

• sensor.fi_kospi / sensor.fi_kosdaq — 한국 지수
• sensor.fi_nasdaq / _dow / _sp500 — 미국 지수
• sensor.fi_nikkei / _hangseng / _ftse / _dax — 글로벌 지수
• sensor.fi_usdkrw — USD/KRW 환율

• sensor.fi_kr_<6자리> — 한국 종목 (예 _kr_005930)
• sensor.fi_us_<티커> — 미국 종목 (예 _us_aapl)
• sensor.fi_other_<슬러그> — 암호화폐·환율·선물 (예 _other_btc_usd, 24/7 갱신)

• 기본: price, change, change_pct (전일 종가 대비), prev_close, asof, stale
• "상세 attribute 포함" ON 시: fifty_two_week_high/low, fifty/two_hundred_day_average, regular_market_day_high/low/volume, market_state, currency, quote_type, long_name, equity는 dividend_* / forward_pe / trailing_pe
• "USD→KRW 환산" ON 시 (USD 자산만): price_krw
• 단기 변동률 (옵션 없이 자동): change_pct_1min / _5min / _15min / _30min / _60min / _90min / _120min / _180min (8개 윈도우 고정)

• sensor.fi_portfolio_kr_value / _kr_pl / _us_value / _us_pl / _krw_total / _krw_pl
• binary_sensor.fi_portfolio_pl_alert — 평단가 대비 ±임계값 돌파 시 ON

• binary_sensor.fi_disclosure_<corp_code> — 24시간 윈도우, device label은 종목명 (예 삼성전자)

• kr_finance_kit_kr_market_closed — 한국 장 마감 시점 fire
• kr_finance_kit_us_market_closed — 미국 장 마감 시점 fire

옵션 화면이 아닌 HA 서비스(=동작)로 입력 — 평단가·수량은 HA 암호화 저장소에만 저장됩니다.

Settings → 개발자 도구(Developer Tools) → 동작(Actions) 탭 → 검색창에 kr_finance_kit.add_position 입력 → 폼이 자동으로 나타납니다.

HA 2024.8+ 부터 기존 "서비스(Services)" 탭이 "동작(Actions)" 으로 명칭만 변경됐습니다. 같은 화면입니다.

⚠ 암호화폐 / 환율 / 선물 (BTC-USD, EUR=X, GC=F …) 은 보유 종목 추적 미지원. 시세 sensor (sensor.fi_other_*) 는 제공되지만 add_position 의 market 라디오에는 KR/US 만 있어요.

💱 환산 자동 — KR 종목은 원 그대로, US 종목은 달러 그대로 입력. USD/KRW 환율은 통합이 자동으로 가져와서 sensor.fi_portfolio_krw_total / sensor.fi_portfolio_krw_pl 에 합산합니다. 환산값을 미리 넣으면 이중 환산되어 망가져요.

🛡️ 입력 검증 — schema 단계에서 ticker는 정규식 ^[A-Za-z0-9][A-Za-z0-9.\-]{0,19}$ 필터, quantity·avg_price는 양수 + finite (NaN/Infinity 거부) + 최대 10억. 잘못된 값 (특수문자, 음수, 빈 칸, 한글 ticker, HTML/SQL 인젝션 시도 등) 은 서비스 호출이 시작 전에 명확한 에러 메시지와 함께 차단됩니다.

저장 후 6개 portfolio sensor (sensor.fi_portfolio_*) + P/L alert binary_sensor가 자동으로 활성화됩니다.

같은 화면에서 kr_finance_kit.remove_position 선택 → ticker + market 입력 → 동작 수행.

여러 종목을 한 번에 넣고 싶다면 개발자 도구 → 동작 → "YAML 모드로 이동":

action: kr_finance_kit.add_position
data:
  ticker: "005930"
  quantity: 10
  avg_price: 60000
  market: KR

종목별로 동작 1회씩 실행. 자동화 스크립트로 묶어두면 HA 시작 시 자동 등록도 가능.

옵션 화면에서 종목을 여러 개 등록해두고, 블루프린트 입력에서 체크박스로 알림 받을 종목만 선택하는 패턴. 종목 추가/삭제 시 자동화 재생성 불필요.

change_pct (전일 종가 대비) 기반. 입력: 종목·하락 임계값·상승 임계값·알림 대상.

종목별로 다른 분을 트리거하려면 블루프린트 자동화를 여러 개 만드시면 됩니다. 예:

• 자동화 1: 종목=[삼성전자], 윈도우=15분
• 자동화 2: 종목=[비트코인], 윈도우=60분

v0.1.53부터 sensor가 1·5·15·30·60·90·120·180분 8개 윈도우 attribute를 옵션 입력 없이 자동 생성. 블루프린트 number 입력에 그 중 하나(예 30) 넣으면 즉시 동작.

📥 Import 직후 warm-up — 첫 알림은 윈도우만큼 가격 샘플이 쌓여야 옴 ⚠️ HA 재시작 시 — N분 윈도우는 N분 동안 attribute None (memory-only buffer)

장 마감 직후(기본 15:30 KST) 지수·환율·종목·평가손익을 한 메시지로.

모든 블루프린트는 notify.send_message (HA 2024.6+ 표준) 사용. mobile_app 자동 호환. service-only notify (일부 telegram_bot 모드 등) 사용자는 docs/examples/ 의 raw YAML 참고.

마크다운 표 위주의 슬림한 vertical-stack 예시 — 본인 취향대로 수정하세요. ApexCharts 1개 외에는 빌트인 markdown 카드만 사용.

1. docs/examples/dashboard.yaml 의 view 블록 복사
2. HA → Settings → Dashboards → ⋮ Edit → ⋮ Raw configuration editor
3. views: 아래에 paste → Save
4. 섹션 6 의 종목 entity_id 와 섹션 7 의 disclosure entity_id 를 본인 종목으로 교체

entity 참조는 sensor.fi_* / binary_sensor.fi_* 형식. v0.1.54+ migration 후, v0.1.61+ positions attribute 가 있어야 보유 종목 현황 표가 작동합니다.

다른 모든 카드는 HA 빌트인 (markdown 만 사용).

trigger:
  - platform: state
    entity_id: binary_sensor.fi_portfolio_pl_alert
    to: "on"
action:
  - service: notify.mobile_app_my_phone
    data:
      title: "포트폴리오 알림"
      message: >
        평가손익 {{ state_attr('binary_sensor.fi_portfolio_pl_alert', 'current_pl_pct') }}%
        — 임계값 ±{{ state_attr('binary_sensor.fi_portfolio_pl_alert', 'threshold_pct') }}%

trigger:
  - platform: event
    event_type: kr_finance_kit_kr_market_closed
action:
  - service: notify.notify
    data:
      message: "코스피 종가 {{ states('sensor.fi_kospi') }}"

더 많은 예시: docs/examples/

HA Assist에 자동 등록 (finance_query LLM tool). 8개 query_type:

• index / fx / quote / portfolio / disclosures / disclosure_for_ticker / top_movers / market_summary

예시 질문:

• "코스피 지금 얼마야?"
• "삼성전자 시세 알려줘"
• "오늘 가장 많이 오른 종목?"
• "오늘 시장 요약해줘"
• "관심 종목 새 공시 있어?"

Google Assistant / Alexa / ChatGPT 음성 모드 / 로컬 Whisper — HA Assist 통해 모두 사용 가능 (LLM 기반 conversation 통합 필요).

• 가격이 안 뜸 / Unavailable → HA 재시작 후 1~2분. 계속되면 Issues
• 옵션 새 항목이 안 보임 → HA 완전 재시작 (Reload 아님, translation cache flush)
• already_in_progress 에러 → v0.1.47+ 받기, HA Restart
• 구성 흐름 500 에러 → v0.1.48+ 받기
• 더 자세한 가이드: docs/installation-ko.md

도움이 되셨다면 커피 한 잔 🙏

토스

PayPal

_{🤝 버그 리포트·기능 제안: Issues | 📦 변경 이력: Releases | 📝 MIT License}