{ "openapi": "3.1.0", "info": { "title": "토스증권 Open API", "version": "1.1.1" }, "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`, 종료된 주문 `CLOSED`)을 선택해 주문 목록을 조회하고, 개별 `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` -- FILLED, CANCELED, REJECTED, REPLACED 등 종료 상태 주문을 반환합니다.\n\nsymbol을 지정하면 해당 종목의 주문만 필터링하여 반환합니다.\n\n**페이징 동작:**\n- `status=OPEN`: 모든 대기 중 주문을 전량 반환합니다. `limit`, `cursor` 는 무시되며, `from`/`to` 만 주문 생성일(`orderedAt`, KST 기준) 범위 필터로 적용됩니다 (미지정 시 전체 기간).\n- `status=CLOSED`: `limit` (기본 20, 최대 100), `cursor`, `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`: 종료된 주문 그룹 — `orders[].status` ∈ `{FILLED, CANCELED, REJECTED, REPLACED, CANCEL_REJECTED, REPLACE_REJECTED, PARTIAL_FILLED}`\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", "schema": { "type": "string", "format": "date" }, "example": "2026-03-01" }, { "name": "to", "in": "query", "required": false, "description": "조회 종료일 (inclusive, KST 기준). 주문 생성 시간(`orderedAt`) 기준. 미지정 시 전체 기간.\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` 에서는 무시됩니다 (전량 반환). `CLOSED` 에서는 적용됩니다 (기본 20, 최대 100).\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" ] } } } }, "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" ] } ] }