kiwoom-mcp-server 0.8.0

package/dist/isa/classify.js

@@ -0,0 +1,198 @@
+/**
+ * ISA 손익통산을 위한 종목 과세유형 분류.
+ *
+ * - DOMESTIC_EQUITY: 국내 상장주식·국내주식형 ETF — 매매차익은 비과세(통산 이익
+ *   미포함), 매매손실은 통산 시 차감.
+ * - TAXABLE: 그 외(해외지수·채권·원자재·파생형 ETF 등) — 매매손익이 배당소득으로
+ *   과세되어 통산에 포함.
+ *
+ * 과세유형은 API가 제공하지 않으므로 종목명 휴리스틱으로 추정한다. 분류가 틀릴 수
+ * 있으므로 반드시 `confident` 플래그를 함께 전달하고, 호출자(tool)는 overrides로
+ * 수동 지정을 받을 수 있어야 한다.
+ */
+/** 국내 상장 ETF/ETN 브랜드 접두어 (2026 기준 주요 운용사). */
+const ETF_BRANDS = [
+    "KODEX",
+    "TIGER",
+    "KIWOOM",
+    "RISE",
+    "KBSTAR",
+    "SOL",
+    "ACE",
+    "PLUS",
+    "ARIRANG",
+    "HANARO",
+    "KOSEF",
+    "WON",
+    "1Q",
+    "TIMEFOLIO",
+    "FOCUS",
+    "UNICORN",
+    "KTOP",
+    "TREX",
+    "파워",
+    "마이다스",
+    "BNK",
+    "HK",
+    "ITF",
+    "KCGI",
+    "DAISHIN343",
+    "히어로즈",
+];
+/** 이름에 이 키워드가 있으면 과세대상(기타형)으로 판단. 도메스틱 키워드보다 우선. */
+const TAXABLE_KEYWORDS = [
+    // 해외 지역/지수
+    "미국",
+    "나스닥",
+    "S&P",
+    "다우",
+    "필라델피아",
+    "글로벌",
+    "월드",
+    "선진",
+    "신흥",
+    "차이나",
+    "중국",
+    "항셍",
+    "일본",
+    "닛케이",
+    "인도",
+    "베트남",
+    "대만",
+    "유럽",
+    "유로",
+    "독일",
+    // 채권/금리/통화
+    "채권",
+    "국채",
+    "국고채",
+    "회사채",
+    "단기채",
+    "종합채",
+    "금리",
+    "KOFR",
+    "SOFR",
+    "CD금리",
+    "머니마켓",
+    "MMF",
+    "달러",
+    "엔화",
+    "엔선물",
+    "위안",
+    // 원자재/대체
+    "골드",
+    "금현물",
+    "금선물",
+    "은현물",
+    "은선물",
+    "원유",
+    "원자재",
+    "구리",
+    "니켈",
+    "리츠",
+    "부동산",
+    "인프라",
+    "하이일드",
+    // 파생/구조형 (국내 기초자산이어도 과세대상)
+    "레버리지",
+    "인버스",
+    "커버드콜",
+    "합성",
+    "(H)",
+    "TDF",
+    "TRF",
+];
+/** 국내주식형 ETF로 판단하는 키워드 (TAXABLE 키워드에 안 걸렸을 때만). */
+const DOMESTIC_KEYWORDS = [
+    "코스피",
+    "코스닥",
+    "KRX",
+    "200",
+    "150",
+    "100",
+    "300",
+    "TOP",
+    "배당",
+    "그룹",
+    "밸류",
+    "성장",
+    "모멘텀",
+    "로우볼",
+    "삼성",
+    "반도체",
+    "자동차",
+    "은행",
+    "증권",
+    "보험",
+    "바이오",
+    "헬스케어",
+    "2차전지",
+    "소프트웨어",
+    "게임",
+    "엔터",
+    "방산",
+    "조선",
+];
+/**
+ * 이름이 국내 상장 ETF/ETN 브랜드로 시작하는지 여부. `classifyInstrument`의 ETF
+ * 판정과 동일한 기준이며, ka40002 조회 대상(브랜드 ETF)을 고르는 게이트로도 쓴다.
+ */
+export function isLikelyEtf(name) {
+    const upper = name.toUpperCase().trim();
+    return ETF_BRANDS.some((brand) => upper.startsWith(brand.toUpperCase()));
+}
+/**
+ * 키움 ka40002 `etftxon_type`(ETF 과세유형)을 ISA 손익통산 분류로 매핑한다.
+ * 권위 있는 값이 있을 때만 사용하고, 알 수 없거나 빈 값이면 null을 반환해
+ * 호출자가 종목명 휴리스틱으로 폴백하도록 한다.
+ *
+ * - "비과세" → DOMESTIC_EQUITY (국내주식형 — 매매차익 비과세, 손실만 통산 차감)
+ * - "보유기간과세" → TAXABLE (기타형 — 매매손익이 배당소득 과세, 통산 포함)
+ */
+export function mapEtfTaxonType(raw) {
+    const t = raw.trim();
+    if (t.includes("보유기간과세"))
+        return "TAXABLE";
+    if (t.includes("비과세"))
+        return "DOMESTIC_EQUITY";
+    return null;
+}
+/**
+ * @param isEtfHint ETF 여부를 외부(ka10099 마스터리스트 `marketName == "ETF"`)에서 알 때
+ *   전달한다. 브랜드 접두어가 없는 ETF도 ETF로 취급해 개별주식 오분류를 막는다.
+ *   생략하면 종목명 브랜드 접두어(`isLikelyEtf`)로 판정한다.
+ */
+export function classifyInstrument(code, name, overrides, isEtfHint) {
+    const override = overrides?.get(code);
+    if (override) {
+        return { taxType: override, confident: true, reason: "수동 지정" };
+    }
+    const upper = name.toUpperCase().trim();
+    const isEtf = isEtfHint ?? isLikelyEtf(name);
+    if (!isEtf) {
+        return {
+            taxType: "DOMESTIC_EQUITY",
+            confident: true,
+            reason: "국내 개별주식 — 매매차익 비과세, 손실은 통산 차감",
+        };
+    }
+    if (TAXABLE_KEYWORDS.some((k) => upper.includes(k.toUpperCase()))) {
+        return {
+            taxType: "TAXABLE",
+            confident: true,
+            reason: "해외/채권/원자재/파생형 ETF — 매매손익 통산 포함",
+        };
+    }
+    if (DOMESTIC_KEYWORDS.some((k) => upper.includes(k.toUpperCase()))) {
+        return {
+            taxType: "DOMESTIC_EQUITY",
+            confident: true,
+            reason: "국내주식형 ETF — 매매차익 비과세, 손실은 통산 차감",
+        };
+    }
+    return {
+        taxType: "TAXABLE",
+        confident: false,
+        reason: "유형 미확인 — 보수적으로 과세대상 가정 (overrides로 수정 가능)",
+    };
+}

