iiOdZddlmZddlmZmZgdZeGddZeGddZeGd d Z eGd d Z ed GddZ eGddZ eGddZ eGddZeGddZeGddZeGddZy)a ProjectX Data Models Author: @TexasCoding Date: 2025-08-02 Overview: Contains all data model classes for the ProjectX API client. Provides comprehensive data structures for trading entities, configuration, and real-time events. All models use dataclasses for type safety and automatic serialization/deserialization. Key Features: - Comprehensive trading entity models (Instrument, Order, Position, Trade) - Configuration models with default values - Real-time event models for WebSocket data - Type-safe dataclass implementations - Automatic serialization/deserialization - Comprehensive field documentation and examples Data Models: - Trading Entities: Instrument, Order, Position, Trade, Account - Configuration: ProjectXConfig with default TopStepX endpoints - Responses: OrderPlaceResponse, BracketOrderResponse - Events: OrderUpdateEvent, PositionUpdateEvent, MarketDataEvent Example Usage: ```python from project_x_py.models import ( Instrument, Order, Position, Trade, Account, ProjectXConfig, OrderPlaceResponse, ) # Create instrument model instrument = Instrument( id="CON.F.US.MNQ.U25", name="MNQU25", description="E-mini NASDAQ-100 Futures September 2025", tickSize=0.25, tickValue=0.50, activeContract=True, ) # Create order model order = Order( id=12345, accountId=1001, contractId="CON.F.US.MNQ.U25", creationTimestamp="2024-01-01T10:00:00Z", updateTimestamp="2024-01-01T10:00:05Z", status=OrderStatus.OPEN, type=OrderType.LIMIT, side=OrderSide.BUY, size=5, limitPrice=2050.0, ) # Create position model position = Position( id=67890, accountId=1001, contractId="CON.F.US.MNQ.U25", creationTimestamp="2024-01-01T10:00:00Z", type=PositionType.LONG, size=5, averagePrice=2050.0, ) # Create configuration config = ProjectXConfig( api_url="https://api.topstepx.com/api", user_hub_url="https://rtc.topstepx.com/hubs/user", market_hub_url="https://rtc.topstepx.com/hubs/market", timezone="America/Chicago", ) ``` Trading Entity Models: - Instrument: Tradeable financial instruments with tick information - Order: Trading orders with status, type, and execution details - Position: Open trading positions with size and average price - Trade: Executed trades with P&L and fee information - Account: Trading accounts with balance and permissions Configuration Models: - ProjectXConfig: Client configuration with endpoints and settings - Default TopStepX endpoints for production use - Customizable for different ProjectX deployments - Comprehensive validation and error handling Event Models: - OrderUpdateEvent: Real-time order status updates - PositionUpdateEvent: Real-time position changes - MarketDataEvent: Real-time market data updates Model Features: - Type-safe dataclass implementations - Comprehensive field documentation - Automatic serialization/deserialization - Validation and error handling - Default values for optional fields - Enum support for status and type fields See Also: - `config`: Configuration management utilities - `exceptions`: Error handling for model validation - `types`: Type definitions and protocols ) dataclass)AnyUnion) AccountBracketOrderResponse InstrumentMarketDataEventOrderOrderPlaceResponseOrderUpdateEventPositionPositionUpdateEventProjectXConfigTradecbeZdZUdZeed<eed<eed<eed<eed<eed<dZedzed <y) ra Represents a tradeable financial instrument/contract. Attributes: id (str): Unique contract identifier used in API calls name (str): Contract name/symbol (e.g., "MNQU25", "ESH25") description (str): Human-readable description of the contract tickSize (float): Minimum price movement (e.g., 0.1) tickValue (float): Dollar value per tick movement activeContract (bool): Whether the contract is currently active for trading Example: >>> print(f"Trading {instrument.name}") >>> print( ... f"Tick size: ${instrument.tickSize}, Tick value: ${instrument.tickValue}" ... ) idname descriptiontickSize tickValueactiveContractNsymbolId) __name__ __module__ __qualname____doc__str__annotations__floatboolrL/home/work/apex_v16/venv/lib/python3.12/site-packages/project_x_py/models.pyrrs8$ G IOHcDjr"rcNeZdZUdZeed<eed<eed<eed<eed<eed<y) rac Represents a trading account with balance and permissions. Attributes: id (int): Unique account identifier name (str): Account name/label balance (float): Current account balance in dollars canTrade (bool): Whether trading is enabled for this account isVisible (bool): Whether the account is visible in the interface simulated (bool): Whether this is a simulated/demo account Example: >>> print(f"Account: {account.name}") >>> print(f"Balance: ${account.balance:,.2f}") >>> print(f"Trading enabled: {account.canTrade}") rrbalancecanTrade isVisible simulatedN) rrrrintrrrr r!r"r#rrs'" G I NNOOr"rceZdZUdZeed<eed<eed<eed<edzed<eed<eed <eed <eed <dZedzed <dZedzed <dZ e dzed<dZ e dzed<dZ e dzed<dZ edzed<edefdZedefdZedefdZedefdZedefdZedefdZedefdZedefdZedefdZedefdZedefdZede fdZedefdZedefd Zy)!r a\ Represents a trading order with all its details. Attributes: id (int): Unique order identifier accountId (int): Account that placed the order contractId (str): Contract being traded symbolId (Optional[str]): Symbol ID corresponding to the contract creationTimestamp (str): When the order was created (ISO format) updateTimestamp (Optional[str]): When the order was last updated status (int): Order status code (OrderStatus enum): 0=None, 1=Open, 2=Filled, 3=Cancelled, 4=Expired, 5=Rejected, 6=Pending type (int): Order type (OrderType enum): 0=Unknown, 1=Limit, 2=Market, 3=StopLimit, 4=Stop, 5=TrailingStop, 6=JoinBid, 7=JoinAsk side (int): Order side (OrderSide enum): 0=Bid, 1=Ask size (int): Number of contracts fillVolume (Optional[int]): Number of contracts filled (partial fills) limitPrice (Optional[float]): Limit price (for limit orders) stopPrice (Optional[float]): Stop price (for stop orders) filledPrice (Optional[float]): The price at which the order was filled, if any customTag (Optional[str]): Custom tag associated with the order, if any Example: >>> side_str = "Bid" if order.side == 0 else "Ask" >>> print(f"Order {order.id}: {side_str} {order.size} {order.contractId}") r accountId contractIdcreationTimestampNupdateTimestampstatustypesidesizer fillVolume limitPrice stopPrice filledPrice customTagreturnc |jdk(S)zCheck if order is still open.r/selfs r#is_openz Order.is_open{{ar"c |jdk(S)z$Check if order is completely filled.r;r<s r# is_filledzOrder.is_filledr?r"c |jdk(S)zCheck if order was cancelled.r;r<s r# is_cancelledzOrder.is_cancelledr?r"c |jdk(S)zCheck if order was rejected.r;r<s r# is_rejectedzOrder.is_rejectedr?r"c|jdvS)z,Check if order is working (open or pending).)r:r;r<s r# is_workingzOrder.is_workings{{f$$r"c|jdvS)z&Check if order is in a terminal state.)rArDrGr;r<s r# is_terminalzOrder.is_terminals{{l**r"c |jdk(S)zCheck if this is a buy order.rr1r<s r#is_buyz Order.is_buyyyA~r"c |jdk(S)zCheck if this is a sell order.r:rPr<s r#is_sellz Order.is_sell rRr"c"|jrdSdS)zGet order side as string.BUYSELL)rQr<s r#side_strzOrder.side_strs u//r"cNdddddddd}|j|jd S) zGet order type as string.LIMITMARKET STOP_LIMITSTOP TRAILING_STOPJOIN_BIDJOIN_ASK)r:rArDrMrGrJUNKNOWN)getr0)r=type_maps r#type_strzOrder.type_strs7 ||DIIy11r"cNdddddddd}|j|jd S) zGet order status as string.NONEOPENFILLED CANCELLEDEXPIREDREJECTEDPENDING)rr:rArDrMrGrJrb)rcr/)r= status_maps r# status_strzOrder.status_str%s7 ~~dkk955r"cr|j|jdk(ry|j|jz dzS)z-Get percentage of order that has been filled.rdr3r2r<s r#filled_percentzOrder.filled_percent3s3 ?? "dii1n$))+s22r"cd|j |jS|j|jz S)zGet remaining unfilled size.rsr<s r#remaining_sizezOrder.remaining_size:s+ ?? "99 yy4??**r"cd|jvr.|jjd}t|dk\r|dS|jS)z Extract symbol from contract ID..rMrDr,splitlenr=partss r#symbolz Order.symbolAsB $// !OO))#.E5zQQxr")rrrrr)rrrr3r4rr5r6r7propertyr r>rBrErHrKrNrQrTrXrerortrvr~r!r"r#r r s6 GNO4Z K I I IHcDj!Jd !#J #"Iut|" $K$ IsTz      4   d   T  %D%%+T++0#00 2# 2 2 6C 6 6333 +++ r"r c@eZdZUdZeed<eed<eed<edzed<y)r a Response from placing an order. Attributes: orderId (int): ID of the newly created order success (bool): Whether the order placement was successful errorCode (int): Error code (0 = success) errorMessage (Optional[str]): Error message if placement failed Example: >>> if response.success: ... print(f"Order placed successfully with ID: {response.orderId}") ... else: ... print(f"Order failed: {response.errorMessage}") orderIdsuccess errorCodeN errorMessage)rrrrr)rr rr!r"r#r r Ks" L MN*r"r F)initc:eZdZUdZeed<eed<eed<eed<eed<eed<eed<dededededededed ed d fd Z d ed e eeeffdZ e d e fdZe d e fdZe d efdZe d efdZe d efdZe d efdZddeded efdZy )r a Represents an open trading position. Attributes: id (int): Unique position identifier accountId (int): Account holding the position contractId (str): Contract of the position creationTimestamp (str): When the position was opened (ISO format) type (int): Position type code (PositionType enum): 0=UNDEFINED, 1=LONG, 2=SHORT size (int): Position size (number of contracts, always positive) averagePrice (float): Average entry price of the position Note: This model contains only the fields returned by ProjectX API. For P&L calculations, use PositionManager.calculate_position_pnl() method. Example: >>> direction = "LONG" if position.type == PositionType.LONG else "SHORT" >>> print( ... f"{direction} {position.size} {position.contractId} @ ${position.averagePrice}" ... ) rr+r,r-r0r2 averagePrice_extrar8Nc f||_||_||_||_||_||_||_y)N)rr+r,r-r0r2r) r=rr+r,r-r0r2rrs r#__init__zPosition.__init__s7"$!2  (r"keyct||}t|ttztzr|St d|dt |d)Nz Attribute z has type z, expected int, str, or float)getattr isinstancer)rr TypeErrorr0)r=rvalues r# __getitem__zPosition.__getitem__sJc" eS3Y. /LSEDK=8UV r"c |jdk(S)z!Check if this is a long position.r:r0r<s r#is_longzPosition.is_longrRr"c |jdk(S)z"Check if this is a short position.rArr<s r#is_shortzPosition.is_shortrRr"c8|jry|jryy)z!Get position direction as string.LONGSHORT UNDEFINED)rrr<s r# directionzPosition.directions << ]]r"cd|jvr.|jjd}t|dk\r|dS|jS)zFExtract symbol from contract ID (e.g., 'MNQ' from 'CON.F.US.MNQ.H25').rxrMrDryr|s r#r~zPosition.symbolsB $// !OO))#.E5zQQxr"cL|jr |j S|jS)z2Get size with sign (negative for short positions).)rr2r<s r# signed_sizezPosition.signed_sizes"]] z9 9r"c4|j|jzS)zCalculate total position cost.)r2rr<s r# total_costzPosition.total_costsyy4,,,,r" current_price tick_valuec|jr||jz |jz|zS|jr|j|z |jz|zSy)z Calculate unrealized P&L given current price. Args: current_price: Current market price tick_value: Value per point move (default: 1.0) Returns: Unrealized P&L in dollars rq)rrr2r)r=rrs r#unrealized_pnlzPosition.unrealized_pnlsS <<!D$5$55BZO O ]]%% 5BZO Or")g?)rrrrr)rrrrrrrrr rrrr~rrrr!r"r#r r csg0 GNO I I) ) )  )  ))))) )*suS#u_'=$3:S::-E--Euur"r ceZdZUdZdZeed<eed<eed<eed<eed<edzed <eed <eed <eed <e ed <eed<y)raD Represents an executed trade with P&L information. Attributes: id (int): Unique trade identifier accountId (int): Account that executed the trade contractId (str): Contract that was traded creationTimestamp (str): When the trade was executed (ISO format) price (float): Execution price profitAndLoss (Optional[float]): Realized P&L (None for half-turn trades) fees (float): Trading fees/commissions side (int): Trade side: 0=Buy, 1=Sell size (int): Number of contracts traded voided (bool): Whether the trade was voided/cancelled orderId (int): ID of the order that generated this trade Note: A profitAndLoss value of None indicates a "half-turn" trade, meaning this trade opened or added to a position rather than closing it. Example: >>> side_str = "Buy" if trade.side == 0 else "Sell" >>> pnl_str = f"${trade.profitAndLoss}" if trade.profitAndLoss else "Half-turn" >>> print(f"{side_str} {trade.size} @ ${trade.price} - P&L: {pnl_str}") ) r+r,r-feesrrprice profitAndLossr1r2voidedrr+r,r-rNrrr1r2rr) rrrr __slots__r)rrrr r!r"r#rrsM4 I GNO L4< K I I L Lr"rceZdZUdZeed<edzed<edzed<edzed<eed<eed<eed <d ed <d ed <d ed <edzed<y)raP Response from placing a bracket order with entry, stop loss, and take profit. Attributes: success (bool): Whether the bracket order was successfully placed entry_order_id (Optional[int]): ID of the entry order stop_order_id (Optional[int]): ID of the stop loss order target_order_id (Optional[int]): ID of the take profit order entry_price (float): Entry price used stop_loss_price (float): Stop loss price used take_profit_price (float): Take profit price used entry_response (OrderPlaceResponse): Response from entry order stop_response (Optional[OrderPlaceResponse]): Response from stop loss order target_response (Optional[OrderPlaceResponse]): Response from take profit order error_message (Optional[str]): Error message if bracket order failed Example: >>> if response.success: ... print(f"Bracket order placed successfully:") ... print(f" Entry: {response.entry_order_id} @ ${response.entry_price}") ... print(f" Stop: {response.stop_order_id} @ ${response.stop_loss_price}") ... print( ... f" Target: {response.target_order_id} @ ${response.take_profit_price}" ... ) ... else: ... print(f"Bracket order failed: {response.error_message}") rNentry_order_id stop_order_idtarget_order_id entry_pricestop_loss_pricetake_profit_pricezOrderPlaceResponse | Noneentry_response stop_responsetarget_response error_message) rrrrr rr)rrr!r"r#rrsZ8M$J:4Z//..00:r"rceZdZUdZdZeed<dZeed<dZeed<dZ eed <d Z eed <d Z e ed <dZ e ed<dZeed<dZe ed<dZe ed<y)ra Configuration settings for the ProjectX client. Default URLs are set for TopStepX endpoints. For custom ProjectX endpoints, update the URLs accordingly using create_custom_config() or direct assignment. TopStepX (Default): - user_hub_url: "https://rtc.topstepx.com/hubs/user" - market_hub_url: "https://rtc.topstepx.com/hubs/market" Attributes: api_url (str): Base URL for the API endpoints realtime_url (str): URL for real-time WebSocket connections user_hub_url (str): URL for user hub WebSocket (accounts, positions, orders) market_hub_url (str): URL for market hub WebSocket (quotes, trades, depth) timezone (str): Timezone for timestamp handling timeout_seconds (int): Request timeout in seconds retry_attempts (int): Number of retry attempts for failed requests retry_delay_seconds (float): Delay between retry attempts requests_per_minute (int): Rate limiting - requests per minute burst_limit (int): Rate limiting - burst limit zhttps://api.topstepx.com/apiapi_urlzwss://realtime.topstepx.com/api realtime_urlz"https://rtc.topstepx.com/hubs/user user_hub_urlz$https://rtc.topstepx.com/hubs/marketmarket_hub_urlzAmerica/Chicagotimezonetimeout_secondsrDretry_attemptsg@retry_delay_seconds<requests_per_minute burst_limitN)rrrrrrrrrrrrr)rrrrrr!r"r#rrGso.2GS19L#9rs>pd"      8  4 JJ JZ  . }}}@ 33 3l '' 'V !! !H      r"