CryptoTaxEdge classification API

The full machine-readable contract is published as an OpenAPI 3.1 spec: request and response schemas, the closed treatment enum, and every error code, ready for codegen and validation.

Each request carries a bearer token. Create your own API key in Settings → API keys: sign in (free, no credit card), click “Create API key”, and copy the token. Developer keys include 250 classifications a month on the free tier (~25,000 on Pro); the same key works on both the REST API and the MCP server. For partner integrations with volume pricing, contact us.

Authorization: Bearer YOUR_API_KEY

A valid key is required on every request; there is no anonymous access to the public API. Rate limit is 60 requests per minute per key, and a single batch request carries up to 100 transactions, so a partner steadily fills up to 6,000 transactions a minute. tx_id is yours: we echo it back as id on each batch result so you can correlate to your records. chain is optional and auto-detected when omitted. We never return source or vendor internals. Quota counts distinct successful classifications only: re-running a hash you already classified is always free, and failed or review-routed results never consume quota. Check your pool anytime with GET /quota-status (free, never consumes quota).

Two known-good Ethereum mainnet hashes you can drop straight into a request. Re-runs are free, so testing costs you nothing:

curl -X POST https://app.cryptotaxedge.com/v1/classify-batch \
  -H 'Authorization: Bearer YOUR_PARTNER_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "hashes": [
      { "tx_id": "row_1", "hash": "0x280710a5673a8ff1af7f623ddb5148417ac36539228d0eec8edb8a57b19383c2", "chain": "ethereum" },
      { "tx_id": "row_2", "hash": "0x9b5693fc24d2e31c59317f53f7ca77b3d570ad86999bd22a4fc53a7d06a48da6", "chain": "ethereum" }
    ]
  }'

Agent-native stacks can call the same classify_batch tool over MCP (JSON-RPC 2.0) at mcp.cryptotaxedge.com, same parameters, same key. MCP setup →

A handful of treatments are genuinely two-sided: the same on-chain event has two defensible tax positions, and which one a firm posts is a house call, not a fact the chain settles. Send an optional policy object and the returned verdict reflects your firm's chosen position for those treatments, applied on the wire so every downstream system reads one answer. Four dimensions are governed today:

{
  "hashes": [
    { "tx_id": "row_1", "hash": "0x280710a5673a8ff1af7f623ddb5148417ac36539228d0eec8edb8a57b19383c2", "chain": "ethereum" }
  ],
  "policy": {
    "lp":      "non_taxable",
    "wrap":    "non_taxable",
    "lst":     "disposal",
    "staking": "income"
  }
}

Strictly additive. Omit policy (or any single key) and that treatment falls back to the platform default, byte-identical to a policy-free call. Unknown keys and invalid values are ignored, never an error. Policy never overrides a transaction we flagged for review: it resolves a grey treatment, never papers over a classification we are not sure of. The grey_area block still names the position not taken.

{
  "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",
                    "token_address": "0xae7a...fe84", "to": "0x89c6...f818" } ],
    "received": [ { "symbol": "USDC",  "amount": "3.723749", "decimals": 6,  "action": "received",
                    "token_address": "0xa0b8...eb48", "from": "0x1231...4eae" } ],
    "gas": null
  }
}

Complex transactions additionally return a per-leg breakdown plus a memo, so you can post the correct number of taxable events for a single on-chain transaction.

{
  "category": "swap",
  "treatment": "disposal",
  "confidence": 88,
  "parent": { "category": "swap", "description": "Flash-loan arbitrage: borrow, two swap legs, repay." },
  "legs": [
    { "leg_index": 0, "role": "flash_borrow", "category": "borrow", "taxable": false },
    { "leg_index": 1, "role": "arb_swap_1",  "category": "swap",   "taxable": true },
    { "leg_index": 2, "role": "arb_swap_2",  "category": "swap",   "taxable": true },
    { "leg_index": 3, "role": "flash_repay",  "category": "repay",  "taxable": false }
  ],
  "memo": "Borrow and repay are non-events; recognize gain or loss on the two swap legs."
}

treatment is a closed set of five values you can switch on exhaustively: disposal, income, non_taxable, expense, needs_review. Anything the engine cannot map to one of those five is clamped to needs_review, so a partner switch statement never sees an out-of-contract value. confidence is an integer from 0 to 100.

An uncertain transaction is never a silent wrong non-taxable. When the engine cannot reach a confident verdict it returns needs_review: true with taxable: null and a review_note explaining why: a deliberate deferral for a human to resolve, never a forced verdict, never a guess dressed as an answer, and never billed. A taxable of false means a positive non-taxable finding; a taxable of null always travels with needs_review: true and means undetermined. Treat the two as distinct in your ledger.

