algotradelib 0.0.0.9000
C++ header-only library for algorithmic trading
Loading...
Searching...
No Matches
algotradelib::kiwoom::KiwoomClient Class Reference

The asynchronous Kiwoom REST client: market data, account inquiries and orders for domestic stocks. More...

#include <algotradelib/src/brokers/kiwoom/client.hpp>

Inheritance diagram for algotradelib::kiwoom::KiwoomClient:
Collaboration diagram for algotradelib::kiwoom::KiwoomClient:

Public Types

using QuoteHandler = net::any_completion_handler<void(Result<QuoteSnapshot>)>
 Completion handler for one normalized quote.
using BarsHandler = net::any_completion_handler<void(Result<BarSeries>)>
 Completion handler for one normalized bar series.
using DepthHandler = net::any_completion_handler<void(Result<DepthSnapshot>)>
 Completion handler for one normalized order book.
using PriceLimitsHandler = net::any_completion_handler<void(Result<PriceLimits>)>
 Completion handler for one instrument's price bounds.
using TradesHandler = net::any_completion_handler<void(Result<std::vector<TradePrint>>)>
 Completion handler for recent executions.
using InstrumentHandler = net::any_completion_handler<void(Result<Instrument>)>
 Completion handler for one instrument's reference data.
using HoldingsHandler = net::any_completion_handler<void(Result<HoldingsSnapshot>)>
 Completion handler for one normalized holdings snapshot.
using BuyingPowerHandler = net::any_completion_handler<void(Result<BuyingPower>)>
 Completion handler for one normalized buying-power reading.
using DepositHandler = net::any_completion_handler<void(Result<KiwoomDeposit>)>
 Completion handler for Kiwoom's own fuller deposit detail.
using OrderableHandler = net::any_completion_handler<void(Result<KiwoomOrderableAmount>)>
 Completion handler for Kiwoom's per-margin-tier orderable amounts and quantities.
using AccountsHandler = net::any_completion_handler<void(Result<std::vector<KiwoomAccountInfo>>)>
 Completion handler for the one account the bound credential drives.
using OrderAckHandler = net::any_completion_handler<void(Result<KiwoomOrderAck>)>
 Completion handler for one Kiwoom order acknowledgement.
using OpenOrderHandler = net::any_completion_handler<void(Result<KiwoomOpenOrderPage>)>
 Completion handler for one page of modifiable or cancellable orders.
using OrderPageHandler = net::any_completion_handler<void(Result<OrderPage>)>
 Completion handler for one normalized page of order history.
using TokenHandler = net::any_completion_handler<void(std::optional<BrokerError>)>
 Internal completion handler for a shared access-token refresh.

Public Member Functions

 KiwoomClient (net::any_io_executor executor, ssl::context &context, KiwoomConfig config, network::HttpClientOptions options={})
 Constructs a client; nothing is sent until the first request.
template<typename CompletionToken>
auto async_quote (InstrumentId instrument, CompletionToken &&token)
 Requests and normalizes a current quote, from ka10007 시세표성정보요청.
template<typename CompletionToken>
auto async_price_limits (InstrumentId instrument, CompletionToken &&token)
 Requests today's upper and lower price bound, from the same ka10007 response.
template<typename CompletionToken>
auto async_depth (InstrumentId instrument, CompletionToken &&token)
 Requests the resting orders on both sides of the book, from ka10004 주식호가요청.
template<typename CompletionToken>
auto async_trades (InstrumentId instrument, int count, CompletionToken &&token)
 Requests recent executions, newest first, from ka10003 체결정보요청.
template<typename CompletionToken>
auto async_instrument (InstrumentId instrument, CompletionToken &&token)
 Requests static reference data for one instrument, from ka10100 종목정보 조회.
template<typename CompletionToken>
auto async_bars (BarQuery query, CompletionToken &&token)
 Requests bars, following Kiwoom's continuation pages from before_'s Korean date (or today).
const KiwoomConfig & config () const noexcept
 Returns the configuration (the session reads its holdings assertions from it).
net::strand< net::any_io_executor > get_executor () const noexcept
 Returns the client's strand.
template<typename CompletionToken>
auto async_holdings (KiwoomAccount account, CompletionToken &&token)
 Requests the holdings kt00018 lists for KiwoomConfig::holdings_venue_ (refused before sending until it is KRX or NXT); whether that is every holding is what KiwoomConfig::holdings_position_scope_ asserts, which this call does not check.
