로드된 토스증권 OpenAPI 명세의 요약 정보를 반환합니다. 버전, 서버 URL, tag 목록, operation 수, 실주문 활성화 상태, snapshot/원격 사용 여부를 포함합니다.

등록된 operation 목록을 필터링해 반환합니다. tag, method, path, readOnly, destructive, keyword 로 필터링할 수 있습니다.

operationId, summary, description, path, tag 를 대상으로 operation 을 검색합니다.

특정 operationId 의 상세 정보(method, path, tag, 설명, 필수/선택 입력, requestBody, 응답 스키마, 계좌 헤더 필요 여부, mutation 여부, rate limit 그룹, MCP 도구 이름)를 반환합니다.

operationId 로 임의의 토스증권 API operation 을 호출합니다. 직접 도구 등록을 지원하지 않는 클라이언트를 위한 wrapper 입니다. 이 wrapper 도 동일한 mutation guard 를 통과하므로 주문 안전정책을 우회할 수 없습니다 (dryRun 기본 true).

인증 설정과 토큰 준비 상태를 안전하게 반환합니다. client ID 는 마스킹되며 client secret 과 access token 은 절대 반환하지 않습니다.

access token 을 명시적으로 재발급합니다. 토큰 문자열은 반환하지 않고 만료 정보만 반환합니다.

계좌 목록 조회

사용자의 계좌 목록을 조회합니다.

• 현재는 종합매매 (BROKERAGE) 계좌만 반환하며, 계좌가 없으면 빈 배열. 자녀계좌는 사용할 수 없습니다.

• 응답의 accountSeq 는 다른 모든 사용자 컨텍스트 API (보유 주식, 주문, 매수가능금액 등) 의 X-Tossinvest-Account 헤더에 사용합니다.

• accountType enum 은 BROKERAGE / OVERSEAS_DERIVATIVES / PENSION_SAVINGS / RESHORING_INVESTMENT 가 정의되어 있으나 본 API 에서는 현재 BROKERAGE 만 노출됩니다. enum 의미는 Account.accountType schema 참조.

Rate Limits Group: ACCOUNT

[GET /api/v1/accounts]

tags: Account

매수 가능 금액 조회

매수 주문 시 사용할 수 있는 매수 가능 금액을 조회합니다. 미수거래를 제외한 현금 기반 매수 가능 금액(미수 미발생 기준)을 반환합니다.

Rate Limits Group: ORDER_INFO

[GET /api/v1/buying-power]

tags: Order Info

캔들 차트 조회

종목의 캔들(OHLCV) 차트 데이터를 조회합니다. 최대 200개 봉을 반환합니다.

Rate Limits Group: MARKET_DATA_CHART

[GET /api/v1/candles]

tags: Market Data

매매 수수료 조회

현재 계좌의 시장별 매매 수수료율을 조회합니다. 국내주식과 해외주식의 수수료 정보를 배열로 반환합니다.

Rate Limits Group: ORDER_INFO

[GET /api/v1/commissions]

tags: Order Info

조건주문 목록 조회

조건주문 목록을 조회합니다.

모든 타입 반환: 이 API 로 등록한 조건주문뿐 아니라 다른 채널(토스증권 앱 등)에서 등록한 조건주문도 함께 반환됩니다. 타입별 필터는 제공하지 않으며, 응답의 type 필드로 구분합니다.

지원하는 status 값:

• OPEN: 진행 중(감시 중·일시중지·주문 진행 중 포함) 조건주문

• CLOSED: 종료된(완료·만료) 조건주문

symbol 을 지정하면 해당 종목의 조건주문만 반환합니다. OPEN/CLOSED 모두에서 사용할 수 있습니다.

페이징: 커서 기반. 응답의 nextCursor 를 다음 요청의 cursor 로 전달합니다. limit 기본 20, 최대 100.

Rate Limits Group: CONDITIONAL_ORDER_HISTORY

[GET /api/v1/conditional-orders]

