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 — 短期（保有期間が1年以下）。Part II — 長期（保有期間が1年超）。

列：

• (a) 資産の説明（例：「2.5 SOL」）
• (b) 取得日（MM/DD/YYYY）
• (c) 売却日または処分日（MM/DD/YYYY）
• (d) 譲渡収入（米ドルでの売却価格）
• (e) 取得原価またはその他の基準額（米ドルでの購入価格＋手数料）
• (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 トークンやバーンされた LP トークンを追跡する場合があります。

ステーキング報酬

ステーキング報酬（SOL バリデーター報酬、リキッドステーキングの利回り）は、受け取った時点の公正市場価値で所得となります。取得原価は受領時の FMV と同額です。

エアドロップ

エアドロップは、受取人が支配権と管理権を得た時点の公正市場価値で所得となります。支配権が確立される時点の扱いは、管轄区域によって異なる場合があります。

トークンの移行

1:1 のトークン移行（例：プロトコルのアップグレード）は、一般に課税対象となる事象ではありません。新しいトークンは、古いトークンの取得原価と保有期間を引き継ぎます。

失敗したトランザクション

失敗した Solana トランザクション（ステータスが failed、または内部命令エラー）は、課税対象のイベントではありません。トランザクション手数料（SOL）は、地域によっては事業経費として控除できる場合があります。取引のエクスポートからは、必ず失敗した tx を除外してください。

取得原価の計算方法

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. 取引の欠落 — オンチェーンの tx が取引記録にない（手動入力の漏れ）
2. 架空の取引 — 対応するオンチェーンの tx がない取引記録
3. 金額の不一致 — 取引記録の金額がオンチェーンの金額と異なる
4. 重複記録 — 同じ tx が二重に記録されている

照合ワークフロー：

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 の取引を 1 つの Koinly または CoinTracker インポートファイルにまとめ、ポートフォリオ全体の税務報告を行います。

監査の準備

照合を使って、取引記録がオンチェーン履歴を漏れなく反映していることを確認します。裏付けとなるトランザクションハッシュを添えて、整理された Form 8949 を作成します。

ファイル

ファイル	説明
references/planned_features.md	エクスポート形式の仕様、Form 8949 へのマッピング、Solana tx の分類、照合方法
scripts/tax_exporter.py	デモスクリプト：取引を生成し、Koinly CSV と Form 8949 CSV にエクスポートして、形式の違いを表示します

関連スキル

• helius-api — 照合用に Solana のトランザクション履歴を取得・解析します
• birdeye-api / coingecko-api — 取得原価の確認に使う過去の価格データ
• solana-onchain — ウォレットのトランザクション分析と分類
• trade-journal — 社内の取引記録の管理