template<typename CompletionToken>
auto async_buying_power (Currency currency, KiwoomAccount account, CompletionToken &&token)
 Requests what the account may spend, from kt00001 예수금상세현황요청.
template<typename CompletionToken>
auto async_deposit (CompletionToken &&token)
 Requests Kiwoom's own fuller deposit detail, which async_buying_power reads one field of.
template<typename CompletionToken>
auto async_orderable_amount (InstrumentId instrument, OrderSide side, std::optional< Decimal64 > price, CompletionToken &&token)
 Requests what may be ordered of one instrument, per margin tier (kt00010).
template<typename CompletionToken>
auto async_accounts (CompletionToken &&token)
 Requests the one account the bound credential drives, from ka00001 계좌번호조회.
template<typename CompletionToken>
auto async_place_order (KiwoomAccount account, OrderRequest order, CompletionToken &&token)
 Places an order (kt10000 buy, kt10001 sell).
template<typename CompletionToken>
auto async_replace_order (KiwoomAccount account, KiwoomAmendment amendment, CompletionToken &&token)
 Amends an order's quantity, price or trigger price (kt10002).
template<typename CompletionToken>
auto async_cancel_order (KiwoomAccount account, KiwoomAmendment amendment, CompletionToken &&token)
 Cancels an order, all or part of it (kt10003).
template<typename CompletionToken>
auto async_open_orders (KiwoomAccount account, CompletionToken &&token)
 Requests every order still open to amendment, paging ka10075 미체결요청.
template<typename CompletionToken>
auto async_order_history (KiwoomAccount account, KiwoomHistoryQuery query, CompletionToken &&token)
 Requests one day of order history, paging kt00007 계좌별주문체결내역상세요청.
const network::RateLimitStats * rate_limit_stats () const
 Returns the rate limiter's statistics.
void close ()
 Closes the client for good: pending requests, and later ones that would send, complete with CANCELLED. A request already being sent has reached_broker_ set and an unknown outcome. A request refused before sending is still refused.

Friends

struct KiwoomClientTestAccess

Detailed Description

The asynchronous Kiwoom REST client: market data, account inquiries and orders for domestic stocks.

It requests an access token when first needed and shares one refresh among concurrent requests. Create it with std::make_shared. Each completion runs on the handler's associated executor, or on the client's strand if it has none. Before trading, state the holdings settings in KiwoomConfig. A blocking wrapper is KiwoomBlockingClient.

Definition at line 885 of file client.hpp.

Member Typedef Documentation

◆ AccountsHandler

using algotradelib::kiwoom::KiwoomClient::AccountsHandler = net::any_completion_handler<void(Result<std::vector<KiwoomAccountInfo>>)>

Completion handler for the one account the bound credential drives.

Definition at line 908 of file client.hpp.

◆ BarsHandler

using algotradelib::kiwoom::KiwoomClient::BarsHandler = net::any_completion_handler<void(Result<BarSeries>)>

Completion handler for one normalized bar series.

Definition at line 890 of file client.hpp.

◆ BuyingPowerHandler

using algotradelib::kiwoom::KiwoomClient::BuyingPowerHandler = net::any_completion_handler<void(Result<BuyingPower>)>

Completion handler for one normalized buying-power reading.

Definition at line 902 of file client.hpp.

◆ DepositHandler

using algotradelib::kiwoom::KiwoomClient::DepositHandler = net::any_completion_handler<void(Result<KiwoomDeposit>)>

Completion handler for Kiwoom's own fuller deposit detail.

Definition at line 904 of file client.hpp.

◆ DepthHandler

using algotradelib::kiwoom::KiwoomClient::DepthHandler = net::any_completion_handler<void(Result<DepthSnapshot>)>

Completion handler for one normalized order book.

Definition at line 892 of file client.hpp.

◆ HoldingsHandler

Completion handler for one normalized holdings snapshot.

Definition at line 900 of file client.hpp.

◆ InstrumentHandler

using algotradelib::kiwoom::KiwoomClient::InstrumentHandler = net::any_completion_handler<void(Result<Instrument>)>

Completion handler for one instrument's reference data.

Definition at line 898 of file client.hpp.

◆ OpenOrderHandler

Completion handler for one page of modifiable or cancellable orders.

Definition at line 912 of file client.hpp.

◆ OrderableHandler

Completion handler for Kiwoom's per-margin-tier orderable amounts and quantities.

Definition at line 906 of file client.hpp.

◆ OrderAckHandler

using algotradelib::kiwoom::KiwoomClient::OrderAckHandler = net::any_completion_handler<void(Result<KiwoomOrderAck>)>

