Back to Details

tax-liability-tracking

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Tax Liability Tracking

税务负债追踪

Real-time tax liability analysis purpose-built for active Solana traders. Track proportional cost basis across partial sells, classify realized vs unrealized gains, project quarterly tax obligations, and surface tax-aware signals that feed back into trading decisions.
专为活跃Solana交易者打造的实时税务负债分析工具。追踪部分卖出时的比例成本基准，区分已实现与未实现收益，预测季度税务义务，并提供可反馈至交易决策的税务感知信号。

Why This Matters

为何这很重要

Active crypto traders generate hundreds of taxable events per year. Without real-time tracking:
  • You do not know your actual after-tax P&L until year-end
  • Partial sells (the "house money" play) create cost basis confusion
  • Short-term vs long-term classification shifts your effective tax rate by 15-20%
  • Tax-loss harvesting windows close without you noticing
  • Quarterly estimated payments become guesswork
This skill keeps a running tax ledger alongside your trading activity so every decision incorporates its tax consequence.
活跃的加密货币交易者每年会产生数百个应税事件。如果没有实时追踪：
  • 你要到年底才能知道实际的税后盈亏
  • 部分卖出（“本金回收”操作）会造成成本基准混淆
  • 短期与长期收益的分类会使实际税率相差15-20%
  • 你可能错过税损收割的窗口期
  • 季度预估税款只能靠猜测
本工具会在交易活动之外持续记录税务台账，让每一项决策都能考虑到其税务影响。

Core Concepts

核心概念

Proportional Cost Basis for Partial Sells

部分卖出的比例成本基准

This is the most critical concept. When you sell a portion of a position, the cost basis splits proportionally — it does not shift to zero for the remaining tokens.
Example — The Accumulate / House-Money Play:
  1. Buy: 1,000 tokens at $1.00 each. Total cost basis = $1,000.
  2. Partial sell: Sell 800 tokens at $1.25 each. Proceeds = $1,000.
  3. What happened:
    • The 800 sold tokens had proportional cost basis = 800 x $1.00 = $800
    • Realized gain on the sale = $1,000 - $800 = $200
    • The remaining 200 tokens retain cost basis = 200 x $1.00 = $200
    • The remaining tokens are NOT "free" — they carry their original per-unit cost
Common mistake: Recording the partial sell as "capital recovered, remaining basis = $0." This understates the realized gain on the partial sell and overstates the gain when the remaining tokens are eventually sold. The total tax owed is the same either way, but the timing and classification (short-term vs long-term) can differ significantly.
这是最关键的概念。当你卖出部分仓位时，成本基准会按比例拆分——剩余代币的成本基准不会归零。
示例——累积/本金回收操作：
  1. 买入：以每个1.00美元的价格购买1000个代币，总成本基准=1000美元。
  2. 部分卖出：以每个1.25美元的价格卖出800个代币，收益=1000美元。
  3. 结果：
    • 卖出的800个代币对应的比例成本基准=800×1.00美元=800美元
    • 本次卖出的已实现收益=1000美元-800美元=200美元
    • 剩余200个代币保留的成本基准=200×1.00美元=200美元
    • 剩余代币并非“免费”——它们仍保留原始单位成本
常见误区：将部分卖出记录为“已收回本金，剩余基准=0”。这会低估本次部分卖出的已实现收益，同时高估剩余代币最终卖出时的收益。虽然总应缴税额相同，但纳税时机和收益分类（短期vs长期）可能存在显著差异。

Gain Classification

收益分类

ClassificationHolding PeriodUS Federal Rate (2024)
Short-term capital gain< 1 yearOrdinary income rate (10-37%)
Long-term capital gain>= 1 year0%, 15%, or 20%
Each tax lot tracks its own acquisition date. Partial sells consume lots in the order specified by your accounting method (FIFO, LIFO, or specific identification).
分类持有周期2024年美国联邦税率
短期资本收益< 1年普通所得税率（10-37%）
长期资本收益>= 1年0%、15%或20%
每个税务批次都会追踪自身的买入日期。部分卖出会按照你选择的会计方法（FIFO、LIFO或特定识别法）的顺序消耗批次。

SOL-Denominated Trading with USD Reporting

以SOL计价交易，以USD申报

