kalshi-csv 0.1.0__py3-none-any.whl

kalshi_csv/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "0.1.0"
+
+from .parser import KalshiCSV
+
+__all__ = ["KalshiCSV", "__version__"]

kalshi_csv/cli.py

@@ -0,0 +1,80 @@
+import argparse
+import sys
+
+from .parser import KalshiCSV
+from .formatter import (
+    color_white,
+    color_yellow,
+    color_cyan,
+    format_currency_color,
+)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Parse Kalshi transaction CSV and generate IRS tax summary."
+    )
+    parser.add_argument("csv_path", help="Path to Kalshi transactions CSV file")
+    parser.add_argument(
+        "--irs-file",
+        help="Write IRS Form 8949 summary to this file",
+    )
+    parser.add_argument(
+        "--no-color",
+        action="store_true",
+        help="Disable ANSI color output",
+    )
+
+    args = parser.parse_args()
+    no_color = args.no_color
+
+    kalshi = KalshiCSV(args.csv_path)
+    kalshi.parse()
+
+    print()
+    print(
+        f"{'Ticker':<32} | {'Side':<4} | {'Qty':<6} | {'Entry':<6} | {'Exit':<6} | {'P&L (No Fees)':<14}"
+    )
+    print("-" * 83)
+
+    for trade in kalshi.trades:
+        pnl_str = format_currency_color(trade["pnl_no_fees"], no_color)
+        print(
+            f"{trade['ticker']:<32} | {trade['side']:<4} | {trade['qty']:<6.2f} | "
+            f"${trade['entry']:<5.2f} | ${trade['exit']:<5.2f} | {pnl_str:<14}"
+        )
+
+    print("-" * 83)
+    print(f"Total Transactions Parsed: {kalshi.summary['trade_count']}")
+    print(f"Total Exchange Fees Paid:  ${kalshi.summary['total_fees']:.2f}")
+    print(
+        f"Internal Tracked Net P&L:  "
+        + format_currency_color(kalshi.summary["total_pnl_without_fees"], no_color)
+    )
+    print("-" * 83)
+
+    irs = kalshi.irs_summary()
+    print(color_yellow("=== IRS FORM 8949 / SCHEDULE D AGGREGATE SUMMARY ===", no_color))
+    print("Use these exact aggregates for a single-line summary entry:")
+    print(f"  * Box to Check:            {color_white('Box C', no_color)} (Short-term, not reported on Form 1099-B)")
+    print(f"  * (a) Description:         {irs['description']}")
+    print(f"  * (d) Gross Proceeds:      {format_currency_color(irs['gross_proceeds'], no_color)}")
+    print(f"  * (e) Cost or Other Basis: {color_cyan(f'${irs['cost_basis']:.2f}', no_color)}")
+    print(f"  * (h) Gain or (Loss):      {format_currency_color(irs['gain_or_loss'], no_color)}")
+    print(color_yellow("====================================================", no_color))
+    print()
+
+    if args.irs_file:
+        with open(args.irs_file, "w", encoding="utf-8") as f:
+            f.write("IRS FORM 8949 / SCHEDULE D AGGREGATE SUMMARY\n")
+            f.write("Use these exact aggregates for a single-line summary entry:\n")
+            f.write(f"  * Box to Check:            Box C (Short-term, not reported on Form 1099-B)\n")
+            f.write(f"  * (a) Description:         {irs['description']}\n")
+            f.write(f"  * (d) Gross Proceeds:      ${irs['gross_proceeds']:.2f}\n")
+            f.write(f"  * (e) Cost or Other Basis: ${irs['cost_basis']:.2f}\n")
+            f.write(f"  * (h) Gain or (Loss):      ${irs['gain_or_loss']:.2f}\n")
+        print(f"IRS summary written to: {args.irs_file}")
+
+
+if __name__ == "__main__":
+    main()

kalshi_csv/formatter.py

