한국투자증권 API, Kotlin에서 사용해보기

한국투자증권에서 제공하는 API를 kt_kisopenapi 라이브러리로 Kotlin에서 사용해봅시다.

2025년 2월 7일 오후 11:14

chevron_right

서론

국내 증권사에서는 API를 제공해도 원도우 HTS와 연동되어 있어 사용에 불편함이 있다. 2022년 4월 11에 한국투자증권에서는 KIS Developers라는 이름으로 HTTP/Websocket API를 제공하기 시작했다[1]. LS증권에서도 2023년 7월 7일에 OPEN API 서비스를 오픈했다(당시 이베스트투자증권)[2]. 이들 API를 사용하면 원도우 HTS를 사용하지 않고도 증권사의 정보를 받아올 수 있다. 이번 글에서는 한국투자증권에서 제공하는 API를 Java/Kotlin에서 사용하는 방법을 소개한다.

사전 설정

여기의 설명을 따라 app key와 app secret를 발급받는다. 발급받은 app key와 app secret는 안전하게 보관해야 한다.

라이브러리 소개

kt_kisopenapi 라이브러리는 한국투자증권 API의 Kotlin wrapper이다. 이 글을 쓰는 시점의 최신 버전은 0.2.5이다. MIT License로 배포된다.

이 라이브러리는 이 글의 저자가 개발한 것이며, 한국투자증권과는 무관한 비공식 라이브러리임에 유의하자. 사용에 따른 책임은 본인에게 있다.

다른 라이브러리

Python
- Soju06/python-kis: 작성 당시 ⭐159, MIT License
- pjueon/pykis: 작성 당시 ⭐48, Apache License 2.0

설치

build.gradle.kts에 다음을 추가한다.

implementation("io.github.devngho:kt_kisopenapi:[VERSION]")

implementation("io.github.devngho:kt_kisopenapi:[VERSION]")

사용법

클라이언트 초기화

val client = KISApiClient.with(
    appKey = "[앱 키]",
    appSecret = "[앱 시크릿]",
    account = "[계좌번호]",
    id = "[HTS ID]",
)

val client = KISApiClient.with(
    appKey = "[앱 키]",
    appSecret = "[앱 시크릿]",
    account = "[계좌번호]",
    id = "[HTS ID]",
)

account와 id는 반드시 필요하지는 않지만, 계좌 잔액 조회 등의 기능에 필요하다.

위 코드를 호출하면 기본적으로 API 토큰을 발급한다.

주가 조회

val stock = client.stockDomestic("005930")

stock.update(StockPrice::class, BaseProductInfo::class)

println("${stock.name}: ${stock.price.price}")

val stock = client.stockDomestic("005930")

stock.update(StockPrice::class, BaseProductInfo::class)

println("${stock.name}: ${stock.price.price}")

위 코드는 삼성전자의 주가를 조회하는 코드이다. update 함수는 정보를 업데이트하는 함수로, 여기서는 주가와 기본 정보를 동시에 업데이트한다.

val stock = client.stockDomestic("005930")

stock.update<StockPrice>()

println("${stock.ticker}: ${stock.price.price}")

val stock = client.stockDomestic("005930")

stock.update<StockPrice>()

println("${stock.ticker}: ${stock.price.price}")

하나의 정보만 업데이트할 때는 위와 같이 사용할 수 있다.

println(InquirePrice(client).call(InquirePrice.InquirePriceData(ticker="005930")).value?.output?.price)

println(InquirePrice(client).call(InquirePrice.InquirePriceData(ticker="005930")).value?.output?.price)

API를 직접 호출하는 방법도 있다.

해외주식 조회

val stock = client.stockOverseas("AAPL", OverseasMarket.NASDAQ)

stock.update(StockOverseasPrice::class, BaseProductInfo::class)

println("${stock.name}: ${stock.price.price}")

val stock = client.stockOverseas("AAPL", OverseasMarket.NASDAQ)

stock.update(StockOverseasPrice::class, BaseProductInfo::class)

println("${stock.name}: ${stock.price.price}")

해외주식에서는 거래소를 지정해야 한다.

매매

// 지정가 주문
stock.buy(
    count = BigInteger(1),
    type = OrderTypeCode.SelectPrice,
    price = BigInteger.fromInt(53700)
)

stock.sell(
    count = BigInteger(1),
    type = OrderTypeCode.SelectPrice,
    price = BigInteger.fromInt(53700)
)

