How an AI Agent Should Attribute Realized and Unrealized PnL
Learn how an AI trading agent can correctly separate realized and unrealized profit and loss, track changes, and handle uncertainty in live markets.
Produced with automation, then checked by deterministic quality rules and an independent source-grounded review before publication.
- 01Realized PnL is recorded only when a position is closed or partially closed with a confirmed trade execution.
- 02Unrealized PnL reflects the current market value of open positions and must be recomputed on each price update.
- 03Accurate attribution requires linking each trade to its originating order and maintaining a durable mutation identifier.
- 04Risk limits and owner‑authorized scopes should be consulted before recognizing PnL to avoid exceeding daily loss caps.
- 05Both realized and unrealized PnL calculations must handle missing or stale market data by flagging uncertainty rather than assuming zero.
An AI trading agent attributes realized profit and loss (PnL) when a trade results in a confirmed change to the account balance, and it attributes unrealized PnL by continuously valuing open positions against the latest market data. This distinction ensures that performance metrics reflect actual cash flow and the current risk exposure of the portfolio.
What Is Realized PnL and How Is It Recorded?
Realized PnL is the net cash effect of a trade that closes all or part of a position. The agent must capture the exact execution price, quantity, fees, and any owner‑defined limits that apply to the trade. Because order execution can be delayed or partially filled, the agent should wait for a durable mutation identifier confirming the trade before updating the realized PnL ledger.
- The trade’s execution price is taken from the market data source that includes timestamp and freshness metadata.
- Fees and commissions are subtracted as reported by the venue; missing fee data is flagged as uncertain.
- Owner‑authorized loss limits are checked; if a trade would breach a daily loss cap, the agent must abort or seek owner approval.
- Partial fills generate separate realized PnL entries for each fill, each linked to its own mutation ID.
How Is Unrealized PnL Calculated for Open Positions?
Unrealized PnL represents the difference between the current market value of an open position and its cost basis. The agent recomputes this value whenever new market data arrives, using the most recent price that includes source, timestamp, and any quality warnings.
- The cost basis is the weighted average price of all fills that created the position.
- The current market price must be verified; if the data is stale or missing, the agent records a warning instead of a numeric PnL.
- Unrealized PnL is stored separately from realized PnL to avoid double counting.
- Large price swings may trigger a review of risk limits before the agent acts on the updated PnL.
How Should an AI Agent Handle Data Gaps and Stale Prices?
When market data is missing, delayed, or flagged with warnings, the agent must treat the unrealized PnL as uncertain. It should log the condition, avoid making trade decisions based on that data, and optionally pause execution until reliable data returns. For related context, see How an AI Agent Should Handle Partial Fills.
- Include source and timestamp in every price snapshot.
- Record a warning in the decision log when data freshness falls below the acceptable threshold.
- Do not default missing money to zero; instead, propagate the uncertainty to downstream risk checks.
- Consider an emergency stop if data gaps persist beyond a configurable window.
What Controls Influence PnL Attribution?
Owner‑signed limits and agent key scopes shape how PnL is recognized. Limits may cap daily notional, daily loss, or maximum position size. The agent must verify that any realized gain does not inadvertently mask a breach of a loss limit.
- Daily loss limits are evaluated after each realized PnL update.
- Order‑size limits affect the maximum exposure that can generate unrealized PnL.
- Expiry dates on agent keys can force a re‑evaluation of open positions before the key becomes invalid.
- Permissions should be reviewed regularly; see Essential Risk Limits Every AI Trading Agent Should Enforce.
How Do Error States and Timeouts Affect PnL Tracking?
A timeout does not prove that an order failed; the agent must query the durable mutation state to confirm success or failure before adjusting PnL. If an error persists, the agent should log the error and may pause further activity pending owner review.
- Check the mutation identifier for a definitive success or failure status.
- Log each timeout and the subsequent reconciliation outcome.
- If the error relates to market data unavailability, refer to How a Trading Agent Should Respond When Execution Is Unavailable.
- Repeated errors may trigger an emergency stop as described in the system documentation.
Accurate PnL attribution is a foundation for risk management, not a shortcut to performance claims.
Frequently asked questions
Separating the two ensures that cash‑flow effects are recorded only when they actually occur, while unrealized values reflect current market risk without affecting the account balance.
The agent should flag the data as uncertain, avoid making trade decisions based on it, and optionally pause execution until fresh data is available.
By checking the durable mutation identifier returned by the venue; this confirms success independent of timeout signals.
Limits define thresholds such as daily loss caps; the agent must evaluate realized PnL against these limits before confirming the trade.
If data gaps, repeated errors, or limit breaches persist, the agent should trigger an emergency stop to halt new activity while the owner reviews the situation.
Sources and verification
Product claims in this article were checked against these first-party references. Runtime status remains authoritative for current availability.
- Felix documentationfirst party
- Felix machine referencefirst party
Build with Felix now.
Felix infrastructure is live through MCP and the API. The full trading app launches September 17.
A decision log captures every step an AI trading agent takes, providing transparency, auditability, and a safety net for operators. This guide outlines the key fields and best practices for building a robust log.
Market hours shape the context of every quote, influencing its freshness, liquidity, and price formation. This article explains why timing matters and how to interpret quotes responsibly.