FAQ - KiwoomRestApi.Net

Getting Started

+

키움 OpenAPI 앱 키와 시크릿 키는 어떻게 발급받나요?

키움증권 영웅문 홈페이지의 Open API 섹션에서 앱 키를 발급받을 수 있습니다.

발급 절차:

1. 키움증권 홈페이지에 로그인
2. Open API > API 신청 메뉴로 이동
3. 앱 이름과 용도를 입력하여 신청
4. 승인 후 앱 키(App Key)와 시크릿 키(Secret Key)를 확인

발급받은 키는 외부에 노출되지 않도록 안전하게 관리하세요. 환경 변수나 KeyVault 등을 활용하는 것이 좋습니다.

+

지원하는 .NET 버전은 무엇인가요?

.NET 6.0 이상을 지원합니다.

.NET STANDARD 2.0, 2.1, .NET 6, 7, 8, 10 모두 호환됩니다.

+

NuGet 패키지는 어떻게 설치하나요?

다음 방법 중 하나로 설치할 수 있습니다:

.NET CLI:

dotnet add package KiwoomRestApi.Net

NuGet 패키지 관리자 콘솔:

PM> Install-Package KiwoomRestApi.Net

+

모의투자와 실거래의 차이는 무엇인가요?

클라이언트 생성 시 isMock 파라미터로 구분합니다:

/* 모의투자 (테스트용) */
var client = KiwoomRestApiClient.Create(appKey, secretKey, isMock: true);

/* 실거래 */
var client = KiwoomRestApiClient.Create(appKey, secretKey, isMock: false);

모의투자 모드에서는 일부 API(출금, 특정 계좌 조회 등)가 제한될 수 있습니다.

모의투자와 실거래는 각각 별도의 앱 키가 필요합니다.

💡 API 연동 없이 매매 전략만 가볍게 검증해보고 싶다면 모의투자 게임 플랫폼 ox64.app도 참고해보세요.

Authentication

+

접근 토큰은 자동으로 관리되나요?

네. KiwoomRestApiClient.Create 또는 CreateAsync를 호출하면 자동으로 OAuth 2.0 접근 토큰이 발급됩니다. 클라이언트 내부에서 토큰을 관리하므로 별도로 처리할 필요가 없습니다.

/* Create 시 자동으로 토큰 발급 */
var client = KiwoomRestApiClient.Create(appKey, secretKey, isMock: true);

/* 토큰 수동 접근 */
var token = client.Token;

+

토큰 만료 시 어떻게 되나요?

키움 REST API의 접근 토큰은 발급 후 일정 시간이 지나면 만료됩니다. 만료된 경우 새로운 클라이언트를 생성하거나 GetAccessTokenAsync를 호출하여 토큰을 재발급받아야 합니다.

API Usage

+

페이지네이션은 어떻게 처리하나요?

대량의 데이터를 조회할 때는 응답의 ContYn과 NextKey를 사용하여 페이지네이션을 처리합니다:

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

if (result.ContYn)
{
    client.ContYn = true;
    client.NextKey = result.NextKey;
    var nextPage = await client.Chart.GetTickChartsAsync("", 1, false);
}

+

API 호출 속도 제한이 있나요?

키움 REST API에는 초당 호출 횟수 제한이 있습니다. 제한을 초과하면 에러가 반환됩니다.

PagingDelay 속성을 사용하여 페이지네이션 시 자동으로 지연을 줄 수 있습니다:

client.PagingDelay = 1000; // 페이지 간 1초 지연

+

어떤 Enum 타입을 사용해야 하나요?

모든 API 파라미터는 타입 안전한 Enum으로 제공됩니다. 각 API 메서드의 파라미터에 맞는 Enum을 사용하면 됩니다:

/* 각 네임스페이스별 Enum */
using KiwoomRestApi.Net.Enums.Account;
using KiwoomRestApi.Net.Enums.StockInfo;
using KiwoomRestApi.Net.Enums.Order;
using KiwoomRestApi.Net.Enums.Chart;
// ... 기타

전체 Enum 목록은 API Reference의 Enums 섹션에서 확인할 수 있습니다.

+

모의투자에서 사용할 수 없는 API가 있나요?

네, 일부 API는 모의투자 모드에서 지원되지 않습니다:

모의투자 미지원 API 예시:

• 출금 가능 금액 조회 (GetAvailableWithdrawalAmountsAsync)
• 위탁계좌 체결내역 조회 (GetConsignedTransactionsAsync)
• 신용융자주문 조회 (GetCreditDepositOrdersAsync)
• 대출/신용 관련 API
• 금현물 주문 (Gold Spot 주문/수정/취소)

API Reference에서 no mock 태그가 있는 API는 모의투자에서 사용할 수 없습니다.

WebSocket / Real-time

+

WebSocket 실시간 데이터는 어떻게 시작하나요?

REST API 클라이언트에서 토큰을 가져와 WebSocket 클라이언트를 생성한 후, 구독할 서비스와 종목 코드를 지정합니다:

var socketClient = KiwoomSocketClient.Create(client.Token, isMock: true);

/* 이벤트 핸들러 등록 */
socketClient.OnRealtimeStockTradeReceived += (data) => {
    // 체결 데이터 처리
};

