/crypto-tax-export

name: crypto-tax-export
description: Export trade history and tax calculations in formats compatible with Koinly, CoinTracker, CoinLedger, TokenTax, and IRS Form 8949
license: MIT
metadata:
  author: agipro
  version: "0.1.0"
  category: trading

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.

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.

Token Migrations

A 1:1 token migration (e.g., protocol upgrade) is generally **not** a taxable event. The new token inherits the cost basis and holding period of the old token.

Failed Transactions

Failed Solana transactions (status: failed, or inner instruction errors) are **not** taxable events. The transaction fee (SOL) may still be deductible as a cost of doing business in some jurisdictions. Always exclude failed txs from trade export.

Cost Basis Methods

from enum import Enum

class CostBasisMethod(Enum):
    FIFO = "fifo"      # First In, First Out (IRS default)
    LIFO = "lifo"      # Last In, First Out
    HIFO = "hifo"      # Highest In, First Out (minimizes gains)
    SPEC_ID = "spec_id" # Specific Identification (requires lot tracking)

def compute_gain(
    proceeds: float,
    cost_basis: float,
    adjustments: float = 0.0,
) -> float:
    """Compute gain or loss for Form 8949 column (h)."""
    return proceeds - cost_basis + adjustments

Reconciliation

Reconciling on-chain history with an internal trade journal catches:

1. **Missing trades** — on-chain tx not in journal (manual entry missed) 2. **Pha