broker

package

v0.29.0 Latest Latest Go to latest Published: Sep 18, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/smallfish06/krsec

Links

Open Source Insights

Documentation ¶

Overview ¶

Package broker defines the common interface and types shared across all broker adapters.

The central Broker interface provides methods for authentication, quotes, OHLCV data, balance/position queries, and order management. Concrete implementations live under internal/kis (and future brokers).

Types such as Quote, Balance, Position, Instrument, OHLCV, OrderRequest, and OrderResult are broker-agnostic and safe for external use.

Constants ¶

View Source

const (
	CodeKIS    = "kis"
	CodeKiwoom = "kiwoom"
	CodeLS     = "ls"
	CodeToss   = "toss"
)

Canonical broker identifiers used in config/routes.

View Source

const (
	NameKIS    = "KIS"
	NameKiwoom = "KIWOOM"
	NameLS     = "LS"
	NameToss   = "TOSS"
)

Broker display names returned by broker implementations.

Variables ¶

View Source

var (
	// ErrUnauthorized indicates authentication failure
	ErrUnauthorized = errors.New("unauthorized")

	// ErrInvalidCredentials indicates invalid credentials
	ErrInvalidCredentials = errors.New("invalid credentials")

	// ErrTokenExpired indicates the token has expired
	ErrTokenExpired = errors.New("token expired")

	// ErrInvalidSymbol indicates an invalid symbol
	ErrInvalidSymbol = errors.New("invalid symbol")

	// ErrInvalidMarket indicates an invalid market
	ErrInvalidMarket = errors.New("invalid market")

	// ErrInsufficientBalance indicates insufficient balance
	ErrInsufficientBalance = errors.New("insufficient balance")

	// ErrOrderNotFound indicates order not found
	ErrOrderNotFound = errors.New("order not found")

	// ErrInstrumentNotFound indicates instrument not found
	ErrInstrumentNotFound = errors.New("instrument not found")

	// ErrInvalidOrderRequest indicates an invalid order request
	ErrInvalidOrderRequest = errors.New("invalid order request")

	// ErrRateLimitExceeded indicates rate limit exceeded
	ErrRateLimitExceeded = errors.New("rate limit exceeded")

	// ErrServerError indicates a server error
	ErrServerError = errors.New("server error")

	// ErrUpstreamBadRequest indicates the upstream API rejected the request
	ErrUpstreamBadRequest = errors.New("upstream bad request")

	// ErrNotSupported indicates the selected broker cannot perform the operation.
	ErrNotSupported = errors.New("not supported")
)

Functions ¶

This section is empty.

Types ¶

type AccountInfo ¶

type AccountInfo struct {
	ID     string `json:"id"`
	Name   string `json:"name"`
	Broker string `json:"broker"`
}

AccountInfo represents basic account information

type AccountSummary ¶

type AccountSummary struct {
	TotalAssets     float64   `json:"total_assets"`
	TotalCash       float64   `json:"total_cash"`
	TotalProfitLoss float64   `json:"total_profit_loss"`
	Accounts        []Balance `json:"accounts"`
}

AccountSummary represents aggregated balance across multiple accounts

type AssetType ¶

type AssetType string

AssetType represents the type of asset

const (
	AssetStock    AssetType = "stock"
	AssetBond     AssetType = "bond"
	AssetFund     AssetType = "fund"
	AssetCash     AssetType = "cash"
	AssetOverseas AssetType = "overseas"
)

Asset types reported in balances and positions.

type Balance ¶

