Initial support for options trading

[itshukychen]

💡 Overview

This PR introduces initial support for option selling/buying tracking in PortfolioPerformance.

Previously, options imported from IB were treated as standard securities. While this accurately reflected the instrument itself, it had several limitations:

• There was no way to track earnings and losses from premiums.
• Each option trade created a distinct security (due to strike, expiry, and type differences), making aggregation and performance tracking difficult.

This PR addresses these issues by:

• Treating option buy/sell transactions as a new type of earning/loss.
• Associating them with the underlying security, enabling performance tracking by trading asset (e.g., SPX, SPXW), rather than per-contract.

---

✅ Changes

• Introduced new transaction types: OPTION_BUY and OPTION_SELL across the application (transactions, earnings, accounts, etc.).
• Implemented support for option transactions in IBFlex import.
• Fixed bug: IBFlex was previously importing unexecuted option trades.
• Removed support for tracking open option positions, due to how PP handles securities (explained below).
• Added test coverage for IBFlex option imports.

---

🔍 Background & Rationale

Before this change, each unique option (strike/expiry/type) was treated as its own security, cluttering the portfolio view and preventing strategy-level analysis.

This implementation instead groups transactions under the underlying instrument, making it possible to track P&L across strategies like SPX weekly puts or similar.

By doing so, we lose per-option price tracking, which is tied to the specific option contract. I consider this tradeoff acceptable, as:

• Tracking unrealized P&L for options is complex and less relevant in PP’s current model.
• Users benefit more from tracking realized premium income/losses.
• Users requiring open position tracking can use more specialized tools.

---

❓ Open Questions

1. Option price tracking:
   Currently, the underlying security’s price is used (if available), which adds helpful context.
   → Should we consider adding price tracking at the option level in the future?

2. Option metadata:
   Right now, the full option ticker (e.g. SPXW 250613P05605000) is stored in the transaction comment.
   → Would it make sense to model a dedicated OptionTransaction class with structured fields for metadata and future pricing support?

---

Looking forward to feedback! Let me know if this direction aligns with project goals, or if any part of the implementation needs refinement.

[pfalcon]

@itshukychen :

Looking forward to feedback!

Sure!

This PR introduces initial support for option selling tracking

How option selling is different from option buying, from futures selling, from futures buying, from XYZ selling or XYZ buying, etc, etc.?

Previously, options imported from IB were treated as standard securities.

And that's the right approach, because an option (future, XYZ, etc.) is a security (or "securitized" asset, feel free to track your real estate portfolio with PP).

There was no way to track earnings and losses from premiums.

That's because PP doesn't support short trades, which is a well-known limitation, with many people making attempts towards resolving it.

Each option trade created a distinct security (due to strike, expiry, and type differences), making aggregation and performance tracking difficult.

Each option is distinct security in PP because it's a distinct security in reality. And no, it doesn't make "aggregation and performance tracking difficult", it just needs to be done separately, at a different level.

Introduced new transaction types: OPTION_BUY and OPTION_SELL across the application (transactions, earnings, accounts, etc.).

For comparison, #1736 also tried to implement short trades support with adhoc transaction types. That didn't fly. Again, an attempt to implement much more generic and direly needed feature by introducing adhoc transaction types didn't fly, countered by a question "What do you do if you buy 1 security, sell 2, and buy 1 again?" Back to OPTION_BUY/OPTION_SELL, do you anticipate that someone wanting to add futures support will need to add FUTURES_BUY/FUTURES_SELL, someone wanting to support XYZ would need to add XYZ_BUY/XYZ_SELL, and given that number of derivatives/funky instruments is potentially unlimited, do you anticipate the potential need to add dozens of adhoc *_BUY/*_SELL transactions? If not, then maybe OPTION_BUY/OPTION_SELL should be treated the same way either.

Removed support for tracking open option positions, due to how PP handles securities (explained below).

Oh no, please don't remove anything ;-). Feel free to add a new visualization/analysis/whatever layer for options, but removing something behind people's back doesn't sound right.

Before this change, each unique option (strike/expiry/type) was treated as its own security, cluttering the portfolio view

Well, that only means that first change which would be added to PP related to options would be a simple and easy to review "Shown only options" / "Show only non-options" filter.

and preventing strategy-level analysis.

What do you mean "preventing"? It's enabling it. Anyone can take what's real - individual transactions and analyze them in any way they want. It's opposite, your change of "removing" something and enforcing rigid adhoc structure will prevent/complicate any strategy-level analysis beyond that adhoc one.

This implementation instead groups transactions under the underlying instrument, making it possible to track P&L across strategies like SPX weekly puts or similar.

In the UI - sounds stellar. Shaking up (removing!) things from the data model for that sound questionable.

By doing so, we lose per-option price tracking, which is tied to the specific option contract. I consider this tradeoff acceptable, as:

Please don't lose us anything. That's not acceptable ;-).

Tracking unrealized P&L for options is complex

An option is security and tracking unrealized P&L for a security is simple: opening amount - current amount. That works for any security (options included), so again, please don't lose that for us.

Users benefit more from tracking realized premium income/losses.

I would suggest that users benefit from ability to track their transactions in general and generic way. On top of which any analysis can be implemented. Consequently, any change which limits them in recording and tracking what actually happens and enforcing limited and adhoc view is not for users' benefit.

Users requiring open position tracking can use more specialized tools.

Sorry, but again, the opposite - users requiring more specialized tracking for options beyond the "generic security" level, can implement a more specialized tool on top of existing PP data model. If such a tool implemented within PP - again, great/stellar. (If not, many people certainly implemented it outside, again interfacing with a generic "it's a security" data model.)

[itshukychen]

Thanks @pfalcon for the feedback on the PR — I appreciate the thoughtful consideration.

I’d like to open a broader discussion around how derivatives in general might be better supported in PortfolioPerformance. I fully understand and respect the architectural decisions in PP so far, and I hope this can be a collaborative exploration of the right path forward.

---

Current Limitations with Derivative Instruments

Most derivatives — including options, futures, and future options — introduce characteristics that differ fundamentally from standard securities:

• They have expiration dates, which define their lifespan. Once expired, they typically disappear from broker platforms and are no longer tradable.
• Expiration rarely triggers a transaction; the instrument simply becomes worthless or settles silently.
• Some derivatives (e.g. options) involve a premium — a cash transaction when buying or selling.
• Others (e.g. many futures contracts) involve no upfront cash transfer — gains or losses are only realized on settlement.
• In many cases, selling opens a position, not closes one — and the sold item may not even exist in your portfolio prior to the sale (i.e., a short exposure).

These properties are difficult to model within PP's current structure, where:

• Each instrument is treated as a long-term, persistent security.
• Selling implies ownership and closes a position.
• There is no expiration awareness.
• There’s no native concept of short positions or open obligations.

---

Selling a Stock vs Selling a Derivative

This distinction is critical for both risk modeling and portfolio visualization:

Action	Selling a Stock	Selling a Derivative
Purpose	Close an existing position	Open a position/obligation
Risk Impact	Reduces exposure	Increases exposure
Ownership	You own what you sell	You’re selling something you may not own (short)
Cash Flow	Receive proceeds	May receive premium or nothing
Lifecycle	Complete on sale	Open until expiry/assignment/close

From a modeling standpoint:

• Selling a stock decreases your holdings and ends exposure.
• Selling a derivative creates a liability, often shown as a negative position (e.g., -1 contract) in broker systems.

This matters especially for premium-based strategies (e.g., selling puts for income), which behave more like income generation than capital gains — even though they rely on buy/sell mechanics.

---

Challenges with Current PP Modeling

If I import a year’s worth of option or future trades into PP today:

• I may end up with hundreds of short-lived instruments, each cluttering the security list.
• Expired instruments stay visible, even though they’ve gone to zero and are no longer relevant.
• Premiums collected are treated as capital gains from asset sales, not as income from taking on risk.
• There is no mechanism to archive, auto-zero, or filter out expired contracts.

---

Proposal for Discussion

If derivatives are to be supported more fully in PP, a few potential directions could help:

1. Introduce expiration metadata for securities, and allow for auto-zeroing or archiving once expired.
2. Support short positions or open obligations, so that selling a derivative reflects increased risk rather than a reduction of assets.
3. Treat premium income (where applicable) as a type of earning, similar to dividends or interest, rather than as proceeds from an asset sale.
4. Add optional instrument type metadata (e.g., Option, Future, Future Option) to allow lifecycle-specific behavior and clearer visualization.

---

Final Thoughts

I’m not advocating for a full redesign, but rather raising a modeling gap that is increasingly relevant for users who trade derivatives for income or hedging purposes.

I’d love to hear your thoughts on whether derivatives support fits within the scope of PP, and if so, how you think it might be structured to balance flexibility with PP’s core model.

Happy to rework my approach and contribute in whatever direction aligns best with the project.

FYI
I edited a fix to my initial comment as my PR aims to support both buying and selling of options

[pfalcon]

@itshukychen :

Thanks @pfalcon for the feedback on the PR — I appreciate the thoughtful consideration.

Glad that you find it useful. And I'd like to note that I don't steer PP direction, everything here is just my personal opinion (but backed by contribution to PP over some time, and even more experimenting with it).

Most derivatives — including options, futures, and future options — introduce characteristics that differ fundamentally from standard securities:

I would disagree with such formulation. I'd say, they differ somewhat, mostly adding more properties. (There's definitely more behavior behind them, but arguably, PP's task is capture results of that behavior == state of properties, not model the behavior).

They have expiration dates, which define their lifespan. Once expired, they typically disappear from broker platforms and are no longer tradable.

They disappear from "platform", but not from broker statements, and arguably, PP's task is exactly to capture these statements and make available to user or further analytics in many ways.

Expiration rarely triggers a transaction; the instrument simply becomes worthless or settles silently.

I again would disagree. For most people, source of PP transaction is brokerage statements, and expiration is always mirrored in these statement, so for as long as they are properly imported into PP, this aspect of the behavior is not something to worry on the PP side.

Each instrument is treated as a long-term, persistent security.

Each instrument which had transactions is persistent (cannot be deleted). That's of course how it should be. But PP has concept of "inactive" instruments, which is perfect fit for expiring instruments.

Selling a stock decreases your holdings and ends exposure.
Selling a derivative creates a liability, often shown as a negative position (e.g., -1 contract) in broker systems.

As was mentioned previously, this is (largely) not underlying/derivative difference, but short vs long trade difference, with lack of short trades support being major limitation of PP, requiring addressing with priority.

Expired instruments stay visible, even though they’ve gone to zero and are no longer relevant.

As mentioned above, the most obvious way to deal with that is to set them "inactive". Such are not shown by default, but can be easily shown still (checking which previous option you sold before, at what strike, for how much premium would be very natural and regular tasks). How this is done (setting inactive) - is a separate matter, worth discussion.

Premiums collected are treated as capital gains from asset sales, not as income from taking on risk.

But they are absolutely capital gains - you buy security, you sell it, or sell, then buy (expiration is nothing than selling/buying for 0). It's unrealistic to expect them treated otherwise - either by majority of participants or by tax codes.

Here's important point - it's unrealistic to make PP do what each individual may want. And the approach of the contributors should be "let's implement something generic, aspects of which may suit many people, then hopefully one aspect of this generic solution may work for us, or if still not, then maybe it will be small change in personal fork on top of generic solution, without enforcing it on everyone".

So again, it's unrealistic to treat capital gains from options as "income" (e.g. as dividends from stocks), because it's not. But if you instead formulate user story as "I want capital gains (fees, etc.) from options calculated separately from stocks", you get my full understanding. Actually, that's what I implemented (well, prorotyped) in my fork.

There is no mechanism to archive, auto-zero, or filter out expired contracts.

As discussed, there's no-nonsense archiving mechanism. PP has not bad filtering mechanisms, but they can be elaborated 5x times more for good. There's no "auto" in zeroing, and we'd need separate discussion on whether it's "better" (in some definition of "better") be done inside or outside PP (again, you get "auto" if you just properly import brokerage statements).

Introduce expiration metadata for securities, and allow for auto-zeroing or archiving once expired.

If you say "let's add "expirationDate" property to Security", you get my immediate +0.5. I'm sure we'll get there, eventually. However, I don't think adding that is any kind of first step of priority. To remind, you can add arbitrary custom fields to security in PP. So, you can add expiration date. What's next?

Support short positions

This is absolutely the highest priority issue in PP. I said "enough" to perfectionism ("it's not complete!") brushed up my 2-years old patches and posted #4832. All effort was made to make it a breeze for @buchen to merge. We'll see how it goes.

Add optional instrument type metadata (e.g., Option, Future, Future Option)

PP currently (to the best of my knowledge) supports 2 types of instruments: exchange [currency] pair and well, "everything else". Being an exchange pair is "calculated property". #4827 adds another calculated property for "being an option". An explicit type field is possible, but probably again not a priority, because a custom field can be added and seen where it goes from there.

I’m not advocating for a full redesign, but rather raising a modeling gap that is increasingly relevant for users who trade derivatives for income or hedging purposes.

It's definitely useful to consider what lies on a path for better derivative support in PP, and specifically, what lies on critical path (can't be maneuvered around). Short sale support is definitely such a thing. Pulling that together definitely would be helpful. An obvious problem area is test coverage. Last time I intended to post #4832 was winter holidays, I then faced #4481, got feedback, and there it waited another half a year.

[starze]

A few weeks ago I created a pull request to reintroduce the previously available support for options trading in Portfolio Performance versions prior to 0.63. With these changes it is possible to import option buy transactions with a price of 0$ again. They are handled as regular buy and sell transactions.

You can find the details here:

• WIP: Allow import of expired options #4647
• 0€ Inbound delivery (or: How to handle scrip dividends?) #3365 (comment)

---

I would suggest that users benefit from ability to track their transactions in general and generic way.

My approach aligns more with the generic idea suggested by @pfalcon, rather than the direction described by you, @itshukychen.

I’d like to open a broader discussion around how derivatives in general might be better supported in PortfolioPerformance

I truly appreciate any discussion and effort aimed at improving or reinstating support for options and other derivative instruments.

Some thoughts about our different approaches:

• In my opinion we can handle Option trading exactly the same as Stock trading.
• If we sell Options, we get money - same if we sell Stocks
  • we usually call it premium when trading options but its actually the same with short stocks - except that they usually do not expire and fall to 0$
• If we buy Options we pay money - same if we buy Stocks.
  • If we Sell and Buy Options before expiration date its exaclty the same behaviour.
• The only specialty with expired Options can be reduced to a buy transaction with 0$ (on expiration).
  • If we consider delisted stocks while being short its almost the same with stocks, too.
• If we look at the reports of Interactive broker its excactly the same bahaviour. I already described this in 0€ Inbound delivery (or: How to handle scrip dividends?) #3365 (comment)

Some thoughts on your other ideas and requirements

• Grouping of "options only" performance could also be based on asset allocations (so we can keep it generic)
• An automatism that closes/buys expired Options is not necessary because Option prices fall to 0$ when expired and therefore the performance calculations are always reflecting the correct values. The buy order will eventually get imported with the next Interactive-Broker flexquery import and clean the portfolio holdings.
• The "problem" with too many Instruments in the Stocks list can be handled by setting old options as "inactive" (multi-select) and filter them out.

