API & data processing
Investment Tax Calculation API
A Python API that accepted US stock market transactions in XLSX files and returned per-stock calculations and a consolidated total for a Ukrainian client.
- Spreadsheet
Transactions in English or Ukrainian.
- Organization
Purchases and sales grouped by stock.
- Calculation
Matching against the earliest purchases.
- Response
Per-stock values and a total in JSON.
This page draws on my experience building the project. The original materials are no longer available, and the diagram is illustrative.
Bringing a period’s transactions together
A Ukrainian client traded on the US stock market, mainly through swing trading, and needed to calculate the tax amounts associated with his transactions. The data came in an XLSX spreadsheet, usually covering a year.
I developed the entire API in Python. It accepted the file, organized the transactions and returned JSON containing per-stock values and a consolidated total. I used pandas and NumPy for reading, processing and calculations.
Purchases and sales of the same stock
The main challenge was each stock’s transaction history. A purchase could be sold in several parts, with further purchases and sales of the same stock throughout the period.
I used a queue to match transactions: as sales were processed, they consumed the earliest purchases available in the file. This FIFO approach tracked the quantities associated with each transaction.
Spreadsheet parsing was another concern. The client needed to submit documents in both English and Ukrainian, so the processing recognized the information in either language format.
Delivery and the scope of this account
The client used the API and confirmed that it worked for him. The delivery automated spreadsheet reading and calculation consolidation into a response another system could consume.
I estimate that the automation saved roughly a month of manual work per year. This is a retrospective estimate, without tracked hours or confirmation from the client.
The validation I received was the client’s feedback after using the API. This account does not include an independent tax review.
Technologies
Python · pandas · NumPy