tags: Conditional Order History

조건주문 생성

특정 종목의 가격을 감시해 조건 충족 시 자동으로 매매(매수/매도)하는 조건주문을 생성합니다.

감시가와 매매 방향(매수/매도)을 설정한 후 가격이 감시가에 도달하면 조건이 발동되어 주문이 생성됩니다.

타입(type) — 조건의 개수와 관계를 정합니다:

• SINGLE: first 한 조건만 감시합니다.

• OCO (One-Cancels-the-Other): 두 조건(first·second)을 동시에 감시하다, 하나의 조건이 충족되면 나머지 조건은 자동 취소됩니다. first/second 모두 매도(SELL) 이며 first 감시가 > 현재가 > second 감시가 여야 합니다. 호가유형은 지정가(LIMIT)만 지원합니다.

• OTO (One-Triggers-the-Other): first 조건이 체결되면 그때부터 second 조건 감시가 시작됩니다. first 는 매수(BUY), second 는 매도(SELL) 입니다. 호가유형은 지정가(LIMIT)만 지원합니다.

Rate Limits Group: CONDITIONAL_ORDER

[POST /api/v1/conditional-orders]

tags: Conditional Order

⚠️ 실제 자산에 영향을 주는 조건주문 API 입니다. 기본값은 dryRun=true 이며 실행하려면 TOSSINVEST_ENABLE_CONDITIONAL_ORDERS=true 와 confirmation 이 필요합니다.

조건주문 상세 조회

조건주문 단건 상세를 조회합니다. 진행 중 + 종료된 조건주문을 모두 조회할 수 있습니다. conditionalOrderId 로 조건주문을 식별합니다.

Rate Limits Group: CONDITIONAL_ORDER_HISTORY

[GET /api/v1/conditional-orders/{conditionalOrderId}]

tags: Conditional Order History

조건주문 취소

조건주문을 취소합니다. conditionalOrderId 로 취소 대상을 식별합니다.

Rate Limits Group: CONDITIONAL_ORDER

[DELETE /api/v1/conditional-orders/{conditionalOrderId}]

tags: Conditional Order

⚠️ 실제 자산에 영향을 주는 조건주문 API 입니다. 기본값은 dryRun=true 이며 실행하려면 TOSSINVEST_ENABLE_CONDITIONAL_ORDERS=true 와 confirmation 이 필요합니다.

조건주문 수정

조건주문을 수정합니다. 조건주문 전체를 재설정하므로 본문에 type·expireDate·first(필요 시 second) 를 모두 전달합니다. 수량(quantity)은 각 감시 조건(first/second) 안에 입력합니다. (등록과 달리 expireDate 가 필수입니다.) 종목은 conditionalOrderId 로 식별되므로 본문에 symbol 은 필요 없습니다. 본문의 type 은 변경 결과 타입이며, 타입 전환(예: SINGLE→OCO)이 허용됩니다. 응답의 type 으로 확인하세요.

conditionalOrderId 로 수정 대상을 식별합니다.

주의: 수정은 기존 조건주문을 취소하고 새 조건주문을 생성하는 방식으로 동작합니다. 따라서 수정 후에는 새로운 conditionalOrderId 가 발급되고 기존 ID 는 무효화됩니다. 이후 조회·수정·취소에는 반드시 응답으로 반환된 conditionalOrderId 를 사용하세요.

Rate Limits Group: CONDITIONAL_ORDER

[POST /api/v1/conditional-orders/{conditionalOrderId}/modify]

tags: Conditional Order

⚠️ 실제 자산에 영향을 주는 조건주문 API 입니다. 기본값은 dryRun=true 이며 실행하려면 TOSSINVEST_ENABLE_CONDITIONAL_ORDERS=true 와 confirmation 이 필요합니다.

환율 조회

KRW ↔ USD 환율 정보를 조회합니다.

• 갱신 주기 1분, 참고용 표시 환율. 실제 주문 시 적용되는 거래 환율과 다를 수 있습니다.

