crypto-tax-export

加密货币税务导出

为税务软件和 IRS 申报导出交易历史和税务计算结果。支持 Solana 特有的交易类型（Jupiter 兑换、LP 操作、质押奖励、空投），并生成兼容 Koinly、CoinTracker、CoinLedger、TokenTax、TurboTax/TaxAct 和 IRS Form 8949 的 CSV 文件。

**免责声明：**此技能仅提供数据格式化和计算工具，不构成税务建议。如需了解如何申报加密货币交易，请咨询合格的税务专业人士。各司法管辖区的税法各不相同，且经常变化。

前提条件

• Python 3.10+
• 交易历史数据（来自内部交易日志、链上历史记录或交易所导出数据）
• 如需链上对账：Solana RPC 或 Helius API 访问权限（参见 helius-api 技能）
• 如需计算成本基础：历史价格数据（参见 birdeye-api 或 coingecko-api 技能）

功能

功能	描述
多格式 CSV 导出	Koinly、CoinTracker、CoinLedger、TokenTax、TurboTax、TaxAct
生成 IRS Form 8949	Part I（短期）和 Part II（长期），涵盖 a 至 h 列
Solana 交易分类	Jupiter 兑换、多跳路由、LP 存入/提取、质押、空投
成本基础计算方法	FIFO、LIFO、HIFO、特定识别法
对账	将链上历史记录与内部交易日志进行匹配
失败交易处理	识别并排除失败的交易（不构成应税事件）

支持的导出格式

Koinly CSV

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

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

标签：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

类型：Trade、Income、Gift Received、Mining、Staking Reward、Airdrop。

TokenTax CSV

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

类型：Trade、Income、Staking、Airdrop、Spending。

TurboTax / TaxAct CSV

两者都接受简化的 Form 8949 格式：

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

IRS Form 8949

Part I — 短期（持有一年或更短）。Part II — 长期（持有超过一年）。

列：

• (a) 财产描述（例如，“2.5 SOL”）
• (b) 获得日期（MM/DD/YYYY）
• (c) 出售或处置日期（MM/DD/YYYY）
• (d) 收益（以 USD 计的销售价格）
• (e) 成本或其他基础（以 USD 计的购买价格 + 费用）
• (f) 代码（如有，按照 IRS 说明填写）
• (g) 调整金额
• (h) 收益或损失（d 减 e，再按 g 调整）

勾选框：如果成本基础已向 IRS 报告，勾选 (A)；如果未报告，勾选 (B)；如果未收到 Form 1099-B，勾选 (C)。

Solana 交易分类

Jupiter 兑换（单跳）

直接进行代币间兑换。将发送的代币归类为处置，将收到的代币归类为获得。兑换的双方都属于应税事件。

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 兑换（多跳）

通过中间代币进行路由兑换（例如，SOL -> USDC -> BONK）。出于税务目的，仅涉及初始发送和最终接收。中间跳转不属于单独的应税事件。

LP 存入/提取

• 存入：将代币发送到 LP，通常视为按公允市场价值处置。
• 提取：从 LP 收到代币，视为按公允市场价值获得。
• 收到/销毁的 LP 代币可用于持续追踪成本基础。

质押奖励

质押奖励（SOL 验证者奖励、流动性质押收益）在收到时按公允市场价值作为收入处理。成本基础等于收到时的公允市场价值。

空投

当接收者取得支配权和控制权时，空投按公允市场价值作为收入处理。部分司法管辖区对何时取得支配权有不同规定。

代币迁移

1:1 代币迁移（例如，协议升级）通常不构成应税事件。新代币继承旧代币的成本基础和持有期限。

失败的交易

失败的 Solana 交易（状态为 failed，或出现内部指令错误）不是应税事件。在某些司法辖区，交易手续费（SOL）仍可作为营业成本抵扣。导出交易时，务必排除失败的交易。

成本基础计算方法

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

对账

将链上历史记录与内部交易日志对账，可以发现：

1. 缺失的交易 — 链上交易不在日志中（漏记手动录入）
2. 虚构的交易 — 日志中有记录，但没有匹配的链上交易
3. 金额不匹配 — 日志中的金额与链上金额不同
4. 重复记录 — 同一笔交易被记录了两次

对账工作流：

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),
        },
    }

快速入门

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

# Generate sample trades
trades = generate_demo_trades()

# Export to Koinly format
export_koinly_csv(trades, "koinly_import.csv")

# Export to Form 8949 format
export_form_8949_csv(trades, "form_8949.csv")

直接运行演示：

python scripts/tax_exporter.py --demo

用例

年终报税

导出日志中的所有交易，与链上历史记录对账，生成 Form 8949 条目，然后导入 TurboTax 或交给你的 CPA。

税损收割审查

使用 HIFO 成本基础计算方法导出，以找出存在未实现亏损、可在年底前抵消收益的持仓。

多平台整合

将多个钱包和 DEX 的交易合并到一个 Koinly 或 CoinTracker 导入文件中，以统一进行投资组合税务申报。

审计准备

使用对账功能，根据链上历史记录核实交易记录是否完整。生成整洁的 Form 8949，并附上交易哈希作为支持材料。

文件

文件	说明
references/planned_features.md	导出格式规范、Form 8949 映射、Solana 交易分类、对账方法
scripts/tax_exporter.py	演示脚本：生成交易、导出为 Koinly CSV 和 Form 8949 CSV，并展示格式差异

相关技能

• helius-api — 获取并解析 Solana 交易历史记录以进行对账
• birdeye-api / coingecko-api — 用于查询成本基础的历史价格数据
• solana-onchain — 钱包交易分析与分类
• trade-journal — 内部交易记录管理