/* 구독 시작 */
await socketClient.WebSocket.SubscribeAsync(
    serviceNames: [KiwoomWebSocketServiceName.StockTrade],
    parameters: ["005930"],
    groupId: "1"
);

+

어떤 실시간 서비스를 사용할 수 있나요?

다음 실시간 서비스를 지원합니다:

• StockTrade — 주식 체결 데이터
• OrderBook — 주식 호가
• Balance — 잔고
• OrderTrade — 주문 체결
• ViEvent — VI 발동
• EtfNav — ETF NAV
• ElwTheoreticalPrice — ELW 이론가
• ElwIndicator — ELW 지표
• StockInfo — 주식 기본 정보
• BestQuote — 우선호가
• StockTrend — 주식 추이
• ExpectedTrade — 예상 체결
• IndustryIndex — 업종 지수
• IndustryChange — 업종 등락
• ProgramTransaction — 프로그램 매매
• DailyBroker — 일중 증권사
• MarketOpenTime — 장시작 시간
• AfterMarketQuote — 주식시간외호가
• InternationalGoldPrice — 국제금환산가격

+

WebSocket 연결이 끊어지면 어떻게 되나요?

WebSocket 연결이 끊어지면 이벤트 수신이 중단됩니다. 자동 재연결 로직을 직접 구현해야 합니다:

try
{
    await socketClient.WebSocket.SubscribeAsync(...);
}
catch (WebSocketException)
{
    // 재연결 로직
    await Task.Delay(TimeSpan.FromSeconds(5));
    socketClient = KiwoomSocketClient.Create(client.Token, isMock);
    await socketClient.WebSocket.SubscribeAsync(...);
}

Trading

+

시장가와 지정가 주문의 차이는 무엇인가요?

TransactionType 파라미터로 구분합니다:

/* 시장가 주문 - 즉시 체결 */
await client.Order.PlaceOrderAsync(
    orderType: KiwoomOrderType.Buy,
    domesticStockExchangeType: KiwoomOrderDomesticStockExchangeType.Krx,
    stockCode: "005930",
    orderQuantity: 10,
    transactionType: KiwoomOrderTransactionType.Market
);

/* 지정가 주문 - 특정 가격에 체결 */
await client.Order.PlaceOrderAsync(
    orderType: KiwoomOrderType.Buy,
    domesticStockExchangeType: KiwoomOrderDomesticStockExchangeType.Krx,
    stockCode: "005930",
    orderQuantity: 10,
    transactionType: KiwoomOrderTransactionType.Normal,
    orderPrice: 75000
);

+

주문을 취소하거나 수정할 수 있나요?

네, 미체결 주문에 대해 취소 및 수정이 가능합니다:

/* 주문 취소 */
await client.Order.CancelOrderAsync(
    domesticStockExchangeType: KiwoomOrderDomesticStockExchangeType.Krx,
    originalOrderId: "주문번호",
    stockCode: "005930",
    cancelQuantity: 5
);

/* 주문 수정 (수량, 가격 변경) */
await client.Order.ModifyOrderAsync(
    domesticStockExchangeType: KiwoomOrderDomesticStockExchangeType.Krx,
    originalOrderId: "주문번호",
    stockCode: "005930",
    modifyQuantity: 15,
    modifyPrice: 76000
);

+

금현물 거래도 지원하나요?

네, 금현물 거래를 완벽하게 지원합니다:

/* 금현물 매수 */
await client.Order.GoldSpotPlaceOrderAsync(
    orderType: KiwoomOrderType.Buy,
    stockCode: KiwoomGoldSpotStockCode.MiniGold_100g,
    orderQuantity: 1,
    transactionType: KiwoomOrderGoldSpotTransactionType.Normal
);

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

금현물 거래는 모의투자 모드에서 지원되지 않습니다.

Troubleshooting

+

"접근토큰 발급에 실패했습니다" 오류가 발생합니다.

다음 사항을 확인하세요:

• 앱 키와 시크릿 키가 올바른지 확인
• 모의투자/실거래에 맞는 키를 사용 중인지 확인
• 키움증권에서 API 승인이 완료되었는지 확인
• 앱 키에 공백이 포함되지 않았는지 확인

+

API 호출 시 "조회가능한 건수를 초과하였습니다" 에러가 발생합니다.

키움 REST API의 호출 횟수 제한을 초과한 경우입니다. 다음 방법으로 해결할 수 있습니다:

• API 호출 사이에 적절한 지연을 추가하세요
• PagingDelay 속성을 사용하여 페이지네이션 간 지연을 설정하세요
• 불필요한 API 호출을 줄이세요

+

응답 데이터가 null로 반환됩니다.

다음을 확인하세요:

• IsSuccess가 true인지 확인
• 조회 조건(날짜, 종목 코드 등)이 올바른지 확인
• 해당 날짜에 거래 데이터가 존재하는지 확인 (휴일, 장외 시간 등)
• 모의투자 모드에서 지원되는 API인지 확인

+

WebSocket 이벤트가 수신되지 않습니다.

다음을 확인하세요:

• SubscribeAsync가 정상적으로 호출되었는지 확인
• 이벤트 핸들러가 SubscribeAsync 호출 이전에 등록되었는지 확인
• 종목 코드가 올바른지 확인
• 장 시간 중인지 확인 (일부 서비스는 장 시간에만 동작)
• REST API 클라이언트와 동일한 모의투자/실거래 모드인지 확인