한국투자증권 API 연동 자동화

계좌 자산 리포트를
디스코드 알림으로 편리하게

Bizarre는 한국투자증권 Open API를 활용하여 계좌의 자산 현황을 주기적으로 조회하고, 핵심 자산 요약을 디스코드 웹훅으로 정갈하게 전송하는 백그라운드 자동화 도구입니다.

시작하기 GitHub 저장소
discord-balance-webhook.md
Bizarre Bot BOT 오늘 오전 9:00
📊 실시간 계좌 자산 현황 요약 (계정 01)
조회 시간: 2026-06-15 09:00:05
  • 💵 예수금 총액: 12,450,000 원
  • 📈 주식 평가금액: 45,780,000 원
  • 💎 순자산 총금액: 58,230,000 원
  • 💰 총 매입 금액: 42,000,000 원
  • 🔥 총 평가 손익: +3,780,000 원 (+9.00%)
* 총자산 10,000원 초과의 활성 계좌만 선별하여 리포팅되었습니다.

안정적인 핵심 기능

복잡한 한투 API 연동과 백그라운드 크론 작업을 단순화하고, 디스코드 채널로 실시간 알림을 보내 자산을 정밀하게 모니터링합니다.

다중 계정 관리

최대 20개의 한국투자증권 계정을 등록하고, 각 계정별 자산 현황을 동적 활성화를 통해 독립적으로 모니터링할 수 있습니다.

토큰 자동 갱신

SQLite DB와 연동하여 만료 마진 내의 한투 Access Token을 안전하게 재사용하고, 만료 전에 백그라운드에서 자동 갱신합니다.

자산 현황 요약

25가지의 전체 자산 데이터 중 총자산이 10,000원을 초과하는 계좌만 선별하고, 0원이 아닌 실질 자산 항목을 마크다운 메시지로 디스코드에 전송합니다.

PM2 크론 스케줄

15분 주기로 백그라운드 자동 기동하여 작동하도록 PM2를 활용한 데몬형 크론 구동 시스템이 사전 설정되어 제공됩니다.

신뢰성을 위한
클린 아키텍처

Bizarre는 소프트웨어의 유지보수성과 확장성을 극대화하기 위해 의존성 규칙이 중심부인 Domain 레이어를 향하도록 설계된 클린 아키텍처 구조를 따릅니다.

Presentation
Presentation Layer (CLI)

issue-token, report-balance 등 사용자 명령어 진입점

Application
Application Layer (Usecase)

토큰 발급, 자산 조회 및 디스코드 전송 유스케이스 서비스

Domain
Domain Layer (Core)

핵심 비즈니스 모델 및 각 어댑터들의 추상 인터페이스 정의

Infrastructure
Infrastructure Layer (Details)

SQLite DB 연동, 한투 Open API 통신, Discord Webhook 연동 실체

graph TD classDef presentation fill:#1e293b,stroke:#3b82f6,color:#f8fafc; classDef application fill:#1e293b,stroke:#10b981,color:#f8fafc; classDef domain fill:#1e293b,stroke:#94a3b8,color:#f8fafc; classDef infra fill:#1e293b,stroke:#ef4444,color:#f8fafc; subgraph Presentation [Presentation Layer] CLI[issue-token, report-balance]:::presentation end subgraph Application [Application Layer] IT[IssueTokens]:::application RAB[ReportAccountBalance]:::application TP[TokenProvider]:::application end subgraph Domain [Domain Layer] T[Token Interfaces]:::domain AB[AccountBalance Interfaces]:::domain N[Notifier Interface]:::domain end subgraph Infrastructure [Infrastructure Layer] HTI[HantuTokenIssuer]:::infra HABL[HantuAccountBalanceLoader]:::infra STR[SqliteTokenRepository]:::infra DN[DiscordNotifier]:::infra end CLI --> IT CLI --> RAB CLI --> TP IT --> T RAB --> AB RAB --> N RAB --> TP TP --> T HTI -.->|implements| T HABL -.->|implements| AB STR -.->|implements| T DN -.->|implements| N

정갈한 설치 및 실행

환경 변수 설정부터 백그라운드 크론 구동까지, 몇 가지 명령어만으로 신속하게 시스템을 구축할 수 있습니다.

1. 환경 변수 설정 (.env)

프로젝트 루트 폴더에 .env 파일을 생성하고 디스코드 웹훅 및 한투 App Key 설정을 작성합니다.

env 
# Discord Webhook 설정
WEBHOOK_ID="123456789012345678"
WEBHOOK_TOKEN="abcdefghijklmnopqrstuvwxyz_123456789"

# 한국투자증권 계정 설정 (최대 20개 계정 지원, XX = 01 ~ 20)
HANTU_01_NO="12345678-01"
HANTU_01_AK="your_hantu_app_key"
HANTU_01_SK="your_hantu_app_secret"

2. 명령어 실행

패키지 매니저(pnpm)를 통해 의존성을 설치하고, 초기 토큰 발급 및 백그라운드 PM2 스케줄을 기동합니다.

bash 
# 1. 의존성 패키지 설치
pnpm install

# 2. 한국투자증권 API Access Token 첫 발급 및 DB 저장
pnpm token

# 3. PM2 백그라운드 크론 구동 시작
pnpm start       # 프로덕션 서비스 기동 (15분 주기, 영업일 08:30 - 16:30만 발송)
pnpm start:dev   # 개발용 서비스 기동 (5분 주기, 시간 제한 없이 항상 발송)

# (선택) 서비스 중지 및 실행 로그 확인
pnpm stop
pnpm logs