• dateTime 미지정 시 현재 시점의 유효 환율이 응답됩니다.

• 응답의 validFrom ~ validUntil 은 해당 환율의 유효 시간 윈도 (보통 1분) 입니다.

Rate Limits Group: MARKET_INFO

[GET /api/v1/exchange-rate]

tags: Market Info

보유 주식 조회

보유 주식 정보를 조회합니다. 국내(KR)·미국(US) 주식만 포함하며, 해외 옵션·채권은 제외합니다. 보유 종목이 없으면 요약 금액은 0이고 items는 빈 배열입니다.

Rate Limits Group: ASSET

[GET /api/v1/holdings]

tags: Asset

국내 장 운영 정보 조회

국내 시장의 거래 가능 시간을 조회합니다. 통합 모드 (KRX+NXT) 기준이며, 특수장(시간외종가/시간외단일가)은 제외됩니다. 전일/당일/익일 3영업일 정보를 반환합니다. 모든 시간은 KST(+09:00) 기준.

Rate Limits Group: MARKET_INFO

[GET /api/v1/market-calendar/KR]

tags: Market Info

해외 장 운영 정보 조회

미국 시장의 장 운영 시간을 조회합니다. 4 세션(dayMarket, preMarket, regularMarket, afterMarket) 별로 nullable. 휴장 시 4 세션 모두 null. 전일/당일/익일 3영업일 정보를 반환합니다. 모든 시간은 KST(+09:00) 기준.

Rate Limits Group: MARKET_INFO

[GET /api/v1/market-calendar/US]

tags: Market Info

시장 지표 현재가 조회

시장 지표(국내 지수·국채)의 현재가를 조회합니다. 최대 200건 까지 다건 조회를 지원하며 콤마(,)로 구분합니다.

지원 심볼은 그룹 상단 Market Indicators 설명의 심볼 카탈로그(8종)를 따르며, 카탈로그에 없는 심볼은 400 unsupported-symbol 로 응답합니다.

Rate Limits Group: MARKET_INDICATOR

[GET /api/v1/market-indicators/prices]

tags: Market Indicators

시장 지표 캔들 차트 조회

시장 지표(국내 지수·국채)의 캔들(OHLCV) 차트 데이터를 조회합니다. 최대 200개 봉을 반환합니다.

지원 심볼은 그룹 상단 Market Indicators 설명의 심볼 카탈로그(8종)와 동일하며, 카탈로그에 없는 심볼은 400 unsupported-symbol 로 응답합니다. 개별 종목의 캔들은 GET /api/v1/candles 를 사용하세요.

분봉(1m)은 지수(KOSPI·KOSDAQ)만 지원합니다. 국채(KR_BOND_*)는 일봉(1d)만 지원하며, 분봉 요청 시 400 invalid-request 로 응답합니다.

Rate Limits Group: MARKET_INDICATOR_CHART

[GET /api/v1/market-indicators/{symbol}/candles]

tags: Market Indicators

투자자별 매매대금 조회

KRX 시장(코스피·코스닥)의 투자자별 매매대금을 조회합니다. 개인·외국인·기관·기타법인 4개 투자자 분류의 매수·매도 거래대금을 집계 단위(interval)별 기록으로 최신순 제공하며, 기관은 7개 세부 분류(breakdown)를 함께 제공합니다.

• KOSPI / KOSDAQ 만 지원합니다. 그 외 심볼은 400 unsupported-symbol 로 응답합니다.

• 모든 거래대금은 원화(KRW) 정수이며, 별도의 통화 필드는 제공하지 않습니다.

• 4개 분류(개인·외국인·기관·기타법인)의 매수 합계와 매도 합계는 시장 전체 기준으로 서로 같습니다.

• foreigner 는 외국인 전체 합계(등록·미등록 외국인 포함)이며, institution 의 buyAmount/sellAmount 는 breakdown 7개 항목의 합과 일치합니다.

