한국장/미국장 현재 상태, 휴장 여부, 최근/다음 거래일을 한 번에 조회합니다.

종목 분석 전 데이터 기준시각을 확인할 때 사용합니다. KRX와 NYSE/NASDAQ의 주말, 정규 휴장일, 장전/정규장/시간외/장마감 상태를 함께 반환합니다. 한국장은 2026-09-14부터 애프터마켓(16:00~20:00)이 세션으로 잡히고, 프리마켓은 시행 전이라 나오지 않습니다. current_session·sessions·next_session이 지금 체결되는 세션과 오늘 남은 세션을 알려줍니다(is_open은 정규장만 뜻함).

상태요약 — 버전/라이선스/국내·미국 시장 상태/최근 성공·실패/캐시 쓰기 가능 여부를 한 번에.

문제가 있는지 대화 중 가볍게 확인할 때 사용합니다. 이미 기록된 최근 호출 로그와 업데이트 확인 캐시만 읽으므로 네트워크를 새로 호출하지 않습니다(빠름). 라이선스 미활성 상태에서도 원인 파악용으로 동작해야 하므로 다른 도구와 달리 라이선스 게이트를 걸지 않습니다. 문제가 있으면 LeetKit Manager의 [진단]이나 상단 [지원 문의]를 안내하세요. 터미널 명령은 안내하지 마세요.

종목검색 — 종목명 또는 종목코드로 한국 주식 종목을 조회합니다. "삼성전자 종목코드", "반도체 관련주", "005930 뭐야" 같은 질문에 사용합니다.

⚠️ 사용자가 종목명만 주고 코드를 모를 때 반드시 이 도구를 먼저 호출. 종목 코드를 추측하지 말 것. 상장폐지·재할당으로 코드가 바뀔 수 있음.

search_stock으로도 동일하게 호출 가능 (별명).

Args: query: 검색할 종목명 또는 코드 (예: "삼성전자", "005930", "알멕")

종목코드조회 (stock lookup) — 한국 주식 종목명/코드 조회 전용 도구.

search와 동일 기능. 도구 디스커버리에서 "stock"/"ticker"/"종목" 키워드로 빠르게 매칭되도록 명확한 이름을 갖는 별명입니다.

⚠️ 종목명만 있고 6자리 코드를 모를 때 이 도구를 먼저 호출해야 합니다. 코드 추측(guessing) 금지. 다른 도구(get_price, get_chart 등)에 잘못된 코드를 넣으면 엉뚱한 종목이 조회됩니다.

Args: query: 종목명(한/영) 또는 6자리 코드. 예: "알멕", "Samsung", "005930"

Returns: 매칭된 종목 리스트. 여러 개면 사용자에게 확인 요청 필요.

관심종목 — '내 종목' 목록 보기/추가/삭제 (LeetKit 세 Lens 공용).

"내 종목", "관심종목", "○○ 관심종목에 넣어줘", "내 종목 시세 보여줘" 같은 요청에 사용합니다. DartLens·TelegramLens와 같은 목록을 공유합니다.

list 결과의 codes를 그대로 get_multi_stocks / get_flow_batch / get_indicators_bulk에 넘기면 관심종목 전체를 한 번에 볼 수 있습니다. 종목을 하나씩 다시 조회하지 마세요.

Args: action: "list"(기본) / "add" / "remove" / "clear" query: add·remove에 쓸 종목명 또는 6자리 코드 (예: "디오", "039840")

캔들차트 OHLCV — 종목의 시계열 캔들 데이터(시가/고가/저가/종가/거래량, candlestick OHLCV).

⚠️ 여러 종목의 기간 통계만 필요하면 get_multi_chart_stats를 쓰세요. "삼성전자 일봉", "3개월 주봉", "월봉 데이터", "price history" 같은 질문에 사용. 시계열 진입점(US는 get_us_chart).

보조지표(이평선·RSI·MACD 등)는 사용자가 명시 요청할 때만 get_indicators로 숫자만 받아 요약.

Args: code: 종목코드 6자리 (예: "005930") timeframe: "day"(일봉), "week"(주봉), "month"(월봉) count: 가져올 봉 개수 (기본 120 ≈ 6개월, 최대 500)

현재가 — 종목의 현재 시세 스냅샷 (오늘 하루치 OHLC + 거래량).

⚠️ 종목이 2개 이상이면 get_multi_stocks를 쓰세요. "삼성전자 지금 얼마", "현재가", "오늘 시세", "주가 알려줘" 같은 질문에 사용합니다.

⚠️ 단일 시점 스냅샷. 과거 시계열 아님. 차트/히스토리 필요 시 get_chart 사용. 코스피200/코스닥150 등 NXT 대상 종목은 KRX 정규장을 기본값으로 보여주고, NXT(대체거래소) 시세는 별도 블록으로 덧붙입니다(두 시장 수치를 섞지 않음).

Args: code: 종목코드 6자리 (예: "005930")

투자자수급 — 투자자별 매매동향 (개인/기관/외국인 순매매 주식 수)을 가져옵니다.

⚠️ 종목이 2개 이상이면 이 도구를 반복하지 말고 get_flow_batch를 쓰세요. "외국인 수급", "기관 순매수", "수급 분석", "누가 사고 있어" 같은 질문에 사용합니다.

Args: code: 종목코드 6자리 (예: "005930") days: 조회할 일수 (기본 20일)

이벤트반응 — 특정 날짜(event_date) 기준 전후 주가·거래량·수급 반응을 정렬합니다.

DartLens의 scan_earnings_season·list_disclosures에 나온 공시 접수일을 event_date로 넘김 (휴장일이면 다음 거래일 기준). "공시→주가/수급" 또는 "주가/수급 이상→해당 기간 공시 확인" 시간축 정렬용 — 원인 단정·매수/매도 판단 아님.

분석 불가한 사건창(보유 데이터 구간 밖·전 구간 거래정지·수급 결측)은 숫자를 만들지 않고 validation 상태와 코드로 되돌린다. 데이터 없음은 0%·순매매 0으로 표기되지 않는다.

Args: code: 종목코드 6자리 (예: "005930") event_date: 기준 날짜 YYYY-MM-DD 또는 YYYYMMDD. DartLens 공시 접수일 권장 before: event_date 전 비교 거래일 수 (기본 5, 최대 60) after: event_date 후 비교 거래일 수 (기본 20, 최대 60)

공시반응이력 — 최근 공시들에 이 종목이 어떻게 반응해 왔는지 한 번에.

"이 종목은 호재에 잘 오르나", "공시 나오면 어떻게 움직였나", "최근 반응이 예전보다 약해졌나" 같은 질문에 사용합니다.

get_event_reaction은 날짜 하나만 봅니다. 공시 8건을 보려면 8번 불러야 하고 응답도 8배가 됩니다. 이 도구는 일봉·수급을 한 번만 받아 여러 공시일을 한꺼번에 계산합니다.

⚠️ 반응이 좋았다고 앞으로도 그러리라는 뜻이 아닙니다. 과거 기록일 뿐입니다. ⚠️ 네이버 공시 목록에는 '가격제한폭 확대요건 도달' 같은 시장 안내도 섞입니다. 제목을 보고 실제 기업 공시인지 구분하세요.

Args: code: 종목코드 6자리 max_events: 볼 공시 개수 (기본 8, 최대 15). 같은 날 여러 건이면 하나로 묶습니다. before: 기준일 전 비교 거래일 수 (기본 5) after: 기준일 후 비교 거래일 수 (기본 10, 최대 60) include_types: 이 유형만 봅니다. 유형: 실적/계약/자금조달/지배구조/행정/IR/기타. 예: ["실적"] 이면 가격제한폭 확대·공매도 과열 같은 행정 안내가 빠집니다. exclude_types: 이 유형을 뺍니다 (include_types 와 함께 쓰면 include 적용 후 제외).

