Back to Details

crypto-tax-export

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
导出适用于税务软件和IRS申报的交易历史与税务计算数据。支持Solana特定交易类型（Jupiter兑换、流动性池操作、质押奖励、空投），并生成与Koinly、CoinTracker、CoinLedger、TokenTax、TurboTax/TaxAct以及IRS Form 8949兼容的CSV文件。
免责声明：本工具仅提供数据格式化与计算功能，不构成税务建议。请咨询合格税务专业人士以获取加密货币交易申报指导。税务法规因司法管辖区而异，且会频繁变更。

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)
  • Python 3.10及以上版本
  • 交易历史数据（来自内部交易日志、链上历史记录或交易所导出文件）
  • 链上对账：Solana RPC或Helius API访问权限（详见
    helius-api
    工具）
  • 成本核算：历史价格数据（详见
    birdeye-api
    或
    coingecko-api
    工具）

Capabilities

功能特性

CapabilityDescription
Multi-format CSV exportKoinly, CoinTracker, CoinLedger, TokenTax, TurboTax, TaxAct
IRS Form 8949 generationPart I (short-term) and Part II (long-term), columns a through h
Solana tx classificationJupiter swaps, multi-hop routes, LP deposits/withdrawals, staking, airdrops
Cost basis methodsFIFO, LIFO, HIFO, Specific Identification
ReconciliationMatch on-chain history against internal trade journal
Failed tx handlingIdentify and exclude failed transactions (no taxable event)
功能描述
多格式CSV导出支持Koinly、CoinTracker、CoinLedger、TokenTax、TurboTax、TaxAct
IRS Form 8949生成包含第一部分（短期持有）和第二部分（长期持有），覆盖a至h列
Solana交易分类Jupiter兑换、多路径路由、流动性池存入/取出、质押、空投
成本核算方法FIFO、LIFO、HIFO、特定识别法
对账功能匹配链上历史记录与内部交易日志
失败交易处理识别并排除失败交易（无应税事件）

Supported Export Formats

支持的导出格式

Koinly CSV

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
.
Koinly要求通用导入格式，包含以下列：
Date,Sent Amount,Sent Currency,Received Amount,Received Currency,Fee Amount,Fee Currency,Net Worth Amount,Net Worth Currency,Label,Description,TxHash
标签：
swap
, 
staking
, 
airdrop
, 
liquidity_in
, 
liquidity_out
, 
cost
, 
gift
, 
lost
。

CoinTracker CSV

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
.
Date,Received Quantity,Received Currency,Sent Quantity,Sent Currency,Fee Amount,Fee Currency,Tag
标签：
trade
, 
staking_reward
, 
airdrop
, 
lp_deposit
, 
lp_withdrawal
。

CoinLedger CSV

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
.
Date (UTC),Type,Received Currency,Received Amount,Sent Currency,Sent Amount,Fee Currency,Fee Amount,Exchange/Wallet
类型：
Trade
, 
Income
, 
Gift Received
, 
Mining
, 
Staking Reward
, 
Airdrop
。

TokenTax CSV

TokenTax CSV

Type,BuyAmount,BuyCurrency,SellAmount,SellCurrency,FeeAmount,FeeCurrency,Exchange,Group,Comment,Date
Types: 
Trade
, 
Income
, 
Staking
, 
Airdrop
, 
Spending
.
Type,BuyAmount,BuyCurrency,SellAmount,SellCurrency,FeeAmount,FeeCurrency,Exchange,Group,Comment,Date
类型：
Trade
, 
Income
, 
Staking
, 
Airdrop
, 
Spending
。

TurboTax / TaxAct CSV

TurboTax / TaxAct CSV

Both accept a simplified Form 8949 format:
Description of Property,Date Acquired,Date Sold,Proceeds,Cost Basis,Gain or Loss
两者均接受简化版Form 8949格式：
Description of Property,Date Acquired,Date Sold,Proceeds,Cost Basis,Gain or Loss

IRS Form 8949

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.
第一部分——短期持有（持有一年或更短）。第二部分——长期持有（持有超过一年）。
列：
  • (a) 资产描述（例如："2.5 SOL"）
  • (b) 购入日期（MM/DD/YYYY）
  • (c) 出售或处置日期（MM/DD/YYYY）
  • (d) 收益（美元计价的售价）
  • (e) 成本或其他基准（美元计价的买入价+手续费）
  • (f) 代码（如适用，遵循IRS说明）
  • (g) 调整金额
  • (h) 收益或损失（(d)减(e)，加上(g)的调整值）