• 당일 기록은 장 종료 전까지 갱신될 수 있는 잠정치입니다. updatedAt 으로 마지막 갱신 시각을 확인하세요.

• 다음 페이지는 응답의 nextUntil 값을 until 파라미터로 전달해 조회합니다.

Rate Limits Group: MARKET_INDICATOR

[GET /api/v1/market-indicators/{symbol}/investor-trading]

tags: Market Indicators

호가 조회

매수/매도 호가 및 잔량을 조회합니다.

Rate Limits Group: MARKET_DATA

[GET /api/v1/orderbook]

tags: Market Data

주문 목록 조회

주문 목록을 조회합니다. status 파라미터로 주문 상태를 필터링합니다.

지원하는 status 값:

• 진행 중 주문: OPEN -- PENDING, PARTIAL_FILLED, PENDING_CANCEL, PENDING_REPLACE 상태의 주문을 반환

• 종료된 주문: CLOSED -- FILLED, CANCELED, REJECTED, REPLACED 등 종료 상태 주문을 반환합니다.

symbol을 지정하면 해당 종목의 주문만 필터링하여 반환합니다.

페이징 동작:

• status=OPEN: 모든 대기 중 주문을 전량 반환합니다. limit, cursor 는 무시되며, from/to 만 주문 생성일(orderedAt, KST 기준) 범위 필터로 적용됩니다 (미지정 시 전체 기간).

• status=CLOSED: limit (기본 20, 최대 100), cursor, from/to 파라미터 모두 적용됩니다.

Rate Limits Group: ORDER_HISTORY

[GET /api/v1/orders]

tags: Order History

주문 생성

매수 또는 매도 주문을 생성합니다.

수량 지정 방식 — quantity, orderAmount 중 정확히 하나를 사용:

• quantity: 주문 수량 (주 단위). 지정한 수량만큼 주문. 소수점 수량은 미국 주식 시장가 매도(MARKET+SELL)에만 허용 (그 외는 정수만)

• orderAmount: 주문 금액 (달러). 지정한 금액만큼 주문하며, 체결 수량은 시장가에 따라 결정. US MARKET 전용

금액 주문 (orderAmount): 정규장 시간에만 가능합니다. 정규장 외 시간에 호출 시 422 amount-order-outside-regular-hours 를 반환합니다.

Rate Limits Group: ORDER

[POST /api/v1/orders]

tags: Order

⚠️ 실제 자산에 영향을 주는 주문 API 입니다. 기본값은 dryRun=true 이며 실행하려면 TOSSINVEST_ENABLE_TRADING=true 와 confirmation 이 필요합니다.

주문 상세 조회

특정 주문의 상세 정보를 조회합니다. 모든 주문 상태(체결 완료, 취소, 거부 등)의 주문을 조회할 수 있습니다.

Rate Limits Group: ORDER_HISTORY

[GET /api/v1/orders/{orderId}]

tags: Order History

주문 취소

기존 주문을 취소합니다. 이미 체결된 주문은 취소할 수 없습니다.

Rate Limits Group: ORDER

[POST /api/v1/orders/{orderId}/cancel]

tags: Order

⚠️ 실제 자산에 영향을 주는 주문 API 입니다. 기본값은 dryRun=true 이며 실행하려면 TOSSINVEST_ENABLE_TRADING=true 와 confirmation 이 필요합니다.

주문 정정

기존 주문의 가격 또는 수량을 정정합니다.

KR 주식: quantity 필수. 양의 정수만 허용합니다.

US 주식: quantity 제공 불가. 가격 변경만 지원합니다. quantity 제공 시 400 us-modify-quantity-not-supported 에러를 반환합니다.

Rate Limits Group: ORDER

[POST /api/v1/orders/{orderId}/modify]

tags: Order

⚠️ 실제 자산에 영향을 주는 주문 API 입니다. 기본값은 dryRun=true 이며 실행하려면 TOSSINVEST_ENABLE_TRADING=true 와 confirmation 이 필요합니다.