Completion handler for one Kiwoom order acknowledgement.

Definition at line 910 of file client.hpp.

◆ OrderPageHandler

using algotradelib::kiwoom::KiwoomClient::OrderPageHandler = net::any_completion_handler<void(Result<OrderPage>)>

Completion handler for one normalized page of order history.

Definition at line 914 of file client.hpp.

◆ PriceLimitsHandler

using algotradelib::kiwoom::KiwoomClient::PriceLimitsHandler = net::any_completion_handler<void(Result<PriceLimits>)>

Completion handler for one instrument's price bounds.

Definition at line 894 of file client.hpp.

◆ QuoteHandler

using algotradelib::kiwoom::KiwoomClient::QuoteHandler = net::any_completion_handler<void(Result<QuoteSnapshot>)>

Completion handler for one normalized quote.

Definition at line 888 of file client.hpp.

◆ TokenHandler

using algotradelib::kiwoom::KiwoomClient::TokenHandler = net::any_completion_handler<void(std::optional<BrokerError>)>

Internal completion handler for a shared access-token refresh.

Definition at line 916 of file client.hpp.

◆ TradesHandler

using algotradelib::kiwoom::KiwoomClient::TradesHandler = net::any_completion_handler<void(Result<std::vector<TradePrint>>)>

Completion handler for recent executions.

Definition at line 896 of file client.hpp.

Constructor & Destructor Documentation

◆ KiwoomClient()

algotradelib::kiwoom::KiwoomClient::KiwoomClient ( net::any_io_executor executor,
ssl::context & context,
KiwoomConfig config,
network::HttpClientOptions options = {} )
inline

Constructs a client; nothing is sent until the first request.

Parameters
executorThe executor its strand runs on.
contextThe TLS context; borrowed, and must outlive the client.
configThe credentials, environment and holdings settings.
optionsHTTP options (set rate_limit_ to pace requests).

Definition at line 925 of file client.hpp.

Member Function Documentation

◆ async_accounts()

template<typename CompletionToken>
auto algotradelib::kiwoom::KiwoomClient::async_accounts ( CompletionToken && token)
inline

Requests the one account the bound credential drives, from ka00001 계좌번호조회.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
tokenThe completion token.
Returns
Whatever the completion token returns.

Definition at line 1228 of file client.hpp.

Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::accounts().

◆ async_bars()

template<typename CompletionToken>
auto algotradelib::kiwoom::KiwoomClient::async_bars ( BarQuery query,
CompletionToken && token )
inline

Requests bars, following Kiwoom's continuation pages from before_'s Korean date (or today).

before_ applies by day only: minute bars later than it on the same date are returned. A short series comes back only when Kiwoom has no more. next_cursor_ is set when the series is full and Kiwoom said there is more, and never for minute bars. If Kiwoom offers more but its continuation key is blank, a page adds nothing, or 50 pages were read, the request fails (PROTOCOL, incomplete_listing) instead of returning a partial series. Refused before sending: count_ of zero or less, or a symbol that is not Korean or malformed.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
queryThe query.
tokenThe completion token, called with Result<BarSeries>.
Returns
Whatever the completion token returns.

Definition at line 1080 of file client.hpp.

Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::bars().

◆ async_buying_power()

template<typename CompletionToken>
auto algotradelib::kiwoom::KiwoomClient::async_buying_power ( Currency currency,
KiwoomAccount account,
CompletionToken && token )
inline

Requests what the account may spend, from kt00001 예수금상세현황요청.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
currencyThe currency; anything but KRW is refused before sending.
accountThe bound account.
tokenThe completion token.
Returns
Whatever the completion token returns.

Definition at line 1145 of file client.hpp.

Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::buying_power().

◆ async_cancel_order()

template<typename CompletionToken>
auto algotradelib::kiwoom::KiwoomClient::async_cancel_order ( KiwoomAccount account,
KiwoomAmendment amendment,
CompletionToken && token )
inline

Cancels an order, all or part of it (kt10003).

After an error of unknown outcome (see async_place_order) the order may still rest. Refused before sending, among others: a cancellation without a venue, an order number or a symbol; a fractional or negative quantity; or one carrying a price or trigger price.

Two refusals are recognized as refusals, each from its own server only: the demo server's RC4033 (nothing left to amend or cancel) and the real server's 506550 (no quantity left to cancel) are INVALID_ARGUMENT with reached_broker_ set (kiwoom_recognized_refusal). Each says the cancellation did nothing, not what became of the order: it may have filled. Either code from the other server stays PROTOCOL.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
accountThe account (empty).
amendmentThe order and quantity (zero for all remaining).
tokenThe completion token, called with Result<KiwoomOrderAck>.
Returns
Whatever the completion token returns.