This is the differentiator: the engine flags what it is unsure of rather than committing a wrong number to the books.

confidence is a routing signal, not an accuracy percentage. It reflects how strongly independent evidence agreed on the verdict, and its job is to decide what gets served, what gets hedged, and what gets flagged. Do not read 77 as "77% likely correct".

The score lands in bands that track corroboration:

Because the bands track corroboration rather than complexity, a trivially simple transfer can sit at 60: only one source decoded it, so it is single-source even though the shape is obvious. A more complex swap that three sources agree on scores 95. Both numbers are honest; neither is a quality grade on the transaction itself.

You do not need to invent your own cutoff: anything the engine is not prepared to stand behind already ships needs_review: true. A verdict with needs_review: false is one the engine serves as authoritative, at any confidence. If your workflow wants a stricter posture on top of that, sampling single-source results (the 60 to 79 band) is the sensible dial; the MCP surface applies an additional review floor at 70 for hosts that want it prebuilt. When needs_review is true, taxable is always null; treatment may still name the engine's leaning, and it is a pointer for the reviewer, not a verdict to post.

When a transaction has more than one defensible treatment, the response adds a grey_area block: note is the basis for the split, and alternate carries the position not taken so your accountant can see and switch it. When a policy is supplied, the top-level verdict reflects the firm's chosen position and alternate shows the road not taken. grey_area is null on transactions with a single settled treatment.

{
  "category": "liquidity_add",
  "treatment": "non_taxable",
  "taxable": false,
  "needs_review": false,
  "grey_area": {
    "note": "LP contribution/withdrawal: no LP-specific IRS guidance; general property/realization principle governs.",
    "alternate": {
      "treatment": "disposal",
      "taxable": true,
      "label": "Disposition view (LP entry/exit as a crypto-to-crypto disposal)"
    }
  }
}

Every error uses one envelope, { "error": { "code", "message" } }, with standard HTTP semantics. Codes are stable; messages are human-readable and can change.

Batch semantics: /v1/classify-batch returns HTTP 200 with one result per input; an item that could not be classified carries an error string on that item (for example tx_not_retrievable) instead of failing the whole call. The single endpoint maps the same failures to the HTTP statuses above. Treat any item with error set as not classified, and never as a verdict.

Every field the /v1 wire carries, verified against live responses. Fields marked "only" are conditional; everything else is always present. Unknown future fields are additive: ignore what you do not use.

Deprecated aliases (MCP surface only): the MCP tools historically used the field names tx_type, tax_category, reasoning, source, and authoritative. These are now deprecated aliases of category, treatment, description, and the needs_review flag (authoritative is exactly needs_review: false, never an independent stamp). They are kept for one release for back-compat and will be removed in the next minor version; migrate to the canonical names. None of these aliases ever appear on REST /v1.

category is the canonical transaction type. Its core is the stable set below; the vocabulary grows as new on-chain patterns are named (for example wrap, reward, liquid_staking_mint), always additively, so treat an unfamiliar category gracefully rather than as an error. For an exhaustive switch, branch on treatment (the closed five-value set), not category. ledger_action carries the suggested ledger label.

The full taxonomy, with each category's default treatment, the house position on grey-area categories, and the named alternatives, is published at cryptotaxedge.com/taxonomy.

The contract is versioned in the path (/v1/) and echoed in every response as api_version. Within v1 we only make additive changes: new optional fields may appear, but existing fields are never renamed or removed and the treatment enum never gains a value without a version bump. A breaking change ships as /v2 with v1 kept live through a published deprecation window. Build against the fields you use and ignore unknown ones, and the contract will not break under you.

1. Create an API key in Settings, API keys and send it as Authorization: Bearer on every call.
2. Batch your transactions (up to 100 per call) to POST /v1/classify-batch, each with your own tx_id; use POST /v1/classify for one-offs.
3. Optionally send a policy object to apply your firm's house positions on the wire.
4. Correlate each result to your record by the echoed id, then post from treatment, taxable, and ledger_action. Multi-step transactions carry a per-leg breakdown so you post the right number of events.
5. Route any result with needs_review: true to a human queue rather than to the books; surface grey_area where present.
6. Handle errors from the { error: { code, message } } envelope (full table above). Retry tx_not_yet_mined after the transaction mines and back off on rate_limited.
7. Generate a typed client from the OpenAPI 3.1 spec if your stack supports it, and poll GET /quota-status to surface remaining quota in your own UI.