package/dist/isa/realized.js

@@ -0,0 +1,55 @@
+/**
+ * kt00015 매매 내역으로 종목별 실현손익을 이동평균 원가법으로 재구성한다.
+ *
+ * 배경(라이브 검증): 키움 REST의 종목별 실현손익 TR(ka10072/ka10073)이 이 계좌
+ * 유형에서 빈 결과만 반환해, 계좌 전체 합계 TR(ka10074)을 검증값으로 두고 거래
+ * 내역에서 직접 재구성한다. 매수 정산금액(exct_amt)은 수수료 포함 원가, 매도
+ * 정산금액은 수수료 차감 후 실수령액이므로 증권사 정산과 같은 기준이 된다.
+ */
+export function reconstructRealizedPnl(events) {
+    const ordered = [...events].sort((a, b) => a.date === b.date ? a.seq - b.seq : a.date.localeCompare(b.date));
+    const positions = new Map();
+    const results = new Map();
+    const warnings = [];
+    const resultOf = (event) => {
+        let r = results.get(event.code);
+        if (!r) {
+            r = { code: event.code, name: event.name, realized: 0, soldQuantity: 0, incompleteHistory: false };
+            results.set(event.code, r);
+        }
+        return r;
+    };
+    for (const event of ordered) {
+        if (event.quantity <= 0)
+            continue;
+        const position = positions.get(event.code) ?? { quantity: 0, cost: 0 };
+        positions.set(event.code, position);
+        if (event.side === "BUY") {
+            position.quantity += event.quantity;
+            position.cost += event.netAmount;
+            continue;
+        }
+        // SELL
+        const result = resultOf(event);
+        const covered = Math.min(event.quantity, position.quantity);
+        if (covered < event.quantity) {
+            result.incompleteHistory = true;
+            warnings.push(`${event.name}(${event.code}): 집계 시작일 이전 취득분 매도가 감지되어 실현손익이 불완전합니다. ` +
+                `from_date가 계좌 개설일을 포함하는지 확인하세요.`);
+        }
+        if (covered > 0) {
+            const avgCost = position.cost / position.quantity;
+            const coveredProceeds = event.netAmount * (covered / event.quantity);
+            result.realized += coveredProceeds - avgCost * covered;
+            result.soldQuantity += covered;
+            position.quantity -= covered;
+            position.cost -= avgCost * covered;
+        }
+    }
+    const perStock = [...results.values()];
+    return {
+        perStock,
+        total: perStock.reduce((sum, r) => sum + r.realized, 0),
+        warnings,
+    };
+}

