place-order

주문

실제 계좌에서 돈이 움직인다. 아래 순서를 건너뛰지 않는다.

0. 어느 계좌인지 먼저 확인한다

kiwoom_run(["auth","status"])

domain이 "prod"면 실거래다. 사용자가 모의투자라고 생각하고 있는데 실거래로 붙어 있는 상황이 가장 위험하므로, 실거래일 때는 주문 전에 반드시 그 사실을 말하고 확인을 받는다.

1. 사전점검 (아무것도 전송하지 않는다)

kiwoom_order_validate(side="buy", symbol="005930", qty=10, price=70000)

symbol_ok / market_open / sufficient_balance / price_ok / price_known을 확인한다. 실패하면 VALIDATION_FAILED로 끝나며, 여기서 멈춘다. 실패 이유를 사용자에게 설명하고 어떻게 고칠지 제안한다.

2. 미리보기 (아무것도 전송하지 않는다)

kiwoom_order(action="buy", symbol="005930", qty=10, price=70000, dry_run=True)

dry_run은 기본값이 True다. 전송될 body와 예상 금액이 돌아온다. 이것을 사용자에게 보여주고 확인을 받는다 — 종목, 수량, 가격, 총액, 그리고 실거래인지 모의인지.

3. 전송

사용자가 명시적으로 승인한 뒤에만:

kiwoom_order(
  action="buy", symbol="005930", qty=10, price=70000,
  dry_run=False, confirm=True,
  client_order_id="<이번 주문을 위한 고유 문자열>"
)

dry_run=False와 confirm=True를 둘 다 명시해야 전송된다.

client_order_id는 항상 넣는다

멱등키다. 같은 키로 같은 내용을 다시 호출하면 재전송하지 않고 이전 응답을 돌려준다. 응답을 못 받았을 때 안전하게 재시도할 수 있는 유일한 방법이다.

• 주문 하나마다 새로운 값을 만든다 (예: buy-005930-20260721-001)
• 재시도할 때는 같은 값을 쓴다 — 새 값을 만들면 중복 주문이 된다
• 내용이 다른데 같은 키를 쓰면 IDEMPOTENCY_CONFLICT로 거부된다 (안전장치)

정정·취소

kiwoom_order(action="cancel", symbol="005930", order_no="<원주문번호>", qty=10, ...)
kiwoom_order(action="modify", symbol="005930", order_no="<원주문번호>", qty=10, price=71000, ...)

원주문번호는 kiwoom_run(["account","orders","pending"])의 미체결 목록에서 찾는다. 취소·정정도 1~3단계를 똑같이 거친다.

응답을 못 받았을 때

ORDER_STATUS_UNKNOWN이 오면 주문이 나갔는지 알 수 없다는 뜻이다. 같은 내용으로 다시 보내지 않는다. kiwoom_run(["account","orders","pending"])로 체결·미체결 상태를 먼저 확인하고, 그 결과를 사용자에게 보고한다.

TOKEN_EXPIRED로 실패하면 서버가 토큰을 갱신했을 수 있다 — 같은 client_order_id로 다시 호출한다.

지켜야 할 선

• 먼저 주문을 제안하지 않는다. 사용자가 요청한 주문만 처리한다.
• 수량이나 가격을 추측하지 않는다. "적당히 사줘" 같은 요청에는 구체적인 수량과 가격을 되묻는다.
• 한 번에 하나씩. 여러 종목을 한꺼번에 주문해 달라고 해도 각각 1~3단계를 거친다.
• 성공을 확인 없이 보고하지 않는다. exit_code와 error를 읽고 실제 결과를 말한다. 실패했으면 실패했다고 한다.
• 투자 판단은 사용자의 것이다. 무엇을 살지 권하지 않는다.