KIS-Agent — OpenAPI của Korea Investment & Securities, giờ chỉ cần một lệnh pip

Mình làm cái này cho những ai từng mở tài liệu chính thức của OpenAPI Korea Investment & Securities ra rồi lại đóng lại ngay.
Quản lý token xác thực, canh chừng Rate Limit, giải mã các tên trường như stck_prpr, vòng lặp phân trang 100 bản ghi — mình thấy không ổn khi lần nào cũng phải tự tay viết lại từng thứ đó nên đã gói chúng thành một wrapper.

Dùng được gì?
Ngay trong terminal:

kis price 005930           # giá hiện tại của Samsung Electronics  
kis balance --holdings     # số dư tài khoản + danh mục đang nắm giữ  
kis overseas NAS AAPL      # AAPL trên Nasdaq

Trong code:

agent = Agent(app_key=..., app_secret=..., account_no=...)  
price = agent.get_stock_price("005930")  
agent.order_stock_cash("buy", "005930", "03", "1", "0")  # mua theo giá thị trường

Là công cụ cho tác tử LLM:
Có thể gắn trực tiếp vào tool call của GPT/Claude với đầu ra JSON + khám phá kiểu schema của kis.

Các điểm giải quyết chính

Tự động chuyển đổi tên trường — stck_prpr → currentPrice. Không cần phải nhận nguyên xi phản hồi chính thức
Tích hợp Rate Limiting — đo thực tế 18 RPS / 900 RPM. Không cần đợi lỗi rồi mới điều chỉnh
Caching — khi lặp lại cùng một yêu cầu, giảm 80~95% số lần gọi API
Vượt qua giới hạn 100 bản ghi — với get_daily_price_all() để tự động thu thập toàn bộ giai đoạn
96 mô hình TypedDict — IDE tự động hoàn thành, type checker đều hoạt động

Phạm vi hỗ trợ
Trong nước (KOSPI/KOSDAQ/NXT) · 9 sở giao dịch quốc tế (NASDAQ, NYSE, Tokyo, Thượng Hải, Hồng Kông, Việt Nam, v.v.) · hợp đồng tương lai/quyền chọn trong và ngoài nước · streaming thời gian thực qua WebSocket · phân tích xu hướng theo nhà đầu tư/giao dịch chương trình/công ty chứng khoán

Vì được làm ra với mục đích tự động hóa giao dịch cá nhân nên các tính năng triển khai chủ yếu là những thứ thực sự dùng trong môi trường thực chiến. Nếu có chức năng nào có trong API chính thức mà còn thiếu, hãy để lại issue, mình sẽ bổ sung thêm.