// 시장가 주문
stock.buy(
    count = BigInteger(1),
    type = OrderTypeCode.MarketPrice
)

stock.sell(
    count = BigInteger(1),
    type = OrderTypeCode.MarketPrice
)

// 지정가 주문
stock.buy(
    count = BigInteger(1),
    type = OrderTypeCode.SelectPrice,
    price = BigInteger.fromInt(53700)
)

stock.sell(
    count = BigInteger(1),
    type = OrderTypeCode.SelectPrice,
    price = BigInteger.fromInt(53700)
)

// 시장가 주문
stock.buy(
    count = BigInteger(1),
    type = OrderTypeCode.MarketPrice
)

stock.sell(
    count = BigInteger(1),
    type = OrderTypeCode.MarketPrice
)

매매는 buy와 sell 함수를 사용한다. 해외주식의 경우에는 price를 BigDecimal로 넘겨야 한다.

정정, 취소

val order = stock.buy(
    count = BigInteger(1),
    type = OrderTypeCode.SelectPrice,
    price = BigInteger.fromInt(53700)
).getOrThrow() /* OrderBuy.OrderResponse (sell도 동일) */

// 정정
stock.amend(
    order = order,
    count = BigInteger(1),
    type = OrderTypeCode.SelectPrice,
    price = BigInteger.fromInt(53800),
    orderAll = true
)

// 취소
stock.cancel(
    order = order,
    count = BigInteger(1),
    type = OrderTypeCode.SelectPrice,
    orderAll = true
)

val order = stock.buy(
    count = BigInteger(1),
    type = OrderTypeCode.SelectPrice,
    price = BigInteger.fromInt(53700)
).getOrThrow() /* OrderBuy.OrderResponse (sell도 동일) */

// 정정
stock.amend(
    order = order,
    count = BigInteger(1),
    type = OrderTypeCode.SelectPrice,
    price = BigInteger.fromInt(53800),
    orderAll = true
)

// 취소
stock.cancel(
    order = order,
    count = BigInteger(1),
    type = OrderTypeCode.SelectPrice,
    orderAll = true
)

정정은 amend 함수를, 취소는 cancel 함수를 사용한다. orderAll은 주문 전량을 정정할지 여부를 나타낸다.

마치며

이 라이브러리의 추가적인 기능은 javadocs를 참고하자.

이 글에서는 kt_kisopenapi 라이브러리를 사용해 한국투자증권 API를 Kotlin에서 사용하는 방법을 소개했다. 이를 통해 주식 정보를 분석하거나 매매를 자동화하는 등 다양한 기능을 구현할 수 있다. 이 글이 도움이 되었기를 바란다.

참고 자료

[1]
한국투자증권, “KIS Developers 4/11 정식 오픈,” KIS Developers, https://apiportal.koreainvestment.com/community/10000000-0000-0011-0000-000000000001. [Accessed 2 7 2025].
[↑]
[2]
LS증권, “이베스트투자증권 OPEN API 서비스 정식 오픈(2023.07.07),” LS증권 OPEN API, https://openapi.ls-sec.co.kr/community/10000000-0000-0011-0000-000000000001. [Accessed 2 7 2025].
[↑]

인용하기

BibTeX

@misc{devngho202520250207ktkisopenapi,
  author       = {Yu, Dongho},
  title        = {한국투자증권 API, Kotlin에서 사용해보기},
  howpublished = {\url{https://ngho.dev/posts/20250207ktkisopenapi}},
  year         = {2025},
  month        = {feb},
  note         = {Accessed: 2025-02-08}
}

@misc{devngho202520250207ktkisopenapi,
  author       = {Yu, Dongho},
  title        = {한국투자증권 API, Kotlin에서 사용해보기},
  howpublished = {\url{https://ngho.dev/posts/20250207ktkisopenapi}},
  year         = {2025},
  month        = {feb},
  note         = {Accessed: 2025-02-08}
}

APA 유동호. (2025년 2월 7일). 한국투자증권 API, Kotlin에서 사용해보기. devngho 블로그. https://ngho.dev/posts/20250207ktkisopenapi

Chicago 유동호. “한국투자증권 API, Kotlin에서 사용해보기.” devngho 블로그, 2025년 2월 7일, https://ngho.dev/posts/20250207ktkisopenapi.

MLA 유동호. “한국투자증권 API, Kotlin에서 사용해보기.” devngho 블로그, 2025년 2월 7일, https://ngho.dev/posts/20250207ktkisopenapi.