The Classification Record schema

cte-classification-v1 · frozen 2026-08-04 · JSON Schema · changelog

Every CryptoTaxEdge classification — REST or MCP — returns the same record shape. This page freezes that shape as a versioned contract you can build against and pin: fields are added, never removed or repurposed, within a major version.

The record

{
  "api_version": "v1",
  "hash": "0x...",
  "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": [ ... ], "received": [ ... ], "gas": null }
}

The three rules integrators must honor

Rule	Meaning
`treatment` is closed	Exactly five values: `disposal`, `income`, `non_taxable`, `expense`, `needs_review`. Branch exhaustive logic here. `category` is an open vocabulary — display it, never switch on it exhaustively.
`taxable: null` never means false	`null` always travels with `needs_review: true`: taxability is not asserted. Route the row to a human.
`needs_review` is the gate	`true` = the engine defers instead of guessing — queue it, never book it. `false` = served as authoritative at any confidence. `grey_area`, when present, carries the defensible position not taken.

Validate your integration

Validate any response against the schema with standard tooling:

npx ajv-cli validate -s https://cryptotaxedge.com/schema/cte-classification-v1.json -d response.json --spec=draft2020

Worked examples for canonical shapes live in the MCP repo and the developer quickstart. Full API reference: dashboard.cryptotaxedge.com/api.

Classifications are informational only, not tax advice. Verify results with a qualified tax professional before filing.