repository·main·Indexed 41 days ago
https://github.com/kay-ou/ptradeapiDocumentation for the Ptrade quantitative trading API, featuring usage guides and comparative analysis across four major versions, including V005 (Community Maintained), V016 (Guosheng Securities), and V041 (Dongguan Securities). Includes API references for core frameworks, trading interfaces (stocks, futures, options, margin), market and financial data interfaces, and technical indicators.
The Ptrade API documentation provides a comprehensive guide for developing quantitative trading strategies on the Hundsun (恒生) investment research platform. It covers strategy development, backtesting, and live trading across various asset classes including stocks, convertible bonds, ETFs, futures, and options.
Key areas of the documentation include:
initialize, handle_data, and before_trading_start.The Ptrade API is a comprehensive framework for quantitative trading, research, and strategy execution. It is organized into several functional domains:
initialize, handle_data, etc.) that drive strategy execution.cancel_order and get_positions.Depending on your expertise and needs, use the following entry points:
The documentation is organized into several key directories:
docs/getting-started/: Guides for new users and quick start instructions.docs/api-reference/: Detailed descriptions of API modules (e.g., stock-trading.md, market-data.md, technical-indicators.md).docs/examples.md: A library of strategy code examples.docs/api-classification.md: A quick reference index of functions by category.docs/versions/: Comparison tables and selection guides for different brokerage versions.docs/version-differences.md: Analysis of technical differences between versions.docs/advanced/: FAQ and advanced feature documentation.The Ptrade API documentation is organized into four primary functional modules. Use these modules to locate specific interfaces for your quantitative trading strategy:
framework.md): Strategy frameworks, lifecycles, and event handling.objects.md): Definitions for core objects like Order, Position, and Security.utilities.md): Helper tools for logging, time management, and data conversion.stock-trading.md): Spot trading for stocks, ETFs, and convertible bonds.futures.md): Futures contract trading and position management.options.md): Options contract trading and exercise functions.margin-trading.md): Margin buying, short selling, and collateral management.market-data.md): K-line data, real-time quotes, and L2 data.stock-info.md): Basic stock info and financial data queries.financial-data.md): Financial statements and indicators.basic-info.md): Trading calendars, stock lists, etc.technical-indicators.md): Calculation of MACD, KDJ, RSI, etc.settings.md): Parameter configuration, notifications, and system management.The Ptrade API documentation is organized into four functional modules to help you find the right interfaces for your quantitative trading strategy:
Order, Position, and Security.Ptrade uses an event-driven architecture where the strategy lifecycle is managed through predefined event handlers (functions). A complete trading day typically follows this sequence:
initialize(context): Executed once at startup for global configuration.before_trading_start(context, data): Executed once before the market opens each day.handle_data(context, data): The main loop that executes during trading hours based on your set frequency (daily or minute).after_trading_end(context, data): Executed once after the market closes each day.Additional flexible event handlers include:
tick_data(context, data): For Tick-level logic.run_daily() / run_interval(): Scheduled tasks (daily or custom second-level intervals).on_order_response() / on_trade_response(): Real-time push events for order and trade status updates.The return type of get_history depends on the security_list provided and the Python version being used:
is_dict=True)Returns an OrderedDict where keys are stock codes and values are arrays containing [datetime, open, high, low, close, volume, money, price].
If security_list is a single string (e.g., '600570.SS'), it returns a pandas.DataFrame where the index is datetime.datetime and columns are the requested fields.
If security_list is a list (e.g., ['600570.SS', '600571.SS']), it returns a pandas.DataFrame with a datetime.datetime index and columns including code and the requested fields. Use .query('code in ["xxxxxx.SS"]') to filter for a specific stock.
If security_list is a list and field is a single string, it returns a pandas.DataFrame where the index is datetime.datetime and columns are the stock codes.
If security_list is a list and field is a list, it returns a pandas.Panel. The items axis contains the fields (e.g., 'open'). You can swap axes to make stock codes the primary index: panel_info.swapaxes("minor_axis", "items").
To protect against server exceptions or strategy optimizations, you must persist global variables (g) to prevent data loss when a strategy restarts.
before_trading_start(), handle_data(), and after_trading_end().initialize() first, then restores variables from the persisted state. Restored variables will overwrite those initialized in initialize().g starting with __ (e.g., g.__test_class) are treated as private and will not be saved.You can manually save complex state (like a dictionary of holding days) using the pickle module.
import pickle
from collections import defaultdict
def initialize(context):
g.notebook_path = get_research_path()
try:
with open(g.notebook_path + 'hold_days.pkl', 'rb') as f:
g.hold_days = pickle.load(f)
except:
g.hold_days = defaultdict(list)
g.security = '600570.SS'
set_universe(g.security)
def before_trading_start(context, data):
if g.hold_days:
g.hold_days[g.security] += 1
def handle_data(context, data):
# ... logic ...
with open(g.notebook_path + 'hold_days.pkl', 'wb') as f:
pickle.dump(g.hold_days, f, -1)import pickle
from collections import defaultdict
'''
持仓N日后卖出，仓龄变量每日pickle进行保存，重启策略后可以保证逻辑连贯
'''
def initialize(context):
g.notebook_path = get_research_path()
#尝试启动pickle文件
try:
with open(g.notebook_path+'hold_days.pkl','rb')as f:
g.hold_days = pickle.load(f)
#定义空的全局字典变量
except:
g.hold_days = defaultdict(list)
g.security ='600570.SS'
set_universe(g.security)
# 仓龄增加一天
def before_trading_start(context, data):
if g.hold_days:
g.hold_days[g.security]+=1
# 每天将存储仓龄的字典对象进行pickle保存
def handle_data(context, data):
if g.security notin list(context.portfolio.positions.keys())and g.security notin g.hold_days:
order(g.security,100)
g.hold_days[g.security]=1
if g.hold_days:
if g.hold_days[g.security]>5:
order(g.security,-100)
del g.hold_days[g.security]
with open(g.notebook_path+'hold_days.pkl','wb')as f:
pickle.dump(g.hold_days,f,-1)Ptrade strategies are driven by specific callback functions that the engine calls at different stages of the trading lifecycle.
initialize(context): Runs once when the strategy starts. Use this for setup, parameter initialization, and registering periodic tasks.handle_data(context, data): The main logic loop. Executes on every bar (daily or minute) depending on your strategy settings.before_trading_start(context, data): Runs once every day before the market opens.after_trading_end(context, data): Runs once every day after the market closes.tick_data(context, data): Processes Tick-level data (available in trading environments only).on_order_response(context, order_list): Triggered when an order status changes (trading environments only).on_trade_response(context, trade_list): Triggered when a trade execution occurs (trading environments only).def initialize(context):
# Setup code here
pass
def handle_data(context, data):
# Main strategy logic here
passThe Position object provides information about a specific held security.
Key attributes:
sid: Security code.enable_amount: Available quantity.amount: Total position quantity.last_sale_price: Latest price.cost_basis: Position cost price (not supported for futures).today_amount: Quantity opened today (backtesting only, not supported for futures).Futures-specific fields:
delivery_date: Delivery date.today_short_amount: Today's short opening quantity.today_long_amount: Today's long opening quantity.long_cost_basis: Long position cost.short_cost_basis: Short position cost.margin_rate: Margin ratio.contract_multiplier: Contract multiplier.long_amount: Total long position.short_amount: Total short position.long_pnl: Long floating PnL.short_pnl: Short floating PnL.long_enable_amount: Long available quantity.short_enable_amount: Short available quantity.business_type: Business type.def handle_data(context, data):
order(g.security, 1000)
position = get_position(g.security)
log.info(position)