수급벌크 — 여러 종목의 투자자 수급(기관·외국인 순매매)을 한 번에 병렬 조회.

개별 get_flow를 N번 부르는 것보다 훨씬 빠릅니다 (서버 내부 asyncio.gather). "이 종목들 외국인 매수 같이 들어왔나", "관심종목 수급 비교" 같은 질문에 사용.

summary=True 는 심층 모드입니다: 일별 원문 대신 종목당 5/20/60일 누적 순매매와 순매수(양수) 일수로 압축해, 상한이 60일로 늘어납니다. "15종목 최근 60일 수급 판정" 같은 질문을 단건 호출 없이 한 번에 봅니다.

Args: codes: 종목코드 리스트 (최대 30개) days: 종목당 조회 일수 (기본 5, 일별 모드 최대 20 / summary 모드 최대 60) summary: True 면 일별 행 대신 5/20/60일 누적·순매수 일수 요약 (기본 False)

수급스크리닝 — 거래대금/거래량 상위 N개 중 외국인·기관이 최근 며칠 연속 순매수한 종목만 추립니다.

"거래대금 상위 중 외국인·기관 동반 매수", "이틀 연속 수급 들어온 종목" 같은 스크리닝 전용. 랭킹+수급을 서버에서 join해 매치 종목만 반환 → 토큰·시간 절감. 후보는 get_volume_ranking 과 같은 순위입니다 — trade_value 면 시장 전체 거래대금 상위 N개 (대형주 포함), volume 이면 시장 전체 거래량 상위 N개.

Args: top_n: 상위 후보 수 (기본 100, 최대 500). 클수록 정확하나 느림(500≈20~50초) market: "KOSPI"/"KOSDAQ"/"ALL" (기본 ALL) foreign_days: 최근 N일 모두 외국인 순매수여야 매치 (0=미적용) inst_days: 최근 N일 모두 기관 순매수여야 매치 (0=미적용) exclude_etf: ETF/ETN 제외 (기본 True) sort_by: "trade_value"(거래대금, 기본)/"volume"(거래량)

재무지표 — 한 종목의 전체 재무지표(연간·분기 추이 19개 항목).

⚠️ 여러 종목을 비교하려면 get_financial_batch를 쓰세요. 이 도구는 종목당 3,500자를 뱉어서, 5종목만 비교해도 재무가 전체 토큰의 78%를 먹습니다. "PER", "PBR", "재무제표", "시가총액", "저평가" 같은 질문에 사용합니다.

Args: code: 종목코드 6자리 (예: "005930")

재무벌크 — 여러 종목의 핵심 재무지표(PER/PBR/ROE/영업이익률/부채비율/배당률)를 한 표로.

⭐ 종목 비교의 기본 도구. "A와 B를 PER·PBR로 비교", "이 5종목 중 저평가", "업종 내 비교" 같은 요청에 get_financial을 종목마다 부르지 말고 이걸 쓰세요. (실측: 5종목 비교 시 get_financial 5회가 전체 토큰의 78%를 차지했습니다.)

한 종목의 전체 지표(연간·분기 시계열, EPS/BPS/유보율 등)가 필요하면 그때만 get_financial을 쓰세요.

Args: codes: 종목코드 6자리 리스트 (최대 30개)

시장지수 — KOSPI, KOSDAQ 지수 현재값을 가져옵니다. "코스피", "코스닥", "시장 지수", "오늘 시장 어때" 같은 질문에 사용합니다.

테마목록 — 네이버 증권의 테마 목록을 가져옵니다. "어떤 테마가 있어?", "테마 리스트", "오늘 강세 테마" 같은 질문에 사용합니다. 총 7페이지가 있으며 한 페이지당 40개 테마가 있습니다. 전일대비 등락률 순으로 정렬되어 있어요.

Args: page: 페이지 번호 (1~7, 기본 1)

테마종목 — 특정 테마에 속한 종목 리스트를 가져옵니다. "반도체 테마 종목", "2차전지 관련주", "AI 테마주" 같은 질문에 사용합니다. 테마명 부분 매칭을 지원합니다.

⚠️ 등락률 내림차순으로 반환합니다. count로 자르면 그날 많이 오른 종목만 남고 소외된(많이 내린) 종목은 뒤쪽 쪽으로 밀립니다. 결과 머리말에 테마 전체 종목 수와 이 쪽의 범위("전체 N개 중 1~30번째")가 나옵니다. 저평가·소외 종목을 찾는 용도라면 count를 전체 종목 수로 주거나(최대 500) 꼬리말의 page=로 이어 받으세요. 시가총액 기준 모집단이 필요하면 get_market_cap_ranking을 쓰세요.

Args: theme_name: 테마명 (예: "2차전지", "AI", "반도체") count: 한 번에 받을 종목 수 (기본 30, 최대 500) include_reason: 편입사유 포함 여부. False로 하면 토큰 대폭 절감. "왜 이 테마에 들어갔는지" 필요 없으면 False 권장. page: count 개씩 나눈 몇 번째 쪽인가 (기본 1). page=2, count=30 이면 31~60번째.

업종목록 — 네이버 증권의 업종(섹터) 목록을 가져옵니다. "업종별 현황", "섹터 리스트", "업종 등락률" 같은 질문에 사용합니다. 약 79개 업종이 전일대비 등락률 순으로 정렬됩니다.

업종종목 — 특정 업종에 속한 종목 리스트를 가져옵니다. "통신장비 업종 종목", "반도체 업종", "제약 섹터 종목" 같은 질문에 사용합니다. 업종명 부분 매칭을 지원합니다.

⚠️ 등락률 내림차순으로 반환합니다. count로 자르면 그날 많이 오른 종목만 남고 소외된(많이 내린) 종목은 뒤쪽 쪽으로 밀립니다. 결과 머리말에 업종 전체 종목 수와 이 쪽의 범위("전체 175개 중 1~30번째")가 나옵니다. 업종 전체를 보려면:

• 500종목 이하 업종: count를 머리말의 전체 수로 주세요 (예: 제약 175 → count=175).

• 그보다 큰 업종(예: '기타' 약 1,500종목): count=500 으로 page=1, 2, 3, 4 를 차례로. 꼬리말에 다음 쪽 호출법이 나옵니다. 쪽은 같은 순간의 목록에서 자릅니다(장중 5분 캐시). 몇 분 넘게 띄워 받으면 그 사이 등락률 순서가 바뀌어 경계 종목이 겹치거나 빠질 수 있습니다.

Args: sector_name: 업종명 (예: "통신장비", "반도체", "제약") count: 한 번에 받을 종목 수 (기본 30, 최대 500) page: count 개씩 나눈 몇 번째 쪽인가 (기본 1). page=2, count=30 이면 31~60번째.

업종밸류에이션 — 업종·테마의 PER·PBR·ROE 집계와 종목별 할증/할인 위치.

"반도체 업종 평균 PER", "이 업종에서 싼 편인가", "동종 대비 할증인가" 같은 질문에 사용합니다. 개별 종목 지표(get_financial)로는 알 수 없는 비교 기준을 만듭니다.

통계는 중앙값이 기준입니다. 평균은 적자 기업과 극단값(PER 500배 등)에 쉽게 흔들려 업종 대표값으로 쓰기 어렵습니다.

집계는 항상 업종 전체로 하고, top_n 은 아래 위치 표에 몇 종목을 보여줄지만 정합니다 - top_n 을 바꿔도 중앙값은 변하지 않습니다. (업종이 집계 상한을 넘으면 전체 중앙값 대신 표본 중앙값(sample_median) 으로 이름을 낮춰 표기합니다.)

⚠️ 적자 기업의 PER은 음수로 나오며 집계에서 제외합니다(제외 건수를 함께 표기).

⭐ 종목코드만 넘겨도 됩니다 — code="005930" 이면 그 종목의 업종을 찾아 집계한 뒤, 그 종목이 업종 안에서 어디에 있는지 표시합니다. 업종명을 모를 때 이 방식을 쓰세요(ETF·ETN은 소속 업종이 없어 조회되지 않습니다).

Args: sector_name: 업종명 또는 테마명 (예: "반도체와반도체장비", "건설"). code 를 주면 생략할 수 있습니다. top_n: 위치 표에 표시할 종목 수 (기본 40, 최대 80). 집계 분모가 아닙니다. kind: "sector"(업종, 기본) / "theme"(테마) code: 6자리 종목코드. 주면 업종을 자동 판정합니다.

거래량/거래대금 순위 — 상위 종목을 가져옵니다.

"거래량 많은 종목" → sort_by="volume" (기본, 주수 기준) "거래대금 많은 종목"/"거래 규모 큰 종목"/"돈이 몰린 종목" → sort_by="trade_value" (원 기준)

두 순위는 뽑는 대상부터 다릅니다. volume 은 시장 전체의 거래량 순위, trade_value 는 시장 전체의 거래대금 순위를 그대로 받습니다(거래량 상위 안에서 다시 줄 세우는 게 아님). 주가가 높은 대형주(삼성전자·SK하이닉스 등)는 주수가 작아 volume 순위에는 잘 안 보이고, 주가가 몇 원~몇백 원인 종목은 주수만 커서 volume 순위 위쪽에 올라옵니다. 시장 자금이 어디 몰렸는지 볼 때는 trade_value 를 쓰세요.

거래량·거래대금은 KRX 체결분입니다(넥스트레이드 체결은 들어 있지 않음).

Args: market: "KOSPI" / "KOSDAQ" / "ALL" (기본 ALL) count: 가져올 종목 수 (기본 50, 최대 500) sort_by: "volume"(거래량 주수) / "trade_value"(거래대금 원)

등락률순위 — 등락률 상위/하위 종목을 가져옵니다. "상한가 종목", "급등주", "급락주", "상승률 상위" 같은 질문에 사용합니다.

Args: direction: "up"(상승률 상위) / "down"(하락률 상위) market: "KOSPI" / "KOSDAQ" / "ALL" (기본 ALL) count: 가져올 종목 수 (기본 50, 최대 500)

시가총액순위 — 시가총액 상위 종목을 가져옵니다. "대형주", "시가총액 TOP", "코스피 대장주", "코스닥 전 종목 시총" 같은 질문에 사용합니다.

결과 머리말에 시장 전체 종목 수와 이 표의 순위 범위("전체 1,820개 중 1~50위")가 나옵니다. 501위 아래도 받을 수 있습니다 — count 개씩 나눈 쪽을 page로 고릅니다.

• 시장 전체: count=500 으로 page=1, 2, … 를 꼬리말에 "다음 쪽"이 없을 때까지. (2026-09 기준 KOSPI 약 950개 = 2쪽, KOSDAQ 약 1,800개 = 4쪽)

• 특정 순위 구간: 예) 301~400위 = count=100, page=4. 쪽은 같은 순간의 목록에서 자릅니다(장중 1분 캐시). 장중에 몇 분 넘게 띄워 받으면 그 사이 순위가 바뀌어 경계 종목이 겹치거나 빠질 수 있습니다.

⚠️ 순위표에는 주식만 있는 게 아닙니다. 리츠·인프라펀드·상장 펀드·외국기업(DR 포함) 행이 같은 순위에 섞여 있고, 거래정지 종목도 들어 있습니다. 해당 행은 '구분' 열에 표시되고, 시장 전체의 구분별 개수는 결과 끝에 나옵니다. "상장 기업 수"처럼 주식만 셀 때는 그 개수를 쓰세요.

Args: market: "KOSPI" / "KOSDAQ" (기본 KOSPI, ALL 미지원) count: 한 번에 받을 종목 수 (기본 50, 최대 500) page: count 개씩 나눈 몇 번째 쪽인가 (기본 1). page=2, count=500 이면 501~1000위.

벌크조회 — 여러 종목의 기본 정보(가격/등락률/거래량)를 한 번에 가져옵니다. "이 종목들 현재가 보여줘", "리스트 종목 시세 한번에" 같은 질문에 사용합니다. 개별 get_price를 여러 번 호출하는 것보다 훨씬 토큰 효율적입니다. 스크리닝 결과 N개 종목을 비교 분석할 때 필수 도구.

Args: codes: 종목코드 리스트 (최대 30개, 예: ["005930", "000660", "005380"])

차트통계벌크 — 여러 종목의 기간 집계 통계(현재가/최고가/최저가/낙폭/기간수익률)를 한 번에 병렬 조회.

⚠️ 시계열 아님 — 집계값만 반환(캔들·OHLCV는 get_chart). 개별 get_chart N번 대신 이걸로. ⭐ 스크리닝 필수: "52주 고점 대비 -30% 종목" 등 drawdown_pct·period_return_pct 필터에 사용.

Args: codes: 종목코드 리스트 (최대 100개) days: 과거 조회 일수 (기본 260 = 52주)

기술지표 — 이평선·RSI·MACD·볼린저·스토캐스틱 등 종합 판정 (JSON).

스크리닝·조건 필터·상태 판정 등 숫자 비교가 필요할 때만 호출. 차트 시각화용 아님(시각화는 get_chart). OHLCV 대신 판정 결과만 반환해 토큰 절약. 반환값의 라벨 필드(phase_label, type_label, position 등)는 그대로 인용할 것.

키 이름이 곧 정의입니다 — 임의로 바꿔 읽지 마세요: volume.latest(+latest_date) 마지막 봉의 거래량. '오늘'이 아님 volume.avg_20b / ratio_vs_avg_20b 20봉(거래일) 평균 대비 volume.trade_value_est_krw 종가×거래량 추산. 실제 거래대금과 다름 volume.volume_rank_252b 252봉 중 순위, 1이 최다 position.bars_since_high/low 달력일이 아니라 봉 개수. 달력일이 필요하면 high_date/low_date로 직접 계산하세요. position.high_52w/low_52w 봉이 1년치(일 252·주 52·월 12)가 안 되면 null. 그때 조회 구간 고저는 lookback_high/low 에 있습니다 주봉·월봉의 크로스 경과는 days_ago 가 아니라 bars_ago(봉 개수) _meta.data_basis가 in_progress_bar면 마지막 봉이 미마감이라 이 판정들은 장 마감 시 달라질 수 있습니다.

Args: code: 종목코드 (예: "005930") days: 조회 일수 (기본 260, 30~500). 구조 분석 지표는 500+ 권장. include: 지표 키. 기본 ["ma", "ma_phase", "volume", "candle"]. 스냅샷: ma ma_phase ma_slope ma_cross rsi macd bollinger stochastic obv volume position candle 구조: support_resistance volume_profile price_channel timeframe: "day"/"week"/"month" (분봉 미지원) params: 비표준 파라미터 오버라이드(사용자 명시 요청 시만). 예: {"rsi":{"period":21}}

기술지표벌크 — 여러 종목(최대 100개)의 지표를 병렬 판정. 스크리닝 핵심.

⚠️ 시계열·캔들 아님 — 집계 판정값만(시각화는 get_chart). get_indicators N번 대신 이걸로.

