openapi.json

{
    "openapi": "3.1.0",
    "info": {
        "title": "토스증권 Open API",
        "version": "1.0.3"
    },
    "servers": [
        {
            "url": "https://openapi.tossinvest.com"
        }
    ],
    "security": [
        {
            "oauth2ClientCredentials": []
        }
    ],
    "tags": [
        {
            "name": "Auth",
            "description": "토스증권 Open API의 모든 요청에 필요한 액세스 토큰을 발급하는 그룹입니다. OAuth 2.0 Client Credentials Grant 방식으로 `client_id`·`client_secret`을 토큰으로 교환하며, 발급된 토큰은 이후 모든 API의 `Authorization: Bearer` 헤더에 사용됩니다. 이 그룹의 엔드포인트만 `Authorization` 헤더 없이 호출하며, 응답은 BFF 공통 envelope이 아닌 OAuth 2.0 표준 형식을 따릅니다."
        },
        {
            "name": "Market Data",
            "description": "종목의 실시간성 시세 정보를 조회하는 그룹입니다. 매수/매도 호가, 현재가, 최근 체결 내역, 상·하한가, 캔들 차트(1분봉·일봉)를 제공합니다. 계좌 정보 없이 액세스 토큰만으로 호출할 수 있습니다. 호가·현재가·체결·상하한가는 `MARKET_DATA` Rate Limits Group 에 속하고, 캔들 차트는 호출 부하 특성이 달라 별도의 `MARKET_DATA_CHART` Rate Limits Group 으로 관리되므로, 두 그룹의 한도 응답 헤더를 각각 확인하는 것을 권장합니다.\n\n**이용 안내**  \n- 웹 소켓은 추후 지원 예정입니다"
        },
        {
            "name": "Stock Info",
            "description": "종목명·시장·통화·상장 상태·발행주식수 등 종목의 기본 참조 정보와 매수 유의사항을 제공하는 그룹입니다. 정리매매·단기과열·투자경고/위험·VI 발동·신주인수권 같은 매수 시 주의가 필요한 정보도 조회할 수 있습니다. 응답은 영업일 단위(또는 그 이상)로 갱신되는 데이터이므로 짧은 주기로 폴링하지 말고 화면·세션 진입 시점에 한 번 캐시해 사용하기를 권장합니다."
        },
        {
            "name": "Market Info",
            "description": "환율과 시장 운영 일정을 조회하는 그룹입니다. KRW↔USD 환율(1분 주기 갱신, 참고용 표시 환율)과 국내(KRX·NXT)·미국 시장의 장 운영 캘린더를 제공합니다. 장 캘린더는 영업일 여부와 데이마켓·프리·정규·애프터마켓 등 세션별 운영 시간을 포함하므로, 주문 가능 시간대 판단이나 휴장일 처리에 활용할 수 있습니다. 계좌와 무관한 정보로 토큰만으로 호출 가능합니다."
        },
        {
            "name": "Account",
            "description": "사용자 본인의 계좌 목록을 조회하는 그룹입니다. 해지·휴면 등을 제외한 정상 상태의 계좌만 반환하며, 계좌가 없으면 빈 배열을 응답합니다. 응답에 포함된 `accountSeq`는 보유 주식·주문·매수 가능 금액 등 계좌정보가  필요한 모든 API의 `X-Tossinvest-Account` 헤더 값으로 사용되므로, 다른 계좌 관련 API를 호출하기 전 가장 먼저 호출하는 진입점에 해당합니다."
        },
        {
            "name": "Asset",
            "description": "본인 계좌의 보유 자산 현황을 조회하는 그룹입니다. 종목별 보유 수량·매입가·평가금액·손익과 함께 계좌 전체의 합산 요약을 제공합니다. 국내(KR)·미국(US) 주식이 대상이며 해외 옵션·채권 등은 제외됩니다. 손익률은 원화(KRW) 환산 기준으로 계산됩니다. 호출 시 액세스 토큰과 `X-Tossinvest-Account` 헤더가 함께 필요합니다."
        },
        {
            "name": "Order",
            "description": "실제 매매 주문을 처리하는 그룹입니다. 지정가·시장가 주문 생성, 미체결 주문의 가격·수량 정정, 주문 취소를 지원합니다. 계좌에 직접 영향을 주는 API이므로 액세스 토큰과 `X-Tossinvest-Account` 헤더가 모두 필요합니다."
        },
        {
            "name": "Order History",
            "description": "제출한 주문의 처리 상태와 체결 내역을 조회하는 그룹입니다. `status` 파라미터로 라이프사이클 그룹(현재 진행 중 주문 `OPEN`)을 선택해 주문 목록을 조회하고, 개별 `orderId`로 모든 상태의 주문 상세를 조회할 수 있습니다. 상세 조회는 부분 체결 내역 등 주문 단위 정보를 포함합니다. 호출 시 `X-Tossinvest-Account` 헤더가 필요합니다."
        },
        {
            "name": "Order Info",
            "description": "주문을 내기 전 확인하는 거래 가능 정보를 제공하는 그룹입니다. 미수거래를 제외한 현금 기반 매수 가능 금액, 종목별 매도 가능 수량, 시장별 매매 수수료를 조회할 수 있습니다. 주문 화면에서 입력 가능한 최대 수량·금액을 안내하거나 예상 비용을 계산하는 용도로 활용하며, 정확한 주문 검증을 위해 주문 생성 직전에 호출하는 것을 권장합니다. 호출 시 `X-Tossinvest-Account` 헤더가 필요합니다."
        }
    ],
    "paths": {
        "/oauth2/token": {
            "post": {
                "tags": ["Auth"],
                "summary": "OAuth2 액세스 토큰 발급",
                "description": "OAuth 2.0 Client Credentials Grant 로 access token 을 발급합니다.\n\n- 요청 본문은 `application/x-www-form-urlencoded` 으로 전송합니다.\n- 발급된 token 은 다른 모든 API 의 `Authorization: Bearer {access_token}` 헤더에 사용합니다.\n- 응답 형식은 BFF 공통 envelope 이 아닌 OAuth2 표준 형식을 따릅니다.\n- refresh token 은 제공되지 않습니다. 만료 시 동일 엔드포인트로 재발급합니다.\n- client 당 유효한 access token 은 1 개입니다. 재발급 시 이전에 발급된 token 은 즉시 무효화됩니다.\n\n**Rate Limits Group**: `AUTH`\n",
                "operationId": "issueOAuth2Token",
                "security": [],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/x-www-form-urlencoded": {
                            "schema": {
                                "$ref": "#/components/schemas/OAuth2TokenRequest"
                            },
                            "example": {
                                "grant_type": "client_credentials",
                                "client_id": "c_01HXYZABCDEFG123456789",
                                "client_secret": "s_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "토큰 발급 성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OAuth2TokenResponse"
                                },
                                "example": {
                                    "access_token": "eyJraWQiOiIyMDI2LTA0LTAxLWtleSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjXzAxSFhZWiJ9...",
                                    "token_type": "Bearer",
                                    "expires_in": 86400
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "잘못된 요청.\n필수 파라미터 누락, 지원하지 않는 grant_type 등.\n",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OAuth2ErrorResponse"
                                },
                                "examples": {
                                    "invalidRequest": {
                                        "summary": "필수 파라미터 누락 / 형식 오류",
                                        "value": {
                                            "error": "invalid_request",
                                            "error_description": "Required parameter is missing."
                                        }
                                    },
                                    "unsupportedGrantType": {
                                        "summary": "지원하지 않는 grant_type",
                                        "value": {
                                            "error": "unsupported_grant_type",
                                            "error_description": "Only client_credentials grant type is supported."
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "클라이언트 인증 실패.\n`client_id` / `client_secret` 가 잘못되었거나 클라이언트가 비활성 상태인 경우.\n",
                        "headers": {
                            "WWW-Authenticate": {
                                "description": "Basic 인증 챌린지. 토큰 엔드포인트는 `Basic realm=\"openapi\"` 로 응답합니다.\n",
                                "schema": {
                                    "type": "string"
                                },
                                "example": "Basic realm=\"openapi\""
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/OAuth2ErrorResponse"
                                },
                                "example": {
                                    "error": "invalid_client",
                                    "error_description": "Client authentication failed."
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    }
                }
            }
        },
        "/api/v1/orderbook": {
            "get": {
                "tags": ["Market Data"],
                "summary": "호가 조회",
                "description": "매수/매도 호가 및 잔량을 조회합니다.\n\n**Rate Limits Group**: `MARKET_DATA`\n",
                "operationId": "getOrderbook",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SymbolQuery"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "$ref": "#/components/schemas/OrderbookResponse"
                                                }
                                            }
                                        }
                                    ]
                                },
                                "examples": {
                                    "krStock": {
                                        "summary": "국내 주식 (삼성전자)",
                                        "value": {
                                            "result": {
                                                "timestamp": "2026-03-25T09:30:00.123+09:00",
                                                "currency": "KRW",
                                                "asks": [
                                                    {
                                                        "price": "72300",
                                                        "volume": "1200"
                                                    },
                                                    {
                                                        "price": "72200",
                                                        "volume": "3400"
                                                    },
                                                    {
                                                        "price": "72100",
                                                        "volume": "8500"
                                                    }
                                                ],
                                                "bids": [
                                                    {
                                                        "price": "72000",
                                                        "volume": "5200"
                                                    },
                                                    {
                                                        "price": "71900",
                                                        "volume": "4100"
                                                    },
                                                    {
                                                        "price": "71800",
                                                        "volume": "2700"
                                                    }
                                                ]
                                            }
                                        }
                                    },
                                    "usStock": {
                                        "summary": "해외 주식 (Apple)",
                                        "value": {
                                            "result": {
                                                "timestamp": "2026-03-25T22:30:00.456+09:00",
                                                "currency": "USD",
                                                "asks": [
                                                    {
                                                        "price": "185.75",
                                                        "volume": "250"
                                                    },
                                                    {
                                                        "price": "185.70",
                                                        "volume": "410"
                                                    }
                                                ],
                                                "bids": [
                                                    {
                                                        "price": "185.65",
                                                        "volume": "180"
                                                    },
                                                    {
                                                        "price": "185.60",
                                                        "volume": "320"
                                                    }
                                                ]
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalErrorMarketData"
                    }
                }
            }
        },
        "/api/v1/prices": {
            "get": {
                "tags": ["Market Data"],
                "summary": "현재가 조회",
                "description": "종목의 현재가 정보를 조회합니다. 최대 200건 까지 다건 조회를 지원하며 콤마(`,`)로 구분합니다.\n\n**Rate Limits Group**: `MARKET_DATA`\n",
                "operationId": "getPrices",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "parameters": [
                    {
                        "name": "symbols",
                        "in": "query",
                        "required": true,
                        "description": "종목 심볼. 최대 200 개를 콤마(`,`)로 구분. 예: `005930,000660` 또는 `AAPL,MSFT`. 영문 대/소문자, 숫자, '.', '-' 만 허용한다.",
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9.,\\-]+$"
                        },
                        "example": "005930,000660"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "type": "array",
                                                    "items": {
                                                        "$ref": "#/components/schemas/PriceResponse"
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "examples": {
                                    "krStock": {
                                        "summary": "국내 주식 (삼성전자)",
                                        "value": {
                                            "result": [
                                                {
                                                    "symbol": "005930",
                                                    "timestamp": "2026-03-25T09:30:00.123+09:00",
                                                    "lastPrice": "72000",
                                                    "currency": "KRW"
                                                }
                                            ]
                                        }
                                    },
                                    "usStock": {
                                        "summary": "해외 주식 (Apple)",
                                        "value": {
                                            "result": [
                                                {
                                                    "symbol": "AAPL",
                                                    "timestamp": "2026-03-25T22:30:00.456+09:00",
                                                    "lastPrice": "185.70",
                                                    "currency": "USD"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "잘못된 요청",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "invalidBatchSize": {
                                        "summary": "symbols 개수가 허용 범위(1~200) 를 벗어남",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "요청이 올바르지 않습니다.",
                                                "data": {
                                                    "field": "symbols",
                                                    "constraint": {
                                                        "min": 1,
                                                        "max": 200
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalErrorMarketData"
                    }
                }
            }
        },
        "/api/v1/trades": {
            "get": {
                "tags": ["Market Data"],
                "summary": "최근 체결 내역 조회",
                "description": "당일 최근 체결 내역을 조회합니다.\n\n**Rate Limits Group**: `MARKET_DATA`\n",
                "operationId": "getTrades",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SymbolQuery"
                    },
                    {
                        "name": "count",
                        "in": "query",
                        "required": false,
                        "description": "조회 건수 (최대 50)",
                        "schema": {
                            "type": "integer",
                            "default": 50,
                            "minimum": 1,
                            "maximum": 50
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "type": "array",
                                                    "items": {
                                                        "$ref": "#/components/schemas/Trade"
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "examples": {
                                    "krStock": {
                                        "summary": "국내 주식 (삼성전자)",
                                        "value": {
                                            "result": [
                                                {
                                                    "price": "72000",
                                                    "volume": "120",
                                                    "timestamp": "2026-03-25T09:30:42.000+09:00",
                                                    "currency": "KRW"
                                                },
                                                {
                                                    "price": "71900",
                                                    "volume": "50",
                                                    "timestamp": "2026-03-25T09:30:41.500+09:00",
                                                    "currency": "KRW"
                                                },
                                                {
                                                    "price": "72000",
                                                    "volume": "200",
                                                    "timestamp": "2026-03-25T09:30:40.800+09:00",
                                                    "currency": "KRW"
                                                }
                                            ]
                                        }
                                    },
                                    "usStock": {
                                        "summary": "해외 주식 (Apple)",
                                        "value": {
                                            "result": [
                                                {
                                                    "price": "185.70",
                                                    "volume": "15",
                                                    "timestamp": "2026-03-25T22:30:42.100+09:00",
                                                    "currency": "USD"
                                                },
                                                {
                                                    "price": "185.75",
                                                    "volume": "8",
                                                    "timestamp": "2026-03-25T22:30:41.700+09:00",
                                                    "currency": "USD"
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalErrorMarketData"
                    }
                }
            }
        },
        "/api/v1/price-limits": {
            "get": {
                "tags": ["Market Data"],
                "summary": "상/하한가 조회",
                "description": "종목의 당일 상한가 및 하한가를 조회합니다.\n\n**Rate Limits Group**: `MARKET_DATA`\n",
                "operationId": "getPriceLimit",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SymbolQuery"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "$ref": "#/components/schemas/PriceLimitResponse"
                                                }
                                            }
                                        }
                                    ]
                                },
                                "examples": {
                                    "krStock": {
                                        "summary": "국내 주식 (삼성전자)",
                                        "value": {
                                            "result": {
                                                "timestamp": "2026-03-25T09:30:00.123+09:00",
                                                "upperLimitPrice": "93000",
                                                "lowerLimitPrice": "50400",
                                                "currency": "KRW"
                                            }
                                        }
                                    },
                                    "usStock": {
                                        "summary": "해외 주식 (Apple, 가격제한 없음)",
                                        "value": {
                                            "result": {
                                                "timestamp": "2026-03-25T22:30:00.456+09:00",
                                                "upperLimitPrice": null,
                                                "lowerLimitPrice": null,
                                                "currency": "USD"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalErrorMarketData"
                    }
                }
            }
        },
        "/api/v1/candles": {
            "get": {
                "tags": ["Market Data"],
                "summary": "캔들 차트 조회",
                "description": "종목의 캔들(OHLCV) 차트 데이터를 조회합니다. 최대 200개 봉을 반환합니다.\n\n**Rate Limits Group**: `MARKET_DATA_CHART`\n",
                "operationId": "getCandles",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SymbolQuery"
                    },
                    {
                        "name": "interval",
                        "in": "query",
                        "required": true,
                        "description": "봉 단위",
                        "schema": {
                            "type": "string",
                            "enum": ["1m", "1d"]
                        }
                    },
                    {
                        "name": "count",
                        "in": "query",
                        "required": false,
                        "description": "조회 봉 수 (최대 200)",
                        "schema": {
                            "type": "integer",
                            "default": 100,
                            "minimum": 1,
                            "maximum": 200
                        }
                    },
                    {
                        "name": "before",
                        "in": "query",
                        "required": false,
                        "description": "페이지네이션 상한 (exclusive, ISO 8601). 이 시각보다 이전의 봉만 반환합니다. 미지정 시 가장 최신 봉부터 반환.\n다음 페이지 요청 시 이전 응답의 `nextBefore` 값을 그대로 전달합니다.\n",
                        "schema": {
                            "type": "string",
                            "format": "date-time"
                        },
                        "example": "2026-03-25T09:00:00+09:00"
                    },
                    {
                        "name": "adjusted",
                        "in": "query",
                        "required": false,
                        "description": "수정주가 적용 여부. `true` 면 수정주가 적용, `false` 면 미적용.",
                        "schema": {
                            "type": "boolean",
                            "default": true
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "$ref": "#/components/schemas/CandlePageResponse"
                                                }
                                            }
                                        }
                                    ]
                                },
                                "examples": {
                                    "dailyCandles": {
                                        "summary": "일봉 (1d)",
                                        "value": {
                                            "result": {
                                                "candles": [
                                                    {
                                                        "timestamp": "2026-03-25T09:00:00+09:00",
                                                        "openPrice": "71600",
                                                        "highPrice": "72300",
                                                        "lowPrice": "71500",
                                                        "closePrice": "72000",
                                                        "volume": "3521000",
                                                        "currency": "KRW"
                                                    },
                                                    {
                                                        "timestamp": "2026-03-24T09:00:00+09:00",
                                                        "openPrice": "71200",
                                                        "highPrice": "71800",
                                                        "lowPrice": "71000",
                                                        "closePrice": "71600",
                                                        "volume": "2984000",
                                                        "currency": "KRW"
                                                    }
                                                ],
                                                "nextBefore": "2026-03-24T09:00:00+09:00"
                                            }
                                        }
                                    },
                                    "minuteCandles": {
                                        "summary": "분봉 (1m)",
                                        "value": {
                                            "result": {
                                                "candles": [
                                                    {
                                                        "timestamp": "2026-03-25T09:32:00+09:00",
                                                        "openPrice": "72000",
                                                        "highPrice": "72100",
                                                        "lowPrice": "71950",
                                                        "closePrice": "72050",
                                                        "volume": "15200",
                                                        "currency": "KRW"
                                                    },
                                                    {
                                                        "timestamp": "2026-03-25T09:31:00+09:00",
                                                        "openPrice": "71950",
                                                        "highPrice": "72050",
                                                        "lowPrice": "71900",
                                                        "closePrice": "72000",
                                                        "volume": "18400",
                                                        "currency": "KRW"
                                                    }
                                                ],
                                                "nextBefore": "2026-03-25T09:31:00+09:00"
                                            }
                                        }
                                    },
                                    "lastPage": {
                                        "summary": "마지막 페이지 (nextBefore null)",
                                        "value": {
                                            "result": {
                                                "candles": [
                                                    {
                                                        "timestamp": "2026-03-20T09:00:00+09:00",
                                                        "openPrice": "70800",
                                                        "highPrice": "71200",
                                                        "lowPrice": "70500",
                                                        "closePrice": "71000",
                                                        "volume": "2112000",
                                                        "currency": "KRW"
                                                    }
                                                ],
                                                "nextBefore": null
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "잘못된 요청",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "unsupportedCandleInterval": {
                                        "summary": "지원하지 않는 캔들 주기",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "지원하지 않는 캔들 주기입니다.",
                                                "data": {
                                                    "field": "interval",
                                                    "allowedValues": ["1m", "1d"]
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalErrorMarketData"
                    }
                }
            }
        },
        "/api/v1/stocks": {
            "get": {
                "tags": ["Stock Info"],
                "summary": "종목 기본 정보 조회",
                "description": "종목의 기본 정보를 조회합니다. `symbols` 를 콤마로 구분하여 최대 200건 까지 다건 조회를 지원합니다.\n종목명, 시장, 통화, 상장 상태, 거래정지 여부 등 트레이딩에서 필요한 참조 데이터를 제공합니다.\n\n**Rate Limits Group**: `STOCK`\n",
                "operationId": "getStocks",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "parameters": [
                    {
                        "name": "symbols",
                        "in": "query",
                        "required": true,
                        "description": "종목 심볼. 콤마로 구분하여 최대 200건. 예: 005930 또는 005930,AAPL. 영문 대/소문자, 숫자, '.', '-' 만 허용한다.",
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9.,\\-]+$"
                        },
                        "example": "005930,AAPL"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "type": "array",
                                                    "items": {
                                                        "$ref": "#/components/schemas/StockInfo"
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "examples": {
                                    "multiple": {
                                        "summary": "다건 조회 (국내 + 미국)",
                                        "value": {
                                            "result": [
                                                {
                                                    "symbol": "005930",
                                                    "name": "삼성전자",
                                                    "englishName": "SamsungElec",
                                                    "isinCode": "KR7005930003",
                                                    "market": "KOSPI",
                                                    "securityType": "STOCK",
                                                    "isCommonShare": true,
                                                    "status": "ACTIVE",
                                                    "currency": "KRW",
                                                    "listDate": "1975-06-11",
                                                    "delistDate": null,
                                                    "sharesOutstanding": "5919637922",
                                                    "leverageFactor": null,
                                                    "koreanMarketDetail": {
                                                        "liquidationTrading": false,
                                                        "nxtSupported": true,
                                                        "krxTradingSuspended": false,
                                                        "nxtTradingSuspended": false
                                                    }
                                                },
                                                {
                                                    "symbol": "AAPL",
                                                    "name": "애플",
                                                    "englishName": "APPLE INC",
                                                    "isinCode": "US0378331005",
                                                    "market": "NASDAQ",
                                                    "securityType": "STOCK",
                                                    "isCommonShare": true,
                                                    "status": "ACTIVE",
                                                    "currency": "USD",
                                                    "listDate": "1980-12-12",
                                                    "delistDate": null,
                                                    "sharesOutstanding": "14702703000",
                                                    "leverageFactor": null,
                                                    "koreanMarketDetail": null
                                                }
                                            ]
                                        }
                                    },
                                    "krxStock": {
                                        "summary": "국내 주식 (삼성전자)",
                                        "value": {
                                            "result": [
                                                {
                                                    "symbol": "005930",
                                                    "name": "삼성전자",
                                                    "englishName": "SamsungElec",
                                                    "isinCode": "KR7005930003",
                                                    "market": "KOSPI",
                                                    "securityType": "STOCK",
                                                    "isCommonShare": true,
                                                    "status": "ACTIVE",
                                                    "currency": "KRW",
                                                    "listDate": "1975-06-11",
                                                    "delistDate": null,
                                                    "sharesOutstanding": "5919637922",
                                                    "leverageFactor": null,
                                                    "koreanMarketDetail": {
                                                        "liquidationTrading": false,
                                                        "nxtSupported": true,
                                                        "krxTradingSuspended": false,
                                                        "nxtTradingSuspended": false
                                                    }
                                                }
                                            ]
                                        }
                                    },
                                    "usStock": {
                                        "summary": "미국 주식 (Apple)",
                                        "value": {
                                            "result": [
                                                {
                                                    "symbol": "AAPL",
                                                    "name": "애플",
                                                    "englishName": "APPLE INC",
                                                    "isinCode": "US0378331005",
                                                    "market": "NASDAQ",
                                                    "securityType": "STOCK",
                                                    "isCommonShare": true,
                                                    "status": "ACTIVE",
                                                    "currency": "USD",
                                                    "listDate": "1980-12-12",
                                                    "delistDate": null,
                                                    "sharesOutstanding": "14702703000",
                                                    "leverageFactor": null,
                                                    "koreanMarketDetail": null
                                                }
                                            ]
                                        }
                                    },
                                    "etf": {
                                        "summary": "ETF (KODEX 200)",
                                        "value": {
                                            "result": [
                                                {
                                                    "symbol": "069500",
                                                    "name": "KODEX 200",
                                                    "englishName": "KODEX 200",
                                                    "isinCode": "KR7069500007",
                                                    "market": "KOSPI",
                                                    "securityType": "ETF",
                                                    "isCommonShare": true,
                                                    "status": "ACTIVE",
                                                    "currency": "KRW",
                                                    "listDate": "2002-10-14",
                                                    "delistDate": null,
                                                    "sharesOutstanding": "208050000",
                                                    "leverageFactor": "1",
                                                    "koreanMarketDetail": {
                                                        "liquidationTrading": false,
                                                        "nxtSupported": false,
                                                        "krxTradingSuspended": false,
                                                        "nxtTradingSuspended": null
                                                    }
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "잘못된 요청",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "tooManySymbols": {
                                        "summary": "허용 개수 초과 (1~200건)",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "요청이 올바르지 않습니다.",
                                                "data": {
                                                    "field": "symbols",
                                                    "constraint": {
                                                        "min": 1,
                                                        "max": 200
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalErrorStock"
                    }
                }
            }
        },
        "/api/v1/stocks/{symbol}/warnings": {
            "get": {
                "tags": ["Stock Info"],
                "summary": "매수 유의사항 조회",
                "description": "종목의 매수 유의사항 및 변동성 완화(VI) 발동 정보를 조회합니다.\n\n**포함 종류**: 정리매매(`LIQUIDATION_TRADING`), 단기과열종목(`OVERHEATED`), 투자경고(`INVESTMENT_WARNING`), 투자위험(`INVESTMENT_RISK`), VI 정적/동적/혼합(`VI_STATIC` / `VI_DYNAMIC` / `VI_STATIC_AND_DYNAMIC`), 신주인수권(`STOCK_WARRANTS`). 전체 enum 은 `StockWarning.warningType` 참조.\n\n**\"활성\"의 시간 기준**: 응답 시점 기준으로 `startDate <= 오늘 <= endDate` 인 항목 (또는 `endDate` 가 `null` 인 진행 중 항목).\n\n**응답 정렬**: `startDate` 내림차순 (최근 발동된 항목부터). `startDate` 가 동일한 경우 정렬 순서는 보장되지 않습니다.\n\n**데이터 적시성**: VI 발동/해제는 거래소 이벤트 발생 후 수 초 내 반영됩니다. 정리매매·단기과열·투자경고/위험 지정은 거래소 공시 기준 일배치로 반영됩니다.\n\n**미존재 vs 빈 배열**:\n- 종목 자체가 없으면 `404 stock-not-found`.\n- 종목은 있으나 활성 유의사항이 없으면 `200 OK` + `result: []`.\n\n**Rate Limits Group**: `STOCK`\n",
                "operationId": "getStockWarnings",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Symbol"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "type": "array",
                                                    "items": {
                                                        "$ref": "#/components/schemas/StockWarning"
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "examples": {
                                    "withWarnings": {
                                        "summary": "유의사항이 있는 종목",
                                        "value": {
                                            "result": [
                                                {
                                                    "warningType": "OVERHEATED",
                                                    "exchange": "KRX",
                                                    "startDate": "2026-03-20",
                                                    "endDate": "2026-03-27"
                                                },
                                                {
                                                    "warningType": "VI_STATIC",
                                                    "exchange": "KRX",
                                                    "startDate": "2026-03-26",
                                                    "endDate": null
                                                }
                                            ]
                                        }
                                    },
                                    "noWarnings": {
                                        "summary": "유의사항이 없는 종목",
                                        "value": {
                                            "result": []
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalErrorStock"
                    }
                }
            }
        },
        "/api/v1/exchange-rate": {
            "get": {
                "tags": ["Market Info"],
                "summary": "환율 조회",
                "description": "KRW ↔ USD 환율 정보를 조회합니다.\n\n- **갱신 주기 1분**, 참고용 표시 환율. 실제 주문 시 적용되는 거래 환율과 다를 수 있습니다.\n- `dateTime` 미지정 시 **현재 시점의 유효 환율**이 응답됩니다.\n- 응답의 `validFrom` ~ `validUntil` 은 해당 환율의 **유효 시간 윈도** (보통 1분) 입니다.\n\n**Rate Limits Group**: `MARKET_INFO`\n",
                "operationId": "getExchangeRate",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "parameters": [
                    {
                        "name": "dateTime",
                        "in": "query",
                        "required": false,
                        "description": "조회할 환율 시각. 특정 시점의 환율을 조회할 수 있습니다.",
                        "schema": {
                            "type": "string",
                            "format": "date-time"
                        },
                        "example": "2026-03-25T09:30:00+09:00"
                    },
                    {
                        "name": "baseCurrency",
                        "in": "query",
                        "required": true,
                        "description": "기준 통화",
                        "schema": {
                            "$ref": "#/components/schemas/Currency"
                        },
                        "example": "USD"
                    },
                    {
                        "name": "quoteCurrency",
                        "in": "query",
                        "required": true,
                        "description": "표시 통화 (quote currency)",
                        "schema": {
                            "$ref": "#/components/schemas/Currency"
                        },
                        "example": "KRW"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "$ref": "#/components/schemas/ExchangeRateResponse"
                                                }
                                            }
                                        }
                                    ]
                                },
                                "examples": {
                                    "usdToKrwUp": {
                                        "summary": "USD→KRW 환율 (상승)",
                                        "value": {
                                            "result": {
                                                "baseCurrency": "USD",
                                                "quoteCurrency": "KRW",
                                                "rate": "1380.5",
                                                "midRate": "1375",
                                                "basisPoint": "40",
                                                "rateChangeType": "UP",
                                                "validFrom": "2026-03-25T09:30:00+09:00",
                                                "validUntil": "2026-03-25T09:31:00+09:00"
                                            }
                                        }
                                    },
                                    "usdToKrwDown": {
                                        "summary": "USD→KRW 환율 (하락)",
                                        "value": {
                                            "result": {
                                                "baseCurrency": "USD",
                                                "quoteCurrency": "KRW",
                                                "rate": "1372.3",
                                                "midRate": "1375",
                                                "basisPoint": "-19.6",
                                                "rateChangeType": "DOWN",
                                                "validFrom": "2026-03-25T09:30:00+09:00",
                                                "validUntil": "2026-03-25T09:31:00+09:00"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "잘못된 요청",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "unsupportedCurrency": {
                                        "summary": "지원하지 않는 통화",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "지원하지 않는 통화입니다.",
                                                "data": {
                                                    "field": "baseCurrency",
                                                    "allowedValues": ["KRW", "USD"]
                                                }
                                            }
                                        }
                                    },
                                    "sameCurrency": {
                                        "summary": "기준 통화와 상대 통화가 같음",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "기준 통화와 상대 통화가 같을 수 없습니다.",
                                                "data": {
                                                    "field": "baseCurrency,quoteCurrency"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "환율 정보 없음",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "exchangeRateNotFound": {
                                        "summary": "요청한 시점의 환율 정보 없음",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "exchange-rate-not-found",
                                                "message": "요청한 시점의 환율 정보가 없습니다."
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalErrorMarketInfo"
                    }
                }
            }
        },
        "/api/v1/market-calendar/KR": {
            "get": {
                "tags": ["Market Info"],
                "summary": "국내 장 운영 정보 조회",
                "description": "국내 시장의 거래 가능 시간을 조회합니다. 통합 모드 (KRX+NXT) 기준이며, 특수장(시간외종가/시간외단일가)은 제외됩니다. 전일/당일/익일 3영업일 정보를 반환합니다. 모든 시간은 KST(+09:00) 기준.\n\n**Rate Limits Group**: `MARKET_INFO`\n",
                "operationId": "getKrMarketCalendar",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "parameters": [
                    {
                        "name": "date",
                        "in": "query",
                        "required": false,
                        "description": "조회 기준일 (YYYY-MM-DD)",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        },
                        "example": "2026-03-25"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "$ref": "#/components/schemas/KrMarketCalendarResponse"
                                                }
                                            }
                                        }
                                    ]
                                },
                                "examples": {
                                    "businessDay": {
                                        "summary": "영업일 (KRX+NXT 정상 운영)",
                                        "value": {
                                            "result": {
                                                "today": {
                                                    "date": "2026-03-25",
                                                    "integrated": {
                                                        "preMarket": {
                                                            "startTime": "2026-03-25T08:00:00+09:00",
                                                            "singlePriceAuctionStartTime": "2026-03-25T08:50:00+09:00",
                                                            "endTime": "2026-03-25T09:00:00+09:00"
                                                        },
                                                        "regularMarket": {
                                                            "startTime": "2026-03-25T09:00:00+09:00",
                                                            "singlePriceAuctionStartTime": "2026-03-25T15:20:00+09:00",
                                                            "endTime": "2026-03-25T15:30:00+09:00"
                                                        },
                                                        "afterMarket": {
                                                            "startTime": "2026-03-25T15:30:00+09:00",
                                                            "singlePriceAuctionEndTime": "2026-03-25T15:40:00+09:00",
                                                            "endTime": "2026-03-25T20:00:00+09:00"
                                                        }
                                                    }
                                                },
                                                "previousBusinessDay": {
                                                    "date": "2026-03-24",
                                                    "integrated": {
                                                        "preMarket": {
                                                            "startTime": "2026-03-24T08:00:00+09:00",
                                                            "singlePriceAuctionStartTime": "2026-03-24T08:50:00+09:00",
                                                            "endTime": "2026-03-24T09:00:00+09:00"
                                                        },
                                                        "regularMarket": {
                                                            "startTime": "2026-03-24T09:00:00+09:00",
                                                            "singlePriceAuctionStartTime": "2026-03-24T15:20:00+09:00",
                                                            "endTime": "2026-03-24T15:30:00+09:00"
                                                        },
                                                        "afterMarket": {
                                                            "startTime": "2026-03-24T15:30:00+09:00",
                                                            "singlePriceAuctionEndTime": "2026-03-24T15:40:00+09:00",
                                                            "endTime": "2026-03-24T20:00:00+09:00"
                                                        }
                                                    }
                                                },
                                                "nextBusinessDay": {
                                                    "date": "2026-03-26",
                                                    "integrated": {
                                                        "preMarket": {
                                                            "startTime": "2026-03-26T08:00:00+09:00",
                                                            "singlePriceAuctionStartTime": "2026-03-26T08:50:00+09:00",
                                                            "endTime": "2026-03-26T09:00:00+09:00"
                                                        },
                                                        "regularMarket": {
                                                            "startTime": "2026-03-26T09:00:00+09:00",
                                                            "singlePriceAuctionStartTime": "2026-03-26T15:20:00+09:00",
                                                            "endTime": "2026-03-26T15:30:00+09:00"
                                                        },
                                                        "afterMarket": {
                                                            "startTime": "2026-03-26T15:30:00+09:00",
                                                            "singlePriceAuctionEndTime": "2026-03-26T15:40:00+09:00",
                                                            "endTime": "2026-03-26T20:00:00+09:00"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    },
                                    "holidayToday": {
                                        "summary": "휴장일 (today 만 휴장, integrated null)",
                                        "value": {
                                            "result": {
                                                "today": {
                                                    "date": "2026-05-05",
                                                    "integrated": null
                                                },
                                                "previousBusinessDay": {
                                                    "date": "2026-05-04",
                                                    "integrated": {
                                                        "preMarket": {
                                                            "startTime": "2026-05-04T08:00:00+09:00",
                                                            "singlePriceAuctionStartTime": "2026-05-04T08:50:00+09:00",
                                                            "endTime": "2026-05-04T09:00:00+09:00"
                                                        },
                                                        "regularMarket": {
                                                            "startTime": "2026-05-04T09:00:00+09:00",
                                                            "singlePriceAuctionStartTime": "2026-05-04T15:20:00+09:00",
                                                            "endTime": "2026-05-04T15:30:00+09:00"
                                                        },
                                                        "afterMarket": {
                                                            "startTime": "2026-05-04T15:30:00+09:00",
                                                            "singlePriceAuctionEndTime": "2026-05-04T15:40:00+09:00",
                                                            "endTime": "2026-05-04T20:00:00+09:00"
                                                        }
                                                    }
                                                },
                                                "nextBusinessDay": {
                                                    "date": "2026-05-06",
                                                    "integrated": {
                                                        "preMarket": {
                                                            "startTime": "2026-05-06T08:00:00+09:00",
                                                            "singlePriceAuctionStartTime": "2026-05-06T08:50:00+09:00",
                                                            "endTime": "2026-05-06T09:00:00+09:00"
                                                        },
                                                        "regularMarket": {
                                                            "startTime": "2026-05-06T09:00:00+09:00",
                                                            "singlePriceAuctionStartTime": "2026-05-06T15:20:00+09:00",
                                                            "endTime": "2026-05-06T15:30:00+09:00"
                                                        },
                                                        "afterMarket": {
                                                            "startTime": "2026-05-06T15:30:00+09:00",
                                                            "singlePriceAuctionEndTime": "2026-05-06T15:40:00+09:00",
                                                            "endTime": "2026-05-06T20:00:00+09:00"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    },
                                    "nxtPreMarketHoliday": {
                                        "summary": "부분 휴장 (NXT 프리마켓만 휴장, 정규장·애프터마켓은 운영)",
                                        "value": {
                                            "result": {
                                                "today": {
                                                    "date": "2026-03-25",
                                                    "integrated": {
                                                        "preMarket": null,
                                                        "regularMarket": {
                                                            "startTime": "2026-03-25T09:00:00+09:00",
                                                            "singlePriceAuctionStartTime": "2026-03-25T15:20:00+09:00",
                                                            "endTime": "2026-03-25T15:30:00+09:00"
                                                        },
                                                        "afterMarket": {
                                                            "startTime": "2026-03-25T15:30:00+09:00",
                                                            "singlePriceAuctionEndTime": "2026-03-25T15:40:00+09:00",
                                                            "endTime": "2026-03-25T20:00:00+09:00"
                                                        }
                                                    }
                                                },
                                                "previousBusinessDay": {
                                                    "date": "2026-03-24",
                                                    "integrated": {
                                                        "preMarket": {
                                                            "startTime": "2026-03-24T08:00:00+09:00",
                                                            "singlePriceAuctionStartTime": "2026-03-24T08:50:00+09:00",
                                                            "endTime": "2026-03-24T09:00:00+09:00"
                                                        },
                                                        "regularMarket": {
                                                            "startTime": "2026-03-24T09:00:00+09:00",
                                                            "singlePriceAuctionStartTime": "2026-03-24T15:20:00+09:00",
                                                            "endTime": "2026-03-24T15:30:00+09:00"
                                                        },
                                                        "afterMarket": {
                                                            "startTime": "2026-03-24T15:30:00+09:00",
                                                            "singlePriceAuctionEndTime": "2026-03-24T15:40:00+09:00",
                                                            "endTime": "2026-03-24T20:00:00+09:00"
                                                        }
                                                    }
                                                },
                                                "nextBusinessDay": {
                                                    "date": "2026-03-26",
                                                    "integrated": {
                                                        "preMarket": {
                                                            "startTime": "2026-03-26T08:00:00+09:00",
                                                            "singlePriceAuctionStartTime": "2026-03-26T08:50:00+09:00",
                                                            "endTime": "2026-03-26T09:00:00+09:00"
                                                        },
                                                        "regularMarket": {
                                                            "startTime": "2026-03-26T09:00:00+09:00",
                                                            "singlePriceAuctionStartTime": "2026-03-26T15:20:00+09:00",
                                                            "endTime": "2026-03-26T15:30:00+09:00"
                                                        },
                                                        "afterMarket": {
                                                            "startTime": "2026-03-26T15:30:00+09:00",
                                                            "singlePriceAuctionEndTime": "2026-03-26T15:40:00+09:00",
                                                            "endTime": "2026-03-26T20:00:00+09:00"
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "잘못된 요청",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "unsupportedDate": {
                                        "summary": "지원하지 않는 조회 일자",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "unsupported-date",
                                                "message": "요청한 조회 일자를 지원하지 않습니다.",
                                                "data": {
                                                    "field": "date"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalErrorMarketInfo"
                    }
                }
            }
        },
        "/api/v1/market-calendar/US": {
            "get": {
                "tags": ["Market Info"],
                "summary": "해외 장 운영 정보 조회",
                "description": "미국 시장의 장 운영 시간을 조회합니다. 4 세션(`dayMarket`, `preMarket`, `regularMarket`, `afterMarket`) 별로 nullable. 휴장 시 4 세션 모두 null. 전일/당일/익일 3영업일 정보를 반환합니다. 모든 시간은 KST(+09:00) 기준.\n\n**Rate Limits Group**: `MARKET_INFO`\n",
                "operationId": "getUsMarketCalendar",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "parameters": [
                    {
                        "name": "date",
                        "in": "query",
                        "required": false,
                        "description": "조회 기준일 (YYYY-MM-DD, 미국 현지 날짜)",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        },
                        "example": "2026-03-25"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "$ref": "#/components/schemas/UsMarketCalendarResponse"
                                                }
                                            }
                                        }
                                    ]
                                },
                                "examples": {
                                    "businessDay": {
                                        "summary": "영업일 (데이마켓 포함, 4 세션 nested)",
                                        "value": {
                                            "result": {
                                                "today": {
                                                    "date": "2026-03-25",
                                                    "dayMarket": {
                                                        "startTime": "2026-03-25T09:00:00+09:00",
                                                        "endTime": "2026-03-25T16:50:00+09:00"
                                                    },
                                                    "preMarket": {
                                                        "startTime": "2026-03-25T17:00:00+09:00",
                                                        "endTime": "2026-03-25T22:30:00+09:00"
                                                    },
                                                    "regularMarket": {
                                                        "startTime": "2026-03-25T22:30:00+09:00",
                                                        "endTime": "2026-03-26T05:00:00+09:00"
                                                    },
                                                    "afterMarket": {
                                                        "startTime": "2026-03-26T05:00:00+09:00",
                                                        "endTime": "2026-03-26T07:00:00+09:00"
                                                    }
                                                },
                                                "previousBusinessDay": {
                                                    "date": "2026-03-24",
                                                    "dayMarket": {
                                                        "startTime": "2026-03-24T09:00:00+09:00",
                                                        "endTime": "2026-03-24T16:50:00+09:00"
                                                    },
                                                    "preMarket": {
                                                        "startTime": "2026-03-24T17:00:00+09:00",
                                                        "endTime": "2026-03-24T22:30:00+09:00"
                                                    },
                                                    "regularMarket": {
                                                        "startTime": "2026-03-24T22:30:00+09:00",
                                                        "endTime": "2026-03-25T05:00:00+09:00"
                                                    },
                                                    "afterMarket": {
                                                        "startTime": "2026-03-25T05:00:00+09:00",
                                                        "endTime": "2026-03-25T07:00:00+09:00"
                                                    }
                                                },
                                                "nextBusinessDay": {
                                                    "date": "2026-03-26",
                                                    "dayMarket": {
                                                        "startTime": "2026-03-26T09:00:00+09:00",
                                                        "endTime": "2026-03-26T16:50:00+09:00"
                                                    },
                                                    "preMarket": {
                                                        "startTime": "2026-03-26T17:00:00+09:00",
                                                        "endTime": "2026-03-26T22:30:00+09:00"
                                                    },
                                                    "regularMarket": {
                                                        "startTime": "2026-03-26T22:30:00+09:00",
                                                        "endTime": "2026-03-27T05:00:00+09:00"
                                                    },
                                                    "afterMarket": {
                                                        "startTime": "2026-03-27T05:00:00+09:00",
                                                        "endTime": "2026-03-27T07:00:00+09:00"
                                                    }
                                                }
                                            }
                                        }
                                    },
                                    "holidayToday": {
                                        "summary": "휴장일 (today 만 휴장, 4 세션 모두 null)",
                                        "value": {
                                            "result": {
                                                "today": {
                                                    "date": "2026-07-03",
                                                    "dayMarket": null,
                                                    "preMarket": null,
                                                    "regularMarket": null,
                                                    "afterMarket": null
                                                },
                                                "previousBusinessDay": {
                                                    "date": "2026-07-02",
                                                    "dayMarket": {
                                                        "startTime": "2026-07-02T09:00:00+09:00",
                                                        "endTime": "2026-07-02T16:50:00+09:00"
                                                    },
                                                    "preMarket": {
                                                        "startTime": "2026-07-02T17:00:00+09:00",
                                                        "endTime": "2026-07-02T22:30:00+09:00"
                                                    },
                                                    "regularMarket": {
                                                        "startTime": "2026-07-02T22:30:00+09:00",
                                                        "endTime": "2026-07-03T05:00:00+09:00"
                                                    },
                                                    "afterMarket": {
                                                        "startTime": "2026-07-03T05:00:00+09:00",
                                                        "endTime": "2026-07-03T07:00:00+09:00"
                                                    }
                                                },
                                                "nextBusinessDay": {
                                                    "date": "2026-07-06",
                                                    "dayMarket": {
                                                        "startTime": "2026-07-06T09:00:00+09:00",
                                                        "endTime": "2026-07-06T16:50:00+09:00"
                                                    },
                                                    "preMarket": {
                                                        "startTime": "2026-07-06T17:00:00+09:00",
                                                        "endTime": "2026-07-06T22:30:00+09:00"
                                                    },
                                                    "regularMarket": {
                                                        "startTime": "2026-07-06T22:30:00+09:00",
                                                        "endTime": "2026-07-07T05:00:00+09:00"
                                                    },
                                                    "afterMarket": {
                                                        "startTime": "2026-07-07T05:00:00+09:00",
                                                        "endTime": "2026-07-07T07:00:00+09:00"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalErrorMarketInfo"
                    }
                }
            }
        },
        "/api/v1/accounts": {
            "get": {
                "tags": ["Account"],
                "summary": "계좌 목록 조회",
                "description": "사용자의 계좌 목록을 조회합니다.\n\n- 현재는 **종합매매 (`BROKERAGE`) 계좌만 반환**하며, 계좌가 없으면 빈 배열. 자녀계좌는 사용할 수 없습니다.\n- 응답의 `accountSeq` 는 **다른 모든 사용자 컨텍스트 API** (보유 주식, 주문, 매수가능금액 등) 의 `X-Tossinvest-Account` 헤더에 사용합니다.\n- `accountType` enum 은 `BROKERAGE` / `OVERSEAS_DERIVATIVES` / `PENSION_SAVINGS` / `RESHORING_INVESTMENT` 가 정의되어 있으나 본 API 에서는 현재 `BROKERAGE` 만 노출됩니다. enum 의미는 `Account.accountType` schema 참조.\n\n**Rate Limits Group**: `ACCOUNT`\n",
                "operationId": "getAccounts",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "type": "array",
                                                    "items": {
                                                        "$ref": "#/components/schemas/Account"
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "examples": {
                                    "brokerageAccount": {
                                        "summary": "종합매매 계좌",
                                        "value": {
                                            "result": [
                                                {
                                                    "accountNo": "12345678901",
                                                    "accountSeq": 1,
                                                    "accountType": "BROKERAGE"
                                                }
                                            ]
                                        }
                                    },
                                    "emptyAccounts": {
                                        "summary": "계좌 없음",
                                        "value": {
                                            "result": []
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/ServiceUnavailable"
                    }
                }
            }
        },
        "/api/v1/holdings": {
            "get": {
                "tags": ["Asset"],
                "summary": "보유 주식 조회",
                "description": "보유 주식 정보를 조회합니다.\n국내(KR)·미국(US) 주식만 포함하며, 해외 옵션·채권은 제외합니다.\n보유 종목이 없으면 요약 금액은 0이고 items는 빈 배열입니다.\n\n**Rate Limits Group**: `ASSET`\n",
                "operationId": "getHoldings",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/AccountSeq"
                    },
                    {
                        "name": "symbol",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9.\\-]+$"
                        },
                        "description": "종목 심볼. KR: 6자리 숫자 (예: 005930), US: 티커 (예: AAPL).\n영문 대/소문자, 숫자, '.', '-' 만 허용한다.\n제공 시 해당 종목만 필터링하여 반환하며, 요약 필드도 해당 종목 기준으로 재계산합니다.\n미제공 시 전체 보유 종목을 반환합니다.\n",
                        "example": "005930"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "$ref": "#/components/schemas/HoldingsOverview"
                                                }
                                            }
                                        }
                                    ]
                                },
                                "examples": {
                                    "withHoldings": {
                                        "summary": "보유 종목 있음 (KR + US 혼합)",
                                        "description": "krw에는 KRW로 거래되는 국내 종목의 합만, usd에는 USD로 거래되는 해외 종목의 합만 포함됩니다. rate는 SDK가 제공하는 전체 자산 원화 환산 기준 손익률입니다.",
                                        "value": {
                                            "result": {
                                                "totalPurchaseAmount": {
                                                    "krw": "6500000",
                                                    "usd": "1553"
                                                },
                                                "marketValue": {
                                                    "amount": {
                                                        "krw": "7200000",
                                                        "usd": "1785"
                                                    },
                                                    "amountAfterCost": {
                                                        "krw": "7050000",
                                                        "usd": "1771.43"
                                                    }
                                                },
                                                "profitLoss": {
                                                    "amount": {
                                                        "krw": "700000",
                                                        "usd": "232"
                                                    },
                                                    "amountAfterCost": {
                                                        "krw": "550000",
                                                        "usd": "218.43"
                                                    },
                                                    "rate": "0.1179",
                                                    "rateAfterCost": "0.0983"
                                                },
                                                "dailyProfitLoss": {
                                                    "amount": {
                                                        "krw": "100000",
                                                        "usd": "25"
                                                    },
                                                    "rate": "0.0141"
                                                },
                                                "items": [
                                                    {
                                                        "symbol": "005930",
                                                        "name": "삼성전자",
                                                        "marketCountry": "KR",
                                                        "currency": "KRW",
                                                        "quantity": "100",
                                                        "lastPrice": "72000",
                                                        "averagePurchasePrice": "65000",
                                                        "marketValue": {
                                                            "purchaseAmount": "6500000",
                                                            "amount": "7200000",
                                                            "amountAfterCost": "7050000"
                                                        },
                                                        "profitLoss": {
                                                            "amount": "700000",
                                                            "amountAfterCost": "550000",
                                                            "rate": "0.1077",
                                                            "rateAfterCost": "0.0846"
                                                        },
                                                        "dailyProfitLoss": {
                                                            "amount": "100000",
                                                            "rate": "0.0141"
                                                        },
                                                        "cost": {
                                                            "commission": "14400",
                                                            "tax": "135600"
                                                        }
                                                    },
                                                    {
                                                        "symbol": "AAPL",
                                                        "name": "Apple Inc.",
                                                        "marketCountry": "US",
                                                        "currency": "USD",
                                                        "quantity": "10",
                                                        "lastPrice": "178.5",
                                                        "averagePurchasePrice": "155.3",
                                                        "marketValue": {
                                                            "purchaseAmount": "1553",
                                                            "amount": "1785",
                                                            "amountAfterCost": "1771.43"
                                                        },
                                                        "profitLoss": {
                                                            "amount": "232",
                                                            "amountAfterCost": "218.43",
                                                            "rate": "0.1494",
                                                            "rateAfterCost": "0.1406"
                                                        },
                                                        "dailyProfitLoss": {
                                                            "amount": "25",
                                                            "rate": "0.0142"
                                                        },
                                                        "cost": {
                                                            "commission": "3.57",
                                                            "tax": "10"
                                                        }
                                                    }
                                                ]
                                            }
                                        }
                                    },
                                    "filteredBySymbol": {
                                        "summary": "symbol 필터 적용 (005930)",
                                        "value": {
                                            "result": {
                                                "totalPurchaseAmount": {
                                                    "krw": "6500000",
                                                    "usd": null
                                                },
                                                "marketValue": {
                                                    "amount": {
                                                        "krw": "7200000",
                                                        "usd": null
                                                    },
                                                    "amountAfterCost": {
                                                        "krw": "7050000",
                                                        "usd": null
                                                    }
                                                },
                                                "profitLoss": {
                                                    "amount": {
                                                        "krw": "700000",
                                                        "usd": null
                                                    },
                                                    "amountAfterCost": {
                                                        "krw": "550000",
                                                        "usd": null
                                                    },
                                                    "rate": "0.1077",
                                                    "rateAfterCost": "0.0846"
                                                },
                                                "dailyProfitLoss": {
                                                    "amount": {
                                                        "krw": "100000",
                                                        "usd": null
                                                    },
                                                    "rate": "0.0141"
                                                },
                                                "items": [
                                                    {
                                                        "symbol": "005930",
                                                        "name": "삼성전자",
                                                        "marketCountry": "KR",
                                                        "currency": "KRW",
                                                        "quantity": "100",
                                                        "lastPrice": "72000",
                                                        "averagePurchasePrice": "65000",
                                                        "marketValue": {
                                                            "purchaseAmount": "6500000",
                                                            "amount": "7200000",
                                                            "amountAfterCost": "7050000"
                                                        },
                                                        "profitLoss": {
                                                            "amount": "700000",
                                                            "amountAfterCost": "550000",
                                                            "rate": "0.1077",
                                                            "rateAfterCost": "0.0846"
                                                        },
                                                        "dailyProfitLoss": {
                                                            "amount": "100000",
                                                            "rate": "0.0141"
                                                        },
                                                        "cost": {
                                                            "commission": "14400",
                                                            "tax": "135600"
                                                        }
                                                    }
                                                ]
                                            }
                                        }
                                    },
                                    "filteredByUsSymbol": {
                                        "summary": "symbol 필터 적용 (AAPL, 해외 종목)",
                                        "description": "해외 종목만 필터된 결과의 krw는 0(국내 종목 없음), usd만 합산됩니다. rate는 단일 통화(USD) 기준으로 재계산합니다.",
                                        "value": {
                                            "result": {
                                                "totalPurchaseAmount": {
                                                    "krw": "0",
                                                    "usd": "1500.00"
                                                },
                                                "marketValue": {
                                                    "amount": {
                                                        "krw": "0",
                                                        "usd": "1700.00"
                                                    },
                                                    "amountAfterCost": {
                                                        "krw": "0",
                                                        "usd": "1650.00"
                                                    }
                                                },
                                                "profitLoss": {
                                                    "amount": {
                                                        "krw": "0",
                                                        "usd": "200.00"
                                                    },
                                                    "amountAfterCost": {
                                                        "krw": "0",
                                                        "usd": "150.00"
                                                    },
                                                    "rate": "0.1333",
                                                    "rateAfterCost": "0.1000"
                                                },
                                                "dailyProfitLoss": {
                                                    "amount": {
                                                        "krw": "0",
                                                        "usd": "20.00"
                                                    },
                                                    "rate": "0.0119"
                                                },
                                                "items": [
                                                    {
                                                        "symbol": "AAPL",
                                                        "name": "Apple Inc.",
                                                        "marketCountry": "US",
                                                        "currency": "USD",
                                                        "quantity": "10",
                                                        "lastPrice": "170.00",
                                                        "averagePurchasePrice": "150.00",
                                                        "marketValue": {
                                                            "purchaseAmount": "1500.00",
                                                            "amount": "1700.00",
                                                            "amountAfterCost": "1650.00"
                                                        },
                                                        "profitLoss": {
                                                            "amount": "200.00",
                                                            "amountAfterCost": "150.00",
                                                            "rate": "0.1333",
                                                            "rateAfterCost": "0.10"
                                                        },
                                                        "dailyProfitLoss": {
                                                            "amount": "20.00",
                                                            "rate": "0.012"
                                                        },
                                                        "cost": {
                                                            "commission": "2.15",
                                                            "tax": null
                                                        }
                                                    }
                                                ]
                                            }
                                        }
                                    },
                                    "filteredBySymbolNotFound": {
                                        "summary": "symbol 필터 적용 — 해당 종목 미보유",
                                        "value": {
                                            "result": {
                                                "totalPurchaseAmount": {
                                                    "krw": "0",
                                                    "usd": null
                                                },
                                                "marketValue": {
                                                    "amount": {
                                                        "krw": "0",
                                                        "usd": null
                                                    },
                                                    "amountAfterCost": {
                                                        "krw": "0",
                                                        "usd": null
                                                    }
                                                },
                                                "profitLoss": {
                                                    "amount": {
                                                        "krw": "0",
                                                        "usd": null
                                                    },
                                                    "amountAfterCost": {
                                                        "krw": "0",
                                                        "usd": null
                                                    },
                                                    "rate": "0",
                                                    "rateAfterCost": "0"
                                                },
                                                "dailyProfitLoss": {
                                                    "amount": {
                                                        "krw": "0",
                                                        "usd": null
                                                    },
                                                    "rate": "0"
                                                },
                                                "items": []
                                            }
                                        }
                                    },
                                    "emptyHoldings": {
                                        "summary": "보유 종목 없음",
                                        "value": {
                                            "result": {
                                                "totalPurchaseAmount": {
                                                    "krw": "0",
                                                    "usd": null
                                                },
                                                "marketValue": {
                                                    "amount": {
                                                        "krw": "0",
                                                        "usd": null
                                                    },
                                                    "amountAfterCost": {
                                                        "krw": "0",
                                                        "usd": null
                                                    }
                                                },
                                                "profitLoss": {
                                                    "amount": {
                                                        "krw": "0",
                                                        "usd": null
                                                    },
                                                    "amountAfterCost": {
                                                        "krw": "0",
                                                        "usd": null
                                                    },
                                                    "rate": "0",
                                                    "rateAfterCost": "0"
                                                },
                                                "dailyProfitLoss": {
                                                    "amount": {
                                                        "krw": "0",
                                                        "usd": null
                                                    },
                                                    "rate": "0"
                                                },
                                                "items": []
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/AccountHeaderRequired"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalErrorAsset"
                    }
                }
            }
        },
        "/api/v1/orders": {
            "get": {
                "tags": ["Order History"],
                "summary": "주문 목록 조회",
                "description": "주문 목록을 조회합니다.\nstatus 파라미터로 주문 상태를 필터링합니다.\n\n**지원하는 status 값:**\n- 진행 중 주문: `OPEN` -- PENDING, PARTIAL_FILLED, PENDING_CANCEL, PENDING_REPLACE 상태의 주문을 반환\n- 종료된 주문: `CLOSED` -- 현재 호출 시 `400 closed-not-supported` 를 반환합니다.\n\nsymbol을 지정하면 해당 종목의 주문만 필터링하여 반환합니다.\n\n**페이징 동작:**\n- `status=OPEN`: 모든 대기 중 주문을 전량 반환합니다. `limit`, `cursor` 는 무시되며, `from`/`to` 만 주문 생성일(`orderedAt`, KST 기준) 범위 필터로 적용됩니다 (미지정 시 전체 기간).\n- `status=CLOSED`: 미지원. `cursor`, `limit`, `from`, `to` 파라미터는 현재 효과가 없습니다.\n\n**Rate Limits Group**: `ORDER_HISTORY`\n",
                "operationId": "getOrders",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/AccountSeq"
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": true,
                        "description": "주문 라이프사이클 그룹 필터. 이 값은 각 주문의 세부 상태(`orders[].status`)를 **그룹화한 라벨**이며, `orders[].status` 와 값 체계가 다릅니다.\n\n- `OPEN`: 진행 중 주문 그룹 — `orders[].status` ∈ `{PENDING, PARTIAL_FILLED, PENDING_CANCEL, PENDING_REPLACE}`\n- `CLOSED`: 종료된 주문 그룹. 현재 호출 시 `400 closed-not-supported` 를 반환합니다.\n\n예: `status=OPEN` 을 요청하면 응답의 `orders[].status` 는 개별 주문에 따라 `PENDING`, `PARTIAL_FILLED`, `PENDING_CANCEL`, `PENDING_REPLACE` 중 하나로 내려옵니다.\n",
                        "schema": {
                            "type": "string",
                            "enum": ["OPEN", "CLOSED"]
                        },
                        "example": "OPEN"
                    },
                    {
                        "name": "symbol",
                        "in": "query",
                        "required": false,
                        "description": "종목 심볼. 지정 시 해당 종목의 주문만 조회.\nKRX: 6자리 숫자 (`005930`), US: 영문 티커 (`AAPL`).\n영문 대/소문자, 숫자, '.', '-' 만 허용한다.\n",
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9.\\-]+$"
                        },
                        "examples": {
                            "krStock": {
                                "summary": "국내주식 (삼성전자)",
                                "value": "005930"
                            },
                            "usStock": {
                                "summary": "해외주식 (Apple)",
                                "value": "AAPL"
                            }
                        }
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "required": false,
                        "description": "조회 시작일 (inclusive, KST 기준). 주문 생성 시간(`orderedAt`) 기준. 미지정 시 전체 기간.\n`status=CLOSED` 는 미지원이므로 현재 효과가 없습니다.\n",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        },
                        "example": "2026-03-01"
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "required": false,
                        "description": "조회 종료일 (inclusive, KST 기준). 주문 생성 시간(`orderedAt`) 기준. 미지정 시 전체 기간.\n`status=CLOSED` 는 미지원이므로 현재 효과가 없습니다.\n",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        },
                        "example": "2026-03-31"
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "required": false,
                        "description": "페이지네이션 커서. `OPEN` 에서는 무시되며, `CLOSED` 는 미지원이므로 현재 효과가 없습니다.\n",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "required": false,
                        "description": "페이지 크기. `OPEN` 에서는 무시됩니다 (전량 반환).\n`CLOSED` 는 미지원이므로 현재 효과가 없습니다.\n",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 20
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "$ref": "#/components/schemas/PaginatedOrderResponse"
                                                }
                                            }
                                        }
                                    ]
                                },
                                "examples": {
                                    "pendingMixed": {
                                        "summary": "대기중 주문 — 국내+해외 혼합 (전량 반환)",
                                        "value": {
                                            "result": {
                                                "orders": [
                                                    {
                                                        "orderId": "bAGzNvMOOTa5Uy0xVzYNbxDJ3Qpobwau4jDF3hyZZGWbpHm7wha8CFZc7aXVOWAl",
                                                        "symbol": "005930",
                                                        "side": "BUY",
                                                        "orderType": "LIMIT",
                                                        "timeInForce": "DAY",
                                                        "status": "PENDING",
                                                        "price": "70000",
                                                        "quantity": "10",
                                                        "orderAmount": null,
                                                        "currency": "KRW",
                                                        "orderedAt": "2026-03-29T09:30:00+09:00",
                                                        "canceledAt": null,
                                                        "execution": {
                                                            "filledQuantity": "0",
                                                            "averageFilledPrice": null,
                                                            "filledAmount": null,
                                                            "commission": null,
                                                            "tax": null,
                                                            "filledAt": null,
                                                            "settlementDate": null
                                                        }
                                                    },
                                                    {
                                                        "orderId": "RpP3_wtsiKe9btBvdendaHoBqOIY_Zb_xPkRfYaqCIvf2FXtMDv_mo7VnD7KB-ia",
                                                        "symbol": "AAPL",
                                                        "side": "SELL",
                                                        "orderType": "LIMIT",
                                                        "timeInForce": "DAY",
                                                        "status": "PARTIAL_FILLED",
                                                        "price": "185.5",
                                                        "quantity": "5",
                                                        "orderAmount": null,
                                                        "currency": "USD",
                                                        "orderedAt": "2026-03-29T10:00:00+09:00",
                                                        "canceledAt": null,
                                                        "execution": {
                                                            "filledQuantity": "2",
                                                            "averageFilledPrice": "185.25",
                                                            "filledAmount": "370.5",
                                                            "commission": "0.66",
                                                            "tax": "0",
                                                            "filledAt": "2026-03-29T10:00:05+09:00",
                                                            "settlementDate": null
                                                        }
                                                    }
                                                ],
                                                "nextCursor": null,
                                                "hasNext": false
                                            }
                                        }
                                    },
                                    "completedWithNextPage": {
                                        "summary": "완료된 주문 — 다음 페이지 있음",
                                        "value": {
                                            "result": {
                                                "orders": [
                                                    {
                                                        "orderId": "0d5QIHjmtksbsmM-hBRAgP-ExI8iodGm9fAR5txelPfnMM8XQ_swoJdwL5RpGWMo",
                                                        "symbol": "005930",
                                                        "side": "BUY",
                                                        "orderType": "LIMIT",
                                                        "timeInForce": "DAY",
                                                        "status": "FILLED",
                                                        "price": "70000",
                                                        "quantity": "10",
                                                        "orderAmount": null,
                                                        "currency": "KRW",
                                                        "orderedAt": "2026-03-28T09:30:00+09:00",
                                                        "canceledAt": null,
                                                        "execution": {
                                                            "filledQuantity": "10",
                                                            "averageFilledPrice": "70000",
                                                            "filledAmount": "700000",
                                                            "commission": "1400",
                                                            "tax": "0",
                                                            "filledAt": "2026-03-28T09:31:15+09:00",
                                                            "settlementDate": "2026-03-30"
                                                        }
                                                    }
                                                ],
                                                "nextCursor": "eyJvcmRlcmVkQXQiOiIyMDI2LTAzLTI4VDA5OjMwOjAwKzA5OjAwIiwib3JkZXJJZCI6Ik9SRDIwMjYwMzI4MDAxIn0=",
                                                "hasNext": true
                                            }
                                        }
                                    },
                                    "empty": {
                                        "summary": "주문 없음",
                                        "value": {
                                            "result": {
                                                "orders": [],
                                                "nextCursor": null,
                                                "hasNext": false
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "잘못된 요청",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "invalidStatus": {
                                        "summary": "유효하지 않은 주문 상태 필터",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "유효하지 않은 주문 상태 필터입니다. OPEN 또는 CLOSED 만 허용됩니다.",
                                                "data": {
                                                    "field": "status",
                                                    "allowedValues": ["OPEN", "CLOSED"]
                                                }
                                            }
                                        }
                                    },
                                    "closedNotSupported": {
                                        "summary": "CLOSED 상태 조회 미지원",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "closed-not-supported",
                                                "message": "CLOSED 상태 조회는 아직 지원되지 않습니다.",
                                                "data": {
                                                    "field": "status"
                                                }
                                            }
                                        }
                                    },
                                    "accountHeaderRequired": {
                                        "summary": "X-Tossinvest-Account 헤더 누락",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "account-header-required",
                                                "message": "x-tossinvest-account 헤더가 필요합니다."
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalErrorOrderHistory"
                    }
                }
            },
            "post": {
                "tags": ["Order"],
                "summary": "주문 생성",
                "description": "매수 또는 매도 주문을 생성합니다.\n\n**수량 지정 방식** — `quantity`, `orderAmount` 중 정확히 하나를 사용:\n- `quantity`: 주문 수량 (주 단위). 지정한 수량만큼 주문\n- `orderAmount`: 주문 금액 (달러). 지정한 금액만큼 주문하며, 체결 수량은 시장가에 따라 결정. US MARKET 전용\n\n**금액 주문 (`orderAmount`)**: 정규장 시간에만 가능합니다. 정규장 외 시간에 호출 시 `422 amount-order-outside-regular-hours` 를 반환합니다.\n\n**Rate Limits Group**: `ORDER`\n",
                "operationId": "createOrder",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/AccountSeq"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/OrderCreateRequest"
                            },
                            "examples": {
                                "krLimitBuy": {
                                    "summary": "국내주식 지정가 매수",
                                    "value": {
                                        "clientOrderId": "my-order-001",
                                        "symbol": "005930",
                                        "side": "BUY",
                                        "orderType": "LIMIT",
                                        "quantity": "10",
                                        "price": "70000"
                                    }
                                },
                                "usMarketBuyAmount": {
                                    "summary": "해외주식 소수점 시장가 매수 (금액)",
                                    "value": {
                                        "symbol": "AAPL",
                                        "side": "BUY",
                                        "orderType": "MARKET",
                                        "orderAmount": "100.5"
                                    }
                                },
                                "usLocBuy": {
                                    "summary": "해외주식 종가 지정가 매수 (LOC = LIMIT + CLS)",
                                    "value": {
                                        "symbol": "AAPL",
                                        "side": "BUY",
                                        "orderType": "LIMIT",
                                        "timeInForce": "CLS",
                                        "quantity": "10",
                                        "price": "185.5"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "$ref": "#/components/schemas/OrderResponse"
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "result": {
                                        "orderId": "0d5QIHjmtksbsmM-hBRAgP-ExI8iodGm9fAR5txelPfnMM8XQ_swoJdwL5RpGWMo",
                                        "clientOrderId": "my-order-001"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "잘못된 요청",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "invalidOrderType": {
                                        "summary": "지원하지 않는 호가 유형",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "호가 유형이 올바르지 않습니다.",
                                                "data": {
                                                    "field": "orderType",
                                                    "allowedValues": ["LIMIT", "MARKET"]
                                                }
                                            }
                                        }
                                    },
                                    "invalidTimeInForce": {
                                        "summary": "지원하지 않는 유효 조건",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "주문 유효 조건이 올바르지 않습니다.",
                                                "data": {
                                                    "field": "timeInForce",
                                                    "allowedValues": ["DAY", "CLS"]
                                                }
                                            }
                                        }
                                    },
                                    "clsConditionNotMet": {
                                        "summary": "종가(CLS) 주문 조건 불충족",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "종가 주문(CLS)은 미국 주식 지정가 주문에만 사용할 수 있습니다.",
                                                "data": {
                                                    "field": "timeInForce",
                                                    "allowedConditions": {
                                                        "marketCountry": "US",
                                                        "orderType": "LIMIT"
                                                    }
                                                }
                                            }
                                        }
                                    },
                                    "invalidSide": {
                                        "summary": "잘못된 주문 방향",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "주문 방향이 올바르지 않습니다.",
                                                "data": {
                                                    "field": "side",
                                                    "allowedValues": ["BUY", "SELL"]
                                                }
                                            }
                                        }
                                    },
                                    "quantityOrAmountRequired": {
                                        "summary": "수량 또는 금액 미지정",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "주문 수량 또는 금액 중 하나를 지정해야 합니다.",
                                                "data": {
                                                    "field": "quantity,orderAmount"
                                                }
                                            }
                                        }
                                    },
                                    "limitPriceRequired": {
                                        "summary": "지정가 주문 가격 미지정",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "지정가 주문 시 가격을 지정해야 합니다.",
                                                "data": {
                                                    "field": "price"
                                                }
                                            }
                                        }
                                    },
                                    "invalidTickSize": {
                                        "summary": "호가 단위 불일치",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "주문 가격이 호가 단위에 맞지 않습니다.",
                                                "data": {
                                                    "field": "price",
                                                    "tickSize": "100",
                                                    "nearestPrices": ["50100", "50200"]
                                                }
                                            }
                                        }
                                    },
                                    "confirmHighValueRequired": {
                                        "summary": "1억원 이상 주문 확인 필요",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "confirm-high-value-required",
                                                "message": "1억원 이상 주문은 확인이 필요합니다.",
                                                "data": {
                                                    "field": "confirmHighValueOrder",
                                                    "limits": {
                                                        "threshold": "100000000",
                                                        "currency": "KRW"
                                                    }
                                                }
                                            }
                                        }
                                    },
                                    "amountUsMarketOnly": {
                                        "summary": "금액 주문 조건 불충족",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "금액 주문은 미국 주식 시장가 주문에만 사용할 수 있습니다.",
                                                "data": {
                                                    "field": "orderAmount",
                                                    "allowedConditions": {
                                                        "marketCountry": "US",
                                                        "orderType": "MARKET"
                                                    }
                                                }
                                            }
                                        }
                                    },
                                    "invalidQuantityFormat": {
                                        "summary": "주문 수량 형식 오류",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "주문 수량이 유효한 숫자가 아닙니다.",
                                                "data": {
                                                    "field": "quantity",
                                                    "format": "decimal",
                                                    "pattern": "^-?\\d+(\\.\\d+)?$",
                                                    "maxLength": 30
                                                }
                                            }
                                        }
                                    },
                                    "fractionalQuantityUsMarketOnly": {
                                        "summary": "소수점 수량은 US 시장가에만 허용",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "소수점 수량 주문은 미국 주식 시장가 주문에만 사용할 수 있습니다.",
                                                "data": {
                                                    "field": "quantity",
                                                    "allowedConditions": {
                                                        "marketCountry": "US",
                                                        "orderType": "MARKET"
                                                    }
                                                }
                                            }
                                        }
                                    },
                                    "accountHeaderRequired": {
                                        "summary": "X-Tossinvest-Account 헤더 누락",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "account-header-required",
                                                "message": "x-tossinvest-account 헤더가 필요합니다."
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "409": {
                        "description": "중복 요청",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "requestInProgress": {
                                        "summary": "동일 주문 키에 대해 처리 중인 요청 있음",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "request-in-progress",
                                                "message": "동일 주문 키에 대해 처리 중인 요청이 있습니다. 잠시 후 다시 시도해 주세요."
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "비즈니스 규칙 위반",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "insufficientBuyingPower": {
                                        "summary": "주문 가능 금액 부족",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "insufficient-buying-power",
                                                "message": "주문 가능 금액이 부족합니다."
                                            }
                                        }
                                    },
                                    "outsideOrderHours": {
                                        "summary": "주문 접수 불가 시간",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "order-hours-closed",
                                                "message": "현재 해당 주문을 접수할 수 없는 시간입니다.",
                                                "data": {
                                                    "retryAfterAt": "2026-01-02T09:00:00+09:00"
                                                }
                                            }
                                        }
                                    },
                                    "stockRestricted": {
                                        "summary": "종목 주문 제한",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "stock-restricted",
                                                "message": "해당 종목은 현재 주문이 제한되어 있습니다."
                                            }
                                        }
                                    },
                                    "priceOutOfRange": {
                                        "summary": "주문 가격 허용 범위 초과",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "price-out-of-range",
                                                "message": "주문 가격이 허용 범위를 벗어났습니다."
                                            }
                                        }
                                    },
                                    "oppositePendingOrderExists": {
                                        "summary": "반대 방향 미체결 주문 존재",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "opposite-pending-order-exists",
                                                "message": "동일 종목에 반대 방향의 체결 대기 주문이 있습니다."
                                            }
                                        }
                                    },
                                    "orderTypeNotAllowed": {
                                        "summary": "현재 사용 불가 호가 유형",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "order-type-not-allowed",
                                                "message": "현재 사용할 수 없는 호가 유형입니다."
                                            }
                                        }
                                    },
                                    "prerequisiteRequired": {
                                        "summary": "사전 자격 요건 미충족 (약관 동의/교육 이수/위험고지 등록)",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "prerequisite-required",
                                                "message": "주문 전 필요한 사전 자격 요건이 충족되지 않았습니다."
                                            }
                                        }
                                    },
                                    "marketNotSupportedForStock": {
                                        "summary": "종목-마켓 조합 거래 불가 (KR)",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "market-not-supported-for-stock",
                                                "message": "해당 종목은 이 시장에서 거래할 수 없습니다."
                                            }
                                        }
                                    },
                                    "investorExchangeNotIntegrated": {
                                        "summary": "투자자지시 거래소가 통합(SOR)이 아님 (KR)",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "investor-exchange-not-integrated",
                                                "message": "투자자지시 거래소가 통합(SOR) 으로 설정되어 있어야 주문할 수 있습니다."
                                            }
                                        }
                                    },
                                    "amountOrderOutsideRegularHours": {
                                        "summary": "정규장 외 시간 금액 주문 불가",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "amount-order-outside-regular-hours",
                                                "message": "미국 주식 금액 주문은 정규장 시간에만 접수할 수 있습니다.",
                                                "data": {
                                                    "field": "orderAmount",
                                                    "regularHours": {
                                                        "start": "2026-03-30T09:30:00-04:00",
                                                        "end": "2026-03-30T16:00:00-04:00"
                                                    }
                                                }
                                            }
                                        }
                                    },
                                    "accountRestricted": {
                                        "summary": "계좌 거래 제한 (사고 계좌, 거래 정지 등)",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "account-restricted",
                                                "message": "계좌 상태가 주문을 허용하지 않습니다."
                                            }
                                        }
                                    },
                                    "maxOrderAmountExceeded": {
                                        "summary": "30억원 초과 주문 (KR)",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "max-order-amount-exceeded",
                                                "message": "최대 주문가능금액을 초과하였습니다.",
                                                "data": {
                                                    "limits": {
                                                        "maxAmount": "3000000000",
                                                        "currency": "KRW"
                                                    }
                                                }
                                            }
                                        }
                                    },
                                    "idempotencyKeyConflict": {
                                        "summary": "동일 clientOrderId 로 이전과 다른 본문 재요청 (멱등성 키 충돌)",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "idempotency-key-conflict",
                                                "message": "동일한 clientOrderId 로 다른 내용의 주문을 요청할 수 없습니다."
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "description": "주문 처리 중 일시적 오류 또는 시스템 점검",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "internalError": {
                                        "summary": "주문 처리 중 일시적 오류",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "internal-error",
                                                "message": "처리 중 문제가 생겼어요. 잠시 후 다시 시도해주세요."
                                            }
                                        }
                                    },
                                    "maintenance": {
                                        "summary": "점검 중",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "maintenance",
                                                "message": "점검 중입니다. 잠시 후 다시 시도해 주세요.",
                                                "data": {
                                                    "retryAfterSeconds": 600
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/orders/{orderId}": {
            "get": {
                "tags": ["Order History"],
                "summary": "주문 상세 조회",
                "description": "특정 주문의 상세 정보를 조회합니다.\n모든 주문 상태(체결 완료, 취소, 거부 등)의 주문을 조회할 수 있습니다.\n\n**Rate Limits Group**: `ORDER_HISTORY`\n",
                "operationId": "getOrder",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/AccountSeq"
                    },
                    {
                        "$ref": "#/components/parameters/OrderId"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "$ref": "#/components/schemas/Order"
                                                }
                                            }
                                        }
                                    ]
                                },
                                "examples": {
                                    "krLimitFilled": {
                                        "summary": "국내주식 지정가 매수 — 체결 완료",
                                        "value": {
                                            "result": {
                                                "orderId": "0d5QIHjmtksbsmM-hBRAgP-ExI8iodGm9fAR5txelPfnMM8XQ_swoJdwL5RpGWMo",
                                                "symbol": "005930",
                                                "side": "BUY",
                                                "orderType": "LIMIT",
                                                "timeInForce": "DAY",
                                                "status": "FILLED",
                                                "price": "70000",
                                                "quantity": "10",
                                                "orderAmount": null,
                                                "currency": "KRW",
                                                "orderedAt": "2026-03-28T09:30:00+09:00",
                                                "canceledAt": null,
                                                "execution": {
                                                    "filledQuantity": "10",
                                                    "averageFilledPrice": "70000",
                                                    "filledAmount": "700000",
                                                    "commission": "1400",
                                                    "tax": "0",
                                                    "filledAt": "2026-03-28T09:31:15+09:00",
                                                    "settlementDate": "2026-03-30"
                                                }
                                            }
                                        }
                                    },
                                    "usMarketPartialFilled": {
                                        "summary": "해외주식 시장가 매수 — 부분 체결",
                                        "value": {
                                            "result": {
                                                "orderId": "J4lDkgVA-pMiRPOqXd2nBjxTj8hsTVhzOhIth7i1Izq14XYxIg1r_QTDEH7RTL8d",
                                                "symbol": "AAPL",
                                                "side": "BUY",
                                                "orderType": "MARKET",
                                                "timeInForce": "DAY",
                                                "status": "PARTIAL_FILLED",
                                                "price": null,
                                                "quantity": "5",
                                                "orderAmount": null,
                                                "currency": "USD",
                                                "orderedAt": "2026-03-28T23:30:00+09:00",
                                                "canceledAt": null,
                                                "execution": {
                                                    "filledQuantity": "3",
                                                    "averageFilledPrice": "185.25",
                                                    "filledAmount": "555.75",
                                                    "commission": "0.99",
                                                    "tax": "0",
                                                    "filledAt": "2026-03-28T23:30:05+09:00",
                                                    "settlementDate": null
                                                }
                                            }
                                        }
                                    },
                                    "rejected": {
                                        "summary": "주문 거부",
                                        "value": {
                                            "result": {
                                                "orderId": "Oqqsu76YSdwKZsdKbPwy-D7buUwy-RH2xZYbYSzAyAnlPy48Al5Lb7FyMKwibw4i",
                                                "symbol": "AAPL",
                                                "side": "BUY",
                                                "orderType": "MARKET",
                                                "timeInForce": "DAY",
                                                "status": "REJECTED",
                                                "price": null,
                                                "quantity": "0.5",
                                                "orderAmount": null,
                                                "currency": "USD",
                                                "orderedAt": "2026-03-28T23:30:00+09:00",
                                                "canceledAt": null,
                                                "execution": {
                                                    "filledQuantity": "0",
                                                    "averageFilledPrice": null,
                                                    "filledAmount": null,
                                                    "commission": null,
                                                    "tax": null,
                                                    "filledAt": null,
                                                    "settlementDate": null
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/AccountHeaderRequired"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "404": {
                        "$ref": "#/components/responses/OrderNotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalErrorOrderHistory"
                    }
                }
            }
        },
        "/api/v1/orders/{orderId}/modify": {
            "post": {
                "tags": ["Order"],
                "summary": "주문 정정",
                "description": "기존 주문의 가격 또는 수량을 정정합니다.\n\n**KR 주식:** `quantity` 필수. 양의 정수만 허용합니다.\n\n**US 주식:** `quantity` 제공 불가. 가격 변경만 지원합니다. `quantity` 제공 시 `400 us-modify-quantity-not-supported` 에러를 반환합니다.\n\n**Rate Limits Group**: `ORDER`\n",
                "operationId": "modifyOrder",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/AccountSeq"
                    },
                    {
                        "$ref": "#/components/parameters/OrderId"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/OrderModifyRequest"
                            },
                            "examples": {
                                "krModify": {
                                    "summary": "국내주식 가격+수량 정정",
                                    "value": {
                                        "orderType": "LIMIT",
                                        "quantity": "15",
                                        "price": "71000"
                                    }
                                },
                                "usModify": {
                                    "summary": "해외주식 가격 정정",
                                    "value": {
                                        "orderType": "LIMIT",
                                        "price": "185.5"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "$ref": "#/components/schemas/OrderOperationResponse"
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "result": {
                                        "orderId": "5nfzdqmzfnAw3LFXWHPRy0UNi7y_WZlphJh5hRIsi25-NIfm_GtQgXima5QD2hUz"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "잘못된 요청",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "invalidPrice": {
                                        "summary": "지정가 주문 가격 미지정",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "지정가 주문에는 가격이 필요합니다.",
                                                "data": {
                                                    "field": "price"
                                                }
                                            }
                                        }
                                    },
                                    "invalidQuantityKr": {
                                        "summary": "국내주식 주문 수량 오류",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "주문 수량이 유효하지 않습니다.",
                                                "data": {
                                                    "field": "quantity",
                                                    "constraint": {
                                                        "min": 1,
                                                        "integerOnly": true
                                                    }
                                                }
                                            }
                                        }
                                    },
                                    "invalidTickSize": {
                                        "summary": "호가 단위 불일치",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "주문 가격이 호가 단위에 맞지 않습니다.",
                                                "data": {
                                                    "field": "price",
                                                    "tickSize": "100",
                                                    "nearestPrices": ["50100", "50200"]
                                                }
                                            }
                                        }
                                    },
                                    "invalidParameter": {
                                        "summary": "주문 파라미터 오류",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "요청이 올바르지 않습니다."
                                            }
                                        }
                                    },
                                    "usModifyQuantityNotSupported": {
                                        "summary": "미국 주식 주문 정정은 가격만 지원",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "us-modify-quantity-not-supported",
                                                "message": "미국 주식 주문 정정은 가격만 지원합니다.",
                                                "data": {
                                                    "field": "quantity"
                                                }
                                            }
                                        }
                                    },
                                    "confirmHighValueRequired": {
                                        "summary": "정정 후 1억원 이상 주문 확인 필요",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "confirm-high-value-required",
                                                "message": "1억원 이상 주문은 확인이 필요합니다.",
                                                "data": {
                                                    "field": "confirmHighValueOrder",
                                                    "limits": {
                                                        "threshold": "100000000",
                                                        "currency": "KRW"
                                                    }
                                                }
                                            }
                                        }
                                    },
                                    "accountHeaderRequired": {
                                        "summary": "X-Tossinvest-Account 헤더 누락",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "account-header-required",
                                                "message": "x-tossinvest-account 헤더가 필요합니다."
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "404": {
                        "description": "주문 또는 계좌 없음",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "orderNotFound": {
                                        "summary": "주문을 찾을 수 없음",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "order-not-found",
                                                "message": "주문을 찾을 수 없습니다."
                                            }
                                        }
                                    },
                                    "accountNotFound": {
                                        "summary": "계좌 부재",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "account-not-found",
                                                "message": "계좌를 찾을 수 없습니다."
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "정정 불가 상태",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "alreadyFilled": {
                                        "summary": "이미 체결된 주문",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "already-filled",
                                                "message": "이미 체결된 주문입니다."
                                            }
                                        }
                                    },
                                    "alreadyCanceled": {
                                        "summary": "이미 취소된 주문",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "already-canceled",
                                                "message": "이미 취소된 주문입니다."
                                            }
                                        }
                                    },
                                    "alreadyModified": {
                                        "summary": "이미 정정된 주문",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "already-modified",
                                                "message": "이미 정정된 주문입니다."
                                            }
                                        }
                                    },
                                    "rejectedOrder": {
                                        "summary": "거부된 주문 정정 시도",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "already-rejected",
                                                "message": "거부된 주문은 정정/취소할 수 없습니다."
                                            }
                                        }
                                    },
                                    "alreadyProcessing": {
                                        "summary": "주문 처리 중",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "already-processing",
                                                "message": "주문이 처리 중입니다. 잠시 후 다시 시도해 주세요.",
                                                "data": {
                                                    "retryAfterSeconds": 1
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "비즈니스 규칙 위반",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "modifyRestricted": {
                                        "summary": "정정 불가 주문",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "modify-restricted",
                                                "message": "해당 주문은 정정할 수 없습니다."
                                            }
                                        }
                                    },
                                    "outsideOrderHours": {
                                        "summary": "주문 접수 불가 시간",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "order-hours-closed",
                                                "message": "현재 해당 주문을 접수할 수 없는 시간입니다.",
                                                "data": {
                                                    "retryAfterAt": "2026-01-02T09:00:00+09:00"
                                                }
                                            }
                                        }
                                    },
                                    "investorExchangeNotIntegrated": {
                                        "summary": "투자자지시 거래소가 통합(SOR)이 아님 (KR)",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "investor-exchange-not-integrated",
                                                "message": "투자자지시 거래소가 통합(SOR) 으로 설정되어 있어야 주문할 수 있습니다."
                                            }
                                        }
                                    },
                                    "prerequisiteRequired": {
                                        "summary": "사전 자격 요건 미충족 (약관 동의/교육 이수/위험고지 등록)",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "prerequisite-required",
                                                "message": "주문 전 필요한 사전 자격 요건이 충족되지 않았습니다."
                                            }
                                        }
                                    },
                                    "amountOrderOutsideRegularHours": {
                                        "summary": "정규장 외 시간 금액 주문 정정 불가",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "amount-order-outside-regular-hours",
                                                "message": "미국 주식 금액 주문은 정규장 시간에만 접수할 수 있습니다.",
                                                "data": {
                                                    "field": "orderAmount",
                                                    "regularHours": {
                                                        "start": "2026-03-30T09:30:00-04:00",
                                                        "end": "2026-03-30T16:00:00-04:00"
                                                    }
                                                }
                                            }
                                        }
                                    },
                                    "accountRestricted": {
                                        "summary": "계좌 정정 제한 (사고 계좌 등)",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "account-restricted",
                                                "message": "계좌 상태가 주문을 허용하지 않습니다."
                                            }
                                        }
                                    },
                                    "maxOrderAmountExceeded": {
                                        "summary": "30억원 초과 정정 (KR)",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "max-order-amount-exceeded",
                                                "message": "최대 주문가능금액을 초과하였습니다.",
                                                "data": {
                                                    "limits": {
                                                        "maxAmount": "3000000000",
                                                        "currency": "KRW"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalErrorOrder"
                    }
                }
            }
        },
        "/api/v1/orders/{orderId}/cancel": {
            "post": {
                "tags": ["Order"],
                "summary": "주문 취소",
                "description": "기존 주문을 취소합니다. 이미 체결된 주문은 취소할 수 없습니다.\n\n**Rate Limits Group**: `ORDER`\n",
                "operationId": "cancelOrder",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/AccountSeq"
                    },
                    {
                        "$ref": "#/components/parameters/OrderId"
                    }
                ],
                "requestBody": {
                    "required": false,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object"
                            },
                            "example": {}
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "$ref": "#/components/schemas/OrderOperationResponse"
                                                }
                                            }
                                        }
                                    ]
                                },
                                "example": {
                                    "result": {
                                        "orderId": "Kx9mTqR2vLwE7oPn3YhBjCf1dAsU6gZi8rNk4bWcXeJtMlSyDuQaHp5oVzI0FvRw"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/AccountHeaderRequired"
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "404": {
                        "$ref": "#/components/responses/OrderNotFound"
                    },
                    "409": {
                        "description": "취소 불가 상태",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "alreadyFilled": {
                                        "summary": "이미 체결된 주문",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "already-filled",
                                                "message": "이미 체결된 주문입니다."
                                            }
                                        }
                                    },
                                    "alreadyCanceled": {
                                        "summary": "이미 취소된 주문",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "already-canceled",
                                                "message": "이미 취소된 주문입니다."
                                            }
                                        }
                                    },
                                    "alreadyModified": {
                                        "summary": "이미 정정된 주문",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "already-modified",
                                                "message": "이미 정정된 주문입니다."
                                            }
                                        }
                                    },
                                    "rejectedOrder": {
                                        "summary": "거부된 주문 취소 시도",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "already-rejected",
                                                "message": "거부된 주문은 정정/취소할 수 없습니다."
                                            }
                                        }
                                    },
                                    "alreadyProcessing": {
                                        "summary": "주문 처리 중",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "already-processing",
                                                "message": "주문이 처리 중입니다. 잠시 후 다시 시도해 주세요.",
                                                "data": {
                                                    "retryAfterSeconds": 1
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "비즈니스 규칙 위반",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "cancelRestricted": {
                                        "summary": "취소 불가 주문",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "cancel-restricted",
                                                "message": "해당 주문은 취소할 수 없습니다."
                                            }
                                        }
                                    },
                                    "outsideOrderHours": {
                                        "summary": "취소 접수 불가 시간",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "order-hours-closed",
                                                "message": "현재 해당 주문을 접수할 수 없는 시간입니다."
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalErrorOrder"
                    }
                }
            }
        },
        "/api/v1/buying-power": {
            "get": {
                "tags": ["Order Info"],
                "summary": "매수 가능 금액 조회",
                "description": "매수 주문 시 사용할 수 있는 매수 가능 금액을 조회합니다.\n미수거래를 제외한 현금 기반 매수 가능 금액(미수 미발생 기준)을 반환합니다.\n\n**Rate Limits Group**: `ORDER_INFO`\n",
                "operationId": "getBuyingPower",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/AccountSeq"
                    },
                    {
                        "name": "currency",
                        "in": "query",
                        "required": true,
                        "description": "통화 코드",
                        "schema": {
                            "$ref": "#/components/schemas/Currency"
                        },
                        "examples": {
                            "krw": {
                                "summary": "원화",
                                "value": "KRW"
                            },
                            "usd": {
                                "summary": "달러",
                                "value": "USD"
                            }
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "$ref": "#/components/schemas/BuyingPowerResponse"
                                                }
                                            }
                                        }
                                    ]
                                },
                                "examples": {
                                    "krw": {
                                        "summary": "원화 응답",
                                        "value": {
                                            "result": {
                                                "currency": "KRW",
                                                "cashBuyingPower": "5000000"
                                            }
                                        }
                                    },
                                    "usd": {
                                        "summary": "달러 응답",
                                        "value": {
                                            "result": {
                                                "currency": "USD",
                                                "cashBuyingPower": "3500.5"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "잘못된 요청",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "unsupportedCurrency": {
                                        "summary": "지원하지 않는 통화",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "invalid-request",
                                                "message": "지원하지 않는 통화입니다.",
                                                "data": {
                                                    "field": "currency",
                                                    "allowedValues": ["KRW", "USD"]
                                                }
                                            }
                                        }
                                    },
                                    "accountHeaderRequired": {
                                        "summary": "X-Tossinvest-Account 헤더 누락",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "account-header-required",
                                                "message": "x-tossinvest-account 헤더가 필요합니다."
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "404": {
                        "description": "계좌 없음",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "accountNotFound": {
                                        "summary": "계좌 부재",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "account-not-found",
                                                "message": "계좌를 찾을 수 없습니다."
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalErrorOrderInfo"
                    }
                }
            }
        },
        "/api/v1/sellable-quantity": {
            "get": {
                "tags": ["Order Info"],
                "summary": "판매 가능 수량 조회",
                "description": "특정 종목의 판매 가능 수량을 조회합니다.\n\n**Rate Limits Group**: `ORDER_INFO`\n",
                "operationId": "getSellableQuantity",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/AccountSeq"
                    },
                    {
                        "$ref": "#/components/parameters/SymbolQuery"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "$ref": "#/components/schemas/SellableQuantityResponse"
                                                }
                                            }
                                        }
                                    ]
                                },
                                "examples": {
                                    "kr": {
                                        "summary": "국내주식 응답",
                                        "value": {
                                            "result": {
                                                "sellableQuantity": "100"
                                            }
                                        }
                                    },
                                    "us": {
                                        "summary": "해외주식 응답",
                                        "value": {
                                            "result": {
                                                "sellableQuantity": "5.5"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "잘못된 요청",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "accountNotFound": {
                                        "summary": "조회 가능한 계좌가 없음",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "account-not-found",
                                                "message": "계좌를 찾을 수 없습니다."
                                            }
                                        }
                                    },
                                    "accountHeaderRequired": {
                                        "summary": "X-Tossinvest-Account 헤더 누락",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "account-header-required",
                                                "message": "x-tossinvest-account 헤더가 필요합니다."
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalErrorOrderInfo"
                    }
                }
            }
        },
        "/api/v1/commissions": {
            "get": {
                "tags": ["Order Info"],
                "summary": "매매 수수료 조회",
                "description": "현재 계좌의 시장별 매매 수수료율을 조회합니다.\n국내주식과 해외주식의 수수료 정보를 배열로 반환합니다.\n\n**Rate Limits Group**: `ORDER_INFO`\n",
                "operationId": "getCommissions",
                "security": [
                    {
                        "oauth2ClientCredentials": []
                    }
                ],
                "parameters": [
                    {
                        "$ref": "#/components/parameters/AccountSeq"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "성공",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "allOf": [
                                        {
                                            "$ref": "#/components/schemas/ApiResponse"
                                        },
                                        {
                                            "type": "object",
                                            "properties": {
                                                "result": {
                                                    "type": "array",
                                                    "items": {
                                                        "$ref": "#/components/schemas/Commission"
                                                    }
                                                }
                                            }
                                        }
                                    ]
                                },
                                "examples": {
                                    "standard": {
                                        "summary": "국내 + 해외 수수료",
                                        "value": {
                                            "result": [
                                                {
                                                    "marketCountry": "KR",
                                                    "commissionRate": "0.015",
                                                    "startDate": "2026-01-01",
                                                    "endDate": "2026-12-31"
                                                },
                                                {
                                                    "marketCountry": "US",
                                                    "commissionRate": "0.1",
                                                    "startDate": null,
                                                    "endDate": "2026-06-30"
                                                }
                                            ]
                                        }
                                    },
                                    "unlimited": {
                                        "summary": "무기한 수수료",
                                        "value": {
                                            "result": [
                                                {
                                                    "marketCountry": "KR",
                                                    "commissionRate": "0.015",
                                                    "startDate": "2026-01-01",
                                                    "endDate": null
                                                },
                                                {
                                                    "marketCountry": "US",
                                                    "commissionRate": "0.25",
                                                    "startDate": null,
                                                    "endDate": null
                                                }
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "잘못된 요청",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                },
                                "examples": {
                                    "accountNotFound": {
                                        "summary": "조회 가능한 계좌가 없음",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "account-not-found",
                                                "message": "계좌를 찾을 수 없습니다."
                                            }
                                        }
                                    },
                                    "accountHeaderRequired": {
                                        "summary": "X-Tossinvest-Account 헤더 누락",
                                        "value": {
                                            "error": {
                                                "requestId": "01HXYZABCDEFG123456789",
                                                "code": "account-header-required",
                                                "message": "x-tossinvest-account 헤더가 필요합니다."
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/Unauthorized"
                    },
                    "429": {
                        "$ref": "#/components/responses/RateLimitExceeded"
                    },
                    "500": {
                        "$ref": "#/components/responses/InternalErrorOrderInfo"
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "oauth2ClientCredentials": {
                "type": "oauth2",
                "description": "OAuth 2.0 Client Credentials Grant. `POST /oauth2/token` 으로 발급받은 access token 을\n모든 요청의 `Authorization: Bearer {access_token}` 헤더로 전달합니다.\n",
                "flows": {
                    "clientCredentials": {
                        "tokenUrl": "/oauth2/token",
                        "scopes": {}
                    }
                }
            }
        },
        "headers": {
            "XRequestId": {
                "description": "요청 식별자. 모든 응답(성공·실패) 에 포함되며, 본문 `error.requestId` 와 동일한 값입니다.\nCS 문의 시 첨부를 권장합니다.\n",
                "schema": {
                    "type": "string"
                },
                "example": "01HXYZABCDEFG123456789"
            },
            "WWWAuthenticate": {
                "description": "OAuth 2.0 Bearer 토큰 챌린지.\n401 응답에 포함됩니다. 메시지에 non-ASCII 문자가 포함되는 경우 `error_description` 파라미터는 생략됩니다.\n",
                "schema": {
                    "type": "string"
                },
                "example": "Bearer realm=\"openapi\", error=\"invalid_token\", error_description=\"Token has expired\""
            }
        },
        "parameters": {
            "Symbol": {
                "name": "symbol",
                "in": "path",
                "required": true,
                "description": "종목 심볼. KRX: 6자리 숫자 (예: 005930), US: 영문 티커 (예: AAPL). 영문 대/소문자, 숫자, '.', '-' 만 허용한다.",
                "schema": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9.\\-]+$"
                },
                "examples": {
                    "krx": {
                        "summary": "삼성전자",
                        "value": "005930"
                    },
                    "us": {
                        "summary": "Apple",
                        "value": "AAPL"
                    }
                }
            },
            "SymbolQuery": {
                "name": "symbol",
                "in": "query",
                "required": true,
                "description": "종목 심볼. KRX: 6자리 숫자 (예: 005930), US: 영문 티커 (예: AAPL). 영문 대/소문자, 숫자, '.', '-' 만 허용한다.",
                "schema": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9.\\-]+$"
                },
                "examples": {
                    "krx": {
                        "summary": "삼성전자",
                        "value": "005930"
                    },
                    "us": {
                        "summary": "Apple",
                        "value": "AAPL"
                    }
                }
            },
            "AccountSeq": {
                "name": "X-Tossinvest-Account",
                "in": "header",
                "required": true,
                "description": "API 요청 시 사용할 계좌의 accountSeq.\n`GET /api/v1/accounts` 응답의 `accountSeq` 값을 사용합니다.\n",
                "schema": {
                    "type": "integer",
                    "format": "int64"
                },
                "example": 1
            },
            "OrderId": {
                "name": "orderId",
                "in": "path",
                "required": true,
                "description": "주문 식별자.\n서버에서 발급한 opaque token 입니다.\n",
                "schema": {
                    "type": "string"
                },
                "example": "0d5QIHjmtksbsmM-hBRAgP-ExI8iodGm9fAR5txelPfnMM8XQ_swoJdwL5RpGWMo"
            }
        },
        "responses": {
            "Unauthorized": {
                "description": "인증 실패. `WWW-Authenticate: Bearer ...` 헤더가 함께 내려갑니다.\n",
                "headers": {
                    "WWW-Authenticate": {
                        "description": "OAuth 2.0 Bearer 토큰 챌린지. 메시지에 non-ASCII 문자가 포함되는 경우\n`error_description` 파라미터는 생략됩니다.\n",
                        "schema": {
                            "type": "string"
                        },
                        "example": "Bearer realm=\"openapi\", error=\"invalid_token\", error_description=\"Token has expired\""
                    }
                },
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        },
                        "examples": {
                            "invalidToken": {
                                "summary": "유효하지 않은 토큰",
                                "value": {
                                    "error": {
                                        "requestId": "01HXYZABCDEFG123456789",
                                        "code": "invalid-token",
                                        "message": "유효하지 않은 토큰입니다."
                                    }
                                }
                            },
                            "expiredToken": {
                                "summary": "만료된 토큰",
                                "value": {
                                    "error": {
                                        "requestId": "01HXYZABCDEFG123456789",
                                        "code": "expired-token",
                                        "message": "토큰이 만료되었습니다."
                                    }
                                }
                            },
                            "loginUserNotFound": {
                                "summary": "로그인 정보 없음",
                                "value": {
                                    "error": {
                                        "requestId": "01HXYZABCDEFG123456789",
                                        "code": "login-user-not-found",
                                        "message": "로그인 정보를 찾을 수 없습니다."
                                    }
                                }
                            }
                        }
                    }
                }
            },
            "Forbidden": {
                "description": "권한 부족",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        },
                        "example": {
                            "error": {
                                "requestId": "01HXYZABCDEFG123456789",
                                "code": "forbidden",
                                "message": "요청에 필요한 권한이 부족합니다."
                            }
                        }
                    }
                }
            },
            "NotFound": {
                "description": "종목을 찾을 수 없음",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        },
                        "example": {
                            "error": {
                                "requestId": "01HXYZABCDEFG123456789",
                                "code": "stock-not-found",
                                "message": "종목을 찾을 수 없습니다."
                            }
                        }
                    }
                }
            },
            "RateLimitExceeded": {
                "description": "요청 한도 초과. 포함 헤더의 의미는 아래 `headers` 정의를 참조합니다.",
                "headers": {
                    "X-RateLimit-Limit": {
                        "description": "현재 허용된 초당 요청 수 (burst capacity)",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 10
                    },
                    "X-RateLimit-Remaining": {
                        "description": "현재 버킷에 남은 토큰 수. 429 시 0.",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 0
                    },
                    "X-RateLimit-Reset": {
                        "description": "토큰 1 개가 재충전될 때까지 예상 초",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    },
                    "Retry-After": {
                        "description": "재시도 권장 초",
                        "schema": {
                            "type": "integer"
                        },
                        "example": 1
                    }
                },
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        },
                        "example": {
                            "error": {
                                "requestId": "01HXYZABCDEFG123456789",
                                "code": "rate-limit-exceeded",
                                "message": "요청 한도를 초과했습니다. 잠시 후 다시 시도해 주세요."
                            }
                        }
                    }
                }
            },
            "ServiceUnavailable": {
                "description": "서비스 일시 불가",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        },
                        "example": {
                            "error": {
                                "requestId": "01HXYZABCDEFG123456789",
                                "code": "internal-error",
                                "message": "처리 중 문제가 생겼어요. 잠시 후 다시 시도해주세요."
                            }
                        }
                    }
                }
            },
            "OrderNotFound": {
                "description": "주문을 찾을 수 없음",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        },
                        "example": {
                            "error": {
                                "requestId": "01HXYZABCDEFG123456789",
                                "code": "order-not-found",
                                "message": "주문을 찾을 수 없습니다."
                            }
                        }
                    }
                }
            },
            "OrderInfoAccountNotFound": {
                "description": "조회 가능한 계좌가 없음",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        },
                        "example": {
                            "error": {
                                "requestId": "01HXYZABCDEFG123456789",
                                "code": "account-not-found",
                                "message": "계좌를 찾을 수 없습니다."
                            }
                        }
                    }
                }
            },
            "InternalErrorMarketData": {
                "description": "시세 조회 중 일시적 오류",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        },
                        "example": {
                            "error": {
                                "requestId": "01HXYZABCDEFG123456789",
                                "code": "internal-error",
                                "message": "처리 중 문제가 생겼어요. 잠시 후 다시 시도해주세요."
                            }
                        }
                    }
                }
            },
            "InternalErrorMarketInfo": {
                "description": "시장 정보 조회 중 일시적 오류",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        },
                        "example": {
                            "error": {
                                "requestId": "01HXYZABCDEFG123456789",
                                "code": "internal-error",
                                "message": "처리 중 문제가 생겼어요. 잠시 후 다시 시도해주세요."
                            }
                        }
                    }
                }
            },
            "InternalErrorOrderInfo": {
                "description": "거래 가능 정보 조회 중 일시적 오류",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        },
                        "example": {
                            "error": {
                                "requestId": "01HXYZABCDEFG123456789",
                                "code": "internal-error",
                                "message": "처리 중 문제가 생겼어요. 잠시 후 다시 시도해주세요."
                            }
                        }
                    }
                }
            },
            "InternalErrorAsset": {
                "description": "보유 자산 조회 중 일시적 오류",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        },
                        "example": {
                            "error": {
                                "requestId": "01HXYZABCDEFG123456789",
                                "code": "internal-error",
                                "message": "처리 중 문제가 생겼어요. 잠시 후 다시 시도해주세요."
                            }
                        }
                    }
                }
            },
            "InternalErrorStock": {
                "description": "종목 심볼 조회 중 일시적 오류",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        },
                        "example": {
                            "error": {
                                "requestId": "01HXYZABCDEFG123456789",
                                "code": "internal-error",
                                "message": "처리 중 문제가 생겼어요. 잠시 후 다시 시도해주세요."
                            }
                        }
                    }
                }
            },
            "InternalErrorOrder": {
                "description": "주문 처리 중 일시적 오류",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        },
                        "example": {
                            "error": {
                                "requestId": "01HXYZABCDEFG123456789",
                                "code": "internal-error",
                                "message": "처리 중 문제가 생겼어요. 잠시 후 다시 시도해주세요."
                            }
                        }
                    }
                }
            },
            "InternalErrorOrderHistory": {
                "description": "주문 조회 중 일시적 오류",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        },
                        "example": {
                            "error": {
                                "requestId": "01HXYZABCDEFG123456789",
                                "code": "internal-error",
                                "message": "처리 중 문제가 생겼어요. 잠시 후 다시 시도해주세요."
                            }
                        }
                    }
                }
            },
            "AccountHeaderRequired": {
                "description": "X-Tossinvest-Account 헤더 누락",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/ErrorResponse"
                        },
                        "example": {
                            "error": {
                                "requestId": "01HXYZABCDEFG123456789",
                                "code": "account-header-required",
                                "message": "x-tossinvest-account 헤더가 필요합니다."
                            }
                        }
                    }
                }
            }
        },
        "schemas": {
            "ApiResponse": {
                "type": "object",
                "description": "성공 응답 envelope. 200 응답에 사용됩니다.\n각 엔드포인트의 성공 응답 스키마는 `allOf` 로 본 스키마를 상속하며 `result` 를 구체 타입으로 specialize 합니다.\n실패 응답은 별도의 `ErrorResponse` 스키마를 사용합니다 (4xx/5xx). `result` 와 `error` 는 동시에 나타나지 않습니다.\n",
                "required": ["result"],
                "properties": {
                    "result": {
                        "description": "성공 응답의 페이로드. 엔드포인트별 타입이 다르며, 각 엔드포인트 스펙에서 `allOf` 로 구체 타입을 명시합니다.\n"
                    }
                }
            },
            "ErrorResponse": {
                "type": "object",
                "description": "에러 응답 envelope. 4xx/5xx 응답에 사용됩니다. 성공 응답은 별도의 `ApiResponse` 스키마를 사용합니다.\n",
                "required": ["error"],
                "properties": {
                    "error": {
                        "$ref": "#/components/schemas/ApiError"
                    }
                }
            },
            "ApiError": {
                "type": "object",
                "description": "에러 객체. 에러 식별에 필요한 최소 정보(`requestId`, `code`, `message`)와\n필요 시 해결 힌트(`data`)를 포함합니다.\n",
                "required": ["requestId", "code", "message"],
                "properties": {
                    "requestId": {
                        "type": "string",
                        "description": "요청을 식별하는 고유 ID. 응답 헤더 `X-Request-Id` 와 동일한 값입니다.\n토스증권 CS 문의 시 첨부를 권장합니다.\n",
                        "example": "01HXYZABCDEFG123456789"
                    },
                    "code": {
                        "type": "string",
                        "description": "에러 코드. flat string 식별자.\n도메인 에러는 이유를 직접 표현하는 단일 식별자 (예: `invalid-request`, `order-not-found`) 를 사용합니다.\n클라이언트는 unknown code 를 허용하도록 구현해야 합니다.\n",
                        "example": "order-not-found"
                    },
                    "message": {
                        "type": "string",
                        "description": "사용자에게 노출 가능한 에러 메시지. 내부 정책상 노출이 제한되는 경우 빈 문자열로 내려갈 수 있으므로\n클라이언트는 `code` 기반으로 메시지를 자체 매핑할 것을 권장합니다.\n",
                        "example": "주문 방향이 올바르지 않습니다."
                    },
                    "data": {
                        "type": ["object", "null"],
                        "description": "에러 해결 힌트. 에러 코드별로 포함 여부와 키 구조가 다르며, 없는 경우 필드 자체가 생략됩니다.\n모든 표준 키가 항상 함께 내려가지 않으며, 각 에러 코드에 해당하는 서브셋만 포함됩니다.\n\n## 표준 키 (camelCase)\n\n| 키 | 타입 | 설명 |\n|---|---|---|\n| `field` | string | 검증 실패 원인 필드. 외부 API 에 노출된 이름 (request body JSON key 또는 query parameter name) 을 사용합니다. 복수 필드는 쉼표로 구분 (예: `\"quantity,orderAmount\"`). |\n| `allowedValues` | string[] | enum 후보 값 전체. |\n| `allowedConditions` | object | 조건부 허용 규칙 (`marketCountry` / `orderType` / `side` 등). |\n| `constraint` | object | 필드 제약 (`min` / `max` / `integerOnly` / `step`). |\n| `format` | string | 포맷 규칙명 (예: `decimal`). |\n| `pattern` | string | 정규식. |\n| `maxLength` | number | 문자열 길이 상한. |\n| `limits` | object | 금액 / 수량 한도 (`threshold` / `minimum` / `maximum` + `currency`). |\n| `retryAfterAt` | string | 절대 재시도 시각 (ISO 8601 offset, KST). |\n| `retryAfterSeconds` | number | 상대 재시도 시각 (초). |\n| `tickSize` | string | 호가 단위. |\n| `nearestPrices` | string[] | 근접 유효 가격 (`[lower, upper]`). |\n\n구체적인 에러 코드별 `data` 예시는 각 엔드포인트의 4xx / 5xx 응답 예시를 참고합니다.\n",
                        "additionalProperties": true
                    }
                }
            },
            "Currency": {
                "type": "string",
                "enum": ["KRW", "USD"],
                "description": "통화 코드.\n- KRW: 한국 원화\n- USD: 미국 달러\n\n클라이언트는 unknown enum 값을 허용하도록 구현해야 합니다.\n"
            },
            "MarketCountry": {
                "type": "string",
                "enum": ["KR", "US"],
                "description": "시장 국가 구분.\n- KR: 국내 주식 (KRX)\n- US: 미국 주식 (NYSE, NASDAQ 등)\n\n클라이언트는 unknown enum 값을 허용하도록 구현해야 합니다.\n"
            },
            "OAuth2TokenRequest": {
                "type": "object",
                "description": "OAuth2 Client Credentials Grant 토큰 발급 요청.\n`application/x-www-form-urlencoded` 으로 전송합니다.\n",
                "required": ["grant_type", "client_id", "client_secret"],
                "properties": {
                    "grant_type": {
                        "type": "string",
                        "enum": ["client_credentials"],
                        "description": "인증 방식. `client_credentials` 만 지원합니다."
                    },
                    "client_id": {
                        "type": "string",
                        "description": "발급받은 클라이언트 ID",
                        "example": "c_01HXYZABCDEFG123456789"
                    },
                    "client_secret": {
                        "type": "string",
                        "format": "password",
                        "description": "발급받은 클라이언트 시크릿. 노출되지 않도록 서버 측에서만 사용합니다."
                    }
                }
            },
            "OAuth2TokenResponse": {
                "type": "object",
                "description": "토큰 발급 성공 응답.\nBFF 의 공통 `ApiResponse` envelope 을 사용하지 않고 OAuth2 표준 형식으로 응답합니다.\n",
                "required": ["access_token", "token_type", "expires_in"],
                "properties": {
                    "access_token": {
                        "type": "string",
                        "description": "JWT 형식의 access token. 모든 API 요청의 `Authorization: Bearer` 헤더에 담습니다.",
                        "example": "eyJraWQiOiIyMDI2LTA0LTAxLWtleSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJjXzAxSFhZWiJ9..."
                    },
                    "token_type": {
                        "type": "string",
                        "enum": ["Bearer"],
                        "description": "토큰 타입. 항상 `Bearer`.",
                        "example": "Bearer"
                    },
                    "expires_in": {
                        "type": "integer",
                        "format": "int64",
                        "description": "토큰 만료까지 남은 초.",
                        "example": 86400
                    }
                }
            },
            "OAuth2ErrorResponse": {
                "type": "object",
                "description": "OAuth2 토큰 발급 실패 응답.\n`/oauth2/token` 엔드포인트는 BFF 공통 `ErrorResponse` envelope 이 아닌 OAuth2 표준 포맷으로 응답합니다.\n클라이언트는 `code` 가 아닌 `error` 필드로 에러를 식별해야 합니다.\n",
                "required": ["error"],
                "properties": {
                    "error": {
                        "type": "string",
                        "description": "에러 코드.",
                        "enum": [
                            "invalid_request",
                            "invalid_client",
                            "invalid_grant",
                            "unauthorized_client",
                            "unsupported_grant_type"
                        ]
                    },
                    "error_description": {
                        "type": "string",
                        "description": "에러 상세 설명 (선택). 메시지에 non-ASCII 문자가 포함되는 경우 생략될 수 있습니다.\n",
                        "example": "Client authentication failed."
                    },
                    "error_uri": {
                        "type": "string",
                        "format": "uri",
                        "description": "에러 정보가 게시된 페이지 URI (선택)."
                    }
                }
            },
            "OrderbookEntry": {
                "type": "object",
                "required": ["price", "volume"],
                "properties": {
                    "price": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "호가",
                        "example": "72100"
                    },
                    "volume": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "잔량",
                        "example": "8500"
                    }
                }
            },
            "OrderbookResponse": {
                "type": "object",
                "required": ["currency", "asks", "bids"],
                "properties": {
                    "timestamp": {
                        "type": ["string", "null"],
                        "format": "date-time",
                        "description": "데이터 시각. 데이터 미제공 시 null",
                        "example": "2026-03-25T09:30:00.123+09:00"
                    },
                    "currency": {
                        "$ref": "#/components/schemas/Currency"
                    },
                    "asks": {
                        "type": "array",
                        "description": "매도호가 목록 (낮은 가격순)",
                        "items": {
                            "$ref": "#/components/schemas/OrderbookEntry"
                        }
                    },
                    "bids": {
                        "type": "array",
                        "description": "매수호가 목록 (높은 가격순)",
                        "items": {
                            "$ref": "#/components/schemas/OrderbookEntry"
                        }
                    }
                }
            },
            "PriceResponse": {
                "type": "object",
                "required": ["symbol", "lastPrice", "currency"],
                "properties": {
                    "symbol": {
                        "type": "string",
                        "description": "종목 심볼",
                        "example": "005930"
                    },
                    "timestamp": {
                        "type": ["string", "null"],
                        "format": "date-time",
                        "description": "데이터 시각. 체결 미발생 등으로 시각이 없을 경우 null",
                        "example": "2026-03-25T09:30:00.123+09:00"
                    },
                    "lastPrice": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "현재가",
                        "example": "72000"
                    },
                    "currency": {
                        "$ref": "#/components/schemas/Currency"
                    }
                }
            },
            "Trade": {
                "type": "object",
                "required": ["price", "volume", "timestamp", "currency"],
                "properties": {
                    "price": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "체결가",
                        "example": "72000"
                    },
                    "volume": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "체결 수량",
                        "example": "120"
                    },
                    "timestamp": {
                        "type": "string",
                        "format": "date-time",
                        "description": "체결 시각",
                        "example": "2026-03-25T09:30:42.000+09:00"
                    },
                    "currency": {
                        "$ref": "#/components/schemas/Currency"
                    }
                }
            },
            "PriceLimitResponse": {
                "type": "object",
                "required": ["timestamp", "currency"],
                "properties": {
                    "timestamp": {
                        "type": "string",
                        "format": "date-time",
                        "description": "데이터 시각",
                        "example": "2026-03-25T09:30:00.123+09:00"
                    },
                    "upperLimitPrice": {
                        "type": ["string", "null"],
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "상한가. 미국 주식 등 가격제한이 없는 시장에서는 null",
                        "example": "93000"
                    },
                    "lowerLimitPrice": {
                        "type": ["string", "null"],
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "하한가. 미국 주식 등 가격제한이 없는 시장에서는 null",
                        "example": "50400"
                    },
                    "currency": {
                        "$ref": "#/components/schemas/Currency"
                    }
                }
            },
            "CandlePageResponse": {
                "type": "object",
                "required": ["candles"],
                "properties": {
                    "candles": {
                        "type": "array",
                        "description": "캔들 목록",
                        "items": {
                            "$ref": "#/components/schemas/Candle"
                        }
                    },
                    "nextBefore": {
                        "type": ["string", "null"],
                        "format": "date-time",
                        "description": "다음 페이지 조회 시 `before` 쿼리 파라미터에 그대로 전달. 마지막 페이지면 null."
                    }
                }
            },
            "Candle": {
                "type": "object",
                "required": [
                    "timestamp",
                    "openPrice",
                    "highPrice",
                    "lowPrice",
                    "closePrice",
                    "volume",
                    "currency"
                ],
                "properties": {
                    "timestamp": {
                        "type": "string",
                        "format": "date-time",
                        "description": "봉 시작 시각",
                        "example": "2026-03-25T09:00:00+09:00"
                    },
                    "openPrice": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "시가",
                        "example": "71600"
                    },
                    "highPrice": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "고가",
                        "example": "72300"
                    },
                    "lowPrice": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "저가",
                        "example": "71500"
                    },
                    "closePrice": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "종가",
                        "example": "72000"
                    },
                    "volume": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "거래량",
                        "example": "3521000"
                    },
                    "currency": {
                        "$ref": "#/components/schemas/Currency"
                    }
                }
            },
            "StockInfo": {
                "type": "object",
                "required": [
                    "symbol",
                    "name",
                    "englishName",
                    "isinCode",
                    "market",
                    "securityType",
                    "isCommonShare",
                    "status",
                    "currency",
                    "sharesOutstanding"
                ],
                "properties": {
                    "symbol": {
                        "type": "string",
                        "description": "종목 심볼.",
                        "example": "005930"
                    },
                    "name": {
                        "type": "string",
                        "description": "종목명 (한글)",
                        "example": "삼성전자"
                    },
                    "englishName": {
                        "type": "string",
                        "description": "영문 종목명",
                        "example": "SamsungElec"
                    },
                    "isinCode": {
                        "type": "string",
                        "description": "국제증권식별번호 (ISO 6166)",
                        "example": "KR7005930003"
                    },
                    "market": {
                        "type": "string",
                        "description": "상장 시장. warnings API의 exchange(거래소 단위)와 달리 시장 세그먼트 단위로 구분",
                        "enum": ["KOSPI", "KOSDAQ", "NYSE", "NASDAQ", "AMEX", "KR_ETC", "US_ETC"],
                        "example": "KOSPI"
                    },
                    "securityType": {
                        "type": "string",
                        "description": "종목 유형",
                        "enum": [
                            "STOCK",
                            "FOREIGN_STOCK",
                            "DEPOSITARY_RECEIPT",
                            "INFRASTRUCTURE_FUND",
                            "REIT",
                            "ETF",
                            "FOREIGN_ETF",
                            "ETN",
                            "STOCK_WARRANTS"
                        ],
                        "example": "STOCK"
                    },
                    "isCommonShare": {
                        "type": "boolean",
                        "description": "보통주 여부. 우선주인 경우 false",
                        "example": true
                    },
                    "status": {
                        "type": "string",
                        "description": "상장 상태",
                        "enum": ["SCHEDULED", "ACTIVE", "DELISTED"],
                        "example": "ACTIVE"
                    },
                    "currency": {
                        "$ref": "#/components/schemas/Currency"
                    },
                    "listDate": {
                        "type": ["string", "null"],
                        "format": "date",
                        "description": "상장일 (YYYY-MM-DD, KST 기준). 정보 미제공 시 null",
                        "example": "1975-06-11"
                    },
                    "delistDate": {
                        "type": ["string", "null"],
                        "format": "date",
                        "description": "상장폐지일 (YYYY-MM-DD, KST 기준). 활성 종목은 null",
                        "example": null
                    },
                    "sharesOutstanding": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "발행주식수",
                        "example": "5919637922"
                    },
                    "leverageFactor": {
                        "type": ["string", "null"],
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "레버리지 배수. ETF/ETN에만 적용 (1.0, 2.0, -1.0 등). 일반 주식 등 해당 없는 종목은 null",
                        "example": null
                    },
                    "koreanMarketDetail": {
                        "description": "국내 시장 상세 정보. 국내 종목(KOSPI, KOSDAQ, KR_ETC)에만 제공되며, 해외 종목은 null",
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/KrMarketDetail"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    }
                }
            },
            "KrMarketDetail": {
                "type": "object",
                "required": ["liquidationTrading", "nxtSupported", "krxTradingSuspended"],
                "properties": {
                    "liquidationTrading": {
                        "type": "boolean",
                        "description": "정리매매 여부 (상장폐지 절차 진행 중).",
                        "example": false
                    },
                    "nxtSupported": {
                        "type": "boolean",
                        "description": "NXT 대체거래소 지원 여부",
                        "example": true
                    },
                    "krxTradingSuspended": {
                        "type": "boolean",
                        "description": "KRX 거래정지 여부",
                        "example": false
                    },
                    "nxtTradingSuspended": {
                        "type": ["boolean", "null"],
                        "description": "NXT 거래정지 여부. NXT 미지원 종목(nxtSupported=false)은 null",
                        "example": false
                    }
                }
            },
            "StockWarning": {
                "type": "object",
                "required": ["warningType"],
                "properties": {
                    "warningType": {
                        "type": "string",
                        "description": "유의사항 유형.\n클라이언트는 unknown code 를 허용하도록 구현해야 합니다.\n\n| 값 | 의미 |\n|------|------|\n| `LIQUIDATION_TRADING` | 정리매매 (상장폐지 절차 진행 중) |\n| `OVERHEATED` | 단기과열종목 지정 |\n| `INVESTMENT_WARNING` | 투자경고종목 지정 |\n| `INVESTMENT_RISK` | 투자위험종목 지정 |\n| `VI_STATIC_AND_DYNAMIC` | 변동성 완화장치(VI) 정적 + 동적 동시 발동 |\n| `VI_STATIC` | 변동성 완화장치(VI) 정적 발동 |\n| `VI_DYNAMIC` | 변동성 완화장치(VI) 동적 발동 |\n| `STOCK_WARRANTS` | 신주인수권증서/증권 |\n",
                        "enum": [
                            "LIQUIDATION_TRADING",
                            "OVERHEATED",
                            "INVESTMENT_WARNING",
                            "INVESTMENT_RISK",
                            "VI_STATIC_AND_DYNAMIC",
                            "VI_STATIC",
                            "VI_DYNAMIC",
                            "STOCK_WARRANTS"
                        ],
                        "example": "VI_STATIC"
                    },
                    "exchange": {
                        "type": ["string", "null"],
                        "description": "거래소 코드 (KRX, NXT 등 물리적 거래소 단위). stocks API의 market(상장 시장 단위)과 추상화 수준이 다름. 거래소 무관 경고는 null",
                        "example": "KRX"
                    },
                    "startDate": {
                        "type": ["string", "null"],
                        "format": "date",
                        "description": "적용 시작일 (inclusive, YYYY-MM-DD, KST 기준). 시작일 미정 시 null",
                        "example": "2026-03-26"
                    },
                    "endDate": {
                        "type": ["string", "null"],
                        "format": "date",
                        "description": "적용 종료일 (inclusive, YYYY-MM-DD, KST 기준). 진행 중이거나 미정 시 null",
                        "example": "2026-03-27"
                    }
                }
            },
            "ExchangeRateResponse": {
                "type": "object",
                "required": [
                    "baseCurrency",
                    "quoteCurrency",
                    "rate",
                    "midRate",
                    "basisPoint",
                    "rateChangeType",
                    "validFrom",
                    "validUntil"
                ],
                "properties": {
                    "baseCurrency": {
                        "$ref": "#/components/schemas/Currency",
                        "description": "기준 통화",
                        "example": "USD"
                    },
                    "quoteCurrency": {
                        "$ref": "#/components/schemas/Currency",
                        "description": "표시 통화 (quote currency)",
                        "example": "KRW"
                    },
                    "rate": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "매수 환율 (1 baseCurrency = ? quoteCurrency)",
                        "example": "1380.5"
                    },
                    "midRate": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "매매기준율 (은행간 mid rate)",
                        "example": "1375"
                    },
                    "basisPoint": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "매매기준율(midRate) 대비 basis points. (rate - midRate) / midRate * 10000",
                        "example": "40"
                    },
                    "rateChangeType": {
                        "type": "string",
                        "description": "등락 구분",
                        "enum": ["UP", "EQUAL", "DOWN"],
                        "example": "UP"
                    },
                    "validFrom": {
                        "type": "string",
                        "format": "date-time",
                        "description": "환율 유효 시작 시각",
                        "example": "2026-03-25T09:30:00+09:00"
                    },
                    "validUntil": {
                        "type": "string",
                        "format": "date-time",
                        "description": "환율 유효 종료 시각",
                        "example": "2026-03-25T09:31:00+09:00"
                    }
                }
            },
            "KrMarketCalendarResponse": {
                "type": "object",
                "required": ["today", "previousBusinessDay", "nextBusinessDay"],
                "properties": {
                    "today": {
                        "$ref": "#/components/schemas/KrMarketDay"
                    },
                    "previousBusinessDay": {
                        "$ref": "#/components/schemas/KrMarketDay"
                    },
                    "nextBusinessDay": {
                        "$ref": "#/components/schemas/KrMarketDay"
                    }
                }
            },
            "KrMarketDay": {
                "type": "object",
                "required": ["date"],
                "properties": {
                    "date": {
                        "type": "string",
                        "format": "date",
                        "description": "영업일 (KST 기준)",
                        "example": "2026-03-25"
                    },
                    "integrated": {
                        "description": "거래 가능 시간 (통합 모드 (KRX+NXT) 기준). 둘 다 휴장이면 null",
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/IntegratedHour"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    }
                }
            },
            "IntegratedHour": {
                "type": "object",
                "description": "거래 가능 시간. 특수장(시간외종가/시간외단일가) 제외, 통합 모드 (KRX+NXT) 기준.\n세 세션(`preMarket`, `regularMarket`, `afterMarket`) 각각 nullable. 해당 세션이 휴장이면 null,\n세 세션 모두 null 이면 상위 `integrated` 자체가 null.\n",
                "properties": {
                    "preMarket": {
                        "description": "프리마켓 (NXT 접속매매). NXT 프리마켓이 휴장이면 null",
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/PreMarketSession"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "regularMarket": {
                        "description": "정규장. KRX·NXT 정규장의 합집합. 둘 다 휴장이면 null",
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/RegularMarketSession"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "afterMarket": {
                        "description": "애프터마켓 (NXT). NXT 애프터마켓이 휴장이면 null",
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/AfterMarketSession"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    }
                }
            },
            "PreMarketSession": {
                "type": "object",
                "description": "프리마켓 세션",
                "required": ["startTime", "endTime"],
                "properties": {
                    "startTime": {
                        "type": "string",
                        "format": "date-time",
                        "description": "프리마켓 시작",
                        "example": "2026-03-25T08:00:00+09:00"
                    },
                    "singlePriceAuctionStartTime": {
                        "description": "프리마켓 내 시가단일가 구간 시작 (NXT 프리마켓 접속매매 종료). 단일가 정보 결손 시 null",
                        "example": "2026-03-25T08:50:00+09:00",
                        "oneOf": [
                            {
                                "type": "string",
                                "format": "date-time"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "endTime": {
                        "type": "string",
                        "format": "date-time",
                        "description": "프리마켓 종료 (시가단일가 종료)",
                        "example": "2026-03-25T09:00:00+09:00"
                    }
                }
            },
            "RegularMarketSession": {
                "type": "object",
                "description": "정규장 세션. KRX·NXT 정규장의 합집합(가장 이른 시작 ~ 가장 늦은 종료). 종가단일가 구간을 포함",
                "required": ["startTime", "endTime"],
                "properties": {
                    "startTime": {
                        "type": "string",
                        "format": "date-time",
                        "description": "정규장 시작. 가장 이른 KRX/NXT 정규장 시작 시각",
                        "example": "2026-03-25T09:00:00+09:00"
                    },
                    "singlePriceAuctionStartTime": {
                        "description": "정규장 내 종가단일가 구간 시작 (KRX 기준). KRX 휴장이면 null",
                        "example": "2026-03-25T15:20:00+09:00",
                        "oneOf": [
                            {
                                "type": "string",
                                "format": "date-time"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "endTime": {
                        "type": "string",
                        "format": "date-time",
                        "description": "정규장 종료 (종가단일가 종료)",
                        "example": "2026-03-25T15:30:00+09:00"
                    }
                }
            },
            "AfterMarketSession": {
                "type": "object",
                "description": "애프터마켓 세션 (NXT)",
                "required": ["startTime", "endTime"],
                "properties": {
                    "startTime": {
                        "type": "string",
                        "format": "date-time",
                        "description": "애프터마켓 시작",
                        "example": "2026-03-25T15:30:00+09:00"
                    },
                    "singlePriceAuctionEndTime": {
                        "description": "애프터마켓 내 시가단일가 구간 종료.",
                        "example": "2026-03-25T15:40:00+09:00",
                        "oneOf": [
                            {
                                "type": "string",
                                "format": "date-time"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "endTime": {
                        "type": "string",
                        "format": "date-time",
                        "description": "애프터마켓 전체 종료",
                        "example": "2026-03-25T20:00:00+09:00"
                    }
                }
            },
            "UsMarketCalendarResponse": {
                "type": "object",
                "required": ["today", "previousBusinessDay", "nextBusinessDay"],
                "properties": {
                    "today": {
                        "$ref": "#/components/schemas/UsMarketDay"
                    },
                    "previousBusinessDay": {
                        "$ref": "#/components/schemas/UsMarketDay"
                    },
                    "nextBusinessDay": {
                        "$ref": "#/components/schemas/UsMarketDay"
                    }
                }
            },
            "UsMarketDay": {
                "type": "object",
                "description": "미국 시장 영업일 정보. 4 세션(`dayMarket`, `preMarket`, `regularMarket`, `afterMarket`) 각각 nullable.\n휴장일이면 4 세션 모두 null.\n",
                "required": ["date"],
                "properties": {
                    "date": {
                        "type": "string",
                        "format": "date",
                        "description": "영업일 (미국 현지 기준)",
                        "example": "2026-03-25"
                    },
                    "dayMarket": {
                        "description": "데이마켓 세션 (토스증권). 휴장이면 null",
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/UsDayMarketSession"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "preMarket": {
                        "description": "프리마켓 세션. 휴장이면 null",
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/UsPreMarketSession"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "regularMarket": {
                        "description": "정규장 세션. 휴장이면 null",
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/UsRegularMarketSession"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "afterMarket": {
                        "description": "애프터마켓 세션. 휴장이면 null",
                        "oneOf": [
                            {
                                "$ref": "#/components/schemas/UsAfterMarketSession"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    }
                }
            },
            "UsDayMarketSession": {
                "type": "object",
                "description": "데이마켓 세션 (토스증권)",
                "required": ["startTime", "endTime"],
                "properties": {
                    "startTime": {
                        "type": "string",
                        "format": "date-time",
                        "description": "데이마켓 시작",
                        "example": "2026-03-25T09:00:00+09:00"
                    },
                    "endTime": {
                        "type": "string",
                        "format": "date-time",
                        "description": "데이마켓 종료",
                        "example": "2026-03-25T16:50:00+09:00"
                    }
                }
            },
            "UsPreMarketSession": {
                "type": "object",
                "description": "프리마켓 세션",
                "required": ["startTime", "endTime"],
                "properties": {
                    "startTime": {
                        "type": "string",
                        "format": "date-time",
                        "description": "프리마켓 시작",
                        "example": "2026-03-25T17:00:00+09:00"
                    },
                    "endTime": {
                        "type": "string",
                        "format": "date-time",
                        "description": "프리마켓 종료",
                        "example": "2026-03-25T22:30:00+09:00"
                    }
                }
            },
            "UsRegularMarketSession": {
                "type": "object",
                "description": "정규장 세션",
                "required": ["startTime", "endTime"],
                "properties": {
                    "startTime": {
                        "type": "string",
                        "format": "date-time",
                        "description": "정규장 시작",
                        "example": "2026-03-25T22:30:00+09:00"
                    },
                    "endTime": {
                        "type": "string",
                        "format": "date-time",
                        "description": "정규장 종료",
                        "example": "2026-03-26T05:00:00+09:00"
                    }
                }
            },
            "UsAfterMarketSession": {
                "type": "object",
                "description": "애프터마켓 세션",
                "required": ["startTime", "endTime"],
                "properties": {
                    "startTime": {
                        "type": "string",
                        "format": "date-time",
                        "description": "애프터마켓 시작",
                        "example": "2026-03-26T05:00:00+09:00"
                    },
                    "endTime": {
                        "type": "string",
                        "format": "date-time",
                        "description": "애프터마켓 종료",
                        "example": "2026-03-26T07:00:00+09:00"
                    }
                }
            },
            "Account": {
                "type": "object",
                "required": ["accountNo", "accountSeq", "accountType"],
                "properties": {
                    "accountNo": {
                        "type": "string",
                        "description": "계좌번호",
                        "example": "12345678901"
                    },
                    "accountSeq": {
                        "type": "integer",
                        "format": "int64",
                        "description": "계좌 식별 키. 주문 등 API 호출 시 이 값을 사용",
                        "example": 1
                    },
                    "accountType": {
                        "type": "string",
                        "enum": [
                            "BROKERAGE",
                            "OVERSEAS_DERIVATIVES",
                            "PENSION_SAVINGS",
                            "RESHORING_INVESTMENT"
                        ],
                        "description": "계좌 유형. 현재는 BROKERAGE 만 지원합니다.\n- BROKERAGE: 종합매매. 국내·해외 주식 통합 매매 계좌\n- OVERSEAS_DERIVATIVES: 해외파생. 해외 파생상품 거래 계좌\n- PENSION_SAVINGS: 연금저축. 세제혜택 연금저축 계좌\n- RESHORING_INVESTMENT: RIA 계좌\n\n클라이언트는 unknown enum 값을 허용하도록 구현해야 합니다.\n",
                        "example": "BROKERAGE"
                    }
                }
            },
            "HoldingsOverview": {
                "type": "object",
                "required": [
                    "totalPurchaseAmount",
                    "marketValue",
                    "profitLoss",
                    "dailyProfitLoss",
                    "items"
                ],
                "properties": {
                    "totalPurchaseAmount": {
                        "description": "투자원금. 전체 보유 종목의 통화별 합산",
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/Price"
                            }
                        ]
                    },
                    "marketValue": {
                        "$ref": "#/components/schemas/OverviewMarketValue"
                    },
                    "profitLoss": {
                        "$ref": "#/components/schemas/OverviewProfitLoss"
                    },
                    "dailyProfitLoss": {
                        "$ref": "#/components/schemas/OverviewDailyProfitLoss"
                    },
                    "items": {
                        "type": "array",
                        "description": "보유 종목 목록. 보유 종목이 없으면 빈 배열",
                        "items": {
                            "$ref": "#/components/schemas/HoldingsItem"
                        }
                    }
                }
            },
            "HoldingsItem": {
                "type": "object",
                "required": [
                    "symbol",
                    "name",
                    "marketCountry",
                    "currency",
                    "quantity",
                    "lastPrice",
                    "averagePurchasePrice",
                    "marketValue",
                    "profitLoss",
                    "dailyProfitLoss",
                    "cost"
                ],
                "properties": {
                    "symbol": {
                        "type": "string",
                        "description": "종목 심볼. KR: 6자리 숫자, US: 티커",
                        "example": "005930"
                    },
                    "name": {
                        "type": "string",
                        "description": "종목명",
                        "example": "삼성전자"
                    },
                    "marketCountry": {
                        "$ref": "#/components/schemas/MarketCountry"
                    },
                    "currency": {
                        "$ref": "#/components/schemas/Currency"
                    },
                    "quantity": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "보유 수량",
                        "example": "100"
                    },
                    "lastPrice": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "현재가. 거래 통화(currency) 기준",
                        "example": "72000"
                    },
                    "averagePurchasePrice": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "매수 평균가. 거래 통화(currency) 기준",
                        "example": "65000"
                    },
                    "marketValue": {
                        "$ref": "#/components/schemas/MarketValue"
                    },
                    "profitLoss": {
                        "$ref": "#/components/schemas/ProfitLoss"
                    },
                    "dailyProfitLoss": {
                        "$ref": "#/components/schemas/DailyProfitLoss"
                    },
                    "cost": {
                        "$ref": "#/components/schemas/Cost"
                    }
                }
            },
            "Price": {
                "type": "object",
                "description": "통화별 합산 금액. 각 통화 필드는 해당 통화로 거래된 종목의 합만 포함합니다 (환율 환산을 통한 통화 간 합산 미포함).",
                "required": ["krw"],
                "properties": {
                    "krw": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "KRW로 거래되는 국내 종목의 합산 금액. 국내 종목이 없으면 0"
                    },
                    "usd": {
                        "type": ["string", "null"],
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "USD로 거래되는 해외 종목의 합산 금액. 해외 종목이 없으면 null"
                    }
                }
            },
            "OverviewMarketValue": {
                "type": "object",
                "description": "시장 평가금액. 전체 보유 종목의 통화별 합산",
                "required": ["amount", "amountAfterCost"],
                "properties": {
                    "amount": {
                        "description": "시장 평가금액",
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/Price"
                            }
                        ]
                    },
                    "amountAfterCost": {
                        "description": "세금/수수료 공제 후 평가금액",
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/Price"
                            }
                        ]
                    }
                }
            },
            "OverviewProfitLoss": {
                "type": "object",
                "description": "손익. 전체 보유 종목의 통화별 합산",
                "required": ["amount", "amountAfterCost", "rate", "rateAfterCost"],
                "properties": {
                    "amount": {
                        "description": "손익금액",
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/Price"
                            }
                        ]
                    },
                    "amountAfterCost": {
                        "description": "세금/수수료 공제 후 손익금액",
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/Price"
                            }
                        ]
                    },
                    "rate": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "손익률 (소수비율). 전체 자산을 현재 환율로 원화 환산한 기준. 0.1516 = 15.16%",
                        "example": "0.1516"
                    },
                    "rateAfterCost": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "세금/수수료 공제 후 손익률 (소수비율). 전체 자산을 현재 환율로 원화 환산한 기준. 0.1406 = 14.06%",
                        "example": "0.1406"
                    }
                }
            },
            "OverviewDailyProfitLoss": {
                "type": "object",
                "description": "일간 손익. 전체 보유 종목의 통화별 합산",
                "required": ["amount", "rate"],
                "properties": {
                    "amount": {
                        "description": "일간 손익금액",
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/Price"
                            }
                        ]
                    },
                    "rate": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "일간 손익률 (소수비율). 전체 자산을 현재 환율로 원화 환산한 기준. 0.0185 = 1.85%",
                        "example": "0.0185"
                    }
                }
            },
            "MarketValue": {
                "type": "object",
                "description": "시장 평가. 거래 통화(currency) 기준",
                "required": ["purchaseAmount", "amount", "amountAfterCost"],
                "properties": {
                    "purchaseAmount": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "매입금액",
                        "example": "6500000"
                    },
                    "amount": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "시장 평가금액",
                        "example": "7200000"
                    },
                    "amountAfterCost": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "세금/수수료 공제 후 평가금액",
                        "example": "7050000"
                    }
                }
            },
            "ProfitLoss": {
                "type": "object",
                "description": "손익. 거래 통화(currency) 기준",
                "required": ["amount", "amountAfterCost", "rate", "rateAfterCost"],
                "properties": {
                    "amount": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "손익금액",
                        "example": "700000"
                    },
                    "amountAfterCost": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "세금/수수료 공제 후 손익금액",
                        "example": "550000"
                    },
                    "rate": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "손익률. 소수비율 (0.1077 = 10.77%)",
                        "example": "0.1077"
                    },
                    "rateAfterCost": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "세금/수수료 공제 후 손익률. 소수비율 (0.0846 = 8.46%)",
                        "example": "0.0846"
                    }
                }
            },
            "DailyProfitLoss": {
                "type": "object",
                "description": "일간 손익. 거래 통화(currency) 기준",
                "required": ["amount", "rate"],
                "properties": {
                    "amount": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "일간 손익금액",
                        "example": "100000"
                    },
                    "rate": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "일간 손익률. 소수비율 (0.0141 = 1.41%)",
                        "example": "0.0141"
                    }
                }
            },
            "Cost": {
                "type": "object",
                "description": "비용. 거래 통화(currency) 기준",
                "required": ["commission"],
                "properties": {
                    "commission": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "수수료",
                        "example": "14400"
                    },
                    "tax": {
                        "type": ["string", "null"],
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "세금. 세금이 없는 경우 null",
                        "example": "135600"
                    }
                }
            },
            "OrderCreateRequest": {
                "oneOf": [
                    {
                        "title": "OrderCreateQuantityBased",
                        "description": "수량 기반 주문. quantity 로 주문 수량을 지정.",
                        "type": "object",
                        "required": ["symbol", "side", "orderType", "quantity"],
                        "properties": {
                            "clientOrderId": {
                                "type": "string",
                                "maxLength": 36,
                                "pattern": "^[a-zA-Z0-9\\-_]+$",
                                "description": "클라이언트 지정 주문 식별자. 멱등성 키로 사용됩니다.\n- 미전달: 멱등성 미적용. 매 요청을 별개 주문으로 처리합니다.\n- 전달: 동일 값으로 재요청 시 이전 주문 결과를 그대로 재반환합니다.\n서버는 자동 생성하지 않습니다.\n최대 36자, 영숫자 및 `-`, `_` 허용.\n멱등성 키는 10분간 유효하며, 이후 동일 값으로 재요청 시 새 주문으로 처리됩니다.\n",
                                "example": "my-order-001"
                            },
                            "symbol": {
                                "type": "string",
                                "description": "종목 심볼. KRX: 6자리 숫자, US: 영문 티커",
                                "example": "005930"
                            },
                            "side": {
                                "type": "string",
                                "enum": ["BUY", "SELL"],
                                "description": "주문 방향",
                                "example": "BUY"
                            },
                            "orderType": {
                                "type": "string",
                                "enum": ["LIMIT", "MARKET"],
                                "description": "호가 유형.\n- `LIMIT`: 지정가\n- `MARKET`: 시장가\n",
                                "example": "LIMIT"
                            },
                            "timeInForce": {
                                "type": "string",
                                "enum": ["DAY", "CLS"],
                                "description": "주문 유효 조건 (Time In Force). 미전달 시 `DAY`. `orderType` 과 결합되어 주문 방식이 결정됩니다 (예: `LIMIT` + `CLS` = LOC).\n- `DAY`: 당일 유효 (Day). 정규장 종료까지 미체결분은 자동 취소됩니다.\n- `CLS`: 장 마감 주문 (At the Close). 현재 미국 주식 + `orderType=LIMIT` 조합만 지원합니다.\n",
                                "default": "DAY",
                                "example": "DAY"
                            },
                            "quantity": {
                                "type": "string",
                                "format": "decimal",
                                "pattern": "^\\d+$",
                                "maxLength": 30,
                                "description": "주문 수량 (주 단위). 지정한 수량만큼 주문합니다.\n정수만 가능합니다. (소수점 불가능. 소수점 주문 시 Amount-based variant 의 `orderAmount` 를 사용해야 합니다.)\n",
                                "example": "10"
                            },
                            "price": {
                                "type": "string",
                                "format": "decimal",
                                "pattern": "^\\d+(\\.\\d+)?$",
                                "maxLength": 30,
                                "description": "주문 가격. `orderType`이 `LIMIT` 일 때만 사용합니다.\n- `LIMIT`: 필수. 미전달 시 `400 invalid-request`.\n- `MARKET`: 전달 불가. 전달 시 `400 invalid-request`.\nKR: 정수 (원 단위). 호가 단위에 맞아야 합니다 (예: 50,000~200,000원 구간은 100원 단위).\nKR 은 호가 단위에 맞지 않으면 `400 invalid-request` 에러와 함께 올바른 호가 단위가 `data`에 포함됩니다.\nUS: 소수점 (달러 단위).\n  - $1 미만: 소수점 넷째 자리까지 (그 이하 자릿수는 절삭).\n  - $1 이상: 소수점 둘째 자리까지 (그 이하 자릿수는 절삭).\n",
                                "example": "70000"
                            },
                            "confirmHighValueOrder": {
                                "type": "boolean",
                                "description": "착오주문 방지를 위한 주문 확인 플래그. 기본값 `false`.\n1억원 이상의 주문 시 `true`가 아니면 `400 confirm-high-value-required` 에러를 반환합니다.\n사용자가 해당 주문의 금액을 인지하고 있음을 표시하기 위한 필드입니다.\n",
                                "default": false,
                                "example": false
                            }
                        }
                    },
                    {
                        "title": "OrderCreateAmountBased",
                        "description": "금액 기반 주문 (US MARKET 전용). orderAmount 로 주문 금액을 지정.",
                        "type": "object",
                        "required": ["symbol", "side", "orderType", "orderAmount"],
                        "properties": {
                            "clientOrderId": {
                                "type": "string",
                                "maxLength": 36,
                                "pattern": "^[a-zA-Z0-9\\-_]+$",
                                "description": "클라이언트 지정 주문 식별자. 멱등성 키로 사용됩니다.\n- 미전달: 멱등성 미적용. 매 요청을 별개 주문으로 처리합니다.\n- 전달: 동일 값으로 재요청 시 이전 주문 결과를 그대로 재반환합니다.\n서버는 자동 생성하지 않습니다.\n최대 36자, 영숫자 및 `-`, `_` 허용.\n멱등성 키는 10분간 유효하며, 이후 동일 값으로 재요청 시 새 주문으로 처리됩니다.\n",
                                "example": "my-order-001"
                            },
                            "symbol": {
                                "type": "string",
                                "description": "US 종목 심볼 (영문 티커). 금액 기반 주문은 US MARKET 전용입니다.",
                                "example": "AAPL"
                            },
                            "side": {
                                "type": "string",
                                "enum": ["BUY", "SELL"],
                                "description": "주문 방향",
                                "example": "BUY"
                            },
                            "orderType": {
                                "type": "string",
                                "enum": ["MARKET"],
                                "description": "호가 유형. 금액 기반 주문은 `MARKET` 만 허용합니다.",
                                "example": "MARKET"
                            },
                            "orderAmount": {
                                "type": "string",
                                "format": "decimal",
                                "pattern": "^\\d+(\\.\\d+)?$",
                                "maxLength": 30,
                                "description": "주문 금액 (달러). 지정한 금액만큼 주문합니다.\n체결 수량은 체결 시점의 시장가에 따라 결정됩니다.\n\nQuantity-based 와의 차이: quantity 는 수량을 확정하고 비용이 변동하며,\norderAmount 는 금액을 확정하고 수량이 변동합니다.\n\n정규장 시간에만 접수 가능합니다.\n정규장 시간 외 요청 시 `422 amount-order-outside-regular-hours` 에러를 반환합니다.\n",
                                "example": "100.5"
                            },
                            "confirmHighValueOrder": {
                                "type": "boolean",
                                "description": "착오주문 방지를 위한 주문 확인 플래그. 기본값 `false`.\n1억원 이상의 주문 시 `true`가 아니면 `400 confirm-high-value-required` 에러를 반환합니다.\n사용자가 해당 주문의 금액을 인지하고 있음을 표시하기 위한 필드입니다.\n",
                                "default": false,
                                "example": false
                            }
                        }
                    }
                ]
            },
            "OrderModifyRequest": {
                "type": "object",
                "required": ["orderType"],
                "properties": {
                    "orderType": {
                        "type": "string",
                        "enum": ["LIMIT", "MARKET"],
                        "description": "변경할 호가 유형.\n- `LIMIT`: 지정가\n- `MARKET`: 시장가\n",
                        "example": "LIMIT"
                    },
                    "quantity": {
                        "type": "string",
                        "format": "decimal",
                        "pattern": "^\\d+$",
                        "maxLength": 30,
                        "description": "변경할 수량.\n**KR 주식: 필수.** 양의 정수만 허용합니다 (미전달/0/음수/소수점은 `400 invalid-request`).\nUS 주식: 전달 불가. 제공 시 `400 us-modify-quantity-not-supported` 에러.\n",
                        "example": "15"
                    },
                    "price": {
                        "type": "string",
                        "format": "decimal",
                        "pattern": "^\\d+(\\.\\d+)?$",
                        "maxLength": 30,
                        "description": "변경할 가격. `orderType`이 `LIMIT` 일 때만 사용합니다.\n- `LIMIT`: 필수. 미전달 시 `400 invalid-request`.\n- `MARKET`: 전달 불가. 전달 시 `400 invalid-request`.\nKR: 정수 (원 단위). 호가 단위에 맞아야 합니다. 맞지 않으면 `400 invalid-request` 에러.\nUS: 소수점 (달러 단위).\n  - $1 미만: 소수점 넷째 자리까지 (그 이하 자릿수는 절삭).\n  - $1 이상: 소수점 둘째 자리까지 (그 이하 자릿수는 절삭).\n",
                        "example": "71000"
                    },
                    "confirmHighValueOrder": {
                        "type": "boolean",
                        "description": "착오주문 방지를 위한 주문 확인 플래그. 기본값 `false`.\n1억원 이상의 주문 시 `true`가 아니면 `400 confirm-high-value-required` 에러를 반환합니다.\n사용자가 해당 주문의 금액을 인지하고 있음을 표시하기 위한 필드입니다.\n30억원 이상의 주문은 본 플래그와 무관하게 `422 max-order-amount-exceeded` 에러를 반환합니다.\n",
                        "default": false,
                        "example": false
                    }
                }
            },
            "OrderResponse": {
                "type": "object",
                "required": ["orderId"],
                "properties": {
                    "orderId": {
                        "type": "string",
                        "description": "서버 생성 주문 식별자. 정정/취소 시 사용",
                        "example": "0d5QIHjmtksbsmM-hBRAgP-ExI8iodGm9fAR5txelPfnMM8XQ_swoJdwL5RpGWMo"
                    },
                    "clientOrderId": {
                        "type": ["string", "null"],
                        "description": "요청 시 전달한 값 그대로 반환. 미전달 시 `null`.",
                        "example": "my-order-001"
                    }
                }
            },
            "OrderOperationResponse": {
                "type": "object",
                "required": ["orderId"],
                "properties": {
                    "orderId": {
                        "type": "string",
                        "description": "정정/취소로 새로 발급된 주문 식별자. 원주문의 orderId 와 다릅니다.\n",
                        "example": "5nfzdqmzfnAw3LFXWHPRy0UNi7y_WZlphJh5hRIsi25-NIfm_GtQgXima5QD2hUz"
                    }
                }
            },
            "PaginatedOrderResponse": {
                "type": "object",
                "required": ["orders", "nextCursor", "hasNext"],
                "description": "주문 목록 페이징 응답.\n- `status=OPEN`: 모든 대기 중 주문을 반환합니다. `nextCursor`는 항상 `null`, `hasNext`는 항상 `false`.\n- `status=CLOSED`: 현재 호출 시 `400 closed-not-supported` 를 반환합니다.\n",
                "properties": {
                    "orders": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Order"
                        },
                        "description": "주문 목록"
                    },
                    "nextCursor": {
                        "type": ["string", "null"],
                        "description": "다음 페이지 커서. 다음 페이지가 없으면 null",
                        "example": null
                    },
                    "hasNext": {
                        "type": "boolean",
                        "description": "다음 페이지 존재 여부",
                        "example": false
                    }
                }
            },
            "Order": {
                "type": "object",
                "required": [
                    "orderId",
                    "symbol",
                    "side",
                    "orderType",
                    "timeInForce",
                    "status",
                    "quantity",
                    "currency",
                    "orderedAt",
                    "execution"
                ],
                "properties": {
                    "orderId": {
                        "type": "string",
                        "description": "주문 식별자",
                        "example": "bAGzNvMOOTa5Uy0xVzYNbxDJ3Qpobwau4jDF3hyZZGWbpHm7wha8CFZc7aXVOWAl"
                    },
                    "symbol": {
                        "type": "string",
                        "description": "종목 심볼. KRX: 6자리 숫자, US: 영문 티커",
                        "example": "005930"
                    },
                    "side": {
                        "type": "string",
                        "enum": ["BUY", "SELL"],
                        "description": "주문 방향",
                        "example": "BUY"
                    },
                    "orderType": {
                        "type": "string",
                        "enum": ["LIMIT", "MARKET"],
                        "description": "호가 유형.\n- `LIMIT`: 지정가\n- `MARKET`: 시장가\n\n클라이언트는 unknown code 를 허용하도록 구현해야 합니다.\n",
                        "example": "LIMIT"
                    },
                    "timeInForce": {
                        "type": "string",
                        "enum": ["DAY", "CLS", "OPG"],
                        "description": "주문 유효 조건 (Time In Force). `orderType` 과 결합되어 주문 방식이 결정됩니다 (예: `LIMIT` + `CLS` = LOC).\n- `DAY`: 당일 유효 (Day)\n- `CLS`: 장 마감 주문 (At the Close)\n- `OPG`: 장 개시 주문 (At the Opening). 현재는 지원하지 않습니다.\n\n클라이언트는 unknown code 를 허용하도록 구현해야 합니다.\n",
                        "example": "DAY"
                    },
                    "status": {
                        "$ref": "#/components/schemas/OrderStatus"
                    },
                    "price": {
                        "type": ["string", "null"],
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "주문 가격 (native currency). MARKET 주문 시 null",
                        "example": "70000"
                    },
                    "quantity": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "주문 수량",
                        "example": "10"
                    },
                    "orderAmount": {
                        "type": ["string", "null"],
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "주문 금액 (USD). 금액 기반 US 시장가 매수 주문에만 해당. 그 외 null",
                        "example": null
                    },
                    "currency": {
                        "$ref": "#/components/schemas/Currency",
                        "example": "KRW"
                    },
                    "orderedAt": {
                        "type": "string",
                        "format": "date-time",
                        "description": "주문 시간 (ISO 8601, KST)",
                        "example": "2026-03-29T09:30:00+09:00"
                    },
                    "canceledAt": {
                        "type": ["string", "null"],
                        "format": "date-time",
                        "description": "취소 시간 (ISO 8601, KST). 해당 없으면 null",
                        "example": null
                    },
                    "execution": {
                        "type": "object",
                        "description": "체결 결과. 체결 내역이 없으면 filledQuantity=0",
                        "allOf": [
                            {
                                "$ref": "#/components/schemas/OrderExecution"
                            }
                        ]
                    }
                }
            },
            "OrderExecution": {
                "type": "object",
                "required": [
                    "filledQuantity",
                    "averageFilledPrice",
                    "filledAmount",
                    "commission",
                    "tax",
                    "filledAt",
                    "settlementDate"
                ],
                "properties": {
                    "filledQuantity": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "체결 수량",
                        "example": "10"
                    },
                    "averageFilledPrice": {
                        "type": ["string", "null"],
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "평균 체결 가격 (native currency). 부분 체결 시 체결된 건의 평균",
                        "example": "70000"
                    },
                    "filledAmount": {
                        "type": ["string", "null"],
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "총 체결 금액 (native currency)",
                        "example": "700000"
                    },
                    "commission": {
                        "type": ["string", "null"],
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "총 체결 수수료 (native currency)",
                        "example": "1400"
                    },
                    "tax": {
                        "type": ["string", "null"],
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "총 체결 세금 (native currency)",
                        "example": "0"
                    },
                    "filledAt": {
                        "type": ["string", "null"],
                        "format": "date-time",
                        "description": "최종 체결 시간 (ISO 8601, KST)",
                        "example": "2026-03-28T09:31:15+09:00"
                    },
                    "settlementDate": {
                        "type": ["string", "null"],
                        "format": "date",
                        "description": "결제 예정일 (YYYY-MM-DD, KST 기준). 미결제 시 null",
                        "example": "2026-03-30"
                    }
                }
            },
            "OrderStatus": {
                "type": "string",
                "enum": [
                    "PENDING",
                    "PENDING_CANCEL",
                    "PENDING_REPLACE",
                    "PARTIAL_FILLED",
                    "FILLED",
                    "CANCELED",
                    "REJECTED",
                    "CANCEL_REJECTED",
                    "REPLACE_REJECTED",
                    "REPLACED"
                ],
                "description": "주문 상태.\n- `PENDING`: 체결 대기. 주문이 접수되어 체결을 대기 중인 상태\n- `PENDING_CANCEL`: 취소 대기. 취소 요청이 접수되어 브로커 응답을 대기 중인 상태\n- `PENDING_REPLACE`: 정정 대기. 정정 요청이 접수되어 브로커 응답을 대기 중인 상태\n- `PARTIAL_FILLED`: 부분 체결. 주문 수량 중 일부만 체결된 상태\n- `FILLED`: 체결 완료. 주문 수량이 전량 체결된 상태\n- `CANCELED`: 취소 완료. execution.filledQuantity를 통해 부분 체결 여부를 확인할 수 있음\n- `REJECTED`: 거부됨. 브로커가 주문을 거부한 상태. execution.filledQuantity를 통해 부분 체결 여부를 확인할 수 있음\n- `CANCEL_REJECTED`: 취소 거부. 브로커가 취소 요청을 거부한 경우 별도 주문 레코드로 생성됨. 원주문은 이전 상태로 복귀함\n- `REPLACE_REJECTED`: 정정 거부. 브로커가 정정 요청을 거부한 경우 별도 주문 레코드로 생성됨. 원주문은 이전 상태로 복귀함\n- `REPLACED`: 정정됨. 정정 요청이 수락되어 원주문이 대체된 상태. execution.filledQuantity를 통해 부분 체결 여부를 확인할 수 있음\n\n클라이언트는 unknown code 를 허용하도록 구현해야 합니다.\n",
                "example": "FILLED"
            },
            "BuyingPowerResponse": {
                "type": "object",
                "required": ["currency", "cashBuyingPower"],
                "properties": {
                    "currency": {
                        "$ref": "#/components/schemas/Currency"
                    },
                    "cashBuyingPower": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "현금 기반 매수 가능 금액 (미수 미발생 기준).\n순수 현금으로 매수할 수 있는 금액.\nKRW: 정수 (원 단위). USD: 소수점 포함 (달러 단위).\n",
                        "example": "5000000"
                    }
                }
            },
            "SellableQuantityResponse": {
                "type": "object",
                "required": ["sellableQuantity"],
                "properties": {
                    "sellableQuantity": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "판매 가능 수량.\nKR: 정수 (주 단위). US: 소수점 포함 가능 (주 단위).\n",
                        "example": "100"
                    }
                }
            },
            "Commission": {
                "type": "object",
                "required": ["marketCountry", "commissionRate"],
                "properties": {
                    "marketCountry": {
                        "$ref": "#/components/schemas/MarketCountry"
                    },
                    "commissionRate": {
                        "type": "string",
                        "format": "decimal",
                        "maxLength": 30,
                        "description": "수수료율 (%). 예: 0.015는 0.015%",
                        "example": "0.015"
                    },
                    "startDate": {
                        "type": ["string", "null"],
                        "format": "date",
                        "description": "수수료 적용 시작일 (YYYY-MM-DD, KST 기준). 해외주식은 null",
                        "example": "2026-01-01"
                    },
                    "endDate": {
                        "type": ["string", "null"],
                        "format": "date",
                        "description": "수수료 적용 종료일 (YYYY-MM-DD, KST 기준). 무기한 적용 시 null",
                        "example": "2026-12-31"
                    }
                }
            }
        }
    },
    "x-tagGroups": [
        {
            "name": "인증",
            "tags": ["Auth"]
        },
        {
            "name": "시세·종목 정보",
            "tags": ["Market Data", "Stock Info", "Market Info"]
        },
        {
            "name": "계좌·자산",
            "tags": ["Account", "Asset"]
        },
        {
            "name": "주문",
            "tags": ["Order", "Order History", "Order Info"]
        }
    ]
}