Tutorial - KiwoomRestApi.Net

Getting Started

Setup

Prerequisites

.NET 6.0 이상
Visual Studio 2022 또는 VS Code
키움증권 계정 및 API 접근 권한
키움 OpenAPI에서 발급받은 앱 키와 시크릿 키

Installation

NuGet 패키지를 설치하세요:

dotnet add package KiwoomRestApi.Net

Tip: NuGet 패키지 관리자 콘솔에서도 설치할 수 있습니다: Install-Package KiwoomRestApi.Net

Basic Project Setup

using KiwoomRestApi.Net.Clients;

var appKey = "YOUR_APP_KEY";
var secretKey = "YOUR_SECRET_KEY";
var isMock = true; // 실거래의 경우 false로 설정

// 클라이언트 생성
var client = KiwoomRestApiClient.Create(appKey, secretKey, isMock);

Basic Usage

Data

Getting Stock Information

삼성전자(005930)의 기본 주식 정보를 가져와 보겠습니다:

using KiwoomRestApi.Net.Enums.StockInfo;

// 삼성전자(005930) 주식 정보 가져오기
var stockInfo = await client.StockInfo.GetStockInfoAsync(
    stockCode: "005930",
    date: DateTime.Today,
    marginLoanType: KiwoomStockInfoMarginLoanType.Loan
);

if (stockInfo.IsSuccess)
{
    Console.WriteLine($"주식명: {stockInfo.Data?.StockName}");
    Console.WriteLine($"현재가: {stockInfo.Data?.CurrentPrice:N0} KRW");
    Console.WriteLine($"변동률: {stockInfo.Data?.ChangeRate:F2}%");
    Console.WriteLine($"거래량: {stockInfo.Data?.Volume:N0}");
}
else
{
    Console.WriteLine($"오류: {stockInfo.ReturnMessage}");
}

Understanding the Response

모든 API 호출은 KiwoomRestApiResponse<T> 객체를 반환합니다:

Property	Type	Description
`IsSuccess`	`bool`	API 호출 성공 여부
`Data`	`T?`	응답 데이터
`ReturnMessage`	`string?`	응답 메시지
`ApiId`	`string`	API 식별자
`ContYn`	`bool`	페이지네이션 연속 플래그
`NextKey`	`string`	다음 페이지 키

Account Management

Data

Getting Account Balance

using KiwoomRestApi.Net.Enums.Account;

// 평가 잔고 가져오기
var balances = await client.Account.GetEvaluationBalancesAsync(
    queryType: KiwoomAccountEvaluationBalanceQueryType.Aggregate,
    domesticStockExchangeType: KiwoomAccountDomesticStockExchangeType2.Krx
);

if (balances.IsSuccess)
{
    foreach (var balance in balances.Data?.Items)
    {
        Console.WriteLine($"총자산: {balance.TotalEvaluationAmount:N0} KRW");
        Console.WriteLine($"총 손익: {balance.TotalEvaluationProfitLossAmount:N0} KRW");
        Console.WriteLine($"손익률: {balance.TotalProfitRate:F2}%");
    }
}

Getting Daily Status

// 일별 계좌 상태 가져오기
var dailyStatus = await client.Account.GetDailyStatusAsync();

if (dailyStatus.IsSuccess)
{
    Console.WriteLine($"입금액: {dailyStatus.Data?.DepositAmount:N0} KRW");
    Console.WriteLine($"총 매수: {dailyStatus.Data?.BuyAmount:N0} KRW");
    Console.WriteLine($"총 매도: {dailyStatus.Data?.SellAmount:N0} KRW");
}

Warning: 일부 계좌 API는 모의투자 모드에서 사용할 수 없습니다. 전체 기능을 위해 실제 API 키를 사용하세요.

Stock Information

Data

Market Data & Quotes

// 현재 시장 호가 가져오기
var quote = await client.MarketCondition.GetQuoteAsync("005930");

if (quote.IsSuccess)
{
    Console.WriteLine($"현재가: {quote.Data?.CurrentPrice}");
    Console.WriteLine($"최우수 매수가: {quote.Data?.BuyPrice1}");
    Console.WriteLine($"최우수 매도가: {quote.Data?.SellPrice1}");
}

// 호가창 가져오기
var orderBook = await client.MarketCondition.GetOrderBookListAsync("005930");

