/cost-basis-engine

name: cost-basis-engine
description: Multi-method cost basis computation including specific identification, FIFO, LIFO, HIFO, and proportional average cost with partial sell handling
license: MIT
metadata:
  author: agipro
  version: "0.1.0"
  category: trading

Cost Basis Engine

Compute cost basis for crypto trades using multiple accounting methods and compare the resulting tax liability across methods. This skill handles the full complexity of on-chain activity: partial sells, token migrations, airdrops, staking rewards, LP entry/exit, and multi-hop swaps.

> **Disclaimer**: This skill provides computational tools for informational purposes only. It does not constitute tax, legal, or financial advice. Consult a qualified tax professional for your specific situation. Tax law varies by jurisdiction and changes frequently.

Prerequisites

• Python 3.10+
• No external dependencies required (standard library only)
• Trade history as a list of dicts or CSV with columns: `date`, `action`, `token`, `quantity`, `price_usd`, `fee_usd`

Methods Overview

| Method | Logic | Best For | |--------|-------|----------| | **FIFO** | First lots purchased are sold first | Simplicity, many jurisdictions' default | | **LIFO** | Last lots purchased are sold first | Deferring gains when prices rise over time | | **HIFO** | Highest-cost lots are sold first | Minimizing current tax liability | | **Specific ID** | Trader selects which lots to sell | Maximum control, requires record-keeping | | **Average Cost** | Weighted average of all held lots | Simplicity, required in some jurisdictions |

---

1. FIFO (First-In, First-Out)

Sell the oldest lots first. This is the default method in the US if no other method is elected.

def fifo_sell(lots: list[dict], sell_qty: float, sell_price: float) -> list[dict]:
    """Sell using FIFO. lots sorted oldest-first."""
    remaining = sell_qty
    realized = []
    while remaining > 0 and lots:
        lot = lots[0]
        used = min(lot["qty"], remaining)
        gain = (sell_price - lot["cost_per_unit"]) * used
        realized.append({"qty": used, "basis": lot["cost_per_unit"], "gain": gain})
        lot["qty"] -= used
        remaining -= used
        if lot["qty"] <= 0:
            lots.pop(0)
    return realized

Partial sell example

You hold three lots of TOKEN:

• Lot A: 100 units @ $1.00 (oldest)
• Lot B: 50 units @ $2.00
• Lot C: 75 units @ $1.50

You sell 120 units at $3.00:

• 100 from Lot A: gain = (3.00 - 1.00) * 100 = $200
• 20 from Lot B: gain = (3.00 - 2.00) * 20 = $20
• Total realized gain: **$220**
• Lot B remainder: 30 units @ $2.00

---

2. LIFO (Last-In, First-Out)

Sell the newest lots first. Reverses the order compared to FIFO.

def lifo_sell(lots: list[dict], sell_qty: float, sell_price: float) -> list[dict]:
    """Sell using LIFO. Pops from end (newest first)."""
    remaining = sell_qty
    realized = []
    while remaining > 0 and lots:
        lot = lots[-1]
        used = min(lot["qty"], remaining)
        gain = (sell_price - lot["cost_per_unit"]) * used
        realized.append({"qty": used, "basis": lot["cost_per_unit"], "gain": gain})
        lot["qty"] -= used
        remaining -= used
        if lot["qty"] <= 0:
            lots.pop()
    return realized

Using the same lots and selling 120 at $3.00 with LIFO:

• 75 from Lot C: gain = (3.00 - 1.50) * 75 = $112.50
• 45 from Lot B: gain = (3.00 - 2.00) * 45 = $45
• Total realized gain: **$157.50**

---

3. HIFO (Highest-In, First-Out)

Sell the highest-cost lots first to minimize realized gains.

def hifo_sell(lots: list[dict], sell_qty: float, sell_price: float) -> list[dict]:
    """Sell using HIFO. Sort by cost descending, consume highest first."""
    lots.sort(key=lambda x: x["cost_per_unit"], reverse=True)
    remaining = sell_qty
    realized = []
    for lot in lots:
        if remaining <= 0:
            break
        used = min(lot["qty"], remaining)
        gain = (sell_price - lot["cost_per_unit"]) * used
        realized.append({"qty": used, "basis": lot["cost_per_unit"], "gain": gain})
        lot["qty"] -= used
        remaining -= used
    lots[:] = [l for l in lots if l["qty"] > 0]
    return realized

Same lots, selling 120 at $3.00 with HIFO:

• 50 from Lot B ($2.00, highest): gain = (3.00 - 2.00) * 50 = $50
• 70 from Lot C ($1.50, next highest): gain = (3.00 - 1.50) * 70 = $105
• Total realized gain: **$155**
• Remaining: Lot A 100 @ $1.00, Lot C 5 @ $1.50

---

4. Specific Identification

The trader explicitly selects which lots to sell. Provides maximum control but requires meticulous record-keeping. Each lot must be uniquely identifiable (e.g., by purchase date and time, or a lot ID).

def specific_id_sell(lots: dict[str, dict], lot_ids: list[tuple[str, float]],
                     sell_price: float) -> list[dict]:
    """Sell specific lots by ID. lot_ids = [(lot_id, qty_to_sell), ...]"""
    realized = []
    for lot_id, sell_qty in lot_ids:
        lot = lots[lot_id]
        used = min(lot["qty"], sell_qty)
        gain = (sell_price - lot["cost_per_unit"]) * used
        realized.append({"lot_id": lot_id, "qty": used, "basis": lot["cost_per_unit"], "gain": gain})
        lot["qty"] -= used
        if lot["qty"] <= 0:
            del lots[lot_id]
    return realized

---

5. Proportional / Average Cost Method

Compute a single weighted-average cost per unit across all held lots. Every sell uses that average cost. The average updates after each buy.

def average_cost_basis(lots: list[dict]) -> float:
    """Compute weighted average cost per unit across all lots."""
    total_cost = sum(l["qty"] * l["cost_per_unit"] for l in lots)
    total_qty = sum(l["qty"] for l in lots)
    if total_qty == 0:
        return 0.0
    return total_cost / total_qty

def average_cost_sell(lots: list[dict], sell_qty: float, sell_price: float) -> dict:
    """Sell using average cost. Reduc