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

The asynchronous Toss Securities REST client: market data, accounts and orders. More...

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

Inheritance diagram for algotradelib::tossinvest::TossClient:
Collaboration diagram for algotradelib::tossinvest::TossClient:

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 PricesHandler = net::any_completion_handler<void(Result<std::vector<QuoteSnapshot>>)>
 Completion handler for several instruments quoted at once.
using CalendarHandler = net::any_completion_handler<void(Result<TradingCalendar>)>
 Completion handler for one trading calendar.
using InstrumentHandler = net::any_completion_handler<void(Result<Instrument>)>
 Completion handler for one instrument's reference data.
using AccountsHandler = net::any_completion_handler<void(Result<std::vector<TossAccount>>)>
 Completion handler for Toss account discovery.
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 SellableQuantityHandler = net::any_completion_handler<void(Result<Decimal64>)>
 Completion handler for one instrument's sellable quantity.
using CommissionScheduleHandler = net::any_completion_handler<void(Result<CommissionSchedule>)>
 Completion handler for the account's commission schedule.
using OrderAckHandler = net::any_completion_handler<void(Result<OrderAck>)>
 Completion handler for one accepted Toss order instruction.
using OrderPageHandler = net::any_completion_handler<void(Result<OrderPage>)>
 Completion handler for one normalized page of orders.
using OrderHandler = net::any_completion_handler<void(Result<OrderSnapshot>)>
 Completion handler for one normalized order.
using TokenHandler = net::any_completion_handler<void(std::optional<BrokerError>)>
 Internal completion handler for a shared access-token refresh.

Public Member Functions

 TossClient (net::any_io_executor executor, ssl::context &context, TossConfig config, network::HttpClientOptions options={})
 Constructs a client; nothing is sent until the first request.
template<typename CompletionToken>
auto async_bars (BarQuery query, CompletionToken &&token)
 Requests up to count_ bars, oldest first.
template<typename CompletionToken>
auto async_calendar (Country country, std::optional< Date > from, CompletionToken &&token)
 Requests the trading calendar around a date: that date and the business days either side of it (three days).
template<typename CompletionToken>
auto async_instrument (InstrumentId instrument, CompletionToken &&token)
 Requests static reference data for one instrument.
template<typename CompletionToken>
auto async_price_limits (InstrumentId instrument, CompletionToken &&token)
 Requests today's upper and lower price bound for one instrument.
template<typename CompletionToken>
auto async_trades (InstrumentId instrument, int count, CompletionToken &&token)
 Requests recent executions for one instrument, newest first.
template<typename CompletionToken>
auto async_prices (std::vector< InstrumentId > instruments, CompletionToken &&token)
 Quotes up to 200 instruments in one request.
template<typename CompletionToken>
auto async_depth (InstrumentId instrument, CompletionToken &&token)
 Requests and normalizes the resting orders on both sides of the book.
template<typename CompletionToken>
auto async_quote (InstrumentId instrument, CompletionToken &&token)
 Requests a quote for a Korean instrument (a US instrument is refused before sending; use async_prices).
template<typename CompletionToken>
auto async_accounts (CompletionToken &&token)
 Discovers the brokerage accounts available to the current credentials.
template<typename CompletionToken>
auto async_buying_power (Currency currency, std::int64_t account_sequence, CompletionToken &&token)
 Requests the account's buying power in a currency.
template<typename CompletionToken>
auto async_sellable_quantity (InstrumentId instrument, std::int64_t account_sequence, CompletionToken &&token)
 Requests how much of one instrument the account may sell.
template<typename CompletionToken>
auto async_commissions (std::int64_t account_sequence, CompletionToken &&token)
 Requests the commission rates in force for the account.
template<typename CompletionToken>
auto async_holdings (std::int64_t account_sequence, CompletionToken &&token)
 Requests and normalizes holdings for one discovered account sequence.
template<typename CompletionToken>
auto async_place_order (std::int64_t account_sequence, OrderRequest order, CompletionToken &&token)
 Places an order.
template<typename CompletionToken>
auto async_replace_order (std::int64_t account_sequence, TossAmendment amendment, CompletionToken &&token)
 Amends an open order's price, and for a Korean order its quantity.
template<typename CompletionToken>
auto async_cancel_order (std::int64_t account_sequence, std::string order_id, CompletionToken &&token)
 Cancels an open order.
template<typename CompletionToken>
auto async_orders (TossOrderQuery query, CompletionToken &&token)
 Requests a page of orders.
template<typename CompletionToken>
auto async_order (std::int64_t account_sequence, std::string order_id, CompletionToken &&token)
 Requests one order by id, in any state.
const network::RateLimitStats * rate_limit_stats () const
 Returns the rate limiter's statistics.
void close ()
 Cancels transport work and queued HTTP operations.

Friends