if (orderBook.IsSuccess)
{
    Console.WriteLine("호가창:");
    var quotes = orderBook.Data;
    for (int i = 0; i < 5; i++)
    {
        Console.WriteLine($"  매도 {i+1}: {quotes?.SellQuotes[i].Price} ({quotes?.SellQuotes[i].Quantity})");
    }
    Console.WriteLine("  --------------------");
    for (int i = 0; i < 5; i++)
    {
        Console.WriteLine($"  매수 {i+1}: {quotes?.BuyQuotes[i].Price} ({quotes?.BuyQuotes[i].Quantity})");
    }
}

Ranking Information

using KiwoomRestApi.Net.Enums.RankingInfo;

// 상위 상승종 가져오기
var gainers = await client.RankingInfo.GetChangeRateTopsAsync(
    marketType: KiwoomRankingInfoMarketType.All,
    sortType: KiwoomRankingInfoChangeSortType.Up,
    minVolume: 100,
    stockCondition: KiwoomRankingInfoStockCondition.All,
    creditCondition: KiwoomRankingInfoCreditCondition.All,
    isIncludeUpDown: true,
    priceCondition: KiwoomRankingInfoPriceCondition.All,
    minTransactionAmount: 1000,
    stockExchangeType: KiwoomRankingInfoStockExchangeType.Unified
);

if (gainers.IsSuccess)
{
    Console.WriteLine("상위 상승종:");
    foreach (var stock in gainers.Data?.Items.Take(5) ?? Enumerable.Empty<KiwoomRankingInfoGetChangeRateTopItem>())
    {
        Console.WriteLine($"{stock.StockName}: {stock.ChangeRate:F2}% ({stock.CurrentPrice})");
    }
}

// 거래량 상위 종목 가져오기
var activeStocks = await client.RankingInfo.GetTodayVolumeTopsAsync(
    marketType: KiwoomRankingInfoMarketType.All,
    sortType: KiwoomRankingInfoVolumeSortType.Volume,
    stockCondition: KiwoomRankingInfoStockCondition.All,
    creditCondition: KiwoomRankingInfoCreditCondition.All,
    minVolume: 100,
    priceCondition: KiwoomRankingInfoPriceCondition2.All,
    minTransactionAmount: 1000,
    marketOpenType: KiwoomRankingInfoMarketOpenType.All,
    stockExchangeType: KiwoomRankingInfoStockExchangeType.Unified
);

if (activeStocks.IsSuccess)
{
    Console.WriteLine("거래량 상위 종목:");
    foreach (var stock in activeStocks.Data?.Items.Take(5) ?? Enumerable.Empty<KiwoomRankingInfoGetTodayVolumeTopItem>())
    {
        Console.WriteLine($"{stock.StockName}: {stock.Volume:N0} 주");
    }
}

Trading Operations

Trading

Important: 거래 작업은 실제 API 키가 필요하며 주의해서 사용해야 합니다. 테스트를 위해 모의투자 모드로 시작하세요.

Placing Orders

using KiwoomRestApi.Net.Enums.Order;

// 매수 주문 예제 (시장가)
var buyOrder = await client.Order.PlaceOrderAsync(
    KiwoomOrderType.Buy,
    KiwoomOrderDomesticStockExchangeType.Krx,
    stockCode: "005930",
    orderQuantity: 10,
    KiwoomOrderTransactionType.Market
);

if (buyOrder.IsSuccess)
{
    Console.WriteLine($"주문 성공. 주문번호: {buyOrder.Data?.OrderId}");
}

// 지정가 주문 예제
var limitOrder = await client.Order.PlaceOrderAsync(
    KiwoomOrderType.Buy,
    KiwoomOrderDomesticStockExchangeType.Krx,
    stockCode: "005930",
    orderQuantity: 10,
    KiwoomOrderTransactionType.Limit,
    orderPrice: 75000  // 지정가
);

Order Management

// 미체결 주문 가져오기
var unfilledOrders = await client.Account.GetUnfilledOrdersAsync(
    KiwoomAccountQueryType.All,
    KiwoomAccountTransactionType.All,
    KiwoomAccountStockExchangeType.Unified
);

if (unfilledOrders.IsSuccess)
{
    foreach (var order in unfilledOrders.Data?.Items)
    {
        Console.WriteLine($"주문: {order.OrderId} - {order.StockName}");
        Console.WriteLine($"유형: {order.TaskType}, 수량: {order.OrderQuantity}");
    }
}