type Balance struct {
	// UnavailableFields names JSON fields the provider could not supply. Their
	// numeric zero values are placeholders, not observed zero balances.
	UnavailableFields []string `json:"unavailable_fields,omitempty"`
	AccountID         string   `json:"account_id"`
	Cash              float64  `json:"cash"`
	TotalAssets       float64  `json:"total_assets"`
	BuyingPower       float64  `json:"buying_power"`
	WithdrawableCash  float64  `json:"withdrawable_cash,omitempty"`
	ReceivableAmount  float64  `json:"receivable_amount,omitempty"`
	ProfitLoss        float64  `json:"profit_loss"`
	ProfitLossPct     float64  `json:"profit_loss_pct"`
	PositionCost      float64  `json:"position_cost,omitempty"`
	PositionValue     float64  `json:"position_value,omitempty"`
	SettlementT1      float64  `json:"settlement_t1,omitempty"`
	Unsettled         float64  `json:"unsettled,omitempty"`
	LoanBalance       float64  `json:"loan_balance,omitempty"`

	CashByCurrency          map[string]float64 `json:"cash_by_currency,omitempty"`
	TotalAssetsByCurrency   map[string]float64 `json:"total_assets_by_currency,omitempty"`
	BuyingPowerByCurrency   map[string]float64 `json:"buying_power_by_currency,omitempty"`
	ProfitLossByCurrency    map[string]float64 `json:"profit_loss_by_currency,omitempty"`
	PositionCostByCurrency  map[string]float64 `json:"position_cost_by_currency,omitempty"`
	PositionValueByCurrency map[string]float64 `json:"position_value_by_currency,omitempty"`
}

Balance represents account balance

func (Balance) MarshalJSON ¶ added in v0.28.0

func (b Balance) MarshalJSON() ([]byte, error)

MarshalJSON omits unavailable metrics instead of publishing placeholder zeros. Go callers must also inspect UnavailableFields before using a numeric field.

type Broker ¶

type Broker interface {
	// Name returns the broker name
	Name() string

	// Authenticate authenticates with the broker and returns a token
	Authenticate(ctx context.Context, creds Credentials) (*Token, error)

	// GetQuote retrieves a quote for a given market and symbol
	GetQuote(ctx context.Context, market, symbol string) (*Quote, error)

	// GetOHLCV retrieves OHLCV data for a given market and symbol
	GetOHLCV(ctx context.Context, market, symbol string, opts OHLCVOpts) ([]OHLCV, error)

	// GetBalance retrieves account balance
	GetBalance(ctx context.Context, accountID string) (*Balance, error)

	// GetPositions retrieves account positions
	GetPositions(ctx context.Context, accountID string) ([]Position, error)

	// PlaceOrder places a new order
	PlaceOrder(ctx context.Context, req OrderRequest) (*OrderResult, error)

	// CancelOrder cancels an order
	CancelOrder(ctx context.Context, orderID string) error

	// ModifyOrder modifies an existing order
	ModifyOrder(ctx context.Context, orderID string, req ModifyOrderRequest) (*OrderResult, error)
}

Broker is the common interface for all broker adapters

type Credentials ¶

type Credentials struct {
	AppKey    string `json:"app_key"`
	AppSecret string `json:"app_secret"`
}

Credentials holds broker authentication credentials

type Instrument ¶

type Instrument struct {
	Symbol          string    `json:"symbol"`
	Market          string    `json:"market"`
	ISIN            string    `json:"isin,omitempty"`
	Name            string    `json:"name"`
	NameEn          string    `json:"name_en,omitempty"`
	ShortName       string    `json:"short_name,omitempty"`
	Exchange        string    `json:"exchange,omitempty"`
	Currency        string    `json:"currency,omitempty"`
	Country         string    `json:"country,omitempty"`
	AssetType       AssetType `json:"asset_type,omitempty"`
	ProductType     string    `json:"product_type,omitempty"`
	ProductTypeCode string    `json:"product_type_code,omitempty"`
	SecurityGroup   string    `json:"security_group,omitempty"`
	Sector          string    `json:"sector,omitempty"`
	ListedShares    int64     `json:"listed_shares,omitempty"`
	IsListed        bool      `json:"is_listed"`
	IsSuspended     bool      `json:"is_suspended"`
	ListingDate     string    `json:"listing_date,omitempty"`
	DelistingDate   string    `json:"delisting_date,omitempty"`
}

Instrument represents normalized instrument metadata.

type ModifyOrderRequest ¶

type ModifyOrderRequest struct {
	Type                  OrderType `json:"type,omitempty"`
	Quantity              int64     `json:"quantity,omitempty"`
	QuantityDecimal       string    `json:"quantity_decimal,omitempty"`
	Price                 float64   `json:"price,omitempty"`
	ConfirmHighValueOrder bool      `json:"confirm_high_value_order,omitempty"`
}

ModifyOrderRequest represents an order modification request

type OHLCV ¶

type OHLCV struct {
	Timestamp time.Time `json:"timestamp"`
	Open      float64   `json:"open"`
	High      float64   `json:"high"`
	Low       float64   `json:"low"`
	Close     float64   `json:"close"`
	Volume    int64     `json:"volume"`
}

OHLCV represents candlestick data

type OHLCVOpts ¶

type OHLCVOpts struct {
	Interval string // "1d", "1h", "5m" etc.
	From     time.Time
	To       time.Time
	Limit    int
}

OHLCVOpts options for OHLCV data

type OrderFill ¶

type OrderFill struct {
	// QuantityDecimal preserves fractional executions without rounding.
	QuantityDecimal string    `json:"quantity_decimal,omitempty"`
	OrderID         string    `json:"order_id"`
	Symbol          string    `json:"symbol,omitempty"`
	Market          string    `json:"market,omitempty"`
	Side            string    `json:"side,omitempty"`
	Quantity        int64     `json:"quantity"`
	Price           float64   `json:"price"`
	Amount          float64   `json:"amount,omitempty"`
	Currency        string    `json:"currency,omitempty"`
	FilledAt        time.Time `json:"filled_at"`
	RawStatus       string    `json:"raw_status,omitempty"`
}

OrderFill represents normalized fill execution data.

type OrderRequest ¶

type OrderRequest struct {
	AccountID             string    `json:"account_id"`
	ClientOrderID         string    `json:"client_order_id,omitempty"`
	Symbol                string    `json:"symbol"`
	Market                string    `json:"market"`
	Side                  OrderSide `json:"side"`
	Type                  OrderType `json:"type"`
	TimeInForce           string    `json:"time_in_force,omitempty"`
	Quantity              int64     `json:"quantity"`
	QuantityDecimal       string    `json:"quantity_decimal,omitempty"`
	Price                 float64   `json:"price,omitempty"`
	OrderAmount           float64   `json:"order_amount,omitempty"`
	OrderAmountDecimal    string    `json:"order_amount_decimal,omitempty"`
	ConfirmHighValueOrder bool      `json:"confirm_high_value_order,omitempty"`
}

OrderRequest represents a new order request

type OrderResult ¶

type OrderResult struct {
	// Decimal quantities are authoritative when present; integer fields remain
	// available for clients that only support whole-share orders.
	FilledQuantityDecimal string      `json:"filled_quantity_decimal,omitempty"`
	RemainingQtyDecimal   string      `json:"remaining_quantity_decimal,omitempty"`
	OrderID               string      `json:"order_id"`
	Status                OrderStatus `json:"status"`
	FilledQuantity        int64       `json:"filled_quantity,omitempty"`
	RemainingQty          int64       `json:"remaining_quantity,omitempty"`
	AvgFilledPrice        float64     `json:"avg_filled_price,omitempty"`
	RejectedReason        string      `json:"rejected_reason,omitempty"`
	Message               string      `json:"message,omitempty"`
	Timestamp             time.Time   `json:"timestamp"`
}

OrderResult represents the result of an order operation

type OrderSide ¶

type OrderSide string

OrderSide represents buy or sell

const (
	OrderSideBuy  OrderSide = "buy"
	OrderSideSell OrderSide = "sell"
)

Order sides.

type OrderStatus ¶

type OrderStatus string

OrderStatus represents order status

const (
	OrderStatusPending   OrderStatus = "pending"
	OrderStatusFilled    OrderStatus = "filled"
	OrderStatusCancelled OrderStatus = "cancelled"
	OrderStatusRejected  OrderStatus = "rejected"
)

Order lifecycle statuses.

type OrderType ¶

type OrderType string

OrderType represents order type

const (
	OrderTypeLimit  OrderType = "limit"
	OrderTypeMarket OrderType = "market"
)

Order types.

type Position ¶

type Position struct {
	Symbol              string    `json:"symbol"`
	Name                string    `json:"name"`
	Market              string    `json:"market"`
	MarketCode          string    `json:"market_code,omitempty"`
	AssetType           AssetType `json:"asset_type"`
	Quantity            int64     `json:"quantity"`
	QuantityDecimal     string    `json:"quantity_decimal,omitempty"`
	OrderableQty        int64     `json:"orderable_qty,omitempty"`
	OrderableQtyDecimal string    `json:"orderable_qty_decimal,omitempty"`
	UnsettledQty        int64     `json:"unsettled_qty,omitempty"`
	TodayBuyQty         int64     `json:"today_buy_qty,omitempty"`
	TodaySellQty        int64     `json:"today_sell_qty,omitempty"`
	AvgPrice            float64   `json:"avg_price"`
	CurrentPrice        float64   `json:"current_price"`
	PurchaseValue       float64   `json:"purchase_value,omitempty"`
	MarketValue         float64   `json:"market_value,omitempty"`
	ProfitLoss          float64   `json:"profit_loss"`
	ProfitLossPct       float64   `json:"profit_loss_pct"`
	WeightPct           float64   `json:"weight_pct,omitempty"`
	LoanDate            string    `json:"loan_date,omitempty"`
}

Position represents a stock position

type Quote ¶

type Quote struct {
	Symbol      string    `json:"symbol"`
	Market      string    `json:"market"`
	Price       float64   `json:"price"`
	Open        float64   `json:"open"`
	High        float64   `json:"high"`
	Low         float64   `json:"low"`
	Close       float64   `json:"close"`
	PrevClose   float64   `json:"prev_close,omitempty"`
	Change      float64   `json:"change,omitempty"`
	ChangeRate  float64   `json:"change_rate,omitempty"`
	Volume      int64     `json:"volume"`
	Turnover    float64   `json:"turnover,omitempty"`
	UpperLimit  float64   `json:"upper_limit,omitempty"`
	LowerLimit  float64   `json:"lower_limit,omitempty"`
	BidPrice    float64   `json:"bid_price,omitempty"`
	AskPrice    float64   `json:"ask_price,omitempty"`
	BidSize     int64     `json:"bid_size,omitempty"`
	AskSize     int64     `json:"ask_size,omitempty"`
	MarketState string    `json:"market_state,omitempty"`
	Timestamp   time.Time `json:"timestamp"`
}

Quote represents a stock quote

type Token ¶

type Token struct {
	AccessToken string    `json:"access_token"`
	TokenType   string    `json:"token_type"`
	ExpiresAt   time.Time `json:"expires_at"`
}

Token represents an authentication token

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
mock

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Documentation ¶

Overview ¶

Index ¶

Constants ¶

Variables ¶

Functions ¶

Types ¶

type AccountInfo ¶

type AccountSummary ¶

type AssetType ¶

type Balance ¶

func (Balance) MarshalJSON ¶ added in v0.28.0

type Broker ¶

type Credentials ¶

type Instrument ¶

type ModifyOrderRequest ¶

type OHLCV ¶

type OHLCVOpts ¶

type OrderFill ¶

type OrderRequest ¶

type OrderResult ¶

type OrderSide ¶

type OrderStatus ¶

type OrderType ¶

type Position ¶

type Quote ¶

type Token ¶

Source Files ¶

Directories ¶