勾选框：(A) 基准已上报至IRS，(B) 基准未上报至IRS，(C) 未收到Form 1099-B。

Solana Transaction Classification

Solana交易分类

Jupiter Swaps (Single-Hop)

Jupiter兑换（单路径）

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",
}
直接的代币间兑换。分类为发送代币的处置和接收代币的获取。双方均为应税事件。
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)

Jupiter兑换（多路径）

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.
通过中间代币的路由兑换（例如：SOL -> USDC -> BONK）。税务计算中仅需考虑初始发送和最终接收的代币。中间兑换步骤不属于独立应税事件。

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.
质押奖励（SOL验证节点奖励、流动性质押收益）在收到时按公允价值计为收入。成本基准等于收到时的公允价值。

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.
1:1的代币迁移（例如：协议升级）通常不构成应税事件。新代币继承旧代币的成本基准和持有期限。

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.
失败的Solana交易（状态：失败，或内部指令错误）不构成应税事件。交易手续费（SOL）在部分司法管辖区可作为经营成本扣除。导出交易时需始终排除失败交易。

Cost Basis Methods

成本核算方法

python
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
python
from enum import Enum

class CostBasisMethod(Enum):
    FIFO = "fifo"      # 先进先出（IRS默认方法）
    LIFO = "lifo"      # 后进先出
    HIFO = "hifo"      # 高进先出（最小化收益）
    SPEC_ID = "spec_id" # 特定识别法（需要批次跟踪）