@@ -0,0 +1,39 @@
+def color_green(text, no_color=False):
+    """Wraps text in ANSI green."""
+    if no_color:
+        return text
+    return f"\033[1;32m{text}\033[0m"
+
+
+def color_red(text, no_color=False):
+    """Wraps text in ANSI red."""
+    if no_color:
+        return text
+    return f"\033[1;31m{text}\033[0m"
+
+
+def color_yellow(text, no_color=False):
+    """Wraps text in ANSI yellow."""
+    if no_color:
+        return text
+    return f"\033[1;33m{text}\033[0m"
+
+
+def color_cyan(text, no_color=False):
+    """Wraps text in ANSI cyan."""
+    if no_color:
+        return text
+    return f"\033[1;36m{text}\033[0m"
+
+
+def color_white(text, no_color=False):
+    """Wraps text in ANSI white."""
+    if no_color:
+        return text
+    return f"\033[1;37m{text}\033[0m"
+
+
+def format_currency_color(value, no_color=False):
+    """Returns a signed, colorized string based on profit or loss status."""
+    val_str = f"${value:+.2f}"
+    return color_green(val_str, no_color) if value >= 0 else color_red(val_str, no_color)

kalshi_csv/parser.py

@@ -0,0 +1,70 @@
+import csv
+import os
+
+
+class KalshiCSV:
+    """Parses Kalshi transaction CSV data and calculates tax-relevant aggregates."""
+
+    def __init__(self, file_path):
+        self.file_path = file_path
+        self.trades = []
+        self.summary = {
+            "trade_count": 0,
+            "total_fees": 0.0,
+            "total_pnl_without_fees": 0.0,
+            "total_pnl_with_fees": 0.0,
+            "total_tax_basis": 0.0,
+            "total_tax_proceeds": 0.0,
+        }
+
+    def parse(self):
+        """Processes the CSV file row-by-row and populates trades and summary."""
+        if not os.path.exists(self.file_path):
+            raise FileNotFoundError(f"File '{self.file_path}' not found.")
+
+        with open(self.file_path, mode="r", newline="", encoding="utf-8") as f:
+            reader = csv.DictReader(f)
+
+            for row in reader:
+                if not row.get("realized_pnl_without_fees_dollars"):
+                    continue
+
+                qty = float(row["quantity_fp"])
+                entry = float(row["entry_price_dollars"])
+                exit_val = float(row["exit_price_dollars"])
+                pnl_no_fees = float(row["realized_pnl_without_fees_dollars"])
+                pnl_with_fees = float(row["realized_pnl_with_fees_dollars"])
+                open_fees = float(row["open_fees_dollars"])
+                close_fees = float(row["close_fees_dollars"])
+
+                trade = {
+                    "ticker": row["market_ticker"],
+                    "side": row["side"].upper(),
+                    "qty": qty,
+                    "entry": entry,
+                    "exit": exit_val,
+                    "pnl_no_fees": pnl_no_fees,
+                    "pnl_with_fees": pnl_with_fees,
+                    "open_fees": open_fees,
+                    "close_fees": close_fees,
+                }
+                self.trades.append(trade)
+
+                self.summary["trade_count"] += 1
+                self.summary["total_tax_basis"] += (qty * entry) + open_fees
+                self.summary["total_tax_proceeds"] += (qty * exit_val) - close_fees
+                self.summary["total_pnl_without_fees"] += pnl_no_fees
+                self.summary["total_pnl_with_fees"] += pnl_with_fees
+                self.summary["total_fees"] += open_fees + close_fees
+
+        return self
+
+    def irs_summary(self):
+        """Returns a dict with IRS Form 8949 aggregate fields."""
+        return {
+            "box": "C",
+            "description": "Kalshi Event Contracts (Aggregate Summary)",
+            "gross_proceeds": self.summary["total_tax_proceeds"],
+            "cost_basis": self.summary["total_tax_basis"],
+            "gain_or_loss": self.summary["total_pnl_with_fees"],
+        }

