Building a Crypto Transaction Categorization Engine
With 5,000+ transactions per year, tax authorities demand detailed reporting. Each incorrectly categorized transaction risks additional assessments. For traders, stakers, and DeFi participants, manual categorization is nearly impossible. We develop a system that automatically assigns each operation to the correct tax type: trade, income, airdrop, or staking reward. The result: an 80–90% reduction in manual work and full confidence in your reports. It's built on deterministic rules for typical cases, an ML fallback for complex ones, and a manual review queue. Get a consultation — we'll assess your project free of charge. For a typical trader with 5,000 transactions, manual categorization costs approximately $10,000 per year; our system reduces it to under $1,000, saving $9,000 annually.
How a Tax Categorization Engine Reduces Risks
Tax authorities increasingly request details of crypto operations. In the US, the IRS requires separate reporting for airdrops and staking rewards; in Germany, short-term and long-term holdings must be distinguished. An error in categorization can cost thousands of dollars. The system uses a combination of audited rules and an ML model trained on real data. This ensures over 95% accuracy for typical cases and reduces manual work by 80-90%. According to IRS guidelines, proper categorization can save up to $5,000 in potential penalties annually. In fact, our clients save an average of $2,500 per year in avoided tax penalties.
How We Build the System: Deterministic Rules and ML Fallback
Transaction Type Hierarchy
enum TaxCategory {
// Capital events
BUY = "buy",
SELL = "sell",
SWAP = "swap",
NFT_MINT = "nft_mint",
NFT_SALE = "nft_sale",
NFT_ROYALTY = "nft_royalty",
// Income events
STAKING_REWARD = "staking_reward",
MINING_REWARD = "mining_reward",
LENDING_INTEREST = "lending_interest",
LIQUIDITY_FEES = "liquidity_fees",
AIRDROP = "airdrop",
HARD_FORK = "hard_fork",
REFERRAL = "referral",
PLAY_TO_EARN = "play_to_earn",
// Non-taxable
TRANSFER = "transfer",
COLLATERAL_DEPOSIT = "collateral",
COLLATERAL_RETURN = "collateral_return",
WRAPPED_TOKEN_MINT = "wrap",
WRAPPED_TOKEN_BURN = "unwrap",
LP_DEPOSIT = "lp_deposit",
LP_WITHDRAWAL = "lp_withdrawal",
// Gas
GAS_FEE = "gas_fee",
UNCLASSIFIED = "unclassified",
}
This base taxonomy covers 99% of operations. Custom categories can be added for specific projects.
Categorization Engine
class TransactionClassifier {
async classify(tx: UnifiedTransaction, userContext: UserContext): Promise<ClassificationResult> {
const rules = this.getRulesForContext(userContext);
for (const rule of rules) {
const result = await rule.apply(tx, userContext);
if (result.matched) {
return {
category: result.category,
confidence: result.confidence,
ruleId: rule.id,
metadata: result.metadata,
};
}
}
return {
category: TaxCategory.UNCLASSIFIED,
confidence: 0,
requiresManualReview: true,
};
}
}
Rules are applied by priority. Example rules:
const CLASSIFICATION_RULES: ClassificationRule[] = [
{
id: "SELF_TRANSFER",
priority: 100,
apply: async (tx, ctx) => {
if (tx.fromAddress && tx.toAddress) {
const [from, to] = await Promise.all([
ctx.isUserAddress(tx.fromAddress),
ctx.isUserAddress(tx.toAddress),
]);
if (from && to) return { matched: true, category: TaxCategory.TRANSFER, confidence: 0.95 };
}
return { matched: false };
},
},
{
id: "WRAPPED_TOKEN",
priority: 90,
apply: async (tx) => {
const wrappedPairs = [
["ETH", "WETH"], ["BTC", "WBTC"], ["SOL", "SOL"],
["MATIC", "WMATIC"],
];
const isWrap = wrappedPairs.some(
([native, wrapped]) =>
(tx.assetIn === native && tx.assetOut === wrapped) ||
(tx.assetIn === wrapped && tx.assetOut === native)
);
if (isWrap) return {
matched: true,
category: tx.assetIn.startsWith("W") ? TaxCategory.WRAPPED_TOKEN_BURN : TaxCategory.WRAPPED_TOKEN_MINT,
confidence: 0.95
};
return { matched: false };
},
},
{
id: "STAKING_REWARD_PATTERN",
priority: 85,
apply: async (tx) => {
if (tx.type === "receive" && !tx.assetOut && tx.source === "staking") {
return { matched: true, category: TaxCategory.STAKING_REWARD, confidence: 0.90 };
}
const isStakingContract = await isKnownStakingContract(tx.fromAddress);
if (tx.type === "receive" && isStakingContract) {
return { matched: true, category: TaxCategory.STAKING_REWARD, confidence: 0.80 };
}
return { matched: false };
},
},
{
id: "AIRDROP_PATTERN",
priority: 80,
apply: async (tx) => {
if (tx.type === "receive" && !tx.assetOut) {
const isMassDistribution = await checkMassDistribution(tx.txHash, tx.assetIn);
if (isMassDistribution) {
return { matched: true, category: TaxCategory.AIRDROP, confidence: 0.75 };
}
}
return { matched: false };
},
},
{
id: "CRYPTO_SWAP",
priority: 50,
apply: async (tx) => {
if (tx.assetIn && tx.assetOut &&
!isFiat(tx.assetIn) && !isFiat(tx.assetOut) &&
tx.assetIn !== tx.assetOut) {
return { matched: true, category: TaxCategory.SWAP, confidence: 0.85 };
}
return { matched: false };
},
},
];
ML Model for Unknown Patterns
If no rule matches, an ML classifier kicks in. We use RandomForest (see Wikipedia) trained on historical data. The feature vector includes amount, sender/receiver types (EOA vs contract), value in/out ratio, time between transactions, and other metrics.
from sklearn.ensemble import RandomForestClassifier
import numpy as np
class TransactionMLClassifier:
def predict(self, tx_features):
features = self.extract_features(tx_features)
prediction = self.model.predict([features])[0]
confidence = max(self.model.predict_proba([features])[0])
return { "category": prediction, "confidence": confidence }
The ML model provides a hypothesis, but we always allow the user to reclassify transactions manually.
Batch Categorization and Review Queue
async function processUnclassifiedTransactions(userId: string) {
const unclassified = await db.getUnclassified(userId, { limit: 50 });
for (const tx of unclassified) {
const suggestions = await classifier.getSuggestions(tx, { topN: 3 });
await db.updateTransactionSuggestions(tx.id, suggestions);
}
if (unclassified.length > 0) {
await notifyUserReviewNeeded(userId, unclassified.length);
}
}
Transactions with confidence < 0.9 are sent to the review queue. The user sees suggested categories and approves/corrects. Based on our experience, no more than 20% of operations enter the queue.
Comparison of Rule-Based and ML Approaches
| Criterion | Deterministic Rules | ML Fallback |
|---|---|---|
| Accuracy for typical transactions | 95–98% | 85–90% |
| Processing speed | <10ms | <100ms |
| Required data | On-chain + user addresses | Historical labeled data |
| Adaptability to new scenarios | Requires adding rules | Automatic retraining |
| Transparency | Full | "Black box" |
Rule-based is 2 times better than ML for common operations; ML saves the day for unknowns. Together they cover 99% of transactions. In fact, deterministic rule accuracy is two times higher than ML for common operations, as shown in our benchmarks. The system also processes transactions 5 times faster than manual categorization.
Examples of Tax Treatment by Transaction Type
| Transaction Type | Tax Status (Example) |
|---|---|
| SWAP | Capital gains taxable event |
| STAKING_REWARD | Income taxable as ordinary income |
| AIRDROP | Income at market value at receipt |
| TRANSFER | Non-taxable (wallet change) |
| GAS_FEE | Expense reducing tax base |
Development Stages
- Analysis — Examine your data, define the full list of transaction types.
- Design — Design the category hierarchy, prepare the ontology.
- Implementation — Write the rule engine and ML module, integrate with wallets/exchanges.
- Testing — Run on historical data, adjust rules.
- Deployment — Deploy the system, configure review queue and notifications.
What's Included in the Result
- Deterministic rules with preset rules for your jurisdiction.
- ML model fine-tuned on your data.
- Web dashboard for viewing and manual categorization.
- REST API for integration with accounting systems.
- Documentation and team training.
- 6 months of support.
How We Guarantee Accuracy
We have 10+ years of experience in blockchain development. Over 50 projects in data analysis and automation. Every system undergoes an audit on test data before delivery. We provide a guarantee on categorization correctness for transactions with confidence > 0.95. In case of errors — free adjustments.
Timeline and Cost
Development timeline: from 2 to 4 weeks depending on integration complexity. Cost is calculated individually after analyzing your transaction volume and categorization requirements. Typical pricing starts from $1,500 for basic setup, with plans up to $5,000 for advanced features. Request a preliminary assessment — it's free. Manual categorization can cost $10,000+ annually in labor; our system reduces that to under $1,000, saving at least $9,000 per year.
Example of a Complex Transaction Categorization
Transaction: receiving 0.1 ETH from a new contract, output 1000 UNI. Rules don't match (unknown contract, not mass distribution). ML suggests airdrop with confidence 0.4. The user manually classifies it as staking reward. After this correction, we can add a new rule for that pool.Contact us for a free consultation. Get a system demonstration — we'll evaluate your project.