Solana traders typically think in SOL but US tax obligations are denominated in USD. Every taxable event requires:
  1. SOL price at acquisition — establishes USD cost basis
  2. SOL price at disposition — establishes USD proceeds
  3. Token price in SOL at both events — converted to USD via SOL/USD rate
The skill tracks SOL/USD rates at each event timestamp to compute USD-denominated gains.
Solana交易者通常以SOL为计价单位，但美国税务义务以USD计价。每个应税事件需要：
  1. 买入时的SOL价格——确定USD成本基准
  2. 卖出时的SOL价格——确定USD收益
  3. 两个时点的代币SOL价格——通过SOL/USD汇率转换为USD
本工具会追踪每个事件时间点的SOL/USD汇率，以计算USD计价的收益。

Realized vs Unrealized Gains

已实现vs未实现收益

  • Realized: Position closed (fully or partially). Taxable event occurred.
  • Unrealized: Position still open. No tax event yet, but contributes to estimated liability if you plan to close before year-end.
The after-tax P&L view shows both, with unrealized gains marked at current estimated tax rates.
  • 已实现：仓位已平仓（全部或部分），已发生应税事件。
  • 未实现：仓位仍持有，尚未发生税务事件，但如果计划在年底前平仓，会影响预估负债。
税后盈亏视图会同时展示两者，未实现收益会按当前预估税率标记。

Capabilities

功能特性

Tax Lot Tracking

税务批次追踪

  • Record buys, sells, and token-to-token swaps as taxable events
  • Maintain per-lot cost basis with acquisition date
  • Support FIFO, LIFO, and specific identification accounting methods
  • Handle partial sells with proportional cost basis allocation
  • 将买入、卖出及代币间兑换记录为应税事件
  • 维护每个批次的成本基准及买入日期
  • 支持FIFO、LIFO及特定识别法三种会计方法
  • 处理部分卖出时的比例成本基准分配

Gain Classification Engine

收益分类引擎

  • Classify each realized gain as short-term or long-term
  • Track days remaining until long-term threshold for each open lot
  • Flag positions approaching the 1-year boundary
  • 将每个已实现收益分类为短期或长期
  • 追踪每个未平仓批次距离长期阈值的剩余天数
  • 标记即将达到1年持有期的仓位

Quarterly Tax Projection

季度税务预测

  • Estimate federal tax liability using progressive bracket rates
  • Include state tax estimate (configurable rate)
  • Project Q1-Q4 estimated payment amounts
  • Track cumulative realized gains by quarter
  • 使用累进税率估算联邦税务负债
  • 包含州税估算（税率可配置）
  • 预测Q1-Q4的预估税款金额
  • 按季度追踪累计已实现收益

Tax-Aware Trading Signals

税务感知交易信号

  • Long-term threshold alert: "Position crosses long-term threshold in N days"
  • Profit-taking cost: "Taking profit here triggers $X short-term liability"
  • Loss harvesting: "You have $X in unrealized losses available to harvest"
  • Timing value: "Selling now vs waiting 30 days saves $X in taxes"
  • Wash sale warning: "Repurchasing within 30 days may trigger wash sale rules"
  • 长期阈值提醒：“仓位将在N天后达到长期收益阈值”
  • 获利了结税务成本：“在此点位获利将触发X美元短期税务负债”
  • 税损收割提示：“你有X美元未实现损失可用于税损收割”
  • 时机价值分析：“现在卖出 vs 等待30天可节省X美元税款”
  • 洗售规则警告：“30天内回购可能触发洗售规则”

After-Tax P&L View

税后盈亏视图

  • Standard trading P&L alongside estimated after-tax P&L
  • Per-position breakdown of pre-tax and after-tax returns
  • Running year-to-date tax liability total
  • 标准交易盈亏与预估税后盈亏并列展示
  • 按仓位拆分税前与税后收益
  • 累计年度至今的税务负债总额

Prerequisites

前置要求

  • Python 3.10+
  • No external dependencies for core tracking (stdlib only)
  • Historical SOL/USD prices for accurate USD conversion
  • Trade history in structured format (timestamp, side, token, amount, price)
  • Python 3.10+
  • 核心追踪功能无需外部依赖（仅使用标准库）
  • 历史SOL/USD价格数据（用于准确的USD转换）
  • 结构化格式的交易历史（时间戳、方向、代币、数量、价格）