Definition at line 1347 of file client.hpp.

Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::cancel_order().

◆ async_deposit()

template<typename CompletionToken>
auto algotradelib::kiwoom::KiwoomClient::async_deposit ( CompletionToken && token)
inline

Requests Kiwoom's own fuller deposit detail, which async_buying_power reads one field of.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
tokenThe completion token.
Returns
Whatever the completion token returns.

Definition at line 1168 of file client.hpp.

◆ async_depth()

template<typename CompletionToken>
auto algotradelib::kiwoom::KiwoomClient::async_depth ( InstrumentId instrument,
CompletionToken && token )
inline

Requests the resting orders on both sides of the book, from ka10004 주식호가요청.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
instrumentThe instrument.
tokenThe completion token.
Returns
Whatever the completion token returns.

Definition at line 998 of file client.hpp.

Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::depth().

◆ async_holdings()

template<typename CompletionToken>
auto algotradelib::kiwoom::KiwoomClient::async_holdings ( KiwoomAccount account,
CompletionToken && token )
inline

Requests the holdings kt00018 lists for KiwoomConfig::holdings_venue_ (refused before sending until it is KRX or NXT); whether that is every holding is what KiwoomConfig::holdings_position_scope_ asserts, which this call does not check.

The snapshot fails if one symbol appears on two rows or paging stops while Kiwoom offers more. Its sellable_basis_ follows KiwoomConfig::holdings_sellable_scope_.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
accountThe account (empty).
tokenThe completion token, called with Result<HoldingsSnapshot>.
Returns
Whatever the completion token returns.

Definition at line 1121 of file client.hpp.

Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::holdings().

◆ async_instrument()

template<typename CompletionToken>
auto algotradelib::kiwoom::KiwoomClient::async_instrument ( InstrumentId instrument,
CompletionToken && token )
inline

Requests static reference data for one instrument, from ka10100 종목정보 조회.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
instrumentThe instrument.
tokenThe completion token.
Returns
Whatever the completion token returns.

Definition at line 1049 of file client.hpp.

Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::instrument().

◆ async_open_orders()

template<typename CompletionToken>
auto algotradelib::kiwoom::KiwoomClient::async_open_orders ( KiwoomAccount account,
CompletionToken && token )
inline

Requests every order still open to amendment, paging ka10075 미체결요청.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
accountThe bound account.
tokenThe completion token.
Returns
Whatever the completion token returns.

Definition at line 1375 of file client.hpp.

Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::working_orders().

◆ async_order_history()

template<typename CompletionToken>
auto algotradelib::kiwoom::KiwoomClient::async_order_history ( KiwoomAccount account,
KiwoomHistoryQuery query,
CompletionToken && token )
inline

Requests one day of order history, paging kt00007 계좌별주문체결내역상세요청.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
accountThe bound account.
queryThe query.
tokenThe completion token.
Returns
Whatever the completion token returns.

Definition at line 1399 of file client.hpp.

Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::order_history().

◆ async_orderable_amount()

template<typename CompletionToken>
auto algotradelib::kiwoom::KiwoomClient::async_orderable_amount ( InstrumentId instrument,
OrderSide side,
std::optional< Decimal64 > price,
CompletionToken && token )
inline

Requests what may be ordered of one instrument, per margin tier (kt00010).

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
instrumentThe instrument.
sideThe side.
priceThe unit price to evaluate at (uv), or empty to send none.
tokenThe completion token, called with Result<KiwoomOrderableAmount>.
Returns
Whatever the completion token returns.

Definition at line 1192 of file client.hpp.

◆ async_place_order()

template<typename CompletionToken>
auto algotradelib::kiwoom::KiwoomClient::async_place_order ( KiwoomAccount account,
OrderRequest order,
CompletionToken && token )
inline

Places an order (kt10000 buy, kt10001 sell).

The request is never resent. After an error for which runner::outcome_of returns INDETERMINATE (BrokerError::reached_broker_ set and a category of TRANSPORT, CANCELLED or PROTOCOL, or HTTP with a status of 500 or more), the order may exist. That includes a reply without an order number and an unrecognized failure code Kiwoom declares but does not document (both PROTOCOL). Read async_open_orders or async_order_history before placing again, since Kiwoom has no idempotency key.

