Metadata-Version: 2.4
Name: itr-schedule-fa
Version: 0.1.1
Summary: Generate Indian Income Tax Schedule FA from US broker (like etrade) statements by reconstructing historical holdings, calculating investment values, converting USD to INR using historical exchange rates (using sbi-tt-rates), and producing a portal-ready CSV.
Project-URL: Homepage, https://github.com/jdecodes/itr-schedule-fa
Project-URL: Repository, https://github.com/jdecodes/itr-schedule-fa
Project-URL: Issues, https://github.com/jdecodes/itr-schedule-fa/issues
Author-email: jdecodes <jaideep_sharma@live.com>
License: MIT
License-File: LICENSE
Keywords: espp,etrade,foreign-assets,income-tax,india,itr,rsu,sbi-tt-rates,schedule-fa,tax
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: fa-inrdata-api>=0.1.0
Requires-Dist: openpyxl>=3.1
Requires-Dist: pandas>=2.2
Requires-Dist: sbi-tt-rates>=0.1.0
Requires-Dist: yfinance>=1.5.2
Description-Content-Type: text/markdown

# itr-schedule-fa

Convert US broker statements into Schedule FA for the Indian Income Tax Return.

`itr-schedule-fa` is an open source Python library that converts broker statements into the Schedule FA format required by the Indian Income Tax portal.

The project currently supports **E*TRADE** statements and is designed so additional brokers can be added over time.

---

## What it does

Preparing Schedule FA usually involves:

* reconstructing historical holdings
* calculating acquisition values
* finding the peak value during the financial year
* converting USD values into INR using historical exchange rates
* preparing the data in the format expected by the Income Tax portal

This library performs those calculations and generates a Schedule FA CSV from your broker statements.

---

## Features

* Parse E*TRADE holdings statements
* Parse E*TRADE gain/loss statements
* Reconstruct holdings for the reporting year
* Calculate:

  * Initial investment value
  * Peak investment value
  * Closing balance
  * Gross sale proceeds
* Convert USD values to INR using historical exchange rates
* Generate Schedule FA CSV

---

## Installation

```bash
pip install itr-schedule-fa
```

---

## Supported brokers

----------------------------------
| Broker  | Status      | version|
| ------- | ----------- |--------|
| E*TRADE | Supported   | 0.0.1  |
----------------------------------
More brokers are planned.

---

## Supported stocks

Currently the library supports multiple stocks**
(if your broker is etrade)

---

## Required files

The library accepts up to three input files.

| File              | Required | Description                                     |
| ----------------- | -------- | ----------------------------------------------- |
| `holdings.xlsx`   | Yes      | Current holdings exported from your broker      |
| `gnl_within.xlsx` | No       | Shares sold during the reporting financial year |
| `gnl_after.xlsx`  | No       | Shares sold after the reporting financial year  |

If there were no transactions in a category, simply omit that file.
Note : All 3 files are needed in expanded view for the parsers to work.

---

## E*TRADE Holdings Report

Holdings -> View By Status -> Download Expanded

## E*TRADE Gain/Loss Reports

Download for current FY year and last year as well.

If filing for FY 2025-26 (AY 2026-27), download (Expanded View):

- Gain & Loss report for 2025
- Gain & Loss report for 2026

The purpose of the second Gain & Loss report is to reconstruct your holdings as of 31-Dec-2025.

For example, if you received an RSU in 2024 but sold it in January 2026, it will no longer appear in the holdings report downloaded during ITR filing season.

The transaction report is therefore used to add those shares back so that the holdings accurately reflect the position as of 31-Dec-2025.

## Example

```python
from pathlib import Path

from itr_schedule_fa import ScheduleFA
from itr_schedule_fa.factory import (
    supported_brokers,
    supported_tickers,
)

BROKER = "etrade"
TICKER = "QCOM"
REPORTING_YEAR = 2025  # a convention that fy 2025-26


def main():
    print(f"Broker         : {BROKER}")
    print(f"Ticker         : {TICKER}")
    print(f"Reporting Year : {REPORTING_YEAR}")

    if TICKER not in supported_tickers():
        raise ValueError(
            f"Unsupported ticker '{TICKER}'. Supported tickers: {', '.join(supported_tickers())}"
        )

    if BROKER not in supported_brokers():
        raise ValueError(
            f"Unsupported broker '{BROKER}'. Supported brokers: {', '.join(supported_brokers())}"
        )

    data_dir = Path(__file__).parent / "data"

    owned = data_dir / "holdings.xlsx"
    sold_within = data_dir / "gnl_within.xlsx"
    sold_after = data_dir / "gnl_after.xlsx"

    fa = ScheduleFA(
        ticker=TICKER,
        year=REPORTING_YEAR,
        broker=BROKER,
    )

    fa.set_data(
        owned=owned,
        sold_within_reporting_year=(sold_within if sold_within.exists() else None),
        sold_after_reporting_year=(sold_after if sold_after.exists() else None),
    )

    result = fa.generate()

    output = data_dir / "schedule_fa.csv"
    result.to_csv(output, index=False)

    print(f"Schedule FA written to: {output.resolve()}")


if __name__ == "__main__":
    main()
```

---

## How it works

```
Broker Statements
        │
        ▼
 Parse Holdings
        │
        ▼
 Parse Transactions
        │
        ▼
 Reconstruct Holdings
        │
        ▼
 Historical Stock Prices
        │
        ▼
 Historical Exchange Rates
        │
        ▼
 Schedule FA CSV
```

---

## Exchange rates

The library uses historical SBI TT Buy exchange rates through the `sbi-tt-rates` package.
Link: https://github.com/jdecodes/sbi-tt-rates

Historical SBI TT data is available from **2020 onwards**.

For acquisitions before 2020, the library automatically falls back to historical USD/INR exchange rates from Yahoo Finance and logs a warning.

Example:

```
WARNING: Falling back to Yahoo Finance for acquisition date 2019-08-19 (USD/INR=71.132) because SBI TT data is unavailable.
```

---

## Dividends

Dividend calculations are **not** included.

If you have received dividends, calculate and report them separately while filing your Income Tax Return.

---

## Validation

The library validates the input before generating Schedule FA.

Some examples include:

* unsupported broker
* unsupported ticker
* missing files
* empty holdings file
* missing required columns
* mismatched ticker between statements
* invalid input formats

Validation errors are reported with descriptive exceptions.

---

## Roadmap

Planned improvements include:

* additional US brokers
* dividend calculations
* automatic broker detection

---

## Companion projects

This project uses the following libraries:

- **sbi-tt-rates**  
  https://github.com/jdecodes/sbi-tt-rates

- **fa-inrdata-api**  
  https://github.com/jdecodes/fa-inrdata-api

- **fa-inrdata**  
  https://github.com/jdecodes/fa-inrdata
---

## Contributing

Bug reports, feature requests and pull requests are welcome.

If you'd like to add support for another US broker, feel free to open an issue before starting work so we can discuss the file formats and implementation.

---

## Disclaimer

This is an unofficial open source project.

* This project is **not affiliated with or endorsed by E*TRADE, Morgan Stanley, the State Bank of India (SBI), the Reserve Bank of India (RBI), the Income Tax Department of India, or any other financial institution or government authority.**
* Historical exchange rates are obtained through the **sbi-tt-rates** package. For dates prior to 2020, where SBI TT data is unavailable, the library automatically falls back to historical USD/INR exchange rates from Yahoo Finance.
* **Dividend calculations are not supported.** Any dividend income must be calculated and reported separately while filing your Income Tax Return.
* The library has **only been tested with E*TRADE statement formats**. Statements from other brokers are not currently supported.
* The library has **only been validated for FY 2025-26 (AY 2026-27)**. Future Income Tax portal formats, reporting requirements, or broker statement formats may require updates.
* The generated Schedule FA should always be reviewed before filing your Income Tax Return. Users are responsible for verifying the accuracy of the generated data before submission.

The authors and contributors are **not responsible for any incorrect tax filings, penalties, interest, or financial losses resulting from the use of this software.**

---

## License

MIT License. See the `LICENSE` file for details.
