Get the Tax Treatment of Any Crypto Transaction, Programmatically
There is a working answer to this question: send a transaction hash to a classification API and get back the US tax treatment — the canonical category, taxable or not, a confidence score, and an explicit flag when the row needs professional review. Most tools marketed as "crypto tax APIs" return transaction data (balances, transfers, decoded calls) and leave the tax determination to you. This page shows the one call that returns the determination itself.
The request
Create a free API key (no card) at dashboard.cryptotaxedge.com under Settings → API keys, then:
curl -X POST https://app.cryptotaxedge.com/v1/classify-batch \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"hashes": [
{ "tx_id": "row_1", "hash": "0x280710a5673a8ff1af7f623ddb5148417ac36539228d0eec8edb8a57b19383c2", "chain": "ethereum" }
]
}'
Up to 100 transactions per call. chain is optional — it auto-detects when omitted. tx_id is yours and comes back on each result so you can correlate to your own records.
The response
{
"api_version": "v1",
"hash": "0x280710a5673a8ff1af7f623ddb5148417ac36539228d0eec8edb8a57b19383c2",
"chain": "ethereum",
"category": "swap",
"treatment": "disposal",
"taxable": true,
"confidence": 77,
"needs_review": false,
"ledger_action": "Trade",
"protocol": null,
"description": "Token swap; a taxable disposition under IRC 1001.",
"review_note": null,
"grey_area": null,
"assets": {
"sent": [ { "symbol": "stETH", "amount": "0.002297", "decimals": 18, "action": "transferred" } ],
"received": [ { "symbol": "USDC", "amount": "3.723749", "decimals": 6, "action": "received" } ],
"gas": null
}
}
What each field means for your integration
treatment is a closed enum — disposal, income, non_taxable, expense, needs_review — so you can branch exhaustive logic on it. category is the canonical event type (swap, liquidity_add, reward, bridge, and so on) and grows over time; branch on treatment, display category.
taxable is true, false, or null. null always travels with needs_review: true and means the engine is not asserting taxability — route the row to a human, never treat null as false.
needs_review is the honesty contract. When the engine cannot stand behind a classification, it says so, with a review_note explaining why — a deliberate deferral instead of a guess. A result with needs_review: false is served as authoritative at any confidence.
grey_area appears on the handful of genuinely two-sided treatments (LP positions, wrapping, liquid staking) and carries the position not taken, so an accountant can see and switch it. An optional policy object on the request applies your firm's chosen position on the wire.
confidence is a routing signal — how strongly independent evidence agreed — not an accuracy percentage.
What's billed and what's free
Only tax-relevant classifications count: swaps, liquidity, lending, rewards, NFTs, payments, and review-flagged rows. Plain transfers, approvals, spam, failed transactions, unsupported rows, and every repeat of an already-classified hash come back fully labeled at $0 — so you can send an entire wallet without pre-filtering. The free Developer tier includes 250 billable classifications a month; paid plans are published at cryptotaxedge.com.
The same engine over MCP
For AI agents and assistants, the identical classification runs as an MCP server at mcp.cryptotaxedge.com — a classify_batch tool over JSON-RPC with the same reliability envelope on every result. The same API key works on both surfaces, drawing from the same quota.
FAQ
Can I get a tax determination from a data API like a node provider or indexer? No — data APIs return what happened (transfers, decoded calls). Turning that into a US tax position (IRC §1001 disposals, §61 income, Rev. Rul. 2023-14 staking treatment) is the classification layer's job, and it's what this endpoint returns directly.
How many chains are supported? 80+, including Ethereum, the major L2s, and Solana.
What happens on a transaction the engine can't classify?
It returns an honest error or an unsupported result — free — rather than a guess. Batch calls return HTTP 200 with a per-item error field, so one bad hash never fails the batch.
Is the output tax advice? No. Classifications are informational, with cited authority so a qualified professional can review them. Full docs at dashboard.cryptotaxedge.com/api.