package/dist/isa/tax.js

@@ -0,0 +1,53 @@
+/** 조특법상 ISA 비과세 한도 (원). */
+export const ISA_LIMITS = {
+    GENERAL: 2_000_000,
+    SEOMIN: 4_000_000,
+};
+/** 한도 초과분 분리과세율 (지방소득세 포함 9.9%). */
+export const ISA_TAX_RATE = 0.099;
+function sumByType(items, taxType) {
+    return items.filter((i) => i.taxType === taxType).reduce((sum, i) => sum + i.amount, 0);
+}
+function settle(net, limit) {
+    const used = Math.max(0, net);
+    return {
+        remaining: Math.max(0, limit - used),
+        tax: Math.max(0, used - limit) * ISA_TAX_RATE,
+    };
+}
+/**
+ * ISA 손익통산 계산.
+ *
+ * 규칙 (조특법 제91조의18 기준, 단순화):
+ * - 과세대상(기타형) 상품의 실현손익은 이익·손실 모두 통산에 포함.
+ * - 국내주식형 상품의 실현이익은 애초에 비과세라 통산에서 제외하되,
+ *   클래스 합산이 순손실이면 그 손실은 과세소득에서 차감.
+ * - 배당·분배금·이자는 전액 통산 포함.
+ * - 미실현 손익은 통산에 포함되지 않으며, "전량 매도 시" 시나리오로만 제공.
+ */
+export function computeIsaTaxStatus(input) {
+    const taxableRealized = sumByType(input.realized, "TAXABLE");
+    const domesticRealizedNet = sumByType(input.realized, "DOMESTIC_EQUITY");
+    const domesticLossDeduction = Math.min(0, domesticRealizedNet);
+    const confirmedNet = input.dividends + taxableRealized + domesticLossDeduction;
+    const confirmed = settle(confirmedNet, input.limit);
+    const taxableUnrealized = sumByType(input.unrealized, "TAXABLE");
+    const domesticUnrealizedNet = sumByType(input.unrealized, "DOMESTIC_EQUITY");
+    const scenarioNet = confirmedNet + taxableUnrealized + Math.min(0, domesticUnrealizedNet);
+    const scenario = settle(scenarioNet, input.limit);
+    return {
+        limit: input.limit,
+        dividends: input.dividends,
+        taxableRealized,
+        domesticRealizedNet,
+        domesticLossDeduction,
+        confirmedNet,
+        remainingAllowance: confirmed.remaining,
+        estimatedTaxNow: confirmed.tax,
+        taxableUnrealized,
+        domesticUnrealizedNet,
+        scenarioNet,
+        scenarioRemaining: scenario.remaining,
+        scenarioEstimatedTax: scenario.tax,
+    };
+}

