kiwoom_credentials.hpp File Reference

The examples' Kiwoom credentials: one JSON file per key, or the environment. More...

#include "kis_credentials.hpp"
#include <algotradelib/kiwoom>
#include <filesystem>
#include <optional>
#include <ostream>
#include <stdexcept>
#include <string>
#include <string_view>

Include dependency graph for kiwoom_credentials.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
bool	kiwoom_credentials::valid_label (std::string_view label)
	Tests whether a label can name a file in the credentials directory.
std::optional< std::string >	kiwoom_credentials::take_label (int &argc, char **argv)
	Removes --kiwoom-account LABEL from the command line and returns the label.
void	kiwoom_credentials::refuse_unknown_flags (int argc, char **argv)
	Refuses any flag left on the command line after the credential flags were taken, so a mistyped --kiwoom-acount us stops instead of loading the default label's key.
algotradelib::network::HttpClientOptions	kiwoom_credentials::paced_options ()
	Returns transport options that pace a Kiwoom client at one request a second.
void	kiwoom_credentials::load (const std::optional< std::filesystem::path > &directory, const std::optional< std::string > &label, algotradelib::kiwoom::KiwoomConfig &config, std::ostream &out)
	Loads the credentials from DIR/kiwoom/{demo,real}-LABEL.json (as KIWOOM_DEMO chooses; label kr by default), or from the environment without a directory, and prints where from.

Detailed Description

The examples' Kiwoom credentials: one JSON file per key, or the environment.

Not part of the library. Kiwoom issues one key per account – a Korean-stock account and a US-stock account have a key each – and no request carries an account number: the key is the account. So each key has its own file, named by the environment and a label of your choosing: DIR/kiwoom/demo-kr.json, DIR/kiwoom/demo-us.json, DIR/kiwoom/real-kr.json. --kiwoom-account LABEL picks one (default kr), and KIWOOM_DEMO picks the environment (unset or 1: demo; 0: real). Each file holds appkey, secretkey and demo, as KiwoomConfig::from_json reads them; keep it chmod 600.

The directory is --credentials DIR, else ATL_CREDENTIALS_DIR (kis_credentials::take_directory). With a directory, the environment's KIWOOM_* keys are not read: a directory that lacks the file stops the program rather than falling back, since the environment may hold another account's key. Without one, the examples read KIWOOM_APP_KEY and KIWOOM_SECRET_KEY as before, and a label is refused, because there is nothing for it to select.

A label is the operator's name for an account; the library cannot tell which market a key trades. The Kiwoom adapter calls domestic-stock endpoints only, so a US account's key authenticates and its requests answer as Kiwoom answers them for that account.

Definition in file kiwoom_credentials.hpp.

Function Documentation

load()

void kiwoom_credentials::load ( const std::optional< std::filesystem::path > & directory, const std::optional< std::string > & label, algotradelib::kiwoom::KiwoomConfig & config, std::ostream & out )

inline

Loads the credentials from DIR/kiwoom/{demo,real}-LABEL.json (as KIWOOM_DEMO chooses; label kr by default), or from the environment without a directory, and prints where from.

Parameters

directory	The credentials directory, or std::nullopt to read the environment.
label	The label, or std::nullopt for kr.
config	The configuration to load into.
out	Where to print the source.

Exceptions

std::runtime_error

if a label is given without a directory, or the file or variables are missing, invalid, or contradict the demo setting.

Definition at line 126 of file kiwoom_credentials.hpp.

paced_options()

algotradelib::network::HttpClientOptions kiwoom_credentials::paced_options ( )

inline

Returns transport options that pace a Kiwoom client at one request a second.

A Kiwoom demo account refuses a second request to the same API within a few milliseconds of the first (1700, "허용된 요청 개수를 초과하였습니다", with the API's id): a quote and a price-limit read are both ka10007, so a loop reading both back to back loses one. Requests to different APIs back to back, and to the same API 300 ms apart, were served (measured 2026-10-07). Kiwoom's specification gives no numeric allowance. The library paces nothing unless asked (HttpClientOptions::rate_limit_), so these examples ask, at the pace the KIS examples use.

Returns

The options.

Definition at line 110 of file kiwoom_credentials.hpp.

refuse_unknown_flags()

void kiwoom_credentials::refuse_unknown_flags ( int argc, char ** argv )

inline

Refuses any flag left on the command line after the credential flags were taken, so a mistyped --kiwoom-acount us stops instead of loading the default label's key.

Parameters

argc	The argument count.
argv	The arguments.

Exceptions

std::runtime_error

naming the first unknown flag.

Definition at line 90 of file kiwoom_credentials.hpp.

take_label()

std::optional< std::string > kiwoom_credentials::take_label ( int & argc, char ** argv )

inline

Removes --kiwoom-account LABEL from the command line and returns the label.

Parameters

argc	The argument count; reduced by the arguments removed.
argv	The arguments; the rest are moved down.

Returns

The label, or std::nullopt if the flag is absent.

Exceptions

std::runtime_error

if the flag has no value or the value is not a valid label.

Definition at line 63 of file kiwoom_credentials.hpp.

valid_label()

bool kiwoom_credentials::valid_label ( std::string_view label )

inline

Tests whether a label can name a file in the credentials directory.

Parameters

label

The label.

Returns

true if it is lowercase letters, digits and -, not starting with -.

Definition at line 44 of file kiwoom_credentials.hpp.