跳轉到

finlab.online

finlab.online.base_account.Account

Bases: ABC

股票帳戶的 abstract class 可以繼承此 Account,來實做券商的帳戶買賣動作,目前已經實做 SinopacAccount (永豐證券) 以及 FugleAccount (玉山富果),來進行交易。可以用以下方式建構物件並用來交易:

永豐證券

import os
from finlab.online.sinopac_account import SinopacAccount


# 舊版請使用
# shioaji < 1.0.0 and finlab < 0.3.18
os.environ['SHIOAJI_ACCOUNT']= '永豐證券帳號'
os.environ['SHIOAJI_PASSWORD']= '永豐證券密碼'

# 新版請使用
# shioaji >= 1.0.0 and finlab >= 0.3.18
os.environ['SHIOAJI_API_KEY'] = '永豐證券API_KEY'
os.environ['SHIOAJI_SECRET_KEY'] = '永豐證券SECRET_KEY'
os.environ['SHIOAJI_CERT_PERSON_ID']= '身份證字號'

# shioaji
os.environ['SHIOAJI_CERT_PATH']= '永豐證券憑證路徑'
os.environ['SHIOAJI_CERT_PASSWORD'] = '永豐證券憑證密碼' # 預設與身份證字號

acc = SinopacAccount()
玉山富果:
from finlab.online.fugle_account import FugleAccount
import os
os.environ['FUGLE_CONFIG_PATH'] = '玉山富果交易設定檔(config.ini.example)路徑'
os.environ['FUGLE_MARKET_API_KEY'] = '玉山富果的行情API Token'

acc = FugleAccount()

cancel_order abstractmethod

cancel_order(order_id)

刪除委託單

建議使用 刪除委託單此功能前,先使用 update_order() 來更新委託單的狀況!如下

acc.update_order()
acc.cancel_order('ORDER_ID')

ATTRIBUTE DESCRIPTION
order_id

券商所提供的委託單 ID

TYPE: str

RETURNS DESCRIPTION
None

代表成功更新委託單

create_order abstractmethod

create_order(action, stock_id, quantity, price=None, force=False, wait_for_best_price=False)

產生新的委託單

PARAMETER DESCRIPTION
action

買賣方向,通常為 'BUY' 或是 'SELL'

TYPE: Action

stock_id

股票代號 ex: '2330'

TYPE: str

quantity

委託股票的總數量(張數),允許小數點

TYPE: Number

price

股票買賣的價格(限價單)

TYPE: Number DEFAULT: None

force

是否用最差之價格(長跌停)強制成交? 當成交量足夠時,可以比較快成交,然而當成交量低時,容易有大的滑價

TYPE: bool DEFAULT: False

wait_for_best_price

是否用最佳之價格(長跌停),無限時間等待?當今天要出場時,可以開啟等漲停價來購買,當今天要買入時,可以掛跌停價等待買入時機。

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
str

order id 券商提供的委託單編號

get_cash abstractmethod

get_cash()

拿到當前帳戶的現金

get_market

get_market()

拿到當前帳戶的市場

get_orders abstractmethod

get_orders()

拿到現在所有委託單

RETURNS DESCRIPTION
Dict[str, Order]

所有委託單 id 與委託單資料

Example

{'12345A': Order(order_id='12345A', stock_id='5410',...),...}

get_position abstractmethod

get_position()

拿到當前帳戶的股票部位

RETURNS DESCRIPTION
Position

當前股票部位

get_settlement abstractmethod

get_settlement()

拿到當前帳戶的結算資料

get_stocks abstractmethod

get_stocks(stock_ids)

拿到現在股票報價

ATTRIBUTE DESCRIPTION
stock_ids

一次拿取所有股票的報價,ex: ['1101', '2330']

TYPE: `list` of `str`

RETURNS DESCRIPTION
dict

報價資料,

Example

{'1101': Stock(stock_id='1101', open=31.15, high=31.85, low=31.1, close=31.65, bid_price=31.6, bid_volume=728.0, ask_price=31.65, ask_volume=202)}

get_total_balance abstractmethod

get_total_balance()

拿到當前帳戶的股票部位淨值

update_order abstractmethod

update_order(order_id, price=None, quantity=None)

產生新的委託單

ATTRIBUTE DESCRIPTION
order_id

券商所提供的委託單 ID

TYPE: str

price

更新的限價

TYPE: Number

quantity

更新的待成交量

TYPE: Number

RETURNS DESCRIPTION
None

無跳出 erorr 代表成功更新委託單

finlab.online.order_executor.Position

Position(stocks, weights=None, margin_trading=False, short_selling=False, day_trading_long=False, day_trading_short=False)

使用者可以利用 Position 輕鬆建構股票的部位,並且利用 OrderExecuter 將此部位同步於實際的股票帳戶。