package/dist/kiwoom/api.js

@@ -0,0 +1,372 @@
+import { z } from "zod";
+import { sleep } from "../utils/sleep.js";
+import { KiwoomApiError } from "./errors.js";
+import { accountEvaluationResponseSchema, allIndexResponseSchema, dailyChartItemSchema, depositResponseSchema, etfInfoResponseSchema, foreignHoldingResponseSchema, investorDailyItemSchema, investorTotalItemSchema, minuteChartItemSchema, orderbookResponseSchema, pendingOrdersResponseSchema, priceChangeRankItemSchema, realizedPnlResponseSchema, shortSellingResponseSchema, stockInfoResponseSchema, stockListResponseSchema, themeGroupsResponseSchema, tradingJournalResponseSchema, themeStocksResponseSchema, transactionsResponseSchema, valueRankItemSchema, volumeRankItemSchema, watchlistGroupDetailResponseSchema, watchlistGroupsResponseSchema, } from "./types.js";
+const STOCK_INFO_PATH = "/api/dostk/stkinfo";
+const ACCOUNT_PATH = "/api/dostk/acnt";
+const CHART_PATH = "/api/dostk/chart";
+const MRKCOND_PATH = "/api/dostk/mrkcond";
+const SECTOR_PATH = "/api/dostk/sect";
+const RANK_PATH = "/api/dostk/rkinfo";
+const ETF_PATH = "/api/dostk/etf";
+const WATCHLIST_PATH = "/api/dostk/watchlist";
+const THEME_PATH = "/api/dostk/thme";
+const SHORT_PATH = "/api/dostk/shsa";
+const FOREIGN_PATH = "/api/dostk/frgnistt";
+/** Pulls an array out of an already-envelope-checked response body. */
+function parseArray(json, key, itemSchema) {
+    const value = json[key];
+    return z.array(itemSchema).parse(Array.isArray(value) ? value : []);
+}
+/**
+ * Safety cap for cont-yn pagination. Bounds worst-case latency (each page is
+ * ~1.1s apart, so up to ~22s). A typical retail/ISA account never comes close,
+ * but a heavy account could — when the cap is hit, callers surface a
+ * "results may be truncated" warning instead of silently dropping data.
+ */
+const MAX_PAGES = 20;
+/** Per-TR rate limit is ~1 req/s — space out continuation pages. */
+const PAGE_INTERVAL_MS = 1_100;
+/** ka10001 주식기본정보요청 */
+export async function fetchStockInfo(client, stockCode) {
+    const res = await client.call({
+        path: STOCK_INFO_PATH,
+        apiId: "ka10001",
+        body: { stk_cd: stockCode },
+    });
+    const info = stockInfoResponseSchema.parse(res.json);
+    if (!info.stk_nm && !info.cur_prc) {
+        throw new KiwoomApiError(`종목코드 ${stockCode}에 대한 시세 정보가 없습니다. 코드를 확인해 주세요.`, {
+            apiId: "ka10001",
+        });
+    }
+    return info;
+}
+/** kt00001 예수금상세현황요청 (qry_tp: 3=추정조회, 2=일반조회) */
+export async function fetchDeposit(client, qryTp = "3") {
+    const res = await client.call({
+        path: ACCOUNT_PATH,
+        apiId: "kt00001",
+        body: { qry_tp: qryTp },
+    });
+    return depositResponseSchema.parse(res.json);
+}
+/**
+ * kt00018 계좌평가잔고내역요청 (qry_tp: 1=합산, 2=개별).
+ * Follows cont-yn/next-key continuation headers and merges all holding rows.
+ */
+export async function fetchAccountEvaluation(client, qryTp) {
+    const body = { qry_tp: qryTp, dmst_stex_tp: "KRX" };
+    let res = await client.call({ path: ACCOUNT_PATH, apiId: "kt00018", body });
+    const first = accountEvaluationResponseSchema.parse(res.json);
+    const holdings = [...first.acnt_evlt_remn_indv_tot];
+    let pages = 1;
+    while (res.hasNext && pages < MAX_PAGES) {
+        await sleep(PAGE_INTERVAL_MS);
+        res = await client.call({ path: ACCOUNT_PATH, apiId: "kt00018", body, contYn: "Y", nextKey: res.nextKey });
+        const page = accountEvaluationResponseSchema.parse(res.json);
+        holdings.push(...page.acnt_evlt_remn_indv_tot);
+        pages += 1;
+    }
+    // 남은 페이지가 있는데 상한에서 멈췄으면 데이터가 잘렸다는 뜻.
+    return { ...first, acnt_evlt_remn_indv_tot: holdings, truncated: res.hasNext };
+}
+/**
+ * kt00015 위탁종합거래내역요청 — all transactions in [fromDate, toDate] (yyyyMMdd).
+ * NOTE (live-verified): only 매매 rows are returned for this account type; cash
+ * deposit rows never appeared under any tp/gds_tp combination. Dividend rows
+ * are therefore unverified — callers must handle their possible absence.
+ */
+export async function fetchTransactions(client, fromDate, toDate) {
+    const body = { strt_dt: fromDate, end_dt: toDate, tp: "0", gds_tp: "0", dmst_stex_tp: "KRX" };
+    let res = await client.call({ path: ACCOUNT_PATH, apiId: "kt00015", body });
+    const rows = [...transactionsResponseSchema.parse(res.json).trst_ovrl_trde_prps_array];
+    let pages = 1;
+    while (res.hasNext && pages < MAX_PAGES) {
+        await sleep(PAGE_INTERVAL_MS);
+        res = await client.call({ path: ACCOUNT_PATH, apiId: "kt00015", body, contYn: "Y", nextKey: res.nextKey });
+        rows.push(...transactionsResponseSchema.parse(res.json).trst_ovrl_trde_prps_array);
+        pages += 1;
+    }
+    // 남은 페이지가 있는데 상한에서 멈췄으면 오래된 거래가 잘렸다는 뜻.
+    return { rows, truncated: res.hasNext };
+}
+/** ka10074 일자별실현손익요청 — account-wide realized P&L summary for the period. */
+export async function fetchRealizedPnlSummary(client, fromDate, toDate) {
+    const res = await client.call({
+        path: ACCOUNT_PATH,
+        apiId: "ka10074",
+        body: { strt_dt: fromDate, end_dt: toDate },
+    });
+    return realizedPnlResponseSchema.parse(res.json);
+}
+/**
+ * ka10075 미체결요청 — currently open (unfilled) orders. Read-only.
+ * body: all_stk_tp "0"=전체/"1"=종목, trde_tp "0"=전체, stex_tp "0"=통합.
+ * Array key `oso` live-verified 2026-07-07 (empty — no open orders on the
+ * verification account); item fields are wrapper-sourced, not live-verified. Open orders are
+ * few by nature, so only the first page is fetched (no pagination).
+ */
+export async function fetchPendingOrders(client, stockCode) {
+    const res = await client.call({
+        path: ACCOUNT_PATH,
+        apiId: "ka10075",
+        body: {
+            all_stk_tp: stockCode ? "1" : "0",
+            trde_tp: "0",
+            stk_cd: stockCode ?? "",
+            stex_tp: "0",
+        },
+    });
+    return pendingOrdersResponseSchema.parse(res.json).oso;
+}
+/**
+ * ka10099 종목정보요약 — full instrument list for one market (stocks + ETF/ETN).
+ * mrkt_tp: "0"=코스피(거래소), "10"=코스닥. Single page (live-verified ~2500 rows).
+ */
+export async function fetchStockList(client, marketCode) {
+    const res = await client.call({
+        path: STOCK_INFO_PATH,
+        apiId: "ka10099",
+        body: { mrkt_tp: marketCode },
+    });
+    return stockListResponseSchema.parse(res.json).list;
+}
+const CHART_TRS = {
+    day: { apiId: "ka10081", arrayKey: "stk_dt_pole_chart_qry" },
+    week: { apiId: "ka10082", arrayKey: "stk_stk_pole_chart_qry" },
+    month: { apiId: "ka10083", arrayKey: "stk_mth_pole_chart_qry" },
+};
+/**
+ * ka10081/82/83 일·주·월봉 — newest first; first page (240~600 rows) only,
+ * which is plenty for LLM consumption and avoids pagination rate-limit cost.
+ * upd_stkpc_tp "1" = 수정주가 반영.
+ */
+export async function fetchDailyChart(client, stockCode, period, baseDate) {
+    const { apiId, arrayKey } = CHART_TRS[period];
+    const res = await client.call({
+        path: CHART_PATH,
+        apiId,
+        body: { stk_cd: stockCode, base_dt: baseDate, upd_stkpc_tp: "1" },
+    });
+    return parseArray(res.json, arrayKey, dailyChartItemSchema);
+}
+/** ka10080 분봉 — tic_scope in minutes ("1"|"3"|"5"|"10"|"15"|"30"|"45"|"60"). */
+export async function fetchMinuteChart(client, stockCode, ticScope) {
+    const res = await client.call({
+        path: CHART_PATH,
+        apiId: "ka10080",
+        body: { stk_cd: stockCode, tic_scope: ticScope, upd_stkpc_tp: "1" },
+    });
+    return parseArray(res.json, "stk_min_pole_chart_qry", minuteChartItemSchema);
+}
+/** ka10004 주식호가 — 10-level orderbook; levels 2-10 live in the loose passthrough. */
+export async function fetchOrderbook(client, stockCode) {
+    const res = await client.call({
+        path: MRKCOND_PATH,
+        apiId: "ka10004",
+        body: { stk_cd: stockCode },
+    });
+    return orderbookResponseSchema.parse(res.json);
+}
+/** ka20003 전업종지수 — inds_cd "001"=코스피 그룹(31개), "101"=코스닥 그룹(34개). */
+export async function fetchAllIndices(client, indsCd) {
+    const res = await client.call({
+        path: SECTOR_PATH,
+        apiId: "ka20003",
+        body: { inds_cd: indsCd },
+    });
+    return allIndexResponseSchema.parse(res.json).all_inds_idex;
+}
+/** amt_qty_tp: "1"=금액(백만원), "2"=수량(주) — 순매수(trde_tp "0") 기준. */
+const INVESTOR_UNIT_CODES = { amount: "1", quantity: "2" };
+/** ka10061 종목별투자자기관종합 — investor net-buy totals over a date range. */
+export async function fetchInvestorTotal(client, stockCode, fromDate, toDate, unit) {
+    const res = await client.call({
+        path: STOCK_INFO_PATH,
+        apiId: "ka10061",
+        body: {
+            stk_cd: stockCode,
+            strt_dt: fromDate,
+            end_dt: toDate,
+            amt_qty_tp: INVESTOR_UNIT_CODES[unit],
+            trde_tp: "0",
+            unit_tp: "1",
+        },
+    });
+    return parseArray(res.json, "stk_invsr_orgn_tot", investorTotalItemSchema)[0];
+}
+/** ka10059 종목별투자자기관 — daily investor net-buy rows, newest first from `date`. */
+export async function fetchInvestorDaily(client, stockCode, date, unit) {
+    const res = await client.call({
+        path: STOCK_INFO_PATH,
+        apiId: "ka10059",
+        body: {
+            dt: date,
+            stk_cd: stockCode,
+            amt_qty_tp: INVESTOR_UNIT_CODES[unit],
+            trde_tp: "0",
+            unit_tp: "1",
+        },
+    });
+    return parseArray(res.json, "stk_invsr_orgn", investorDailyItemSchema);
+}
+/** mrkt_tp codes shared by the rank TRs (live-verified 000/001; 101 per legacy convention). */
+const RANKING_MARKET_CODES = {
+    all: "000",
+    kospi: "001",
+    kosdaq: "101",
+};
+/** ka10027 전일대비상위 — sort_tp "1"=상승률, "3"=하락률 (live-verified). */
+export async function fetchPriceChangeRanking(client, market, direction) {
+    const res = await client.call({
+        path: RANK_PATH,
+        apiId: "ka10027",
+        body: {
+            mrkt_tp: RANKING_MARKET_CODES[market],
+            sort_tp: direction === "rise" ? "1" : "3",
+            trde_qty_cnd: "0000",
+            stk_cnd: "0",
+            crd_cnd: "0",
+            updown_incls: "1",
+            pric_cnd: "0",
+            trde_prica_cnd: "0",
+            stex_tp: "1",
+        },
+    });
+    return parseArray(res.json, "pred_pre_flu_rt_upper", priceChangeRankItemSchema);
+}
+/** ka10030 당일거래량상위. */
+export async function fetchVolumeRanking(client, market) {
+    const res = await client.call({
+        path: RANK_PATH,
+        apiId: "ka10030",
+        body: {
+            mrkt_tp: RANKING_MARKET_CODES[market],
+            sort_tp: "1",
+            mang_stk_incls: "0",
+            crd_tp: "0",
+            trde_qty_tp: "0",
+            pric_tp: "0",
+            trde_prica_tp: "0",
+            mrkt_open_tp: "0",
+            stex_tp: "1",
+        },
+    });
+    return parseArray(res.json, "tdy_trde_qty_upper", volumeRankItemSchema);
+}
+/** ka10032 거래대금상위. */
+export async function fetchValueRanking(client, market) {
+    const res = await client.call({
+        path: RANK_PATH,
+        apiId: "ka10032",
+        body: {
+            mrkt_tp: RANKING_MARKET_CODES[market],
+            mang_stk_incls: "0",
+            stex_tp: "1",
+        },
+    });
+    return parseArray(res.json, "trde_prica_upper", valueRankItemSchema);
+}
+/** ka40002 ETF종목정보 — 추적지수·과세유형 등 ETF 기본정보. */
+export async function fetchEtfInfo(client, stockCode) {
+    const res = await client.call({
+        path: ETF_PATH,
+        apiId: "ka40002",
+        body: { stk_cd: stockCode },
+    });
+    return etfInfoResponseSchema.parse(res.json);
+}
+/**
+ * ka01300 관심종목 그룹 리스트 조회 — HTS에 저장된 관심종목 그룹 목록 (읽기 전용).
+ * 응답 배열 키는 nofi. 편집(추가/삭제) TR은 키움 REST에 존재하지 않는다.
+ */
+export async function fetchWatchlistGroups(client) {
+    const res = await client.call({ path: WATCHLIST_PATH, apiId: "ka01300", body: {} });
+    return watchlistGroupsResponseSchema.parse(res.json).nofi;
+}
+/**
+ * ka01301 관심종목 그룹 상세 조회 — 그룹(arn_grp_id = ka01300의 gcod) 내 종목 목록.
+ * 응답 배열 키는 nofj (종목코드 cod2 + 북마크 필드만 반환; 종목명/시세는 미포함).
+ */
+export async function fetchWatchlistGroupDetail(client, groupCode) {
+    const res = await client.call({
+        path: WATCHLIST_PATH,
+        apiId: "ka01301",
+        body: { arn_grp_id: groupCode },
+    });
+    return watchlistGroupDetailResponseSchema.parse(res.json).nofj;
+}
+/**
+ * ka90001 테마그룹별요청 — theme groups (all fields live-verified 2026-07-07).
+ * `stockCode` set → qry_tp "2" (themes the stock belongs to); else qry_tp "0"
+ * (all themes, sorted by change rate). First page only (100/page); open-ended
+ * "all" mode paginates but page-1 top rows are what a caller wants.
+ * date_tp = 기간수익률 산정 일수, flu_pl_amt_tp "1" = 등락률 상위순, stex_tp "1" = KRX.
+ */
+export async function fetchThemeGroups(client, stockCode) {
+    const res = await client.call({
+        path: THEME_PATH,
+        apiId: "ka90001",
+        body: {
+            qry_tp: stockCode ? "2" : "0",
+            stk_cd: stockCode ?? "",
+            date_tp: "10",
+            flu_pl_amt_tp: "1",
+            stex_tp: "1",
+        },
+    });
+    return themeGroupsResponseSchema.parse(res.json).thema_grp;
+}
+/**
+ * ka90002 테마구성종목요청 — member stocks of one theme group (live-verified).
+ * Returns the full response so the theme's aggregate flu_rt/dt_prft_rt (top-level
+ * fields) are available to the caller. themeCode = ka90001 `thema_grp_cd`.
+ */
+export async function fetchThemeStocks(client, themeCode) {
+    const res = await client.call({
+        path: THEME_PATH,
+        apiId: "ka90002",
+        body: { date_tp: "2", thema_grp_cd: themeCode, stex_tp: "1" },
+    });
+    return themeStocksResponseSchema.parse(res.json);
+}
+/**
+ * ka10014 공매도추이요청 — per-stock daily short-selling trend over [fromDate, toDate].
+ * All fields live-verified 2026-07-07. tm_tp "1" = 일별. Rows newest-first.
+ */
+export async function fetchShortSelling(client, stockCode, fromDate, toDate) {
+    const res = await client.call({
+        path: SHORT_PATH,
+        apiId: "ka10014",
+        body: { stk_cd: stockCode, tm_tp: "1", strt_dt: fromDate, end_dt: toDate },
+    });
+    return shortSellingResponseSchema.parse(res.json).shrts_trnsn;
+}
+/**
+ * ka10008 주식외국인종목별매매동향 — per-stock daily foreign holding trend
+ * (보유주식수/보유비중/한도소진률). Live-verified 2026-07-07. Paginates (50/page,
+ * `hasNext`); first page only — recent days are what a caller wants.
+ */
+export async function fetchForeignHolding(client, stockCode) {
+    const res = await client.call({
+        path: FOREIGN_PATH,
+        apiId: "ka10008",
+        body: { stk_cd: stockCode },
+    });
+    return foreignHoldingResponseSchema.parse(res.json).stk_frgnr;
+}
+/**
+ * ka10170 당일매매일지요청 — the day's trading journal (per-stock realized P&L). Account-scoped.
+ * Returns the full response (period totals + return_msg) so callers can surface the
+ * "최근 2개월 이내" notice. base_dt yyyyMMdd; ottks_tp "1" = 단주 포함, ch_crd_tp "0" = 전체.
+ * NOTE: an empty day returns one all-blank row — callers must filter blank rows.
+ */
+export async function fetchTradingJournal(client, baseDate) {
+    const res = await client.call({
+        path: ACCOUNT_PATH,
+        apiId: "ka10170",
+        body: { base_dt: baseDate, ottks_tp: "1", ch_crd_tp: "0" },
+    });
+    return tradingJournalResponseSchema.parse(res.json);
+}