struct TossClientTestAccess

Detailed Description

The asynchronous Toss Securities REST client: market data, accounts and orders.

It requests an access token when first needed, and again after Toss refuses the one it holds (as it does once another program issues a token with the same key); one refresh is shared among concurrent requests, and a refused request is not sent again. 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. A blocking wrapper is TossBlockingClient.

Definition at line 146 of file client.hpp.

Member Typedef Documentation

◆ AccountsHandler

using algotradelib::tossinvest::TossClient::AccountsHandler = net::any_completion_handler<void(Result<std::vector<TossAccount>>)>

Completion handler for Toss account discovery.

Definition at line 172 of file client.hpp.

◆ BarsHandler

using algotradelib::tossinvest::TossClient::BarsHandler = net::any_completion_handler<void(Result<BarSeries>)>

Completion handler for one normalized bar series.

Definition at line 152 of file client.hpp.

◆ BuyingPowerHandler

Completion handler for one normalized buying-power reading.

Definition at line 177 of file client.hpp.

◆ CalendarHandler

Completion handler for one trading calendar.

Definition at line 167 of file client.hpp.

◆ CommissionScheduleHandler

Completion handler for the account's commission schedule.

Definition at line 181 of file client.hpp.

◆ DepthHandler

using algotradelib::tossinvest::TossClient::DepthHandler = net::any_completion_handler<void(Result<DepthSnapshot>)>

Completion handler for one normalized order book.

Definition at line 155 of file client.hpp.

◆ HoldingsHandler

Completion handler for one normalized holdings snapshot.

Definition at line 175 of file client.hpp.

◆ InstrumentHandler

using algotradelib::tossinvest::TossClient::InstrumentHandler = net::any_completion_handler<void(Result<Instrument>)>

Completion handler for one instrument's reference data.

Definition at line 170 of file client.hpp.

◆ OrderAckHandler

using algotradelib::tossinvest::TossClient::OrderAckHandler = net::any_completion_handler<void(Result<OrderAck>)>

Completion handler for one accepted Toss order instruction.

Definition at line 184 of file client.hpp.

◆ OrderHandler

using algotradelib::tossinvest::TossClient::OrderHandler = net::any_completion_handler<void(Result<OrderSnapshot>)>

Completion handler for one normalized order.

Definition at line 190 of file client.hpp.

◆ OrderPageHandler

using algotradelib::tossinvest::TossClient::OrderPageHandler = net::any_completion_handler<void(Result<OrderPage>)>

Completion handler for one normalized page of orders.

Definition at line 187 of file client.hpp.

◆ PriceLimitsHandler

Completion handler for one instrument's price bounds.

Definition at line 158 of file client.hpp.

◆ PricesHandler

using algotradelib::tossinvest::TossClient::PricesHandler = net::any_completion_handler<void(Result<std::vector<QuoteSnapshot>>)>

Completion handler for several instruments quoted at once.

Definition at line 164 of file client.hpp.

◆ QuoteHandler

using algotradelib::tossinvest::TossClient::QuoteHandler = net::any_completion_handler<void(Result<QuoteSnapshot>)>

Completion handler for one normalized quote.

Definition at line 149 of file client.hpp.

◆ SellableQuantityHandler

Completion handler for one instrument's sellable quantity.

Definition at line 179 of file client.hpp.

◆ TokenHandler

using algotradelib::tossinvest::TossClient::TokenHandler = net::any_completion_handler<void(std::optional<BrokerError>)>

Internal completion handler for a shared access-token refresh.

Definition at line 193 of file client.hpp.

◆ TradesHandler

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

Completion handler for recent executions.

Definition at line 161 of file client.hpp.

Constructor & Destructor Documentation

◆ TossClient()