Quick Start

快速开始

python
from tax_tracker import TaxTracker, Trade

tracker = TaxTracker(
    accounting_method="fifo",
    federal_bracket=0.32,   # Your marginal federal rate
    state_rate=0.05,        # Your state income tax rate
    long_term_rate=0.15,    # Your long-term capital gains rate
)
python
from tax_tracker import TaxTracker, Trade

tracker = TaxTracker(
    accounting_method="fifo",
    federal_bracket=0.32,   # 你的边际联邦税率
    state_rate=0.05,        # 你的州所得税税率
    long_term_rate=0.15,    # 你的长期资本收益税率
)

Record the accumulate/house-money play

记录累积/本金回收操作

tracker.add_trade(Trade( timestamp="2025-06-15T10:00:00Z", side="buy", token="BONK", amount=1_000_000, price_usd=0.00002, # Per-token price in USD total_usd=20.00, ))
tracker.add_trade(Trade( timestamp="2025-07-20T14:30:00Z", side="sell", token="BONK", amount=800_000, # Sell 80% to recover capital price_usd=0.000025, total_usd=20.00, ))
tracker.add_trade(Trade( timestamp="2025-06-15T10:00:00Z", side="buy", token="BONK", amount=1_000_000, price_usd=0.00002, # 每个代币的USD价格 total_usd=20.00, ))
tracker.add_trade(Trade( timestamp="2025-07-20T14:30:00Z", side="sell", token="BONK", amount=800_000, # 卖出80%以回收本金 price_usd=0.000025, total_usd=20.00, ))

Check what happened

查看结果

summary = tracker.position_summary("BONK") print(f"Realized gain: ${summary.realized_gain:.2f}")
summary = tracker.position_summary("BONK") print(f"已实现收益: ${summary.realized_gain:.2f}")

Realized gain: $4.00 (sold 800k at $0.000025 = $20, basis = $16, gain = $4)

已实现收益: $4.00 (以0.000025美元价格卖出80万代币=20美元，成本基准=16美元，收益=4美元)

print(f"Remaining basis: ${summary.remaining_cost_basis:.2f}")
print(f"剩余成本基准: ${summary.remaining_cost_basis:.2f}")

Remaining basis: $4.00 (200k tokens x $0.00002 = $4)

剩余成本基准: $4.00 (20万代币 × 0.00002美元=4美元)

print(f"Classification: {summary.gain_type}")
print(f"收益分类: {summary.gain_type}")

Classification: short-term (held ~35 days)

收益分类: short-term (持有约35天)

Tax-aware signals

获取税务感知信号

signals = tracker.get_signals("BONK", current_price_usd=0.00003) for signal in signals: print(f" [{signal.type}] {signal.message}")
signals = tracker.get_signals("BONK", current_price_usd=0.00003) for signal in signals: print(f" [{signal.type}] {signal.message}")

[long_term_countdown] Position crosses long-term threshold in 330 days

[long_term_countdown] Position crosses long-term threshold in 330 days

[profit_taking_cost] Taking full profit triggers $2.80 short-term liability

[profit_taking_cost] Taking full profit triggers $2.80 short-term liability

undefined
undefined

Use Cases

使用场景

1. Day Trader Tax Tracking

1. 日内交易者税务追踪

Track hundreds of daily trades, all short-term. Focus on quarterly estimated payment accuracy and cumulative liability.
追踪数百笔日内交易（均为短期收益），重点关注季度预估税款的准确性及累计负债。

2. Swing Trader with House-Money Plays

2. 波段交易者的本金回收操作

Partial sell to recover capital, let remaining position ride. Proportional cost basis ensures both legs are tracked correctly.
部分卖出以回收本金，让剩余仓位继续持有。比例成本基准确保两部分仓位都能被正确追踪。

3. Long-Term Holder Monitoring

3. 长期持有者监控

Track positions approaching the 1-year long-term threshold. Signals alert when selling now vs waiting N days changes the tax classification.
追踪即将达到1年长期收益阈值的仓位。当“现在卖出”与“等待N天后卖出”会改变税务分类时，信号会发出提醒。

4. Tax-Loss Harvesting

4. 税损收割

Identify positions with unrealized losses. Harvest losses to offset gains while being mindful of wash sale rules.
识别存在未实现损失的仓位，在注意洗售规则的前提下收割损失以抵消收益。

5. Year-End Tax Planning

5. 年末税务规划

Project remaining quarterly liability, identify optimization opportunities before Dec 31.
预测剩余季度负债，在12月31日前识别优化机会。

6. Multi-Token Portfolio

6. 多代币投资组合

Track cost basis and gains across dozens of tokens simultaneously, with per-token and aggregate views.
同时追踪数十种代币的成本基准与收益，支持单代币及汇总视图。

Accounting Methods

会计方法

FIFO (First In, First Out)

FIFO（先进先出）

Sells consume the oldest lots first. Default for most traders. Generally results in more long-term gains if you have been accumulating over time.
卖出时优先消耗最早的批次。是大多数交易者的默认选择。如果长期累积仓位，通常会产生更多长期收益。

LIFO (Last In, First Out)

LIFO（后进先出）

Sells consume the newest lots first. Can minimize short-term gains if recent purchases were at higher prices.
卖出时优先消耗最新的批次。如果近期买入价格更高，可减少短期收益。

Specific Identification

特定识别法

Choose which lots to sell. Maximum flexibility for tax optimization, but requires careful record-keeping. Must be elected before the trade, not after.
选择要卖出的特定批次。在税务优化上灵活性最高，但需要仔细记录。必须在交易前选定，而非事后。

Integration with Trading Workflow

与交易流程集成

Trade Signal → Tax-Aware Filter → Execute/Defer Decision
                    │
                    ├─ "Short-term gain: $X liability"
                    ├─ "Long-term in N days — consider waiting"
                    ├─ "Loss harvest opportunity: $X offset"
                    └─ "Net after-tax profit: $Y"
The tax-aware filter does not block trades — it provides information so the trader can make informed decisions about timing.
交易信号 → 税务感知过滤器 → 执行/延迟决策
                    │
                    ├─ "短期收益：X美元税务负债"
                    ├─ "N天后达到长期收益标准——建议等待"
                    ├─ "税损收割机会：可抵消X美元收益"
                    └─ "税后净利润：Y美元"
税务感知过滤器不会阻止交易——它提供信息，让交易者能就交易时机做出明智决策。

Files

文件说明

References

参考文档

  • references/planned_features.md
    — Detailed feature list, proportional cost basis math with worked examples, gain classification rules, quarterly estimation methodology
  • references/planned_features.md
    — 详细功能列表、比例成本基准计算示例、收益分类规则、季度预估方法

Scripts

脚本

  • scripts/tax_tracker.py
    — Demo implementation with proportional cost basis, gain classification, tax-aware signals, and quarterly projection. Run with 
    --demo
    for an example accumulate/house-money scenario.
  • scripts/tax_tracker.py
    — 演示实现，包含比例成本基准、收益分类、税务感知信号及季度预测功能。运行时添加
    --demo
    参数可查看累积/本金回收场景示例。

Limitations

局限性

  • US federal and state tax rules only (no international tax support yet)
  • Does not handle staking rewards, airdrops, or DeFi yield as income events (planned)
  • Wash sale rules are flagged but not automatically enforced
  • Token-to-token swaps treated as sell + buy (two taxable events) per IRS guidance
  • Does not generate official tax forms (use for tracking and planning only)
  • 仅支持美国联邦及州税规则（暂不支持国际税务）
  • 暂未处理质押奖励、空投或DeFi收益等应税收入事件（已列入计划）
  • 会标记洗售规则，但不会自动强制执行
  • 根据IRS指引，代币间兑换被视为“卖出+买入”两个应税事件
  • 不会生成官方税务表格（仅用于追踪和规划）

Disclaimer

免责声明

Tax calculations produced by this skill are for informational tracking purposes only. Cryptocurrency tax law is complex and evolving. All tax figures should be verified by a qualified tax professional before filing. This skill does not constitute tax advice. Consult a CPA or tax attorney for guidance specific to your situation.
本工具生成的税务计算仅用于信息追踪目的。加密货币税务法规复杂且不断演变。所有税务数据在申报前需经合格税务专业人士核实。本工具不构成税务建议。请咨询注册会计师或税务律师获取针对你个人情况的指导。