Kiwoom API 是一个用于与韩国 Kiwoom 证券（키움증권）REST API 交互的综合技能指南，涵盖 OAuth 2.0 认证、股票信息查询、账户资产状况、每日余额收益率、模拟/实盘环境管理以及限流应对。
用途
该技能面向需要程序化访问 Kiwoom 证券数据的场景，包括股票数据查询、账户资产状况掌握、OAuth 认证与环境管理（模拟/实盘）。当需要进行股价查询、资产查询、API 认证或环境切换时可使用本技能。
安装
安装命令：
npx dlabs install trading-tools
环境配置
若项目根目录没有 .env 文件，可复制本技能的 .env.example 创建：
cd /path/to/your-project
if [ ! -f .env ]; then cp .claude/skills/kiwoom-api/.env.example .env echo "✅ .env 파일 생성됨. API 키를 입력하세요." fi
nano .env # 또는 vim, code 등
必需环境变量：
TRADING_ENV=mock # mock（模拟）| prod（实盘） KIWOOM_REST_API_KEY=your_api_key KIWOOM_REST_API_SECRET=your_api_secret KIWOOM_ACCOUNT_NO=5012345678 # 模拟账号以 50 开头
环境切换
通过修改 .env 中的 TRADING_ENV 值切换环境：
TRADING_ENV=mock # 模拟（默认，推荐） TRADING_ENV=prod # 实盘（谨慎！）
环境对应的 Base URL：
- mock：https://mockapi.kiwoom.com
- prod：https://api.kiwoom.com
认证（OAuth 2.0）
Token 发放使用 /oauth2/token 接口，请求体包含 grant_type=client_credentials、appkey 与 secretkey。返回 return_code 为 0 表示成功，读取 token 字段。Token 有效期约 1 小时，建议缓存以避免重复发放。客户端模板中已实现 token 自动缓存与更新。
主要 API 与能力
股票基本信息查询（ka10001）：接口 /api/dostk/stkinfo，请求体 {"stk_cd": "005930"}。返回字段包括 stk_cd、stk_nm、cur_prc、pred_pre、flu_rt、trde_qty、mac、per、eps、pbr、roe、bps、250hgst、250lwst 等。
账户评价现况（kt00004）：获取当前持有股票与收益现况，包含 summary（deposit、d2_deposit、total_evaluation、total_asset、total_purchase、estimated_asset、today_pnl、monthly_pnl、cumulative_pnl 及各收益率）与 holdings 列表（code、name、quantity、avg_price、current_price、evaluation、pnl_amount、pnl_pct、purchase_amount）。
每日余额收益率（ka01690）：按指定日期（如 "20260207"）查询，summary 含 total_purchase、total_evaluation、total_pnl、total_pnl_pct、deposit、estimated_asset、cash_ratio；holdings 含 code、name、current_price、quantity、avg_price、buy_ratio、evaluation、eval_ratio、pnl_amount、pnl_pct。
成交余额（kt00005）：仅实盘支持，模拟环境会抛出异常。summary 含 deposit、deposit_d1、deposit_d2、orderable_cash、withdrawable、unsettled_cash、total_buy_amount、total_evaluation、total_pnl、total_pnl_pct、substitute_amount、credit_collateral_rate；holdings 含 code、name、settlement_balance、current_quantity、current_price、avg_price、purchase_amount、evaluation、pnl_amount、pnl_pct、credit_type、loan_date、expire_date。
账户 API 支持情况：kt00004（get_account_evaluation()）与 ka01690（get_daily_balance_pnl()）模拟环境支持；kt00005（get_settlement_balance()）不支持，仅实盘。
下单 API（kt10000 买入 / kt10001 卖出）：端点 /api/dostk/ordr。所有参数值必须为字符串，传整数会报类型不符错误。必要参数：dmst_stex_tp（交易所，KRX/NXT/SOR）、stk_cd（6 位代码）、ord_qty（数量，字符串）、ord_uv（单价，字符串，市价="0"）、trde_tp（"0"=限价、"3"=市价、"5"=条件限价）。注意参数名须使用 ord_qty、ord_uv、trde_tp，误用 qty/ordr_prc/trd_dvsn 会报 1511 必填参数错误；acnt_no 属多余参数（账户信息已包含在 OAuth token 中）。
限流管理
Kiwoom API 存在请求次数限制，为避免 HTTP 429 错误：请求间至少等待 0.5~1 秒；出现 429 时增大等待时间；连续查询建议批量处理。
客户端模板
模板位置：.claude/skills/kiwoom-api/assets/kiwoom_api_client_template.py。特点：OAuth token 自动缓存与更新、基于环境变量配置（使用项目根目录 .env）、内置错误处理，实现 ka10001、kt00004、ka01690、kt00005（实盘专用）以及资产摘要（get_asset_summary，kt00004 包装）。使用示例：
from kiwoom_api_client_template import KiwoomAPIClient
client = KiwoomAPIClient() # 按 .env 自动决定 client = KiwoomAPIClient(use_mock=True) # 显式模拟
data = client.get_stock_info("005930") summary = client.get_asset_summary() evaluation = client.get_account_evaluation() daily = client.get_daily_balance_pnl("20260207")
安全建议
模拟环境（推荐）用于开发测试、策略验证、回测与无限制实验；实盘环境仅在验证完成后使用，从小额开始，以查询 API 为主，交易 API 极其谨慎。
股票代码格式
KRX（国内股票）："005930"（三星电子）；NASDAQ："039490_NX"；NYSE："039490_AL"。
响应代码
return_code：0 正常处理、2 输入值错误、3 认证失败、5 超过限流。
常见问题排查
认证失败（3）：检查 .env 中 API Key/Secret、TRADING_ENV 配置、token 过期后重新发放。限流超过（5）：增大请求间隔、使用批处理、减少不必要请求。错误代码：确认为 6 位数字及 KRX 交易所代码。kt00005 在模拟环境不支持（return_code: 20），提示“模拟环境不提供该业务”，可改用 kt00004 查看持仓/余额。ka01690 在周末/节假日返回空数据，可改用上一交易日日期查询。find_project_root() 找不到 .env 时，应收先查找 .env，再回退查找 .env.example。
参考资料（references/）
api_endpoints.md（OAuth、股票信息、账户、交易 API 详细规格）、account.md（ka01690 详细规格）、environment_config.md（环境配置与管理指南）、market_price.md（行情 API）、ranking.md（排名信息 API）、institution.md（机构/外资交易动向 API）、sector.md（行业程序化交易 API）、short_selling.md（卖空趋势 API）、stock_info.md（股票信息 API）、misc.md（token 发放/废弃等）。assets/ 下提供可复用的客户端模板。
API 端点摘要
au10001 token 发放 /oauth2/token（模拟支持）；ka10001 股票基本信息 /api/dostk/stkinfo（支持）；kt00004 账户评价现况 /api/dostk/acnt（支持）；ka01690 每日余额收益率 /api/dostk/acnt（支持）；kt00005 成交余额 /api/dostk/acnt（不支持，仅实盘）；kt10000 买入 /api/dostk/ordr（支持）；kt10001 卖出 /api/dostk/ordr（支持）。
下单响应示例
{ "ord_no": "0362917", "dmst_stex_tp": "KRX", "return_code": 0, "return_msg": "KRX 매수주문이 완료되었습니다." }
实盘前置要求
需在 openapi.kiwoom.com 注册指定终端 IP（未注册报错 8050），可用 curl ifconfig.me 查看当前 IP 后注册。
限制
关于收费、价格、具体平台支持范围等资料未提供；实盘交易需极其谨慎，kt00005 仅实盘可用。