![]() |
algotradelib 0.0.0.9000
C++ header-only library for algorithmic trading
|
The asynchronous Kiwoom REST client: market data, account inquiries and orders for domestic stocks. More...
#include <algotradelib/src/brokers/kiwoom/client.hpp>
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 |
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.
| 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.
| 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.
| 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.
| 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.
| 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.
| using algotradelib::kiwoom::KiwoomClient::HoldingsHandler = net::any_completion_handler<void(Result<HoldingsSnapshot>)> |
Completion handler for one normalized holdings snapshot.
Definition at line 900 of file client.hpp.
| 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.
| using algotradelib::kiwoom::KiwoomClient::OpenOrderHandler = net::any_completion_handler<void(Result<KiwoomOpenOrderPage>)> |
Completion handler for one page of modifiable or cancellable orders.
Definition at line 912 of file client.hpp.
| using algotradelib::kiwoom::KiwoomClient::OrderableHandler = net::any_completion_handler<void(Result<KiwoomOrderableAmount>)> |
Completion handler for Kiwoom's per-margin-tier orderable amounts and quantities.
Definition at line 906 of file client.hpp.
| 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.
| 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.
| 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.
| 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.
| 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.
| 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.
|
inline |
Constructs a client; nothing is sent until the first request.
| executor | The executor its strand runs on. |
| context | The TLS context; borrowed, and must outlive the client. |
| config | The credentials, environment and holdings settings. |
| options | HTTP options (set rate_limit_ to pace requests). |
Definition at line 925 of file client.hpp.
|
inline |
Requests the one account the bound credential drives, from ka00001 계좌번호조회.
| CompletionToken | An Asio completion token. |
| token | The completion token. |
Definition at line 1228 of file client.hpp.
Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::accounts().
|
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.
| CompletionToken | An Asio completion token. |
Definition at line 1080 of file client.hpp.
Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::bars().
|
inline |
Requests what the account may spend, from kt00001 예수금상세현황요청.
| CompletionToken | An Asio completion token. |
| currency | The currency; anything but KRW is refused before sending. |
| account | The bound account. |
| token | The completion token. |
Definition at line 1145 of file client.hpp.
Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::buying_power().
|
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.
| CompletionToken | An Asio completion token. |
| account | The account (empty). |
| amendment | The order and quantity (zero for all remaining). |
| token | The completion token, called with Result<KiwoomOrderAck>. |
Definition at line 1347 of file client.hpp.
Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::cancel_order().
|
inline |
Requests Kiwoom's own fuller deposit detail, which async_buying_power reads one field of.
| CompletionToken | An Asio completion token. |
| token | The completion token. |
Definition at line 1168 of file client.hpp.
|
inline |
Requests the resting orders on both sides of the book, from ka10004 주식호가요청.
| CompletionToken | An Asio completion token. |
| instrument | The instrument. |
| token | The completion token. |
Definition at line 998 of file client.hpp.
Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::depth().
|
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_.
| CompletionToken | An Asio completion token. |
| account | The account (empty). |
| token | The completion token, called with Result<HoldingsSnapshot>. |
Definition at line 1121 of file client.hpp.
Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::holdings().
|
inline |
Requests static reference data for one instrument, from ka10100 종목정보 조회.
| CompletionToken | An Asio completion token. |
| instrument | The instrument. |
| token | The completion token. |
Definition at line 1049 of file client.hpp.
Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::instrument().
|
inline |
Requests every order still open to amendment, paging ka10075 미체결요청.
| CompletionToken | An Asio completion token. |
| account | The bound account. |
| token | The completion token. |
Definition at line 1375 of file client.hpp.
Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::working_orders().
|
inline |
Requests one day of order history, paging kt00007 계좌별주문체결내역상세요청.
| CompletionToken | An Asio completion token. |
| account | The bound account. |
| query | The query. |
| token | The completion token. |
Definition at line 1399 of file client.hpp.
Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::order_history().
|
inline |
Requests what may be ordered of one instrument, per margin tier (kt00010).
| CompletionToken | An Asio completion token. |
| instrument | The instrument. |
| side | The side. |
| price | The unit price to evaluate at (uv), or empty to send none. |
| token | The completion token, called with Result<KiwoomOrderableAmount>. |
Definition at line 1192 of file client.hpp.
|
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.
| CompletionToken | An Asio completion token. |
| account | The account (empty). |
| order | The order. |
| token | The completion token, called with Result<KiwoomOrderAck>. |
Definition at line 1274 of file client.hpp.
Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::place_order().
|
inline |
Requests today's upper and lower price bound, from the same ka10007 response.
| CompletionToken | An Asio completion token. |
| instrument | The instrument. |
| token | The completion token. |
Definition at line 972 of file client.hpp.
Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::price_limits().
|
inline |
Requests and normalizes a current quote, from ka10007 시세표성정보요청.
| CompletionToken | An Asio completion token. |
| instrument | The instrument. |
| token | The completion token. |
Definition at line 946 of file client.hpp.
Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::quote().
|
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.
| CompletionToken | An Asio completion token. |
| account | The account (empty). |
| amendment | The amendment. |
| token | The completion token, called with Result<KiwoomOrderAck>. |
Definition at line 1305 of file client.hpp.
Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::replace_order().
|
inline |
Requests recent executions, newest first, from ka10003 체결정보요청.
| CompletionToken | An Asio completion token. |
| instrument | The instrument. |
| count | The most trades to return. |
| token | The completion token. |
Definition at line 1025 of file client.hpp.
Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::trades().
|
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.
|
inlinenoexcept |
Returns the configuration (the session reads its holdings assertions from it).
Definition at line 1099 of file client.hpp.
Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::holdings(), and KiwoomClient().
|
inlinenoexcept |
Returns the client's strand.
Definition at line 1105 of file client.hpp.
Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::holdings().
|
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).
Definition at line 1427 of file client.hpp.
Referenced by algotradelib::BrokerTraits< kiwoom::KiwoomClient >::rate_limit_stats().
|
friend |
Definition at line 1440 of file client.hpp.