kiwoom-broker

Kiwoom Broker

Use the official Kiwoom Securities CLI as the brokerage adapter. Leave authentication, tokens, and API field mapping to the CLI, and this skill handles command selection and safety boundaries.

Pre-execution checks

The PATH, HOME, and Keyring of the installed general terminal and the Hermes session may differ. Therefore, before querying or ordering, within the current Hermes session perform the following preflight.

1. command -v kiwoomclito find the executable.

2. If not, $HOME/.local/bin/kiwoomclicheck whether is executable. If this fallback succeeds, report it as a PATH issue in that session and run it with an absolute path.

3. If neither exists, do not run it and guide the user to the following installation command.

   uv tool install kwcli
   uv tool update-shell
   

1. If there is no initial setup, have the user run kiwoomcli setupdirectly in an interactive terminal. setup must be done on the same host and same OS user as Hermes. In the lecture exercise, select server demo, account alias 모의계좌. Store the App Key and Secret in the OS credential store and do not create a .env file.
2. setup이 자격 증명 저장소 사용 불가If is reported, it means there is no supported Keyring backend. Do not bypass it by arbitrarily creating .env, but stop and report to the user.
3. kiwoomcli auth status --profile 모의계좌와 kiwoomcli doctorRun . Do not interpret freely; copy the values of the following labels from the status output exactly as they are: 계좌 별칭, 모드, 자격 증명 존재, 자격 증명 출처, 토큰 유효, 지금 API 호출 가능. If the values contradict each other or are not 지금 API 호출 가능: 예, do not proceed to querying or ordering.
4. In the lecture exercise, use only the demo profile. Consider switching to real only if the user explicitly requests use of a real account and provides separate operational approval.

Do not output or log credentials, access tokens, or raw account numbers. Do not call the token issuance endpoint directly.

Query

Always request structured output, and do not re-output the entire raw text as is; summarize only the fields needed for the request.

kiwoomcli domestic etfs info --code 069500 --profile 모의계좌 --format json
kiwoomcli domestic candles daily --code 069500 --date YYYYMMDD --profile 모의계좌 --format json
kiwoomcli domestic accounts holdings --basis total --exchange KRX --profile 모의계좌 --format json

If you are not sure about a command or option, do not guess; look it up first.

kiwoomcli spec search "검색어"
kiwoomcli domestic etfs info -h

return_codeCheck whether is 0. If it is not a success code or the response is empty, do not make up values; report the blocking cause and the next verification command.

Order

Split orders into the following two stages.

1. Unsent preview

Even if the user requests a buy or sell, initially do not append --confirm.

kiwoomcli domestic orders buy \
  --code 069500 \
  --qty 1 \
  --price 90000 \
  --order-type limit \
  --profile 모의계좌 \
  --format json

CLI가 주문은 아직 전송되지 않았습니다Only treat it as an order draft if it is confirmed as . Show the symbol, quantity, price, order type, and mode to the user again and request approval.

2. Execution after approval

Only when all of the following conditions are met, --confirmis added to the same command.

• The user has explicitly approved the order draft just presented.
• The symbol, quantity, price, order type, and mode of the approval target are identical to the preview.
• The OrderIntent와 ApprovalRecordrequired by the parent harness exists.
• The authentication profile is 모의계좌and the server is demo. A real account is not the default scope of this skill's instruction.

If any one of these differs, do not execute. If the input has changed after approval, create a new preview and obtain approval again.

Prohibitions

• curlor your own Python to call the Kiwoom REST API directly.
• Do not create your own token cache or token issuance command.
• Without the user's explicit approval, do not attach --confirm.
• Do not summarize a failure response as if it were a success.
• Do not bypass the CLI's default safety mechanisms.

kiwoomcliis a broker call tool. Strategy judgment, order intent generation, approval recording, duplicate prevention, and execution reconciliation are handled by the magma-finance-lab harness.