condition-search

조건검색

사용자가 HTS(영웅문)에서 미리 만들어 저장한 조건식을 서버에서 불러와 실행한다. 조건식 자체를 여기서 만들 수는 없다 — 없다면 HTS에서 먼저 만들어야 한다고 알린다.

순서

1. 어떤 조건식이 있는지 본다

kiwoom_run(["order","condition","list"])

seq(조건식 번호)와 이름이 돌아온다. 이 번호가 이후 모든 호출의 입력이다. 사용자가 "내 조건식"이라고만 하면 목록을 보여 주고 어느 것인지 고르게 한다. 번호를 추측하지 않는다.

2. 걸린 종목을 받는다

kiwoom_run(["order","condition","search","<seq>","--confirm"])

--confirm은 반드시 넣는다. kiwoom-cli는 확인 프롬프트를 띄우는데 MCP에는 답할 터미널이 없어서, 빠뜨리면 응답 없이 끝난다. 조회일 뿐 아무것도 전송하지 않는다.

결과가 많으면 --cont-yn/--next-key로 이어 받는다 (meta.cont 참고).

3. 실시간 감시 (사용자가 명시적으로 요청할 때만)

kiwoom_run(["order","condition","realtime","<seq>","--confirm"], timeout_seconds=30)
kiwoom_run(["order","condition","stop","<seq>","--confirm"])

• 실시간 등록은 조건에 편입·이탈되는 종목을 흘려보낸다. 바로 끝나지 않을 수 있으므로 timeout_seconds를 명시한다.
• 끝나면 반드시 stop으로 해제한다. 등록해 두고 방치하지 않는다.
• 장 시간이 아니면 아무 일도 일어나지 않는다. 장외 시간에는 2번(일반 조회)을 쓴다.

답할 때

• 조건식 이름을 함께 말한다. "3번 조건"보다 "'거래량 급증 돌파'(3번)"가 쓸모 있다.
• 걸린 종목이 많으면 전부 나열하지 말고 개수를 먼저 말한 뒤 상위 몇 개를 보여 준다. 종목명이 필요하면 stock info나 stock search로 보강한다.
• 조건에 걸렸다는 것은 매수 신호가 아니다. 사용자가 정한 필터를 통과했다는 사실만 전달한다. 종목을 추천하지 않는다.
• meta.env가 "mock"이면 모의투자 서버다. 조건식이 실계좌 HTS의 것과 다를 수 있다.

안 될 때

• 목록이 비어 있으면 조건식을 저장한 적이 없거나 다른 계정의 것이다. HTS에서 조건식을 만들어 서버에 저장해야 API로 보인다고 알린다.
• MCP_ORDERS_DISABLED가 나오면 서버가 오래된 버전이다. 조건검색은 조회이므로 조회 전용 플러그인에서도 동작해야 한다 (kiwoom-mcp 0.1.1+). /plugin update를 안내한다.