algotradelib::tossinvest::TossClient::TossClient ( net::any_io_executor executor,
ssl::context & context,
TossConfig 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.
optionsHTTP options (set rate_limit_ to pace requests).

Definition at line 202 of file client.hpp.

Member Function Documentation

◆ async_accounts()

template<typename CompletionToken>
auto algotradelib::tossinvest::TossClient::async_accounts ( CompletionToken && token)
inline

Discovers the brokerage accounts available to the current credentials.

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

Definition at line 436 of file client.hpp.

Referenced by algotradelib::BrokerTraits< tossinvest::TossClient >::accounts().

◆ async_bars()

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

Requests up to count_ bars, oldest first.

Fewer are returned, with next_cursor_ set when more remain, if history runs out or after 50 pages (at most 10,000 bars). One-minute and one-day bars only.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
queryThe query (one-minute or one-day bars only).
tokenThe completion token, called with Result<BarSeries>.
Returns
Whatever the completion token returns.

Definition at line 225 of file client.hpp.

Referenced by algotradelib::BrokerTraits< tossinvest::TossClient >::bars().

◆ async_buying_power()

template<typename CompletionToken>
auto algotradelib::tossinvest::TossClient::async_buying_power ( Currency currency,
std::int64_t account_sequence,
CompletionToken && token )
inline

Requests the account's buying power in a currency.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
currencyThe currency; Toss answers KRW and USD, and any other is refused before sending.
account_sequenceThe account (TossAccount::sequence_).
tokenThe completion token, called with Result<BuyingPower>.
Returns
Whatever the completion token returns.

Definition at line 460 of file client.hpp.

Referenced by algotradelib::BrokerTraits< tossinvest::TossClient >::buying_power().

◆ async_calendar()

template<typename CompletionToken>
auto algotradelib::tossinvest::TossClient::async_calendar ( Country country,
std::optional< Date > from,
CompletionToken && token )
inline

Requests the trading calendar around a date: that date and the business days either side of it (three days).

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
countryThe market.
fromThe date (empty: Toss's today).
tokenThe completion token, called with Result<TradingCalendar>: a reply whose today has a readable date but no hours field for that market (regularMarket for US, integrated for KR) is refused with invalid_calendar_response rather than read as closed.
Returns
Whatever the completion token returns.

Definition at line 251 of file client.hpp.

Referenced by algotradelib::BrokerTraits< tossinvest::TossClient >::calendar().

◆ async_cancel_order()

template<typename CompletionToken>
auto algotradelib::tossinvest::TossClient::async_cancel_order ( std::int64_t account_sequence,
std::string order_id,
CompletionToken && token )
inline

Cancels an open order.

After an error of unknown outcome (see async_place_order) the order may still rest. Toss answers with a new id in OrderAck::order_id_ that names this cancellation, not the order. If Toss rejects the cancellation, that row is CANCEL_REJECTED and the original order rests under its own id.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
account_sequenceThe account (TossAccount::sequence_).
order_idToss's order id.
tokenThe completion token, called with Result<OrderAck>.
Returns
Whatever the completion token returns.

Definition at line 664 of file client.hpp.

Referenced by algotradelib::BrokerTraits< tossinvest::TossClient >::cancel_order().

◆ async_commissions()

template<typename CompletionToken>
auto algotradelib::tossinvest::TossClient::async_commissions ( std::int64_t account_sequence,
CompletionToken && token )
inline

Requests the commission rates in force for the account.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
account_sequenceThe account (TossAccount::sequence_).
tokenThe completion token.
Returns
Whatever the completion token returns.

Definition at line 516 of file client.hpp.

Referenced by algotradelib::BrokerTraits< tossinvest::TossClient >::commissions().

◆ async_depth()

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

Requests and normalizes the resting orders on both sides of the book.

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

Definition at line 390 of file client.hpp.

Referenced by algotradelib::BrokerTraits< tossinvest::TossClient >::depth().

◆ async_holdings()

template<typename CompletionToken>
auto algotradelib::tossinvest::TossClient::async_holdings ( std::int64_t account_sequence,
CompletionToken && token )
inline

Requests and normalizes holdings for one discovered account sequence.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
account_sequenceThe account (TossAccount::sequence_).
tokenThe completion token.
Returns
Whatever the completion token returns.

Definition at line 539 of file client.hpp.

Referenced by algotradelib::BrokerTraits< tossinvest::TossClient >::holdings().

◆ async_instrument()

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

Requests static reference data for one instrument.

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

Definition at line 274 of file client.hpp.

Referenced by algotradelib::BrokerTraits< tossinvest::TossClient >::instrument().

◆ async_order()

template<typename CompletionToken>
auto algotradelib::tossinvest::TossClient::async_order ( std::int64_t account_sequence,
std::string order_id,
CompletionToken && token )
inline

Requests one order by id, in any state.

Only orders placed as limit, market or closing-auction limit orders are listed or readable; orders of other types placed outside the API (such as after-hours closing-price orders placed in the app) are not.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
account_sequenceThe account (TossAccount::sequence_).
order_idToss's order id.
tokenThe completion token.
Returns
Whatever the completion token returns.

Definition at line 735 of file client.hpp.

Referenced by algotradelib::BrokerTraits< tossinvest::TossClient >::order_by_id().

◆ async_orders()

template<typename CompletionToken>
auto algotradelib::tossinvest::TossClient::async_orders ( TossOrderQuery query,
CompletionToken && token )
inline

Requests a page of orders.

Only orders placed as limit, market or closing-auction limit orders are listed or readable; orders of other types placed outside the API (such as after-hours closing-price orders placed in the app) are not.

An OPEN listing returns all matching open orders and no cursor. A CLOSED listing pages: pass OrderPage::next_cursor_ back as cursor_ to continue.

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

Definition at line 706 of file client.hpp.

Referenced by algotradelib::BrokerTraits< tossinvest::TossClient >::order_history(), and algotradelib::BrokerTraits< tossinvest::TossClient >::working_orders().

◆ async_place_order()

template<typename CompletionToken>
auto algotradelib::tossinvest::TossClient::async_place_order ( std::int64_t account_sequence,
OrderRequest order,
CompletionToken && token )
inline

Places an order.

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 outcome is unknown. Toss's refusals other than a rate limit are reported as PROTOCOL, so they count too. With OrderRequest::client_order_id_ set, Toss treats it as an idempotency key for ten minutes, so sending the same order again returns the original result; without one, read async_orders before placing again.

Refused before sending, among others: an instrument whose venue is not Toss's own (COMBINED for Korea, UNSPECIFIED for the US); an OrderRequest::venue_; a trigger price; a type other than limit or market; a condition other than DAY; an unsupported session; a fractional quantity (except a US market sell, up to six decimals); a Korean price that is not whole won; a client order id that is not 1-36 characters of [A-Za-z0-9_-].

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
account_sequenceThe account (TossAccount::sequence_).
orderThe order.
tokenThe completion token, called with Result<OrderAck>.
Returns
Whatever the completion token returns.

Definition at line 578 of file client.hpp.

Referenced by algotradelib::BrokerTraits< tossinvest::TossClient >::place_order().

◆ async_price_limits()

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

Requests today's upper and lower price bound for one instrument.

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

Definition at line 302 of file client.hpp.

Referenced by algotradelib::BrokerTraits< tossinvest::TossClient >::price_limits().

◆ async_prices()

template<typename CompletionToken>
auto algotradelib::tossinvest::TossClient::async_prices ( std::vector< InstrumentId > instruments,
CompletionToken && token )
inline

Quotes up to 200 instruments in one request.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
instrumentsThe instruments; a longer list is refused, not split.
tokenThe completion token, called with Result<std::vector<QuoteSnapshot>>.
Returns
Whatever the completion token returns.

Definition at line 366 of file client.hpp.

Referenced by algotradelib::BrokerTraits< tossinvest::TossClient >::prices().

◆ async_quote()

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

Requests a quote for a Korean instrument (a US instrument is refused before sending; use async_prices).

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

Definition at line 414 of file client.hpp.

Referenced by algotradelib::BrokerTraits< tossinvest::TossClient >::quote().

◆ async_replace_order()

template<typename CompletionToken>
auto algotradelib::tossinvest::TossClient::async_replace_order ( std::int64_t account_sequence,
TossAmendment amendment,
CompletionToken && token )
inline

Amends an open order's price, and for a Korean order its quantity.

After an error of unknown outcome (see async_place_order) the amendment may have been made; an amendment has no idempotency key. Toss answers with a new id in OrderAck::order_id_, naming this amendment. If Toss carries it out, the original becomes REPLACED and the order rests under the new id; if Toss rejects it, the new id names a REPLACE_REJECTED row and the original rests unchanged under its own id. Read the order's state before acting on either id.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
account_sequenceThe account (TossAccount::sequence_).
amendmentThe amendment.
tokenThe completion token, called with Result<OrderAck>.
Returns
Whatever the completion token returns.

Definition at line 621 of file client.hpp.

Referenced by algotradelib::BrokerTraits< tossinvest::TossClient >::replace_order().

◆ async_sellable_quantity()

template<typename CompletionToken>
auto algotradelib::tossinvest::TossClient::async_sellable_quantity ( InstrumentId instrument,
std::int64_t account_sequence,
CompletionToken && token )
inline

Requests how much of one instrument the account may sell.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
instrumentThe instrument.
account_sequenceThe account (TossAccount::sequence_).
tokenThe completion token.
Returns
Whatever the completion token returns.

Definition at line 484 of file client.hpp.

Referenced by algotradelib::BrokerTraits< tossinvest::TossClient >::sellable_quantity().

◆ async_trades()

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

Requests recent executions for one instrument, newest first.

Template Parameters
CompletionTokenAn Asio completion token.
Parameters
instrumentThe instrument.
countThe most trades to return, clamped to 1-50 (today's trades only).
tokenThe completion token.
Returns
Whatever the completion token returns.

Definition at line 331 of file client.hpp.

Referenced by algotradelib::BrokerTraits< tossinvest::TossClient >::trades().

◆ close()

void algotradelib::tossinvest::TossClient::close ( )
inline

Cancels transport work and queued HTTP operations.

Definition at line 771 of file client.hpp.

◆ rate_limit_stats()

const network::RateLimitStats * algotradelib::tossinvest::TossClient::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 765 of file client.hpp.

Referenced by algotradelib::BrokerTraits< tossinvest::TossClient >::rate_limit_stats().

◆ TossClientTestAccess

friend struct TossClientTestAccess
friend

Definition at line 774 of file client.hpp.


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