Some refusals are recognized as refusals, each from its own server only: the demo server's 800033 (not enough to sell), RC4057 (the market has not opened) and RC4058 (the market has closed), and the real server's 571445 (no securities balance), are INVALID_ARGUMENT with reached_broker_ set, which runner::outcome_of reads as REJECTED (kiwoom_recognized_refusal). A demo code from the real server, or the real code from the demo server, stays PROTOCOL, as does every other refusal this client does not classify further (its documented error codes keep their categories).

Refused before sending, among others: an instrument that is not Korean or whose venue_ is not COMBINED (route with OrderRequest::venue_); no venue on the order; a client order id; a quantity that is not a positive whole number; a missing, non-positive or fractional price on a priced type, or a price on an unpriced one; a trigger price missing or invalid on STOP_LIMIT, or present on another type; a shape Kiwoom has no code for; and any order while KiwoomConfig::holdings_position_scope_ is not stated.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
accountThe account (empty).
orderThe order.
tokenThe completion token, called with Result<KiwoomOrderAck>.
Returns
Whatever the completion token returns.

Definition at line 1274 of file client.hpp.

Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::place_order().

◆ async_price_limits()

template<typename CompletionToken>
auto algotradelib::kiwoom::KiwoomClient::async_price_limits ( InstrumentId instrument,
CompletionToken && token )
inline

Requests today's upper and lower price bound, from the same ka10007 response.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
instrumentThe instrument.
tokenThe completion token.
Returns
Whatever the completion token returns.

Definition at line 972 of file client.hpp.

Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::price_limits().

◆ async_quote()

template<typename CompletionToken>
auto algotradelib::kiwoom::KiwoomClient::async_quote ( InstrumentId instrument,
CompletionToken && token )
inline

Requests and normalizes a current quote, from ka10007 시세표성정보요청.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
instrumentThe instrument.
tokenThe completion token.
Returns
Whatever the completion token returns.

Definition at line 946 of file client.hpp.

Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::quote().

◆ async_replace_order()

template<typename CompletionToken>
auto algotradelib::kiwoom::KiwoomClient::async_replace_order ( KiwoomAccount account,
KiwoomAmendment amendment,
CompletionToken && token )
inline

Amends an order's quantity, price or trigger price (kt10002).

After an error of unknown outcome (see async_place_order) the amendment may have been made. Refused before sending, among others: an amendment without a venue, an order number or a symbol; a fractional or negative quantity; a fractional price; an invalid trigger price; and any amendment while KiwoomConfig::holdings_position_scope_ is not stated.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
accountThe account (empty).
amendmentThe amendment.
tokenThe completion token, called with Result<KiwoomOrderAck>.
Returns
Whatever the completion token returns.

Definition at line 1305 of file client.hpp.

Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::replace_order().

◆ async_trades()

template<typename CompletionToken>
auto algotradelib::kiwoom::KiwoomClient::async_trades ( InstrumentId instrument,
int count,
CompletionToken && token )
inline

Requests recent executions, newest first, from ka10003 체결정보요청.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
instrumentThe instrument.
countThe most trades to return.
tokenThe completion token.
Returns
Whatever the completion token returns.

Definition at line 1025 of file client.hpp.

Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::trades().

◆ close()

void algotradelib::kiwoom::KiwoomClient::close ( )
inline

Closes the client for good: pending requests, and later ones that would send, complete with CANCELLED. A request already being sent has reached_broker_ set and an unknown outcome. A request refused before sending is still refused.

Definition at line 1437 of file client.hpp.

◆ config()

const KiwoomConfig & algotradelib::kiwoom::KiwoomClient::config ( ) const
inlinenoexcept

Returns the configuration (the session reads its holdings assertions from it).

Returns
The configuration.

Definition at line 1099 of file client.hpp.

Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::holdings(), and KiwoomClient().

◆ get_executor()

net::strand< net::any_io_executor > algotradelib::kiwoom::KiwoomClient::get_executor ( ) const
inlinenoexcept

Returns the client's strand.

Returns
The strand.

Definition at line 1105 of file client.hpp.

Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::holdings().

◆ rate_limit_stats()

const network::RateLimitStats * algotradelib::kiwoom::KiwoomClient::rate_limit_stats ( ) const
inline

Returns the rate limiter's statistics.

Read them on the client's strand or while no request is in progress (between calls on the blocking client).

Returns
The statistics, or null if the client has no rate-limit budget.

Definition at line 1427 of file client.hpp.

Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::rate_limit_stats().

◆ KiwoomClientTestAccess

friend struct KiwoomClientTestAccess
friend

Definition at line 1440 of file client.hpp.


The documentation for this class was generated from the following file: