KIS API 한국투자증권 모의투자 완전정복

학습 목표

1단계 — KIS TR_ID 체계 이해

KIS API는 TR_ID(Transaction ID)로 각 기능을 구분합니다. Alpaca처럼 URL 하나로 모든 걸 하지 않고, 헤더의 TR_ID 값이 실제 동작을 결정합니다. 같은 URL이라도 TR_ID가 다르면 매수/매도/조회가 달라집니다.

TR_ID 명명 규칙

이 과정에서 사용할 핵심 TR_ID 9개

2단계 — 삼성전자 현재가 조회

필수 헤더 5개

// KIS 시세 조회 헤더 (모든 조회 API 공통)
{
  "content-type": "application/json",
  "authorization": "Bearer {{ $json.access_token }}",
  "appkey": "{{ $credentials.APP_KEY }}",
  "appsecret": "{{ $credentials.APP_SECRET }}",
  "tr_id": "FHKST01010100"
}

응답 파싱 — 핵심 필드

// 응답 예시 (삼성전자 005930)
{
  "rt_cd": "0",          // 0 = 성공
  "msg_cd": "MCA00000",
  "msg1": "정상처리 되었습니다",
  "output": {
    "stck_prpr": "72400",      // 현재가
    "prdy_vrss": "-800",       // 전일 대비
    "prdy_ctrt": "-1.09",      // 전일 대비율 (%)
    "stck_oprc": "73000",      // 시가
    "stck_hgpr": "73200",      // 고가
    "stck_lwpr": "72200",      // 저가
    "acml_vol": "8724563",    // 누적 거래량
    "per": "15.23",          // PER
    "pbr": "1.45"            // PBR
  }
}

3단계 — 일자별 시세 + 계좌 잔고

일자별 시세 (60일 OHLC)

W2에서 Yahoo Finance로 미국 주식 OHLC를 가져왔습니다. 한국 주식은 KIS의 FHKST01010400을 씁니다.

W2 지표 계산 연결 — 한국 종목 대응

// KIS 일봉 응답 → W2 RSI·MA·볼린저 계산 어댑터
const kisData = $input.item.json.output;

// output은 최근부터 과거 순 - 역순으로 변환
const closes = [];
for (let i = kisData.length - 1; i >= 0; i--) {
  closes.push(parseFloat(kisData[i].stck_clpr));  // 종가
}

const symbol = '005930.KS';
const currentPrice = closes[closes.length - 1];

// W2의 calcRSI, calcMA, calcBB 재사용 (코드 생략)
// ...

return {
  ticker: symbol,
  ticker_name: '삼성전자',
  price: currentPrice,
  rsi14: rsi14.toFixed(2),
  ma20: ma20.toFixed(2),
  bb_upper: bb.upper.toFixed(2),
  bb_lower: bb.lower.toFixed(2),
  market: 'KOSPI'
};

계좌 잔고 조회

// 잔고 조회 응답 구조
{
  "rt_cd": "0",
  "output1": [       // 보유 종목 리스트
    {
      "pdno": "005930",         // 종목코드
      "prdt_name": "삼성전자",      // 종목명
      "hldg_qty": "10",            // 보유 수량
      "pchs_avg_pric": "71500",    // 매입평균가
      "prpr": "72400",             // 현재가
      "evlu_amt": "724000",         // 평가금액
      "evlu_pfls_amt": "9000",      // 평가손익
      "evlu_pfls_rt": "1.26"        // 평가손익률 %
    }
  ],
  "output2": [       // 계좌 요약
    {
      "dnca_tot_amt": "49276000",   // 예수금 총액
      "tot_evlu_amt": "50000000",   // 총 평가금액
      "asst_icdc_amt": "0",          // 자산증감액
      "asst_icdc_erng_rt": "0"        // 자산증감수익률
    }
  ]
}

SP2 완료 체크리스트

학습 목표

1단계 — 해시키(HashKey) 이해와 생성

KIS의 주문 관련 API(매수/매도/정정/취소)는 Body 변조 방지를 위해 HashKey를 요구합니다. Body를 KIS 서버에 먼저 보내 해시를 발급받고, 그 해시를 실제 주문 요청의 헤더에 추가하는 2단계 구조입니다.

해시키 생성 노드

// HashKey 생성 Body (실제 주문과 동일)
{
  "CANO": "{{ $credentials.CANO }}",
  "ACNT_PRDT_CD": "{{ $credentials.ACNT_PRDT_CD }}",
  "PDNO": "005930",
  "ORD_DVSN": "00",
  "ORD_QTY": "10",
  "ORD_UNPR": "72400"
}

// Response
{
  "HASH": "1f9b2d4e8a...",      // 40자리 해시
  "BODY": { ... }
}

2단계 — 매수/매도 주문 실행

매수 주문 API

주문 Body 파라미터

// 삼성전자 10주 시장가 매수
{
  "CANO": "{{ $credentials.CANO }}",
  "ACNT_PRDT_CD": "{{ $credentials.ACNT_PRDT_CD }}",
  "PDNO": "005930",        // 종목코드
  "ORD_DVSN": "01",          // 주문구분: 01=시장가, 00=지정가
  "ORD_QTY": "10",           // 주문 수량
  "ORD_UNPR": "0"             // 시장가는 0, 지정가는 가격
}

// 지정가 매수 (72,000원에 10주)
{
  "CANO": "...",
  "ACNT_PRDT_CD": "01",
  "PDNO": "005930",
  "ORD_DVSN": "00",          // 지정가
  "ORD_QTY": "10",
  "ORD_UNPR": "72000"
}

매도는 TR_ID만 변경

매도 주문은 TR_ID만 VTTC0801U로 바꾸면 됩니다. Body 구조·파라미터는 매수와 완전히 동일. n8n에서는 IF 노드로 side에 따라 TR_ID를 분기합니다.

// IF 노드에서 매수/매도 분기 후 Set 노드
const side = $input.item.json.side;

return {
  tr_id: side === 'buy' ? 'VTTC0802U' : 'VTTC0801U',
  action: side === 'buy' ? '매수' : '매도'
};

성공 응답 확인

{
  "rt_cd": "0",
  "msg_cd": "APBK0013",
  "msg1": "주문 전송 완료 되었습니다.",
  "output": {
    "KRX_FWDG_ORD_ORGNO": "00950",  // 거래소 전송 기관번호
    "ODNO": "0000117057",            // 주문번호 (정정/취소에 사용)
    "ORD_TMD": "093045"               // 주문 시각
  }
}

3단계 — W7 Claude 에이전트 + 2단계 승인 시스템

W7 Orchestrator의 verdict를 KIS 주문으로 연결하되, 자동 실행 전 인간 검토 단계를 추가합니다. 모의투자라도 습관을 미리 들이는 것이 중요합니다.

Level 1 — Discord 2단계 승인 구현

Discord 버튼 메시지 구성

// Discord Interaction 메시지 Body (Webhook 또는 Bot)
{
  "content": "🤖 **자동매매 승인 요청**",
  "embeds": [{
    "title": "삼성전자 (005930) 매수 제안",
    "color": 3066993,
    "fields": [
      { "name": "수량", "value": "10주", "inline": true },
      { "name": "예상금액", "value": "724,000원", "inline": true },
      { "name": "Claude 신뢰도", "value": "4/5", "inline": true },
      { "name": "근거", "value": "HBM 수요 증가 뉴스 + RSI 과매도 반등" }
    ]
  }],
  "components": [{
    "type": 1,
    "components": [
      {
        "type": 2,
        "style": 3,
        "label": "✅ 승인하고 주문",
        "custom_id": "approve_order_12345"
      },
      {
        "type": 2,
        "style": 4,
        "label": "❌ 거부",
        "custom_id": "reject_order_12345"
      }
    ]
  }]
}

Claude 주문 결정 프롬프트 — 한국 종목 특화

SP3 완료 체크리스트