// 주문 취소
var cancelResult = await client.Order.CancelOrderAsync(
    KiwoomOrderDomesticStockExchangeType.Krx,
    originalOrderId: "YOUR_ORDER_NUMBER",
    stockCode: "005930",
    cancelQuantity: 5
);

// 주문 수정
var modifyResult = await client.Order.ModifyOrderAsync(
    KiwoomOrderDomesticStockExchangeType.Krx,
    originalOrderId: "YOUR_ORDER_NUMBER",
    stockCode: "005930",
    modifyQuantity: 15,
    modifyPrice: 76000
);

Chart Data

Data

Basic Charts

다양한 주기의 차트 데이터를 조회할 수 있습니다:

using KiwoomRestApi.Net.Enums.Chart;

var stockCode = "005930";
var date = new DateTime(2026, 3, 1);

// 일봉 차트
var daily = await client.Chart.GetDailyChartsAsync(stockCode, date, false);

// 주봉 차트
var weekly = await client.Chart.GetWeeklyChartsAsync(stockCode, date, false);

// 월봉 차트
var monthly = await client.Chart.GetMonthlyChartsAsync(stockCode, date, false);

// 분봉 차트 (15분)
var minute = await client.Chart.GetMinuteChartsAsync(stockCode, 15, date, false);

// 틱 차트 (30틱)
var tick = await client.Chart.GetTickChartsAsync(stockCode, 30, false);

Range Charts

특정 기간의 차트 데이터를 조회할 수도 있습니다:

var startDate = new DateTime(2026, 1, 1);
var endDate = new DateTime(2026, 3, 6);

// 기간별 일봉 차트
var dailyRange = await client.Chart.GetDailyChartsByRangeAsync(stockCode, startDate, endDate, false);

// 기간별 분봉 차트
var minuteRange = await client.Chart.GetMinuteChartsByRangeAsync(stockCode, 15, startDate, endDate, false);

Industry Charts

// 업종 일봉 차트
var industryDaily = await client.Chart.GetIndustryDailyChartsAsync(
    KiwoomChartIndustryCode.Kospi200, date);

// 업종 분봉 차트 (15분)
var industryMinute = await client.Chart.GetIndustryMinuteChartsAsync(
    KiwoomChartIndustryCode.Kospi200, 15, date);

Gold Spot Charts

using KiwoomRestApi.Net.Enums.Chart;

// 금현물 틱 차트
var goldTick = await client.Chart.GetGoldSpotTickChartsAsync(
    KiwoomGoldSpotStockCode.Gold_1kg, 10, true);

// 금현물 일봉 차트
var goldDaily = await client.Chart.GetGoldSpotDailyChartsAsync(
    KiwoomGoldSpotStockCode.Gold_1kg, date, true);

Real-time Data

WebSocket

Setting up WebSocket Client

using KiwoomRestApi.Net.Enums.WebSocket;

// 소켓 클라이언트 생성
var socketClient = KiwoomSocketClient.Create(client.Token, isMock: true);

// 실시간 주식 체결 데이터 구독
await socketClient.WebSocket.SubscribeAsync(
    serviceNames: [KiwoomWebSocketServiceName.StockTrade],
    parameters: ["005930", "000660", "035420"],
    groupId: "1"
);

Handling Real-time Events

// 주식 체결 이벤트
socketClient.OnRealtimeStockTradeReceived += (realtimeData) =>
{
    foreach (var data in realtimeData)
    {
        Console.WriteLine($"[{data.Item}] {data.Values.CurrentPrice} " +
                         $"({data.Values.ChangeRate:F2}%) " +
                         $"거래량: {data.Values.AccumulatedVolume:N0}");
    }
};

// 주문 체결 이벤트
socketClient.OnRealtimeOrderTradeReceived += (orderData) =>
{
    foreach (var order in orderData)
    {
        Console.WriteLine($"주문 업데이트: {order.Values.OrderId} - {order.Values.OrderStatus}");
    }
};

// 잔고 이벤트
socketClient.OnRealtimeBalanceReceived += (balanceData) =>
{
    foreach (var balance in balanceData)
    {
        Console.WriteLine($"잔고 업데이트: {balance.Values.StockName}");
        Console.WriteLine($"보유 수량: {balance.Values.HoldingQuantity}");
    }
};

Available Services

Service	Enum Value	Description
주식 체결	`StockTrade`	실시간 주식 체결 데이터
주식 호가	`OrderBook`	실시간 호가 데이터
잔고	`Balance`	실시간 잔고 변동
주문 체결	`OrderTrade`	실시간 주문 체결
VI 발동	`ViEvent`	VI(변동성 완화장치) 발동
ETF NAV	`EtfNav`	ETF NAV 데이터

Advanced Features

Advanced

Pagination

대량의 데이터를 조회할 때 페이지네이션을 사용할 수 있습니다:

// 첫 페이지 조회
var firstPage = await client.Chart.GetTickChartsAsync("005930", 1, false);

// 다음 페이지가 있으면
if (firstPage.ContYn)
{
    client.ContYn = true;
    client.NextKey = firstPage.NextKey;

    var secondPage = await client.Chart.GetTickChartsAsync("", 1, false);

    // 초기화
    client.ContYn = false;
    client.NextKey = "";
}

Pagination Loop

모든 페이지를 순회하는 방법입니다:

// 모든 페이지를 순회하는 루프
var response = await client.Chart.GetTickChartsAsync("005930", 1, false);

while (response.IsSuccess)
{
    foreach (var item in response.Data?.Items ?? Enumerable.Empty<KiwoomChartGetTickChartItem>())
    {
        Console.WriteLine($"{item.CurrentPrice}");
    }

    if (!response.ContYn) break;

    client.ContYn = true;
    client.NextKey = response.NextKey;
    response = await client.Chart.GetTickChartsAsync("", 1, false);
}

client.ContYn = false;
client.NextKey = "";

Gold Spot Trading

using KiwoomRestApi.Net.Enums.Order;
using KiwoomRestApi.Net.Enums.Chart;

// 금현물 매수 주문
var goldBuy = await client.Order.GoldSpotPlaceOrderAsync(
    KiwoomOrderType.Buy,
    KiwoomGoldSpotStockCode.MiniGold_100g,
    orderQuantity: 1,
    KiwoomOrderGoldSpotTransactionType.Normal
);

// 금현물 잔고 조회
var goldBalances = await client.Account.GetGoldEvaluationBalancesAsync();

// 금현물 예수금 조회
var goldDeposit = await client.Account.GetGoldDepositAsync(
    KiwoomAccountEvaluationBalanceQueryType.Aggregate,
    KiwoomAccountDomesticStockExchangeType.All
);

Condition Search

// 조건검색 목록 조회
await socketClient.WebSocket.GetConditionSearchListAsync();

// 조건검색 실시간 구독
await socketClient.WebSocket.GetConditionSearchRequestRealtimeAsync(1);

Error Handling

Advanced

Handling API Errors

try
{
    var result = await client.StockInfo.GetStockInfoAsync(
        stockCode: "005930",
        date: DateTime.Today,
        marginLoanType: KiwoomStockInfoMarginLoanType.Loan
    );

    if (!result.IsSuccess)
    {
        Console.WriteLine($"API Error [{result.ApiId}]: {result.ReturnMessage}");
        return;
    }

    // 성공 처리
    Console.WriteLine($"Stock: {result.Data?.StockName}");
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"HTTP Error: {ex.Message}");
}
catch (TaskCanceledException)
{
    Console.WriteLine("Request timed out.");
}
catch (Exception ex)
{
    Console.WriteLine($"Unexpected error: {ex.Message}");
}

Note: API 오류는 IsSuccess == false로 반환됩니다. 네트워크 오류 등은 예외로 발생합니다.

Best Practices

Setup

Connection Management

// IDisposable을 활용한 적절한 해제
using var client = KiwoomRestApiClient.Create(appKey, secretKey, isMock);
using var socketClient = KiwoomSocketClient.Create(client.Token, isMock);

// API 호출...

Rate Limiting

API 호출 시 속도 제한을 구현하는 것이 좋습니다:

// PagingDelay 속성을 활용한 페이지네이션 지연
client.PagingDelay = 1000; // 페이지 간 1초 지연 (ms)

// 또는 SemaphoreSlim을 사용한 수동 제한
private readonly SemaphoreSlim _semaphore = new(1, 1);

public async Task<T> ExecuteWithLimitAsync<T>(Func<Task<T>> apiCall)
{
    await _semaphore.WaitAsync();
    try
    {
        var result = await apiCall();
        await Task.Delay(TimeSpan.FromMilliseconds(100));
        return result;
    }
    finally
    {
        _semaphore.Release();
    }
}

Pro Tip: 개발 및 테스트 시에는 항상 모의투자 모드로 시작하세요. 프로덕션 준비가 되었을 때만 실제 API 키로 전환하세요.