Args: codes: 종목코드 리스트 (최대 100개) days: 조회 일수 (기본 260) include: 지표 키 (기본 ["ma_phase","volume"]). get_indicators 참조. timeframe: "day"/"week"/"month" params: 지표 파라미터 오버라이드(전 종목 공통). get_indicators 참조.

엑셀내보내기 — 단일 종목의 데이터를 Excel 파일로 저장합니다.

Gemini/GPT 같은 다른 AI에 파일 업로드로 넘기거나, 엑셀에서 직접 분석/차트 작성할 때 사용합니다.

Args: data_type: "chart"(일봉 OHLCV) / "flow"(투자자별 수급) / "financial"(재무지표) code: 종목코드 6자리 (예: "005930") days: chart/flow의 경우 과거 일수 (기본 180) filename: 파일명 (비우면 자동 생성)

Returns: 저장된 파일 경로

시장스캔 — 원하는 항목만 골라 여러 종목을 Excel 한 장으로 저장.

로컬 캐시 패턴: 한 번 스캔 → 이후 query_excel(파일경로, 조건)로 즉시 반복 필터링.

fields — 넣을 항목을 직접 고른다

생략하면 ["price", "chart", "financial"] 이 들어갑니다(기존과 동일). 필요 없는 항목을 빼면 그만큼 조회가 줄어 빨라집니다.

무엇을 넣을지 사용자와 정하는 법

사용자가 "엑셀로 만들어줘"라고만 하면 바로 기본 세트로 만들지 말고, 무엇에 쓸 파일인지 한 번 물어보세요. 목적에 따라 넣을 항목이 달라집니다.

"어떤 걸 보시려고 하시나요? 아래처럼 목적을 말씀해 주시면 맞춰 담아드릴게요. — 싼 종목 고르기 / 수급 흐름 보기 / 차트 흐름 보기 / 업종 안에서 비교 / 전부"

목적별 추천 구성

이미 사용자가 목적을 밝혔다면 다시 묻지 말고 위 표대로 골라 담으세요. 종목이 30개를 넘으면 항목이 많을수록 눈에 띄게 느려지므로, 그때는 필요한 것만 담고 나중에 더 필요하면 다시 부르는 편이 낫다고 안내하세요.

Args: codes: 종목코드 리스트 (최대 500개) fields: 넣을 항목. 위 표의 값들 중에서 고릅니다. 생략 시 기본 세트. days: 차트 통계 과거 일수 (기본 260 = 52주) include_financial: (구버전 호환) fields 를 안 줬을 때만 적용됩니다. filename: 파일명 (비우면 자동 생성)

분석결과저장 — 당신이 정리한 표를 그대로 Excel로 저장합니다.

scan_to_excel 은 정해진 지표를 종목별로 담는 도구입니다. 이 도구는 그와 달리, 여러 도구를 돌려 직접 판단하고 정리한 결과(후보 목록, 단계 판정, 겹침 분석 같은 것)를 사용자가 파일로 가져갈 수 있게 만듭니다.

반드시 지킬 것

1. rows 의 숫자는 도구가 돌려준 값만 씁니다. 기억이나 추정으로 채우지 마세요. 확인 못 한 칸은 "-" 또는 "확인 안 됨" 으로 두고, 0 으로 채우지 않습니다.

2. sources 에 어떤 도구를 썼는지 적습니다. 파일만 남았을 때 이 숫자가 어디서 왔는지 알 수 있어야 합니다. 예: ["screen_by_flow", "get_indicators_bulk"]

3. 판단 근거와 한계를 notes 에 적습니다. 무엇을 걸렀고 무엇을 못 봤는지, 장중 잠정치인지 같은 것. 표만 남으면 나중에 잘못 읽힙니다.

4. 매수·매도 권유, 목표가·손절가는 넣지 않습니다.

rows 구성 요령

• 각 dict 의 키가 곧 열 이름입니다. 한글로 쓰세요(예: "종목명", "수급(2일)").

• 모든 행이 같은 키를 갖도록 맞춥니다. 빠진 키는 빈칸이 됩니다.

• 숫자는 숫자 그대로 넣으세요(문자열 "12.5%" 대신 12.5). 자릿점·색은 저장할 때 자동으로 붙습니다. 단위는 열 이름에 넣으세요("기간수익률(%)").

• 종목이 20개 이하면 비교 그래프가 자동으로 함께 저장됩니다.

Args: title: 파일 제목. 첫 시트 이름과 요약에 쓰입니다. 예: "기대 부상후보 스캔" rows: 표 데이터. [{"종목명": "성광벤드", "기간수익률(%)": -8.9}, ...] notes: 판단 근거·제외 기준·한계. 한 줄에 하나씩. sources: 근거가 된 도구 이름들. detail_codes: 종목별 흐름 시트를 만들 6자리 코드들(최대 8개). 각 시트에 종가 추이·기관/외국인 순매매 그래프와 원자료가 들어갑니다. 목록만 있으면 "그래서 어떻게 움직이고 있나"를 다시 조회해야 하므로, 사용자가 더 볼지 정할 수 있게 후보 상위 몇 개는 넣어 주세요. detail_days: 흐름 시트에 담을 거래일 수 (기본 60, 최대 120). extras: 다른 렌즈에서 가져온 것을 종목 시트에 얹습니다. StockLens 는 TelegramLens·DartLens 를 직접 부르지 못하므로, 그 도구들을 먼저 호출해 결과를 여기에 담아 주세요. {"042660": [{"title": "텔레그램 언급", "cols": ["시각","채널","내용"], "rows": [["08-26 10:30","매경 자이앤트","원전 수주 기대"]]}]} 형식이며, 카드는 담은 순서대로 붙습니다. 넣을 만한 것: · TelegramLens — telegram_stock_buzz(언급 원문·telegram_link 를 url 로), telegram_timeline(확산 흐름) · DartLens — get_major_holders(5%룰: 연기금·행동주의 진입), get_insider_trades(임원·주요주주 매매 = 안에서 먼저 움직인 흔적), list_disclosures(정기·수시 공시), get_order_backlog(수주잔고 추이) · StockLens — get_us_short(미국 공매도), get_event_reactions(공시 반응) 행은 ["값", ...] 또는 {"cells": [...], "url": "원문 링크"} 로 넣습니다. ⚠️ 원문에 있는 내용만 옮기고, 없는 것을 지어내지 마세요. filename: 파일명 (비우면 제목으로 자동 생성)

엑셀쿼리 — 저장된 Excel 스냅샷(scan_to_excel 산출)에서 조건에 맞는 종목을 로컬 필터링. HTTP 없이 빠름.

필터 형식(둘 다 지원): 간단: {"per_max": 10, "pbr_max": 1.5, "drawdown_pct_max": -30} 상세: {"per": {"max": 10, "min": 0}, "drawdown_pct": {"max": -30}}

Args: file_path: scan_to_excel로 만든 파일 경로 filters: 필터 조건 (컬럼명_max / 컬럼명_min 형식) sort_by: 정렬 기준 컬럼 (예: "market_cap", "drawdown_pct") descending: 내림차순 (기본 True) limit: 반환 최대 개수 (기본 30)

사용량통계 — 최근 N일간 MCP 도구 사용량을 집계해서 보여줍니다.

디버깅/최적화용. 도구별로:

• 호출 횟수

• 평균/p50/p95 실행 시간

• 평균 토큰 소모량

• 캐시 히트율

• 에러 발생 횟수 를 보여줍니다.

로그 파일 위치: ~/.stocklens/logs/metrics_YYYYMMDD.jsonl (2026-08 이전 기록은 ~/Downloads/kstock/logs/ 에 있고, 그것도 같이 읽습니다)

Args: days: 조회할 일수 (기본 1, 오늘만. 최대 30)

ETF목록 — ETF 전체 목록 조회, 카테고리·이름 키워드 필터링.

category: 카테고리 필터 (빈 문자열=전체). 가능한 값: "국내 시장지수", "국내 업종/테마", "국내 파생", "해외 주식", "원자재", "채권/금리", "단기자금" keyword: ETF 이름에 포함된 키워드로 필터 (예: "우주", "반도체", "배당"). "OO 테마 ETF 뭐 있어" 같은 질문은 category를 추측하지 말고 keyword로 바로 찾는다 — 한국 ETF는 이름 자체가 테마를 직설적으로 담는 관행이라 (예: "TIGER 미국우주테크") 이름 검색만으로 대부분 커버된다. 단, 특정 회사(예: 비상장사)를 "보유"한 ETF를 찾는 건 이 키워드로 안 된다 — 그 회사명이 ETF 이름 자체에 없으면 못 찾으니, 후보 ETF를 좁힌 뒤 get_etf_info로 구성종목을 직접 확인해야 한다. sort_by: 정렬 기준, 전부 큰 값이 앞 — "marketSum"(시가총액, 기본), "quant"(거래량), "threeMonthEarnRate"(3개월 수익률 높은 순 — 손실이 큰 ETF는 맨 뒤), "nav"(주당 NAV). 1·6·12개월 수익률과 배당은 목록에 없어 정렬할 수 없다(종목별 get_etf_info 로 확인). limit: 반환 개수 (기본 20, 최대 50)

ETF정보 — ETF 상세 정보 (기초지수, 보수율, 수익률, 구성종목 TOP10).

code: ETF 종목코드 (예: "069500" KODEX 200, "360750" TIGER 미국S&P500)

US stock price — NYSE/NASDAQ 미국 주식 현재가 스냅샷 (US market via yfinance). "AAPL price", "Tesla 현재가", "MSFT quote", "Nvidia 얼마" 같은 질문에 사용합니다.

현재가 + 전일대비 + 시/고/저 + 거래량 + 52주 고저 + 베타 + 시가총액 + 마켓 상태 (정규장/프리/포스트) 반환. Yahoo Finance 데이터는 최대 15분 지연 가능.

Args: ticker: US 티커 (예: "AAPL", "TSLA", "BRK.B", "SPY")

US stock info — 미국 주식 기업 정보 (섹터, 산업, 시총, 사업 요약 · US company profile). "Apple 어떤 회사", "NVDA 사업 설명", "TSLA sector", "기업 정보" 같은 질문에 사용합니다.

Args: ticker: US 티커 (예: "AAPL", "NVDA")

US stock chart OHLCV — 미국 주식 시계열 캔들 데이터 (US historical price data). "AAPL 차트", "Tesla 1년 주가", "NVDA history" 같은 질문에 사용. US 시계열 진입점(한국은 get_chart).

Args: ticker: US 티커 (예: "AAPL") period: "1d","5d","1mo","3mo","6mo","1y","2y","5y","10y","ytd","max" (기본 3mo) interval: "1m","5m","15m","30m","1h","1d","1wk","1mo" (기본 1d) prepost: 프리/포스트 마켓 포함 (intraday에서만 유효) limit: 최대 행수 (기본 500, 최대 5000). 큰 데이터는 export_us_to_excel 권장(토큰 0).

US stock financials — 미국 주식 재무지표 (PER, PBR, PEG, ROE, 배당률 · US valuation ratios). "AAPL PER", "Apple 재무", "NVDA valuation", "forward P/E" 같은 질문에 사용합니다.

Trailing / Forward P/E, PEG, P/B, P/S, EPS, ROE, ROA, 부채비율, 마진, 성장률, 배당수익률, 배당성향을 반환합니다.

Args: ticker: US 티커 (예: "AAPL")

US earnings calendar — 다음 실적 발표일 + 최근 EPS 서프라이즈 이력 (US earnings date / EPS surprise). "AAPL 실적 언제", "NVDA earnings date", "Tesla 다음 실적" 같은 질문에 사용합니다.

미국 시장은 분기 실적(10-Q)이 주가 변동의 핵심 이벤트입니다.

Args: ticker: US 티커 (예: "NVDA")

US event reaction — 발표 세션에 맞는 기준 거래일로 주가 반응을 정렬 (SL-05).

미국 실적은 장전(BMO)·장후(AMC) 발표가 갈린다. 장전 발표는 당일 봉이, 장후 발표는 다음 거래일 봉이 첫 반응이다. 이 정렬을 자동으로 한다. 완성된 일봉만 쓴다(진행 중 봉 제외).

Args: ticker: US 티커 event_date: 발표일 YYYY-MM-DD session: "auto"(실적 발표 시각에서 자동 판정) / "pre" / "post" / "unknown" after: 사건 후 비교 거래일 수 (기본 5, 최대 20)

US analyst ratings — 미국 주식 애널리스트 목표주가 + 투자의견 (US analyst price target / rating). "AAPL 목표가", "NVDA analyst rating", "Tesla buy/hold", "Wall Street 의견" 같은 질문에 사용합니다.

목표주가(mean/high/low) + buy/hold/sell 분포 + 최근 업·다운그레이드를 반환합니다.

Args: ticker: US 티커 (예: "NVDA")

US dividends — 미국 주식 배당 이력 + ex-date + yield (US dividend history / yield). "AAPL 배당", "KO dividend yield", "SCHD 배당 이력", "ex-date" 같은 질문에 사용합니다.

Args: ticker: US 티커 (예: "KO", "JNJ", "SCHD") limit: 표시할 최근 배당 건수 (기본 12)

US options chain — 미국 주식 옵션 체인 (calls/puts, IV, OI · US equity options). "AAPL options", "Tesla 콜옵션", "NVDA implied volatility", "옵션 체인" 같은 질문에 사용합니다.

기본: 최근접 만기의 현재가 근처 strike. Greeks (delta/gamma/theta)는 미포함.

Args: ticker: US 티커 (예: "AAPL") expiration: 만기일 "YYYY-MM-DD". 미지정 시 가장 가까운 만기. strikes_around_spot: 현재가 기준 좌우 strike 개수 (기본 10)

US insider trading — 내부자 거래 Form 4 + 최근 6개월 순매수 요약 (US insider Form 4). "AAPL insider trading", "NVDA 내부자 매수", "CEO stock sale" 같은 질문에 사용합니다.

Args: ticker: US 티커

US institutional holders — 기관·뮤추얼펀드 보유 현황 (13F holdings). "AAPL institutional holders", "Vanguard 보유", "13F holdings", "who owns" 같은 질문에 사용합니다.

Args: ticker: US 티커

US short interest — 공매도 잔고 + % of float + days to cover (US short interest). "AAPL short interest", "GME 공매도", "short squeeze" 같은 질문에 사용합니다.

⚠️ FINRA bi-monthly 공시라 데이터가 2~4주 stale합니다. 반드시 'date_short_interest'를 확인하세요.

Args: ticker: US 티커

US SEC filings — SEC EDGAR 공시 목록 (accession number·원문 URL 포함).

"AAPL 10-K", "RIVN latest filings", "8-K", "SEC filing" 같은 질문에 사용합니다. 본문·exhibit 를 읽으려면 결과의 accession number 로 get_us_filing_detail 을 부르세요.

기본 조회는 SEC 의 최근 구간(최대 1000건)입니다. 그보다 오래된 공시는 구간 파일로 나뉘어 있고, 결과 메타의 coverage.older_pages 에 구간 목록 (이름·기간·건수)이 옵니다. page= 에 그 이름을 넣어 구간을 옮기고, 한 구간이 limit 보다 크면 coverage.next_offset 을 offset= 에 넣어 이어서 조회하세요. 완전한 검색의 종료 조건은 coverage_complete=true (현재 구간을 끝까지 봤고 older_pages 도 없음)이지, older_pages 가 비었다는 것만이 아닙니다.

SEC 는 발행사를 티커가 아니라 CIK 로 식별합니다. GOOGL/GOOG 같은 클래스주는 같은 발행사로 정규화되어 같은 공시 집합이 나오고, 요청 티커는 메타에 보존됩니다.

Args: ticker: US 티커 limit: 표시할 공시 건수 (기본 15, 최대 100) forms: 공시 유형 필터 (예: ["10-Q", "8-K"]). 비우면 전체. page: 구간 파일 이름 (coverage.older_pages[].name). 비우면 최근 구간. offset: 현재 구간 안에서 건너뛸 건수 (coverage.next_offset 값). 기본 0.

US SEC filing 본문 — 원문 키워드 검색·희석/계약 조항 구조화 (SL-04).

• find: 본문에서 키워드 주변 발췌(전체 매치 수 + 최대 5건 표시). 매치 0건은 "본문에 없다"가 아니다 - 표기가 다를 수 있다.

• analyze: "dilution"(증권 수·전환가·워런트·리픽싱·자금용도) 또는 "contract"(계약금액·기간·해지·최소구매·상대방 비공개)를 범주별 원문 발췌로 구조화. 못 찾은 범주는 '미확인'이지 '없다'가 아니다.

• 둘 다 비우면 문서 목록(본문+exhibit)만 보여준다. 전체 본문은 반환하지 않는다(10-Q 하나가 수십만 자다).

Args: ticker: US 티커 (발행사 CIK 확인용) accession_no: SEC 접수번호 (get_us_filings 결과의 accession) find: 본문 검색 키워드 (선택) analyze: "dilution" / "contract" (선택) document: 읽을 문서 파일명 (비우면 본문. exhibit 는 목록에서 이름 확인)

US stock news — 미국 주식 관련 뉴스 헤드라인 (관련도 판정 포함). "AAPL 뉴스", "Tesla news", "NVDA headlines" 같은 질문에 사용합니다.

Yahoo 피드에는 다른 종목이 중심인 기사가 섞여 옵니다(실측: AAPL 피드에 InterDigital·NVDA 단독 기사). 기사마다 관련도(direct/comparison/ supply_chain/list_or_etf/mention/unrelated)와 근거가 붙습니다. 이 종목이 주제인 기사만 원하면 direct_only=True.

Args: ticker: US 티커 limit: 헤드라인 개수 (기본 10) direct_only: True 면 이 종목이 주제(direct)인 기사만 남깁니다

컨센서스 — 증권사 투자의견·목표주가 + 어닝 서프라이즈(컨센서스 대비 잠정치).

"목표가 얼마야", "컨센서스", "증권사 의견", "적정가", "어닝 서프라이즈/쇼크" 같은 질문에 사용합니다.

어닝 서프라이즈 표는 영업이익·당기순이익만 다룹니다 (에프앤가이드 원표에 매출액이 없음). 매출 실적·전망은 get_financial을 쓰세요.

Args: code: 종목코드 6자리 (예: "005930")

증권사리포트 — 종목·시황·산업·경제 등 증권사 분석 리포트.

"리포트", "증권사 분석", "애널리스트 의견", "리서치" 같은 질문에 사용합니다.

종목 리포트는 code 로, 종목을 가리지 않는 갈래는 kind 로 부릅니다. "오늘 증권가가 시장을 어떻게 보나" 같은 질문이 후자입니다.

Args: code: 종목코드 6자리 (예: "005930"). 종목 리포트를 볼 때만. count: 가져올 리포트 수 (기본 5, 최대 10) kind: 종목 대신 갈래로 볼 때. market(시황) | invest(투자전략) | economy(경제) | debenture(채권) | industry(산업) | company(종목)

리포트읽기 — 증권사 리포트 한 건의 PDF 본문을 읽어옵니다.

⚠️ 한 번에 한 건만. 리포트 하나가 1만 자를 넘어서, 여러 건을 이어 부르면 대화 토큰을 통째로 먹습니다. 목록·목표가·짧은 요약은 get_reports로 충분하고, "이 리포트 자세히", "목표가 근거" 처럼 한 건을 깊게 볼 때만 쓰세요.

어느 모드를 고를지는 사용자 말에 맞춥니다. 사용자가 따로 말하지 않으면 summary로 두세요.

summary로 충분한 이유: 실측상 리포트는 앞쪽에 투자의견·목표가 산출 근거· 실적 추정이 모이고, 뒤쪽은 재무제표 부록과 컴플라이언스 고지문입니다. 판단 근거는 대개 앞 3,000자 안에 다 있습니다.

증권사마다 PDF 만드는 방식이 달라, 글자가 아니라 이미지로 렌더링해 내는 곳은 본문을 읽을 수 없습니다. 그 경우 억지로 몇 글자 내놓지 않고 못 읽었다고 알려주며 원문 링크로 안내합니다.

Args: nid: 리포트 번호. get_reports 결과에 함께 표시됩니다. mode: "summary"(기본) / "full" / "link". 한글("요약"·"전문"·"링크")도 됩니다. max_chars: 글자 수를 직접 지정하고 싶을 때만. 비우면 mode 기본값을 씁니다.

종목뉴스 — 한국 주식 종목의 최근 기사 (네이버 종목 뉴스 + 종목명 뉴스 검색).

"무슨 뉴스 있어", "기사 찾아줘", "재료가 뭐야" 질문에 사용합니다. "오늘 왜 오르나"는 시세·공시·리포트까지 한 번에 묶는 get_move_context 가 맞습니다. 공시(get_disclosure)가 0건이어도 기사는 있을 수 있습니다 — 회사 보도자료는 공시가 아닙니다.

출처가 둘이라 시각 정확도가 다릅니다. 시각 앞의 표기("약")를 그대로 전하세요.

• 종목태그: 네이버가 종목을 붙인 기사. 기사 시각 정확(분 단위). 당일 기사는 늦게 붙습니다.

• 이름검색: 종목명 뉴스 검색. 당일 기사가 바로 잡힘. 시각은 "N시간 전" 표시를 조회 시각에서 뺀 근사값이고, 같은 이름의 다른 대상 기사가 섞일 수 있습니다.

Args: code: 종목코드 6자리 (예: "036090") limit: 기사 수 (기본 10, 최대 30) today_only: True 면 오늘(한국 날짜) 기사만

오늘왜움직였나 — 시세·거래량 배수·기사·거래소 공시·증권사 리포트를 시각순으로 한 번에.

"오늘 왜 오르나", "왜 떨어져", "급등 이유", "무슨 재료", "특징주" 질문에 먼저 사용합니다. get_price → get_disclosure → get_flow 를 따로 이어 부르지 마세요. 이 도구 하나로 모입니다.

원인을 판정하지 않습니다. 사실을 시각순으로 놓을 뿐입니다. 기사 시각이 가격 반응보다 앞서는지는 get_intraday_chart 분봉으로 확인합니다. 공시가 0건이어도 재료 없음이 아닙니다 — 보도자료·기사는 공시가 아닙니다. 한 출처가 실패하면 그 부분만 "조회 실패"로 표시하고 나머지는 돌려줍니다(실패는 없음이 아니라 모름).

Args: code: 종목코드 6자리 (예: "036090")

공시목록 — 종목의 최근 거래소 공시 목록 (네이버 증권 게재, KOSCOM 제공).

"공시", "IR", "실적 발표", "공정공시", "오늘 왜 오르나(재료 확인)" 같은 질문에 사용합니다. 공시가 0건이어도 "재료 없음"이 아닙니다 — 회사 보도자료·언론 기사는 공시가 아니라 이 목록에 안 잡힙니다.

Args: code: 종목코드 6자리 (예: "005930")

US stock search — 미국 주식 종목명/티커 검색 (US stock search, ticker lookup). "Apple 티커", "Tesla symbol", "반도체 ETF", "Nvidia 찾아줘" 같은 질문에 사용합니다.

⚠️ 사용자가 "애플"·"테슬라" 같은 회사명만 주면 이 도구를 먼저 호출하세요. 결과가 여러 개면 사용자에게 확인 요청. 추측 금지.

Args: query: 검색어 (회사명·티커, 한/영 무관)

US market indices — 미국 시장 스냅샷 (주요 지수·VIX·Gold).

"미국 시장 어때", "VIX 얼마", "금값" 같은 질문에 사용합니다.

⚠️ 반환 항목은 소스가 주는 대로이며 고정이 아닙니다. 실측(v0.8.2, 2026-08-27): S&P 500 / Dow Jones / NASDAQ / Russell 2000 / VIX / Gold. 예전에는 선물 4종만 오던 시기도 있었습니다. 반환된 표에 있는 항목만 답변에 쓰고, 없는 지수를 학습지식으로 채우지 마세요. 이 값은 현재 스냅샷입니다. 과거 기간 수익률이 필요하면 get_us_chart로 조회하세요.

US stock screener — 미국 주식 프리셋 스크리너 (US predefined screener). "오늘 급등주", "top gainers", "가장 많이 거래된 종목", "저평가 성장주" 같은 질문에 사용합니다.

사용 가능 preset: day_gainers, day_losers, most_actives, most_shorted_stocks, aggressive_small_caps, growth_technology_stocks, undervalued_growth_stocks, undervalued_large_caps, small_cap_gainers, conservative_foreign_funds

각 행에 증권 유형(common_stock/warrant/right/unit/adr/etf/unknown)이 붙습니다. small_cap_gainers 같은 프리셋에는 GRABW(워런트)·KLXER(라이츠) 같은 파생 식별자가 섞여 나옵니다 - 보통주 후보만 원하면 common_stock_only=True. 유형을 확인할 수 없는 항목은 unknown 으로 남고 보통주로 치지 않습니다.

Args: preset: 스크리너 ID (기본 day_gainers) count: 반환 종목 수 (기본 20) common_stock_only: True 면 보통주만 남깁니다 (unknown 도 제외)

US financial statements — 미국 주식 재무제표 3종 (income/balance/cash_flow). "AAPL 손익계산서", "NVDA 현금흐름표", "Apple balance sheet quarterly" 같은 질문에 사용합니다.

핵심 row만 추출 (Total Revenue, Net Income, Total Assets, Free Cash Flow 등).

Args: ticker: US 티커 statement_type: "income" / "balance" / "cash_flow" (기본 income) period: "annual" / "quarterly" (기본 annual)

US sector overview — 미국 섹터별 top 기업 + 시장 비중 (US sector top companies). "기술주 섹터", "healthcare top companies", "technology 대장주", "섹터 비중" 같은 질문에 사용합니다.

Args: sector_key: technology, healthcare, financial-services, consumer-cyclical, consumer-defensive, communication-services, industrials, energy, basic-materials, utilities, real-estate top_n: top 기업 수 (기본 20)

US ETF info — ETF 전용 상세 (top holdings, 섹터 비중, 자산 배분 · US ETF details). "SPY 구성종목", "QQQ holdings", "VOO 섹터", "ETF 보수" 같은 질문에 사용합니다.

Args: ticker: ETF 티커 (예: "SPY", "QQQ", "VOO", "SCHD")

US multi-ticker prices — 여러 미국 주식 일괄 가격 조회 (US multi-ticker snapshot). "AAPL MSFT NVDA 동시", "big tech 가격", "내 포트폴리오 현재가" 같은 질문에 사용합니다.

Args: tickers: 티커 리스트 (예: ["AAPL", "MSFT", "NVDA"]). 최대 20개 권장.

Financial soundness — 금융회사 자금 건전성 경로 (규제자본·자산건전성, JSON).

은행·보험·증권 같은 금융회사에는 제조업형 CFO 런웨이가 성립하지 않습니다. 이 도구가 그 대체 경로입니다: "KB금융 자본비율", "JPM CET1", "충당금 얼마나 쌓았나" 같은 질문에 사용합니다.

• 확보되는 값(미국 XBRL 자산건전성 등)은 출처·기준일과 함께 돌려줍니다.

• CET1·LCR·NSFR 처럼 공식 원문에만 있는 지표는 값을 지어내지 않고, 어느 보고서에서 확인해야 하는지(required_reports)를 구조화합니다.

• 규제 체계(미국 Fed / 한국 금감원)가 다른 지표를 하나의 점수로 합치거나 시장 간 직접 수치 비교하지 않습니다 - 산식·경과규정이 다릅니다.

Args: symbol: 한국 종목코드 6자리(예: "105560") 또는 US 티커(예: "JPM")

US liquidity ledger — 미국 기업의 사용 가능 유동성 원장 (SEC XBRL, JSON).

"RIVN 런웨이가 현금만 기준인지", "제한 현금 빼면 실제로 쓸 수 있는 돈이 얼마인지", "1년 내 갚을 돈은 얼마인지" 같은 질문에 사용합니다. 재무 요약의 현금 한 줄로는 안 되는 것 - 단기투자·제한 현금·미인출 리볼버·부채 만기· 보고기간 후 조달 - 을 SEC XBRL 원문에서 출처·기준일별로 구조화합니다.

• 총액(total_available)은 기준일이 같은 항목만 더합니다. 제한 현금은 절대 총액에 넣지 않고, 포함형 총계와 교차검증만 합니다(중복 차감 방지).

• 미보고 항목은 0이 아니라 not_reported 로 남습니다. 제한·만기 자료가 없으면 runway_inputs.official_runway 는 unavailable 입니다 - 그때는 현금만 민감도(cash_only_base)까지만 말할 수 있습니다.

• 이 도구는 런웨이 개월 수를 계산하지 않습니다. 분모(burn)는 get_us_financial_statement 의 영업현금흐름에서 읽는 쪽이 정합니다.

Args: ticker: US 티커 (예: "RIVN", "CRSP")

US multi diagnosis — 미국 다종목 차트 통계·완성 봉 기술 상태 배치 (JSON).

"고정 15종목 단계 진단", "관심종목 기술 상태 일괄 점검" 같은 반복 판정에 사용합니다. 종목당 get_us_chart + 지표 계산을 반복 호출하는 대신 한 번에: 차트 통계(완성 봉 종가·5/20/60일 수익률·52주 위치·평균 거래량)와 기술 상태(MA20/60·20-60 크로스·RSI14)를 완성 봉 기준으로 돌려줍니다.

이 도구는 종목을 단일 점수로 압축하지 않습니다. 판정 재료(원값)를 그대로 보존하고, 확인 불가는 unavailable 로 남깁니다 - 등급·점수·순위를 만들어 붙이는 것은 읽는 쪽의 몫이고, 그때도 근거 수치가 함께 있어야 합니다.

Args: tickers: US 티커 리스트 (최대 20개) include: 선택 결합 섹션. "estimates"(애널리스트 EPS 추정 변화), "earnings"(최근 실적 서프라이즈), "short"(공매도 지표+보고 최신성). 기본 None = 차트·기술 상태만.

US Excel export — 미국 주식 장기 데이터를 Excel 파일로 저장 (토큰 소비 없음). "AAPL 10년치 CSV 저장", "TSLA 5년 일봉 엑셀" 같은 질문에 사용. get_us_chart는 500행 상한이라 장기 데이터는 잘림 — 백테스트·CSV·다른 AI 업로드용이면 이 도구로(행 수 무제한).

Args: ticker: US 티커 (예: "AAPL", "SPY", "BRK.B") period: "1d","5d","1mo","3mo","6mo","1y","2y","5y","10y","ytd","max" (기본 10y) interval: "1d","1wk","1mo" (기본 1d) filename: 파일명 (비우면 자동)

분봉차트 — 국내·미국 분봉/시간봉 OHLCV (증권사 연결 필요 구간 있음).

증권사(한국투자증권·키움증권 중 하나) Open API 를 연결한 사용자는 주 사용 증권사에서 KR·US 분봉을 받는다. 미연결 사용자는 US 분봉만 Yahoo 에서 받는다 (KR 분봉은 증권사 연결 필요). 검증된 능력만 활성화된다. 일·주·월봉은 기존 get_chart / get_us_chart 를 사용.

Args: symbol: KR 종목코드 6자리 또는 US 티커 market: "KR" | "US" interval: 1m|3m|5m|10m|15m|30m|60m|120m|240m date: 기준 거래일 (YYYY-MM-DD, 기본 최근 거래일) row_limit: 최대 반환 봉 수 (기본 120, 최대 500) venue: KR 은 KRX 고정. US 는 증권사 사용 시 NYS|NAS|AMS 필요 session: "regular" (기타 세션은 능력 검증 후 지원) completed_only: 완성 봉만 반환 (기본 True) source: auto|kis|kiwoom|naver|yahoo. auto 는 주 사용 증권사 하나에 고정되고, 증권사 명시는 strict(실패해도 다른 공급원으로 대체하지 않음)

분봉지표 — 분봉/시간봉 기준 기술지표 (JSON).

차트와 같은 봉 데이터로 계산한다(공급원 혼합 없음). 일봉 지표는 기존 get_indicators 사용. days 가 아니라 bars(봉 개수) 기준이다.

분봉은 일봉과 키 이름이 다르다 — 이름 그대로 읽으세요: position.lookback_high/low 조회한 봉 구간의 고가·저가. 52주 값이 아님 ma_cross·macd.cross 의 bars_ago 몇 봉 전인지 volume.trade_value_est_krw / _usd 종가×거래량 추산. 통화는 이름대로 미국 가격은 달러 소수 둘째 자리(1달러 미만은 넷째 자리)

Args: symbol: KR 종목코드 또는 US 티커 market: "KR" | "US" interval: 1m|3m|5m|10m|15m|30m|60m|120m|240m bars: 계산에 쓸 봉 개수 (기본 260, 30~500) include: 지표 키 (기본 ["ma","ma_phase","volume","candle"]) venue / session / completed_only / source: get_intraday_chart 와 동일 params: 지표 파라미터 오버라이드

상세수급 - 투자자·기관별 일별 순매매 (증권사 연결 필요, JSON).

기존 get_flow 와 다른 도구다. get_flow 는 기본 데이터의 개인·외국인· 기관 3종이고, 이 도구는 증권사 Open API 로 받는 상세 구분이다.

읽을 때 반드시 지킬 것:

• values 에 없는 항목은 값이 없는 것이고, unsettled 에 있으면 미정산(정산 전이라 아직 값이 아님)이다. 둘 다 0 이 아니다. 0 으로 읽으면 '매매 없음'이 되어 사실과 달라진다.

• data_state 가 provisional 인 행은 확정 수치가 아니다. final 과 섞어서 합계·평균을 내지 않는다.

• institution_total(기관계)과 그 하위 항목(금융투자·보험·투신·은행· 연기금·사모·국가 등)을 함께 더하면 두 번 센다. 기관계는 이미 하위 항목의 합이다.

• measure 는 수량(net_quantity, 단주)과 금액(net_amount, 백만원)이 전혀 다른 값이다. 실측상 같은 항목이 3.7배까지 차이 난다. 응답의 unit 을 빼고 숫자만 인용하지 않는다.

• 국내(KR) 전용이다. US 종목에는 이 데이터가 없다.

• data_availability.unavailable 은 연결된 증권사가 그 항목을 주지 않는다는 뜻이다. 키움은 기관 세부 13종을 주지만 매수·매도 분해가 없고, 한국투자증권은 3종만 주지만 매수·매도를 준다.

Args: code: KR 종목코드 6자리 (단건) codes: 종목코드 목록 (최대 30개). code 와 함께 쓸 수 있다 days: 조회할 거래일 수 (기본 20, 최대 120) measure: "net_quantity"(수량) | "net_amount"(금액) source: auto|kis|kiwoom. auto 는 주 사용 증권사 하나에 고정되고, 증권사를 명시하면 strict(실패해도 다른 곳으로 대체 안 함)

수급압력 - 프로그램매매·공매도·신용·대차·외국인보유 (JSON).

종류를 여러 개 물어도 응답은 종류별 블록으로 나뉜다. 각 블록이 자기 status·provider·granularity·data_as_of·경고를 따로 갖는다. 서로 다른 종류를 하나의 점수나 숫자로 합치지 않는다. 합쳐서 만든 지표는 어느 원본에서 왔는지 되짚을 수 없다.

읽을 때 반드시 지킬 것:

• status 가 ok 가 아닌 블록은 데이터가 없는 것이 아니라 받지 못한 것이다. unavailable_reason 을 함께 읽는다. 0 으로 읽거나 '해당 없음'으로 요약하지 않는다.

• granularity 를 확인한다. 프로그램매매는 한국투자증권이 장중 시계열, 키움증권이 일별이다. 모양이 다른 두 숫자를 같은 기준으로 비교하지 않는다.

• 각 값의 단위는 measure_units 를 따른다. 확인된 가격과 금액은 KRW, 수량은 shares, 비율은 percent 로 정규화된다. unknown 은 공급자 단위를 확인하지 못해 원값을 유지한 것이므로 환산을 추측하지 않는다.

• 장중 시계열의 실제 관측 시각은 행의 observed_at 을 읽는다. date 만 보고 서로 다른 장중 시점을 같은 값으로 합치지 않는다.

• 대차잔고는 공매도 실행이 아니다. 대차는 빌린 주식의 잔고이고, 공매도는 실제 매도 체결이다. 대차잔고 증가를 공매도로 옮겨 적지 않는다.

• securities_lending 은 키움증권만 종목 단위로 준다. 한국투자증권은 시장 전체 값만 있어 종목별 답으로 쓰지 않는다(market_level_only).

• 국내(KR) 전용이다.

Args: code: KR 종목코드 6자리 (단건) codes: 종목코드 목록 (최대 30개) kind: 종류 하나 kinds: 종류 목록. program_trading | short_selling | credit | securities_lending | foreign_holding | cfd days: 조회 기간(일, 기본 30) source: auto|kis|kiwoom (auto 는 주 사용 증권사 하나에 고정)

공모주일정 — 심사·수요예측·청약·상장 단계별 공모주 목록.

"이번 주 청약 뭐 있어", "공모주 일정", "상장 예정 종목" 같은 질문에 씁니다.

단계마다 확정된 것과 아직 아닌 것이 다릅니다. 희망공모가는 심사 단계부터 나오지만 확정공모가와 수요예측 경쟁률은 그 단계를 지나야 나옵니다. 아직 없는 값은 비워서 돌려주며 0 으로 채우지 않습니다.

투자자예탁금 — 시장에 대기 중인 돈의 추이 (고객예탁금·신용잔고·펀드).

종목 수급(get_flow)이 "누가 샀나"라면 이건 "살 돈이 얼마나 있나"입니다. "예탁금 늘고 있어?", "신용잔고 추이" 같은 질문에 씁니다.

Args: days: 조회할 거래일 수 (기본 20, 최대 100)