crypto-tax-export

Files (6)

• SKILL.md
• demo_cointracker_export.csv
• demo_form_8949.csv
• demo_koinly_export.csv
• planned_features.md · references/
• tax_exporter.py · scripts/

SKILL.md (first lines)

# Crypto Tax Export

Export trade history and tax calculations for tax software and IRS filing. Handles Solana-specific transaction types (Jupiter swaps, LP operations, staking rewards, airdrops) and generates CSVs compatible with Koinly, CoinTracker, CoinLedger, TokenTax, TurboTax/TaxAct, and IRS Form 8949.

> **Disclaimer:** This skill provides data formatting and calculation tools only. It does not constitute tax advice. Consult a qualified tax professional for guidance on reporting cryptocurrency transactions. Tax laws vary by jurisdiction and change frequently.

## Prerequisites

- Python 3.10+
- Trade history data (from internal trade journal, on-chain history, or exchange exports)
- For on-chain reconciliation: Solana RPC or Helius API access (see `helius-api` skill)
- For cost basis: historical price data (see `birdeye-api` or `coingecko-api` skills)

## Capabilities

| Capability | Description |
|---|---|
| Multi-format CSV export | Koinly, CoinTracker, CoinLedger, TokenTax, TurboTax, TaxAct |
| IRS Form 8949 generation | Part I (short-term) and Part II (long-term), columns a through h |
| Solana tx classification | Jupiter swaps, multi-hop routes, LP deposits/withdrawals, staking, airdrops |
| Cost basis methods | FIFO, LIFO, HIFO, Specific Identification |
| Reconciliation | Match on-chain history against internal trade journal |
| Failed tx handling | Identify and exclude failed transactions (no taxable event) |

## Supported Export Formats

### Koinly CSV

Koinly expects a universal import format with these columns:

```
Date,Sent Amount,Sent Currency,Received Amount,Received Currency,Fee Amount,Fee Currency,Net Worth Amount,Net Worth Currency,Label,Description,TxHash
```

Labels: `swap`, `staking`, `airdrop`, `liquidity_in`, `liquidity_out`, `cost`, `gift`, `lost`.

### CoinTracker CSV

```
Date,Received Quantity,Received Currency,Sent Quantity,Sent Currency,Fee Amount,Fee Currency,Tag
```

Tags: `trade`, `staking_reward`, `airdrop`, `lp_deposit`, `lp_withdrawal`.

### CoinLedger CSV

```
Date (UTC),Type,Received Currency,Received Amount,Sent Currency,Sent Amount,Fee Currency,Fee Amount,Exchange/Wallet
```

Types: `Trade`, `Income`, `Gift Received`, `Mining`, `Staking Reward`, `Airdrop`.

### TokenTax CSV

```
Type,BuyAmount,BuyCurrency,SellAmount,SellCurrency,FeeAmount,FeeCurrency,Exchange,Group,Comment,Date
```

Types: `Trade`, `Income`, `Staking`, `Airdrop`, `Spending`.

### TurboTax / TaxAct CSV

Both accept a simplified Form 8949 format:

```
Description of Property,Date Acquired,Date Sold,Proceeds,Cost Basis,Gain or Loss
```

### IRS Form 8949

Part I — Short-term (held one year or less). Part II — Long-term (held more than one year).

Columns:
- **(a)** Description of property (e.g., "2.5 SOL")
- **(b)** Date acquired (MM/DD/YYYY)
- **(c)** Date sold or disposed of (MM/DD/YYYY)
- **(d)** Proceeds (sale price in USD)
- **(e)** Cost or other basis (purchase price in USD + fees)
- **(f)** Code, if any (per IRS instructions)
- **(g)** Adjustment amount
- **(h)** Gain or loss (d minus e, adjusted by g)

Check box: **(A)** if basis reported to IRS, **(B)** if not, **(C)** if Form 1099-B not received.

## Solana Transaction Classification

### Jupiter Swaps (Single-Hop)

A direct token-to-token swap. Classified as a **disposal** of the sent token and **acquisition** of the received token. Each side is a taxable event.

```python
tx = {
    "type": "swap",
    "sent": {"amount": 1.5, "currency": "SOL", "usd_value": 225.00},
    "received": {"amount": 50000, "currency": "BONK", "usd_value": 224.50},
    "fee": {"amount": 0.000005, "currency": "SOL", "usd_value": 0.00075},
    "timestamp": "2025-03-15T14:30:00Z",
    "tx_hash": "5abc...def",
}
```

### Jupiter Swaps (Multi-Hop)

A routed swap through intermediate tokens (e.g., SOL -> USDC -> BONK). Only the **initial send** and **final receive** matter for tax purposes. Intermediate hops are not separate taxable events.

### LP Deposits / Withdrawals

- **Deposit**: Sending tokens to an LP is generally treated as a disposal at fair market value.
- **Withdrawal**: Receiving tokens from an LP is an acquisition at fair market value.
- LP tokens received/burned may be tracked for cost basis continuity.

### Staking Rewards

Staking rewards (SOL validator rewards, liquid staking yield) are **income** at fair market value when received. Cost basis equals the FMV at receipt.

### Airdrops

Airdrops are **income** at fair market value when the recipient gains dominion and control. Some jurisdictions differ on when dominion is established.

From Serennity007/awesome-stock-quant-skills, MIT.

More from Serennity007/awesome-stock-quant-skills