建構股票部位

ATTRIBUTE DESCRIPTION
stocks

number.Number): 股票代號與張數 ex: {'1101': 1} 是指持有一張 1101 台泥,可以接受負數,代表做空。

TYPE: `dict` of `str`

margin_trading

做多部位是否使用融資

TYPE: bool

short_selling

做空部位是否使用融券

TYPE: bool

day_trading_long

做多部位為當沖先做多

TYPE: bool

day_trading_short

做空部位為當沖先做空

TYPE: bool

Examples:

設計部位,持有一張和 100 股 1101

from finlab.online.order_executor import Position

Position({'1101': 1.1})
output
[
    {'stock_id': '1101',
     'quantity': 1.1,
     'order_condition': <OrderCondition.CASH: 1>
    }
]

將兩個部位相加

from finlab.online.order_executor import Position

p1 = Position({'1101': 1})
p2 = Position({'2330': 1})
p1 + p2
output
[
    {'stock_id': '1101', 'quantity': 1.0, 'order_condition': <OrderCondition.CASH: 1>},
    {'stock_id': '2330', 'quantity': 1.0, 'order_condition': <OrderCondition.CASH: 1>}
]

from_json classmethod

from_json(path)

Load a JSON file from the given path and convert it to a list of positions.

PARAMETER DESCRIPTION
path

The path to the JSON file.

TYPE: str

RETURNS DESCRIPTION

None

from_list classmethod

from_list(position)

利用 dict 建構股票部位

ATTRIBUTE DESCRIPTION
position

股票詳細部位

from finlab.online.enums import OrderCondition
from finlab.online.order_executor import Position

Position.from_list(
[{
  'stock_id': '1101', # 股票代號
  'quantity': 1.1, # 張數
  'order_condition': OrderCondition.CASH # 現股融資融券、先買後賣
}])

其中 OrderCondition 除了 CASH 外,還有 MARGIN_TRADINGDAY_TRADING_LONGSHORT_SELLINGDAY_TRADING_SHORT

TYPE: `list` of `dict`

from_report classmethod

from_report(report, fund, **kwargs)

利用回測完的報告 finlab.report.Report 建構股票部位。

ATTRIBUTE DESCRIPTION
report

回測完的結果報告。

TYPE: Report

fund

希望部屬的資金。

TYPE: int

price

股票代號對應到的價格,若無則使用最近個交易日的收盤價。

TYPE: pd.Series or `dict` of `float`

odd_lot

是否考慮零股。預設為 False,只使用整張操作。

TYPE: bool

board_lot_size

一張股票等於幾股。預設為1000,一張等於1000股。

TYPE: int

allocation

資產配置演算法選定,預設為finlab.online.utils.greedy_allocation(最大資金部屬貪婪法)。

TYPE: func

Example

from finlab import backtest
from finlab.online.order_executor import Position

report1 = backtest.sim(...)
report2 = backtest.sim(...)

position1 = Position.from_report(report1, 1000000) # 策略操作金額一百萬
position2 = Position.from_report(report2, 1000000) # 策略操作金額一百萬

total_position = position1 + position2

from_weight classmethod

from_weight(weights, fund, price=None, odd_lot=False, board_lot_size=1000, allocation=greedy_allocation, precision=None, **kwargs)

利用 weight 建構股票部位

ATTRIBUTE DESCRIPTION
weights

股票詳細部位

TYPE: `dict` of `float`

fund

資金大小

TYPE: Number

price

股票代號對應到的價格,若無則使用最近個交易日的收盤價。

TYPE: pd.Series or `dict` of `float`

odd_lot

是否考慮零股

TYPE: bool

board_lot_size

一張股票等於幾股

TYPE: int

precision

計算張數時的精度,預設為 None 代表依照 board_lot_size 而定,而 1 代表 0.1 張,2 代表 0.01 張,以此類推。

TYPE: int or None

allocation

資產配置演算法選定,預設為預設為finlab.online.utils.greedy_allocation(最大資金部屬貪婪法)

TYPE: func

margin_trading

做多部位是否使用融資

TYPE: bool

short_selling

做空部位是否使用融券

TYPE: bool

day_trading_long

做多部位為當沖先做多

TYPE: bool

day_trading_short

做空部位為當沖先做空

TYPE: bool

Examples:

例如,用 100 萬的資金,全部投入,持有 1101 和 2330 各一半:

from finlab.online.order_executor import Position

Position.from_weight({
    '1101': 0.5,
    '2330': 0.5,
}, fund=1000000)
output
[
  {'stock_id': '1101', 'quantity': 13, 'order_condition': <OrderCondition.CASH: 1>},
  {'stock_id': '2330', 'quantity': 1, 'order_condition': <OrderCondition.CASH: 1>}
]

to_json

to_json(path)