Introduce expiration metadata

In general I like the idea of adding additional meta data to a generic solution. This allows the usage of generic widgets and on top of it the creation of custom analysis widets or filters that allow more detailed analysis as you described.

In conclusion I see the following things that should be adressed in PP:

1. Adding 0$ transactions again (WIP: Allow import of expired options #4647)
2. Improving support for short transactions (as stated by @pfalcon) - not sure if this is actually necessary
3. optional: Adding tags to identify options and create specific widgets

@buchen and @Nirus2000
I would love to here your thoughts on this because I still wondering what is actually missing to get a generic option support being accepted.

[pfalcon]

@starze :

You can find the details here:
#4647

I left some comments in that PR.

In my opinion we can handle Option trading exactly the same as Stock trading.

Right.

The only specialty with expired Options can be reduced to a buy transaction with 0$ (on expiration).

It's not a specialty in any way. Any security can be bought or sold for 0 amount. Lack of support of that in PP is an obvious issue. (But completely orthogonal to other issues, like lack of short trade support.)

Improving support for short transactions (as stated by @pfalcon) - not sure if this is actually necessary

It's pretty sad that you're not sure. Without different parties being sure of it, a lot of functionality in PP will remain locked out. You can project that to @buchen - just imagine that if he was interested in options, they would have been supported. But he's not interested in them and then "not sure". For the rest, you can project it on yourself - imagine that you maintain a complex open-source project with which you largely satisfied and somebody sent you a wall of code. I have some experience with maintaining open-source projects, and for me, the situation is all familiar - walls of code tend to wait a long time. That's why I'm trying to make simple patches which would have the greatest effect. Then, ideally, there would be positive feedback loop, where a maintainer would be able to easily process simple patches quickly, and contributors would be motivated to make next simple steps to build real complex functionality. Sadly, that approach doesn't seem to work with PP, where simple patches, complex patches - all wait long. I still don't think that bombarding maintainers with walls of code would help.

Actually, assuming that model of what goes into PP and what isn't, is "random selection", it's only worse - because again, walls of code are hard to review, and that likely means that they full of adhoc assumptions and limitation. As an example, comment like #4647 (comment) shows that the case of long options was underthought, probably untested, and possibly doesn't work in reasonable way.

[financelurker]

How option selling is different from option buying, from futures selling, from futures buying, from XYZ selling or XYZ buying, etc, etc.?

Margin Requirements. What hasn't been mentioned by now is: When opening a short position the capital at risk isn't just the opened trade value, but in addition an intial margin set by the broker. In my cash account (not sure how this behaves in a margin account) that required margin cannot be used for other trades until you close that short position again. This aspect is different, when going short instead of long. I'd assume this aspect is crucial for calculating the total position size and RoR of trades. Margin requirements may change over time.

Besides that there are some specifics to options - different forms of collateral depending on short side:

• selling put option:
  • cash secured put -> collateral is cash in your account
  • you're effectivelly long the underlying position: increasing stocks prices are in your favor
• selling call option:
  • covered call -> collateral is 100 shares of the base asset you own in the same account
  • cash secured call -> collateral is cash in your account
  • you're effectivelly short the underlying position: falling stocks prices are in your favor

That being said, I think what collateral type is being used when the option gets exercised can be manually modelled in Portfolio Performance somehow with a combination of sell/buy/in-/outbound-delivery transactions. To start with I would be happy to see the short trades in the trades view and also under calculation, without getting an error (or being silently ignored, like it is in the calculation view).

Would be cool, if others could add other securities and financial products into Portfolio Performance vía some sort of interface/plugin-mechanism. Would that be possible?

---

And just because it was asked what further differences there are:

• Bonds
  • Selling: receives accrued interest when selling
  • Buying: pays accrued interest when buying (in addition to commission, etc.)

I would assume every asset class has it's own specifics in that matter.