kalshi_csv-0.1.0.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: kalshi-csv
+Version: 0.1.0
+Summary: Parse Kalshi transaction CSV files and generate IRS Form 8949 tax summaries
+Project-URL: Homepage, https://github.com/MARKMENTAL/kalshi-csv
+Project-URL: Source, https://codeberg.org/markmental/kalshi-csv
+Project-URL: Issues, https://github.com/MARKMENTAL/kalshi-csv/issues
+Author-email: markmental <marky611@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: csv,form-8949,irs,kalshi,tax
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# kalshi-csv
+
+Parse Kalshi transaction CSV files and generate IRS Form 8949 tax summaries for event contract trading.
+
+## Installation
+
+```bash
+pip install kalshi-csv
+```
+
+## Getting Your Transactions CSV
+
+Download your transaction history from Kalshi:
+
+1. Go to [https://kalshi.com/account/taxes](https://kalshi.com/account/taxes)
+2. Download the transaction CSV for the tax year you want to analyze
+3. Pass it to `kalshi-csv` as shown below
+
+Each tax year produces a separate CSV file.
+
+## CSV Format
+
+The tool expects the standard Kalshi transaction export with these columns:
+
+```
+type, quantity_fp, market_ticker, side, entry_price_dollars, exit_price_dollars,
+open_fees_dollars, close_fees_dollars, realized_pnl_without_fees_dollars,
+realized_pnl_with_fees_dollars, close_timestamp, open_timestamp
+```
+
+Rows without `realized_pnl_without_fees_dollars` are automatically skipped.
+
+## CLI Usage
+
+Parse a Kalshi transactions CSV and display the trade matrix with IRS summary:
+
+```bash
+kalshi-csv Kalshi-Transactions-2026.csv
+```
+
+Export the IRS summary to a file:
+
+```bash
+kalshi-csv Kalshi-Transactions-2026.csv --irs-file irs-summary.txt
+```
+
+Disable colored output (useful for piping or redirecting):
+
+```bash
+kalshi-csv Kalshi-Transactions-2026.csv --no-color
+```
+
+### Sample Output
+
+```
+Ticker                             | Side | Qty    | Entry  | Exit   | P&L (No Fees)
+-------------------------------------------------------------------------------
+KXWCADVANCE-26JUL07ARGEGY-ARG      | YES  | 0.17   | $0.86  | $0.69  | -$0.03
+KXWC1H-26JUL07ARGEGY-TIE           | YES  | 0.34   | $0.28  | $0.00  | -$0.10
+KXMLBGAME-26JUL081940BOSCWS-BOS    | YES  | 0.96   | $0.50  | $0.91  | $0.39
+-------------------------------------------------------------------------------
+Total Transactions Parsed: 3
+Total Exchange Fees Paid:  $0.05
+Internal Tracked Net P&L:  $0.26
+-------------------------------------------------------------------------------
+=== IRS FORM 8949 / SCHEDULE D AGGREGATE SUMMARY ===
+Use these exact aggregates for a single-line summary entry:
+  * Box to Check:            Box C (Short-term, not reported on Form 1099-B)
+  * (a) Description:         Kalshi Event Contracts (Aggregate Summary)
+  * (d) Gross Proceeds:      $2.50
+  * (e) Cost or Other Basis: $2.24
+  * (h) Gain or (Loss):      $0.26
+====================================================
+```
+
+## Library API
+
+Use `kalshi-csv` as a Python library in your own scripts:
+
+```python
+from kalshi_csv import KalshiCSV
+
+kalshi = KalshiCSV("Kalshi-Transactions-2026.csv")
+kalshi.parse()
+
+# Access individual trades
+for trade in kalshi.trades:
+    print(f"{trade['ticker']}: {trade['side']} {trade['qty']} @ ${trade['entry']}")
+    print(f"  P&L: ${trade['pnl_with_fees']:.2f}")
+
+# Access aggregate summary
+print(f"Total trades: {kalshi.summary['trade_count']}")
+print(f"Total fees: ${kalshi.summary['total_fees']:.2f}")
+print(f"Total P&L: ${kalshi.summary['total_pnl_with_fees']:.2f}")
+
+# Get IRS Form 8949 data
+irs = kalshi.irs_summary()
+print(f"Gross Proceeds: ${irs['gross_proceeds']:.2f}")
+print(f"Cost Basis: ${irs['cost_basis']:.2f}")
+print(f"Gain/Loss: ${irs['gain_or_loss']:.2f}")
+```
+
+### Data Structures
+
+**Trade dict** (`kalshi.trades`):
+- `ticker`: Market ticker symbol
+- `side`: "YES" or "NO"
+- `qty`: Quantity of contracts
+- `entry`: Entry price in dollars
+- `exit`: Exit price in dollars
+- `pnl_no_fees`: P&L without fees
+- `pnl_with_fees`: P&L including fees
+- `open_fees`: Opening fees
+- `close_fees`: Closing fees
+
+**Summary dict** (`kalshi.summary`):
+- `trade_count`: Number of trades parsed
+- `total_fees`: Sum of all fees
+- `total_pnl_without_fees`: Total P&L excluding fees
+- `total_pnl_with_fees`: Total P&L including fees
+- `total_tax_basis`: Total cost basis for IRS reporting
+- `total_tax_proceeds`: Total proceeds for IRS reporting
+
+**IRS summary dict** (`kalshi.irs_summary()`):
+- `box`: "C" (for Form 8949 Box C)
+- `description`: "Kalshi Event Contracts (Aggregate Summary)"
+- `gross_proceeds`: Total proceeds
+- `cost_basis`: Total cost basis
+- `gain_or_loss`: Net gain or loss
+
+## IRS Form 8949
+
+Kalshi event contracts are typically reported on **IRS Form 8949, Box C** (short-term transactions not reported on Form 1099-B). The tool calculates:
+
+- **Gross Proceeds**: Total exit value minus close fees
+- **Cost Basis**: Total entry value plus open fees
+- **Gain/Loss**: Realized P&L including all fees
+
+Use the aggregate summary for a single-line entry on Form 8949, or export to a file for your records.
+
+**Disclaimer**: This tool provides calculations based on Kalshi transaction data. Consult a tax professional for specific tax advice.
+
+## Source Code
+
+This project is hosted in two locations:
+- **GitHub**: [https://github.com/MARKMENTAL/kalshi-csv](https://github.com/MARKMENTAL/kalshi-csv)
+- **Codeberg**: [https://codeberg.org/markmental/kalshi-csv](https://codeberg.org/markmental/kalshi-csv)
+
+## License
+
+[MIT](LICENSE)
+

kalshi_csv-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+kalshi_csv/__init__.py,sha256=mVbe7Qp6xTHY0CGboo6nES502Eg4UCY8VsCHXjrzYHw,93
+kalshi_csv/cli.py,sha256=2jylGN1sf9HJaDzKbO8hHf90JdFZtFQMzYF8oWuPbGI,3052
+kalshi_csv/formatter.py,sha256=jwTM16KI4fhta_N9m0_MiFDolRKTRtqkIRuiTqaqPZg,1004
+kalshi_csv/parser.py,sha256=1_eYP_-X550LBKZqhoVoxGnirYhAzHPgZ5FbcgEupWU,2727
+kalshi_csv-0.1.0.dist-info/METADATA,sha256=VJo_t3sAByxyHhmkVc1ZJjM_Wfh1qOkpEBceJpYIZwQ,5960
+kalshi_csv-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+kalshi_csv-0.1.0.dist-info/entry_points.txt,sha256=kHcNVSzHK4sDfBdT3Xs8LnLnmILUzaS9PbYwnnLUgRY,51
+kalshi_csv-0.1.0.dist-info/licenses/LICENSE,sha256=6AEFZwA_fl6iJnJ1CC36ZjuYbfDGFKdV3gDhnpOBM0w,1074
+kalshi_csv-0.1.0.dist-info/RECORD,,

kalshi_csv-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

kalshi_csv-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+kalshi-csv = kalshi_csv.cli:main

kalshi_csv-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Robillard Jr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.