상/하한가 조회

종목의 당일 상한가 및 하한가를 조회합니다.

Rate Limits Group: MARKET_DATA

[GET /api/v1/price-limits]

tags: Market Data

현재가 조회

종목의 현재가 정보를 조회합니다. 최대 200건 까지 다건 조회를 지원하며 콤마(,)로 구분합니다.

Rate Limits Group: MARKET_DATA

[GET /api/v1/prices]

tags: Market Data

주식 랭킹 조회

지정한 시장(marketCountry) · 기간(duration) · 기준(type)의 주식 랭킹을 조회합니다. 상위 100위까지 제공합니다.

• TOP_GAINERS / TOP_LOSERS 는 duration=realtime 을 지원하지 않습니다 (400 unsupported-ranking-duration).

• tradingVolume / tradingAmount 의 집계 기준은 type 이 결정합니다 — TOSS_SECURITIES_* 는 토스증권 체결 기준, 그 외(MARKET_* / TOP_*)는 시장 전체 기준.

• price.basePrice 는 TOP_GAINERS / TOP_LOSERS 만 duration 시작 시점 기준가이며, 나머지 타입은 duration 과 무관하게 항상 전일 기준가입니다. price.changeRate 도 같은 의미를 따릅니다 (기간 등락률 vs 전일 대비 등락률).

• 응답 항목 수는 count 보다 적을 수 있습니다 (시세 조회에 실패한 종목은 제외).

• 랭킹이 집계되지 않은 조합은 에러가 아닌 빈 rankings 배열로 응답하며, 이때 rankedAt 은 null 입니다.

Rate Limits Group: RANKING

[GET /api/v1/rankings]

tags: Ranking

판매 가능 수량 조회

특정 종목의 판매 가능 수량을 조회합니다.

Rate Limits Group: ORDER_INFO

[GET /api/v1/sellable-quantity]

tags: Order Info

종목 기본 정보 조회

종목의 기본 정보를 조회합니다. symbols 를 콤마로 구분하여 최대 200건 까지 다건 조회를 지원합니다. 종목명, 시장, 통화, 상장 상태, 거래정지 여부 등 트레이딩에서 필요한 참조 데이터를 제공합니다.

Rate Limits Group: STOCK

[GET /api/v1/stocks]

tags: Stock Info

매수 유의사항 조회

종목의 매수 유의사항 및 변동성 완화(VI) 발동 정보를 조회합니다.

포함 종류: 정리매매(LIQUIDATION_TRADING), 단기과열종목(OVERHEATED), 투자경고(INVESTMENT_WARNING), 투자위험(INVESTMENT_RISK), VI 정적/동적/혼합(VI_STATIC / VI_DYNAMIC / VI_STATIC_AND_DYNAMIC), 신주인수권(STOCK_WARRANTS). 전체 enum 은 StockWarning.warningType 참조.

"활성"의 시간 기준: 응답 시점 기준으로 startDate <= 오늘 <= endDate 인 항목 (또는 endDate 가 null 인 진행 중 항목).

응답 정렬: startDate 내림차순 (최근 발동된 항목부터). startDate 가 동일한 경우 정렬 순서는 보장되지 않습니다.

데이터 적시성: VI 발동/해제는 거래소 이벤트 발생 후 수 초 내 반영됩니다. 정리매매·단기과열·투자경고/위험 지정은 거래소 공시 기준 일배치로 반영됩니다.

미존재 vs 빈 배열:

• 종목 자체가 없으면 404 stock-not-found.

• 종목은 있으나 활성 유의사항이 없으면 200 OK + result: [].

Rate Limits Group: STOCK

[GET /api/v1/stocks/{symbol}/warnings]

tags: Stock Info

최근 체결 내역 조회

당일 최근 체결 내역을 조회합니다.

Rate Limits Group: MARKET_DATA

[GET /api/v1/trades]

tags: Market Data