Converts the position dictionary to a JSON file and saves it to the specified path.

PARAMETER DESCRIPTION
path

The path where the JSON file will be saved.

TYPE: str

RETURNS DESCRIPTION

None

finlab.online.order_executor.OrderExecutor

OrderExecutor(target_position, account)

對比實際帳戶與欲部屬的股票部位,進行同步 Arguments: target_position (Position): 想要部屬的股票部位。 account (Account): 目前支援永豐與富果帳戶,請參考 Account 來實做。

cancel_orders

cancel_orders()

刪除所有未實現委託單

create_orders

create_orders(market_order=False, best_price_limit=False, view_only=False, extra_bid_pct=0, progress=1, progress_precision=0)

產生委託單,將部位同步成 self.target_position 預設以該商品最後一筆成交價設定為限價來下單

ATTRIBUTE DESCRIPTION
market_order

以類市價盡量即刻成交:所有買單掛漲停價,所有賣單掛跌停價

TYPE: bool

best_price_limit

掛芭樂價:所有買單掛跌停價,所有賣單掛漲停價

TYPE: bool

view_only

預設為 False,會實際下單。若設為 True,不會下單,只會回傳欲執行的委託單資料(dict)

TYPE: bool

extra_bid_pct

以該百分比值乘以價格進行追價下單,如設定為 0.05 時,將以當前價的 +(-)5% 的限價進買入(賣出),也就是更有機會可以成交,但是成交價格可能不理想; 假如設定為 -0.05 時,將以當前價的 -(+)5% 進行買入賣出,也就是限價單將不會立即成交,然而假如成交後,價格比較理想。參數有效範圍為 -0.1 到 0.1 內。

TYPE: float

progress

進度,預設為 1,即全部下單。若設定為 0.5,則只下一半的單。

TYPE: float

progress_precision

進度的精度,預設為 0,即只下整數張。若設定為 1,則下到 0.1 張。

TYPE: int

execute_orders

execute_orders(orders, market_order=False, best_price_limit=False, view_only=False, extra_bid_pct=0, cancel_orders=True)

產生委託單,將部位同步成 self.target_position 預設以該商品最後一筆成交價設定為限價來下單

ATTRIBUTE DESCRIPTION
orders

欲下單的部位,通常是由 self.generate_orders 產生。

TYPE: list

market_order

以類市價盡量即刻成交:所有買單掛漲停價,所有賣單掛跌停價

TYPE: bool

best_price_limit

掛芭樂價:所有買單掛跌停價,所有賣單掛漲停價

TYPE: bool

view_only

預設為 False,會實際下單。若設為 True,不會下單,只會回傳欲執行的委託單資料(dict)

TYPE: bool

extra_bid_pct

以該百分比值乘以價格進行追價下單,如設定為 0.05 時,將以當前價的 +(-)5% 的限價進買入(賣出),也就是更有機會可以成交,但是成交價格可能不理想; 假如設定為 -0.05 時,將以當前價的 -(+)5% 進行買入賣出,也就是限價單將不會立即成交,然而假如成交後,價格比較理想。參數有效範圍為 -0.1 到 0.1 內。

TYPE: float

generate_orders

generate_orders(progress=1, progress_precision=0)

Generate orders based on the difference between target position and present position.

Returns: orders (dict): Orders to be executed.

show_alerting_stocks

show_alerting_stocks()

產生下單部位是否有警示股,以及相關資訊

update_order_price

update_order_price(extra_bid_pct=0)

更新委託單,將委託單的限價調整成當天最後一筆價格。 (讓沒成交的限價單去追價) Attributes: extra_bid_pct (float): 以該百分比值乘以價格進行追價下單,如設定為 0.1 時,將以超出(低於)現價之10%價格下單,以漲停(跌停)價為限。參數有效範圍為 0 到 0.1 內

finlab.online.base_account.Order dataclass

Order status

委託單的狀態

ATTRIBUTE DESCRIPTION
order_id

委託單的 id,與券商 API 所提供的 id 一致

TYPE: str

stock_id

股票代號 ex: '2330'

TYPE: str

action

買賣方向,通常為 'BUY' 或是 'SELL'

TYPE: Action

price

股票買賣的價格(限價單)

TYPE: Number

quantity

委託股票的總數量(張數),允許小數點

TYPE: Number

filled_quantity

以成交股票的數量(張數),允許小數點

TYPE: Number

status

委託狀態,可以設定為:'NEW', 'PARTIALLY_FILLED', 'FILLED', 'CANCEL'

TYPE: OrderStatus

time

委託時間

TYPE: datetime

org_order

券商所提供的委託物件格式

TYPE: Any = None

finlab.online.panel.order_panel

order_panel(account)

下單 GUI 介面 Arguments: account (Account): 請參考 Account 針對不同券商來建構相對應的操作帳戶