KIS-Agent — OpenAPI da Korea Investment & Securities, agora com um único `pip`

Criei isto para quem já abriu a documentação oficial da OpenAPI da Korea Investment & Securities e fechou logo em seguida.
Gerenciamento de token de autenticação, lidar com Rate Limit, decifrar nomes de campos como stck_prpr, loop de paginação de 100 itens — fiquei pensando se fazia sentido implementar tudo isso manualmente toda vez, então agrupei em um wrapper.

O que dá para fazer
Direto no terminal:

kis price 005930           # preço atual da Samsung Electronics  
kis balance --holdings     # saldo da conta + ativos em carteira  
kis overseas NAS AAPL      # AAPL na Nasdaq

No código:

agent = Agent(app_key=..., app_secret=..., account_no=...)  
price = agent.get_stock_price("005930")  
agent.order_stock_cash("buy", "005930", "03", "1", "0")  # compra a mercado

Como ferramenta para agentes LLM:
Com saída em JSON + exploração de tipos do schema kis, dá para conectar diretamente em tool calls do GPT/Claude.

Principais pontos resolvidos

Conversão automática de nomes de campos — stck_prpr → currentPrice. Não é preciso receber a resposta oficial exatamente como vem
Rate Limiting embutido — 18 RPS / 900 RPM com base em medições reais. Sem precisar ajustar só depois que quebrar
Cache — redução de 80~95% nas chamadas de API ao repetir a mesma requisição
Contorno do limite de 100 itens — coleta automática de todo o período com get_daily_price_all()
96 modelos TypedDict — autocomplete da IDE e type checker funcionando por completo

Escopo suportado
Mercado coreano (KOSPI/KOSDAQ/NXT) · 9 bolsas internacionais (NASDAQ, NYSE, Tóquio, Xangai, Hong Kong, Vietnã etc.) · futuros e opções domésticos e internacionais · streaming em tempo real via WebSocket · análise de tendências por investidor/program trading/corretora

Como foi feito com foco em automação de trading pessoal, a implementação prioriza o que realmente é usado na prática. Se houver alguma função da API oficial que esteja faltando, deixe uma issue que eu adiciono.