def compute_gain(
    proceeds: float,
    cost_basis: float,
    adjustments: float = 0.0,
) -> float:
    """计算Form 8949第(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. Phantom trades — journal entry with no matching on-chain tx
  3. Amount mismatches — journal amount differs from on-chain amount
  4. Duplicate entries — same tx recorded twice
Reconciliation workflow:
python
def reconcile(
    journal_trades: list[dict],
    onchain_txs: list[dict],
    tolerance: float = 0.001,
) -> dict:
    """Match journal entries to on-chain transactions.

    Args:
        journal_trades: Internal trade records with tx_hash field.
        onchain_txs: Parsed on-chain transactions.
        tolerance: Relative tolerance for amount matching.

    Returns:
        Dict with matched, missing_onchain, missing_journal,
        mismatched lists.
    """
    onchain_by_hash = {tx["tx_hash"]: tx for tx in onchain_txs}
    matched, missing_onchain, missing_journal, mismatched = [], [], [], []

    for trade in journal_trades:
        tx = onchain_by_hash.pop(trade.get("tx_hash", ""), None)
        if tx is None:
            missing_onchain.append(trade)
        elif abs(trade["amount"] - tx["amount"]) / max(tx["amount"], 1e-9) > tolerance:
            mismatched.append({"journal": trade, "onchain": tx})
        else:
            matched.append({"journal": trade, "onchain": tx})

    missing_journal = list(onchain_by_hash.values())

    return {
        "matched": matched,
        "missing_onchain": missing_onchain,
        "missing_journal": missing_journal,
        "mismatched": mismatched,
        "summary": {
            "total_journal": len(journal_trades),
            "total_onchain": len(onchain_txs),
            "matched": len(matched),
            "missing_onchain": len(missing_onchain),
            "missing_journal": len(missing_journal),
            "mismatched": len(mismatched),
        },
    }
将链上历史记录与内部交易日志对账可发现：
  1. 缺失交易——链上交易未记录在日志中（手动输入遗漏）
  2. 虚假交易——日志中有记录但无对应链上交易
  3. 金额不匹配——日志金额与链上金额不符
  4. 重复记录——同一交易被记录两次
对账流程：
python
def reconcile(
    journal_trades: list[dict],
    onchain_txs: list[dict],
    tolerance: float = 0.001,
) -> dict:
    """匹配日志记录与链上交易。

    参数:
        journal_trades: 包含tx_hash字段的内部交易记录。
        onchain_txs: 解析后的链上交易。
        tolerance: 金额匹配的相对容差。

    返回:
        包含匹配项、链上缺失项、日志缺失项、不匹配项的字典。
    """
    onchain_by_hash = {tx["tx_hash"]: tx for tx in onchain_txs}
    matched, missing_onchain, missing_journal, mismatched = [], [], [], []

    for trade in journal_trades:
        tx = onchain_by_hash.pop(trade.get("tx_hash", ""), None)
        if tx is None:
            missing_onchain.append(trade)
        elif abs(trade["amount"] - tx["amount"]) / max(tx["amount"], 1e-9) > tolerance:
            mismatched.append({"journal": trade, "onchain": tx})
        else:
            matched.append({"journal": trade, "onchain": tx})

    missing_journal = list(onchain_by_hash.values())

    return {
        "matched": matched,
        "missing_onchain": missing_onchain,
        "missing_journal": missing_journal,
        "mismatched": mismatched,
        "summary": {
            "total_journal": len(journal_trades),
            "total_onchain": len(onchain_txs),
            "matched": len(matched),
            "missing_onchain": len(missing_onchain),
            "missing_journal": len(missing_journal),
            "mismatched": len(mismatched),
        },
    }

Quick Start

快速开始

python
from scripts.tax_exporter import (
    generate_demo_trades,
    export_koinly_csv,
    export_form_8949_csv,
)
python
from scripts.tax_exporter import (
    generate_demo_trades,
    export_koinly_csv,
    export_form_8949_csv,
)

Generate sample trades

生成示例交易数据

trades = generate_demo_trades()
trades = generate_demo_trades()

Export to Koinly format

导出为Koinly格式

export_koinly_csv(trades, "koinly_import.csv")
export_koinly_csv(trades, "koinly_import.csv")

Export to Form 8949 format

导出为Form 8949格式

export_form_8949_csv(trades, "form_8949.csv")

Run the demo directly:

```bash
python scripts/tax_exporter.py --demo
export_form_8949_csv(trades, "form_8949.csv")

直接运行演示脚本：

```bash
python scripts/tax_exporter.py --demo

Use Cases

使用场景

End-of-Year Tax Filing

年末税务申报

Export all trades from your journal, reconcile with on-chain history, generate Form 8949 line items, and import into TurboTax or hand to your CPA.
导出日志中所有交易，与链上历史记录对账，生成Form 8949条目，导入TurboTax或提供给注册会计师。

Tax-Loss Harvesting Review

税损收割审查

Export with HIFO cost basis method to identify positions with unrealized losses that could offset gains before year-end.
使用HIFO成本核算方法导出数据，识别年末前可用于抵消收益的未实现亏损头寸。

Multi-Platform Consolidation

多平台整合

Combine trades from multiple wallets and DEXs into a single Koinly or CoinTracker import file for unified portfolio tax reporting.
将多个钱包和去中心化交易所的交易合并为单个Koinly或CoinTracker导入文件，实现统一投资组合税务报告。

Audit Preparation

审计准备

Use reconciliation to verify completeness of your trade records against on-chain history. Produce a clean Form 8949 with supporting transaction hashes.
通过对账功能验证交易记录与链上历史记录的完整性。生成带有交易哈希支持文件的清晰Form 8949。

Files

文件说明

FileDescription
references/planned_features.md
Export format specs, Form 8949 mapping, Solana tx classification, reconciliation methodology
scripts/tax_exporter.py
Demo script: generate trades, export to Koinly CSV and Form 8949 CSV, show format differences
文件描述
references/planned_features.md
导出格式规范、Form 8949映射、Solana交易分类、对账方法
scripts/tax_exporter.py
演示脚本：生成交易数据、导出为Koinly CSV和Form 8949 CSV、展示格式差异

Related Skills

相关工具

  • helius-api
    — Fetch and parse Solana transaction history for reconciliation
  • birdeye-api
    / 
    coingecko-api
    — Historical price data for cost basis lookups
  • solana-onchain
    — Wallet transaction analysis and classification
  • trade-journal
    — Internal trade record keeping
  • helius-api
    — 获取并解析Solana交易历史用于对账
  • birdeye-api
    / 
    coingecko-api
    — 用于成本核算的历史价格数据查询
  • solana-onchain
    — 钱包交易分析与分类
  • trade-journal
    — 内部交易记录管理