内容
align="DB증권 Open代码 (Python)</h1>
<p align="center">
<img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.">
<imghttps://img.shields/license-MIT-green alt="License">
<img src://img.shields.io/badge/DB%E8%AF%81%E88%B8-20API-orange alt="DB증권">
</p>
<p align="center">
DB증권 Open API <strong>全部群组 · 端点</strong> 通过一个客户端调用的Python 示例集合.<br 国内股票 ·股票 · 国内期货期权 · 国外期货 · 场内债券 · 实时WebSocket</p>
<pcenter">
<a href="https://openapi.dbsec.co.kr" target="_blank" rel="noopener noreferrer">
<img src="https://img.shields.io/badge/DB%E8%AF%81%E5%88%B8_Open_API%E7%9B%96%E97%A8-%00A862?style=flat-square&logoColor=white" alt="DB증권 Open API 门户">
</a>
</p>
---
## 制作意图及目标用户
### 示例代码制作意图
本仓库是为DB증권 Open API的Python示例代码仓库，旨在让**生成式AI基础的编程**(ChatGPT · Claude · Gemini)和**传统的Python开发环境**都能直观地学习并应用于实践。
- **`dbsec_sdk/`** 认证 · HTTP客户端 · WebSocket客户端
- **`examples/`** — 按组目录内的API对应一个文件(`<method>.py`) — 全部可独立运行
- **`mcp_server/`** — LLM编程工具（Claude Code · Cursor等）API组 · 规范 · 示例代码查询的代码助手MCP服务器
- **MCP·LLM亲和命名** — 方法名直接体现市场领域标识，如 `kr_stock_*`, `ov_stock_*`, `kr_futopt_*`, `ov_futopt_*`, `bond_*` 前缀统一应用
### 目标用户
- 初次接触DB증권 Open API的Python开发者
- 有自己的投资想法，希望将其转化为代码进行回测或自动化的个人投资者
- 有其他证券公司Open API经验或正在考虑多券商配置的开发者
- 希望通过LLM代码代理（包括MCP工具）构建选股 · 行情分析 · 自动交易的用戶
---
**[OpenAPI示例代码使用注意事项]**
- 本示例代码是为提供DB증권 Open API的对接方法而提供的示例。客户如有开发需求，可参考本示例代码以减少开发负担。
-持续改进和更新，可能会在没有单独通知的情况下发生变化。
- 示例代码仅作为，在实际服务应用前，请务必进行充分的审查和测试。
- 使用示例代码进行开发和运营所产生的程序故障、交易损失或数据错误等间接或直接损失，本公司不承担责任。
- 由于涉及实际交易订单，请务必在**模拟环境**中进行测试。
- 访问令牌的有效期为**24小时**，在有效期内颁发时将获得**相同的令牌**。如果您需要在有效期内重新获得令牌，请在废除现有令牌后再颁发。
- TR代码的InBlock/OutBlock详细信息请参考[DB증권API指南](https://openapi.kr/apiservice)。
- 国外股票接收时，需要TS/HTS实时行情申请（免费）**。
-期货期权实时时，需要通过GMTS/GTS进行**实时行情申请（付**。
---
## 目录
- [核心核心功能)
准备](#准备)
-开始（）](#快速开始分钟)
- [使用examples文件夹](#使用)
- [代码助手MCP服务器](#代码助手MCP服务器)
- [文件夹结构](#)
- [安装)
- [设置](#设置)
- [用法](#用法)
- [认证（自动](#1-认证-自动令牌)
- [统一API调用模式 — `client`](#2api调用模式--clientapis)
- [ — 订单](#3---订单查询)
- [其他产品外股票 ·期权 · 图表 · Web4-其他国外股票--期货期权--债券--websocket)
DataFrame转换](#转换)
-群组](#全部群组--api)
- [规则（领域前缀方法命名规则-领域前缀)
- [ 模拟](#运营模拟)
- [错误代码 & ](#错误代码--流量控制)
- [ API模拟附录--api模拟支持现状)
核心功能 | 内容 |
------|
|覆盖率** | Open API **全部端点覆盖** |
| **异步客户端** | `DBSecClient` 是 **异步** — `await client.apis.群组.方法(...)`。`asyncio.gather` 实现并发调用 |
| **单一入口点** | 通过一行客户端创建，实现认证 · 令牌缓存 · 连续查询自动处理 |
| **领域前缀方法**kr_stock_order`、`ov_stock_inquire_balance_margin` 等方法名直接体现市场领域（MCP友好）|
| **自动流量控制 应用20TPS点별 TPS **** 自动调节 → 服务器 `IGW`（调用次数超出）提前拦截 |
令牌自动颁发/续期**auto_token=True`（默认）：请求时如果令牌不存在或/失效（00121`/`00123`）。`False`则通过 `get_token()`/`force_refresh()`/`revoke()` 直接管理（详见令牌策略）。 |
| **灵活的响应** | 默认 `APIResponse` dict包装器，`resp.to_dataframe(key="Out1")` 可选转换为DataFrame |
| **自动化** | 连接 · 重连（指数）· 订阅恢复 · 终止 |
| **独立示例** | `examples/<group>/<method>.py` — 复制 → 修改值后直接运行 |
| ** · AI 代理友好** | [`llllms.txt)（仓库结构 · 规范 · 示例指南）+ 代码助手MCP服务器 — LLM · AI 代理可以轻松探索API
---
## 准备
1. **开设DB증권账户** — [远程开户](https://www.dbsec.co.kr/custcenter/account/cu_NBranch_viw.do)
2. **申请Open API使用权限** — 在DB증권官网 -> OpenAPI服务申请https://www.dbsec.co.kr/online/accservice/on_OpenApi_w）申请
3. **获取APP_KEY / APP_SECRET** — 申请发. 模拟投资OpenAPI应用于 **模拟投资申请** 必需 — DB证券官网 -> 模拟投资 -> 实时模拟投资申请菜单（https://www.dbsec.co.kr/custcenter/vts/vts_Index_viw02.do）申请
5. **安装Python 3.10或以上**
---
##开始（5分钟）
> 如果您是初学者或需要逐步指导，请参考 **[HOWTOUSE.md](HOWTOUSE.md)** （新手指南）。
```bash
git clone https://github.com/DBsecurities/dbsec-open-api.git
cd dbsec-open-api
pip install -e . # dbsec_sdk + 依赖项（requests · pyyaml · websockets · pandas）一并安装 — 独立示例也由此运行
cp config.yaml.example config.yaml # 输入APP_KEY/SECRET（macOS/Linux/Git Bash）
# Windows CMD: copy config.yaml.example config.yaml
# Windows PowerShell: Copy-Item config.yaml.example
python dbsec_sdk/client_examples/quickstart.py # SDK演示（只）
# 或单发独立示例（使用examples/dbsec_helper.py）：/kr_stock_quote/kr_stock_inquire_price.py
```
`DBSecClient` 是 **异步** 客户端（所有调用均使用`await`，入口使用`asyncio.run`）。
```python
import asyncio
from dbsec_sdk import DBSecClient
async def main():
# 客户端创建 — 流量控制 · 令牌选项（均为默认值，可省略：仅需`DBSecClient("config.yaml")`即可运行）
async with DBSecClient(
"config.yaml",
rate_limit=True, # 流量控制：调用前调整应用TPS+API别TPS间隔，防止`IGW00201`（调用超出）。若为`False`，则不启用。
rate_limit_safety=0.9, # 安全系数（0<s≤1）：实际率 = 应用TPS × s。推荐0.9（10%余量，最大18TPS）
auto_token=True, # 令牌自动颁发/续期：`True`则请求时如果令牌不存在或已过期/失效会自动处理。
# `False`则不自动颁发 → 令牌不存在则`AuthError`，过期/失效是`APIError`（需自行管理）。
rate_limit_backoff=True, # 指数回退：收到`IGW00201`后1 · 2 · 4 · 8秒后重试。`False`则立即`APIError`。
) as client:
# 国内股票现价查询 — 三星电子（只读）
resp = await client.apis.kr_stock_quote.kr_stock_inquire_price(
InputCondMrktDivCode="J", # J: KRX股票
InputIscd1="005930") # 三星电子
# 确认响应成功（`rsp_cd == "00000"`）后使用返回值。
if resp.rsp_cd == "00000":
out = resp.body["Out"]
print(f"三星电子现价：{int(out['Prpr']):,}韩元\n")
# 全部字段输出（转换为DataFrame可查看，详见`resp.to_dataframe()`）
for field, value in out.items():
print(f" {field}: {value}")
else print(f"[{resp.rsp_cd}] 查询失败：{resp.rsp_msg}")
asyncio.run(main())
```
---
## 使用examples文件夹
` 是 **不依赖SDK的独立脚本集合**，每个API对应一个`<method>.py`），
依赖`examples/dbsec_helper.py`（标准库 + `requests` · `pyyaml`）即可运行 — **独立于** `dbsec_sdk`。
"复制 → 修改值后直接非常适合快速学习和单次测试。
### 运行
```bash
.yaml.example config.yaml # 输入应用密钥 + 模式：demo（首次运行一次，macOS/Linux/Git Bash）
# Windows CMD: copy config.yaml.example config.yaml
# Windows PowerShell: Copy-Item config.yaml.example config# 在仓库根目录：
python examples/kr_stock_quote/kr_stock_inquire_price.py
# 或在`examples/`目录内：
cd examples && python kr_stock_quote/kr_stock_inquire_price.py
```
- 令牌优先使用`.dbsec_token.json`缓存（与SDK共享），如果没有有效缓存，首次运行时会请求是否颁发 —
`[1]` 立即颁发并继续 / `[2]` 取消（默认）。非交互式（管道/CI）环境下会安全地取消。
- 每个群组的`README.md` 整理了该的方法列表 · 调用模式。
###/订单示例模式
```python
import sys, pathlib
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1])) # 添加dbsec_helper路径
from dbsec_helper import call_rest, print_response
resp, data = call_rest( # call_rest只负责请求，返回（resp, data）
url="/api/v1/quote/kr-stock/inquiry/price",
body={"In": {"InputCondMrktDivCode": "J", "InputIscd1": "005930"}},
label="现价查询",
)
print_response(resp, data) 全部输出（如果需要）
print("现价：", data["Out"]["Prpr"]) # 提取值使用
# 如果需要，使用`pages = call_rest_paged(...)`
```
### 实时（WebSocket）示例模式
```python
from dbsec_helper import ws_subscribe, run_ws
run_ws(ws tr_cd="S00", # 成交价TR
tr_key="", # 股票代码（账户单位TR为app_key）
group_slug="kr_stock_realtime",
tr_type="1", # 注册类型（直接指定）：1=行情订阅 2=取消 3=账户注册
)) # 按`Ctrl+C` 终止（行情订阅`tr_type="1"`会取消订阅后终止）
```
> `tr_type` 由调用者直接指定自动判断）。一般行情TR为`tr_type="1> 账户单位TR（`IS0/IS1/ISIF/P` —受理/余额）="3"` 调用 **examples vs SDK** —/` 使用`call_rest("/api/...", body={...})`自由输入 · 同步）进行快速学习 · 单次测试，
> `dbsec_sdk/` 使用`await client.apis.群组.字段=值)`（类型 异步 · 流量控制令发（`auto_token`））用于应用/详见 [_usage.md](docs/sdk_usage.md)。
---
## 代码助手MCP服务器
`mcp_server/` 是为LLM编程工具（Claude Desktop · Claude Code · Cursor等）提供DB증권 Open API的
**群组 · 端点列表**、**请求(In) · 响应(Out)参数规格**、**可执行示例代码**的MCP（stdio）服务器。
规格的**原始出处是`examples/`（示例代码）**，请求参数 = 代码注释，响应参数 = docstring的`响应参数（Out）`章节，
模拟支持 · TPS · TR代码在`docs/api_support_matrix.md`中补充。即，**修改示例代码，MCP会自动同步**。
| 工具 | 说明 |
|---|---|
| `list_api_groups()` | 群组列表 + 每个群组的API数量 + 模拟支持数量 |
| `search_apis(query, group?)` | 按关键词 · TR代码 · slug · 路径搜索API（支持中文） |
| `get_api_spec(identifier)` | 端点 · TPS · **In/Out参数** · 请求/响应示例 |
| `get_sample_code(identifier)` | 对应API的Python示例代码原文 |
| `get_setup_guide()` | 安装 · 设置 · 令牌颁发 · 运行开始指南 |
```bash
pip install -r mcp_server/requirements.txt
python mcp_server/run_server.py # 仓库根目录（本地）
python /绝对路径/dbsec-open-api/mcp_server/run_server.py # cwd无关（Claude Desktop适用）
```
- 服务器启动时会与远程仓库 **`git fetch` + `git reset --hard`** 同步。
— **不会提交或推送**。（`config.yaml` · `.dbsec_token.json`等未跟踪文件会保留）
- 在`cwd`无法保证的环境下（如Claude Desktop），在`args`中指定 **`run_server.py`的绝对路径** 即可（无需`cwd`）。
- 环境变量`DBSEC_MCP_GIT_REPO`（克隆目标URL）· `DBSEC_MCP_GIT_BRANCH` · `DBSEC_MCP_GIT_DIR` ·
`DBSEC_MCP_GIT_SKIP_SYNC`（离线）来控制行为。
- 客户端注册方式（`mcpServers` JSON）· 验证方式详见 **[mcp_server/README.md](mcp_server/README.md)**。
> 每个示例的docstring的`响应参数（Out）`章节基于门户规格编写。
> 如果API变更，对应**示例文件的docstring修改**后会自动同步到MCP服务器。
---
## 文件结构
```
dbsec-open-api/
├── pyproject.toml # 包设置（pip + uv）
├── requirements.txt # 依赖项
├── config.yaml.example # 设置模板
│
├── dbsec_sdk/ # 客户端库
│ ├── client.py # DBSecClient（异步单一入口点）+ 内部同步核心
│ ├── config.py # 设置（YAML + 环境变量）
│ ├── auth.py # OAuth2令牌生命周期（get_token/force_refresh/revoke）+ 自动颁发
│ ├── rate_limiter.py # 流量控制（应用20TPS + 端点별TPS，2-tier）
│ exceptions.py # + 错误代码参考 ├── response.py # APIResponse + to_dataframe │
│ ├── apis/ # 群组方法
│ │ .py # APistry — client.apis入口点
│ │ ├── # OAuth认证
│ │ ├── common/ # 持仓
│ ├── kr_stock_order/ 国内股票订单
│ │ ├── kr_stock_quote/ # 国内股票行情
│ │ ├── kr_stock_realtime/ # 国内股票实时
│ │ ├── kr_futopt_order/ # 国内期货期权订单
│ │ ├── kr_futopt_quote/ # 国内期货期权行情
│ │ ├── kr_futopt_realtime/ # 国内期货期权实时
│ │ ├── kr_chart/ # 国内股票/期货图表
│ │ ├── ov_stock_order/ # 国外股票订单
│ │ ├── ov_stock_quote/ # 国外股票行情
│ │ ├── ov_stock_realtime/ # 国外股票实时
│ │ ├── ov_futopt_order/ # 国外期货期权订单
│ │ ├── ov_futopt_quote/ # 国外期货期权行情
│ │ ├── ov_futopt_realtime/ # 国外期货期权实时
│ │ ├── bond_order/ # 场内债券订单
│ │ ├── bond_quote/ # 场内债券行情
│ │ ├── bond_realtime/ # 场内债券实时
│ │ └── ws_common/ # WebSocket公共
│ │
│ ├── websocket/ # 实时WebSocket（stream.py）
│ └── client_examples/ # SDK（client.apis.*）使用示例
│ ├── quickstart.py # 只读查询演示（异步）
│ ├── kr-stock-trading-basic.ipynb # 国内股票交易基础（笔记本）
│ └── ov-stock-trading-basic.ipynb # 国外股票交易基础（笔记本）
│
├── examples/ # 群组별 独立示例（call_rest方式）
│ ├── dbsec_helper.py # 公共助手（配置加载 · 令牌 · REST/WS调用）
│ └── <group_slug>/
│ ├── README.md # 群组内方法列表 + 调用模式
│ └── <method>.py # 每个API一个文件 — 独立运行（docstring中有In/Out规格）
│
├── mcp_server/ # 代码助手MCP服务器（stdio）
│ ├── run_server.py # 入口点（cwd无关）：同步 → 索引 → 服务器启动
│ ├── sync.py # GitHub强制同步（无提交/推送）
│ ├── catalog.py # examples + api_support_matrix.md解析索引
│ └── server.py # FastMCP工具（list/search/spec/sample/guide）
│
├── HOWTOUSE.md # 新手逐步指南
└── docs/ # 指南文档
├──.md # dbsec_sdk使用指南（client.apis.*）
├── api_support_matrix.md # API清单 + 模拟支持⭕/❌ + 端点별TPS
└── errors_and_rate_limits.md # 错误代码 · 流量控制详解
```
# 市场价买入
resp = await client.apis.kr_stock_order.kr_stock_order(
IsuNo="A005930", # A + 6位 ( 삼성전자 )
OrdQty=1,
OrdPrc=0, # 市场价时 0
BnsTpCode="2", # 1: 卖出, 2: 买入
OrdprcPtnCode="03", # 00: 指定价, 03: 市场价, 05: 条件指定, 06: 最优, 07: 最优先
MgntrnCode="000", # 000: 普通 (一般订单), 信用偿还 101/103/105/107/180
LoanDt="00000000", # 一般: 00000000, 信用卖出: 结算日期 (YYYYMMDD)
OrdCndiTpCode="0", # 0: 无, 1: IOC, 2: FOK
TrchNo=1, # 1: KRX 固定
)
print(resp.body["Out"]["OrdNo"])
#### 3-2. 修改 / 取消
```python
# 修改订单 (CSPAT00700)
await client.apis.kr_stock_order.kr_stock_order_modify(
OrgOrdNo=14404,
IsuNo="A005930",
OrdQty=5,
OrdprcPtnCode="00",
OrdCndiTpCode="0",
OrdPrc=80000)
# 取消订单 (CSPAT00800)
await client.apis.kr_stock_order.kr_stock_order_cancel(
OrgOrdNo=14414,
IsuNo="A005930",
OrdQty=10)
```
#### 3-3. 余额 / 成交 / 保证金
```python
# 多个查询使用 asyncio.gather 同时 (流量控制自动遵守 TPS)
balance, deposit = await asyncio.gather(
client.apis.kr_stock_order.kr_stock_inquire_balance(QryTpCode0="0"),
client.apis.kr_stock_order.kr_stock_inquire_deposit(),
)
executions = await client.apis.kr_stock_order.kr_stock_inquire_executions(
SorTpYn="2",
ExecYn="0",
TrdMktCode="0",
BnsTpCode="0",
IsuTpCode="0",
QryTp="0")
psbl_qty = await client.apis.kr_stock_order.kr_stock_inquire_psbl_quantity(
BnsTpCode="2",
IsuNo="A005930",
OrdPrc=77000)
```
#### 3-4. 行情
```python
price = await client.apis.kr_stock_quote.kr_stock_inquire_price(
InputCondMrktDivCode="J",
InputIscd1="005930")
orderbook = await client.apis.kr_stock_quote.kr_stock_inquire_orderbook(
InputCondMrktDivCode="J",
InputIscd1="005930")
ranks = await client.apis.kr_stock_quote.kr_stock_inquire_condition_rise_fall(...)
```
### 4. 其他商品 — 海外股票 · 期权 · 债券 · 图表 · WebSocket
同国内股票相同的 `client.apis.<组>.<方法>(...)` 模式。各组的全部方法、必填字段、执行示例请在组별 README 中查看。
| 商品类别 | 主要方法示例 | 组別指南 |
|-------|----------------|--------------|
| 海外股票订单/查询 | `ov_stock_order`, `ov_stock_inquire_balance_margin` | [examples/ov_stock_order](examples/ov_stock_order/README.md) · [quote](examples/ov_stock_quote/README.md) · [realtime](examples/ov_stock_realtime/README.md) |
| 国内期权 | `kr_futopt_order`, `kr_futopt_order_night`, `kr_futopt_inquire_balance` | [order](examples/kr_futopt_order/README.md) · [quote](examples/kr_futopt_quote/README.md) · [realtime](examples/kr_futopt_realtime/README.md) |
| 海外期权 ⚠️ (运营专用) | `ov_futopt_order`, `ov_futopt_inquire_open_interest` | [order](examples/ov_futopt_order/README.md) · [quote](examples/ov_futopt_quote/README.md) · [realtime](examples/ov_futopt_realtime/README.md) |
| 场内债券 | `bond_order`, `bond_inquire_balance`, `bond_inquire_price` | [order](examples/bond_order/README.md) · [quote](examples/bond_quote/README.md) · [realtime](examples/bond_realtime/README.md) |
| 图表 (国内股票·期权共用) | `kr_chart_tick`, `kr_chart_day` | [kr_chart](examples/kr_chart/README.md) |
| WebSocket 实时 | `client.create_websocket()` → `add_realtime(tr_cd, tr_key, tr_type)` (1=行情订阅·3=账户注册) | [kr_stock_realtime](examples/kr_stock_realtime/README.md) · [ws_common](examples/ws_common/README.md) |
### 5. DataFrame 转换
```python
resp = await client.apis.kr_stock_order.kr_stock_inquire_balance(QryTpCode0="0")
print(resp.body["Out"]["TotEvalAmt"]) # dict 그대로 (pandas 不需要)
df = resp.to_dataframe() # 自动探索 (list[dict] 优先)
df = resp.to_dataframe(key="Out1") # 指定区块
```
---
## 全部组 & API
| 组 | slug | 备注 |
|------|------|------|
| OAuth 认证 | `auth` | Token 发放/废除 |
| 通用 | `common` | 关切銘柄 |
| **国内股票订单** | `kr_stock_order` | NXT 包含, 余额·成交·保证金·信用 |
| 国内股票行情 | `kr_stock_quote` | 종목/当前价/报价/成交/投资者/板块 |
| 国内股票实时 | `kr_stock_realtime` | 订单成交/报价/ELW/行业指数 |
| **国内期权订单** | `kr_futopt_order` | 週間/夜间 分离 |
| 国内期权行情 | `kr_futopt_quote` | 종목/当前价/报价/成交/显示屏 |
| 国内期权实时 | `kr_futopt_realtime` | 指数/股票/商品 期权,迷你,每周,KOSDAQ150,夜间 |
| 国内股票/期权图表 | `kr_chart` | Tick/分/日/周/月 |
| **海外股票订单** | `ov_stock_order` | 美国股票, 余额/保证金/平均購入単価 |
| 海外股票行情 | `ov_stock_quote` | 当前价/报价/成交 + 图表 5种 |
| 海外股票实时 | `ov_stock_realtime` | 成交价/报价 + 延迟版本 |
| **海外期权订单** | `ov_futopt_order` | 订单/成交/未决/保证金 |
| 海外期权行情 | `ov_futopt_quote` | 报价&当前价 + 图表(期权/期货分离) |
| 海外期权实时 | `ov_futopt_realtime` | 订单成交/余额/行情/报价 |
| 场内债券订单 | `bond_order` | 买入/卖出/修改/取消/余额 |
| 场内债券行情 | `bond_quote` | 详细搜索/当前价/报价 |
| 场内债券实时 | `bond_realtime` | 一般/小额 债券 成交·报价 |
| WebSocket 通用 | `ws_common` | 会话初始化 |
> 详细方法名称请参考 `docs/api_support_matrix.md` 或 各组的 `examples/<slug>/README.md`。
---
## 方法命名规则 (域名前缀)
MCP 工具暴露或 LLM 代理使用时 **方法名称应能识别市场域名**, 因此统一添加前缀。
| 域名 | 前缀 | 示例 |
|--------|--------|------|
| 国内股票 | `kr_stock_` | `kr_stock_order`, `kr_stock_inquire_balance`, `kr_stock_realtime_execution_price` |
| 海外股票 | `ov_stock_` | `ov_stock_order`, `ov_stock_inquire_balance_margin`, `ov_stock_realtime_orderbook` |
| 国内期权 | `kr_futopt_` | `kr_futopt_order`, `kr_futopt_inquire_balance`, `kr_futopt_realtime_index_future_orderbook` |
| 海外期权 | `ov_futopt_` | `ov_futopt_order`, `ov_futopt_inquire_open_interest`, `ov_futopt_realtime_future_quote` |
| 场内债券 | `bond_` | `bond_order`, `bond_inquire_balance`, `bond_realtime_normal_execution` |
| 图表 (国内股票·期权共用) | `kr_chart_` | `kr_chart_tick`, `kr_chart_day`, `kr_chart_month` |
| 认证 / 通用 / WebSocket | (无) | `token_issue`, `inquire_group_list`, `ws_session_disconnect` |
**动词/主题模式**
| 动词 | 含义 |
|------|------|
| `order`, `order_modify`, `order_cancel`, `order_buy`, `order_sell` | 订单 |
| `inquire_*` | 查询 (余额/成交/保证金/实现损益等) |
| `realtime_*` | WebSocket 实时 |
| `chart_*` | 时间序列图表 |
| `search_*` | 종목·代码主站搜索 |
| `token_*`, `ws_*` | 认证/会话控制 |
→ 所有方法 **全局唯一** (组内 + 组间 重复 0 件)
---
## 运营 vs 模拟投资
| 项目 | 运营 | 模拟投资 |
|------|------|----------|
| **REST API URL** | `https://openapi.dbsec.co.kr:8443` | **相同** (应用属性内部分支) |
| **WebSocket URL (一般)** | `wss://openapi.dbsec.co.kr:7070/websocket` | `wss://openapi.dbsec.co.kr:17070/websocket` |
| **WebSocket URL (海外期权)** | `wss://openapi.dbsec.co.kr:7071/websocket` | — (不支持) |
| **APP_KEY / APP_SECRET** | 运营发放 | 模拟投资发放 |
> REST API 的运营/模拟投资 URL 相同。发放的应用密钥属性用于服务器分发。 **WebSocket 端口不同** (运营: 7070, 模拟: 17070).
>
> ⚠️ **海外期权 (`ov_futopt_*`) 仅限运营**, 无模拟投资环境。demo 模式调用时库会立即拦截。
`config.yaml` 中修改 `mode` 会自动切换 WebSocket URL:
```yaml
environment:
mode: "demo" # 模拟投资 (17070)
# mode: "production" # 运营 (7070)
```
> ⚠️ **并非所有 API 都支持模拟投资**。请参考 [附录 — API 模拟投资支持状态](#附录--api-模拟投资支持状态).
---
## 错误代码 & 流量控制
核心内容总结。完整的错误代码表、流量控制详细政策、使用示例请参考 **[docs/errors_and_rate_limits.md](docs/errors_and_rate_limits.md)**。
**常见错误**
| 代码 | 说明 |
|------|------|
| IGW00121 / IGW00123 | Token 无效/过期 — `auto_token=True` 自动重新发放, `False` 则表现为 APIError |
| IGW00201 | 调用交易次数超过 — 调用频率调节 |
| 2611 | 交易开始前或交易结束 |
| 2714 / 2752 | 可交易数量·保证金不足 |
**流量控制 (SDK 自动调节)**
SDK 在调用前 **2-tier 流量控制** (应用 20TPS + 端点별 TPS) 自动应用,
服务器 `IGW00201` (调用交易次数超过) 前置拦截。关闭请使用 `DBSecClient(..., rate_limit=False)`。
端点별 TPS 单一来源为 [docs/api_support_matrix.md](docs/api_support_matrix.md) 的 `TPS` 列。
| 分类 | 限制 | 备注 |
|------|------|------|
| REST 应用 (账户) 别 | 20 TPS | 端点별 (订单 10·余额 2 等) 见矩阵 `TPS` 列 |
| Token 发放/废除 | 1 TPM | 文件缓存 (24h 重用) 实际规避 |
| WebSocket 会话 / 종목 | 2会话 / 会话 50종목 | 50종목 超过时 `RateLimitError` |
```python
from dbsec_sdk.exceptions import lookup_error
print(lookup_error("IGW00123")) # "已过期 token。"
```
---
## 附录 — API 模拟投资支持状态
DB 证券 Open API 指南页面 Description 区域 **`※ 支持模拟投资账户 API。`** 字样则表示支持模拟投资。其他则仅在实盘交易环境中调用。
- **⭕ 模拟投资 + 实盘交易均支持** — 行情 · 实时 · 图表组全部可用
- **❌ 实盘交易专用** — 大多数订单及部分查询 API (特别是海外期权系统层面不支持模拟投资)
**各 API별 ⭕/❌ 显示包含的全部矩阵** → **[docs/api_support_matrix.md](docs/api_support_matrix.md)**
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器