Transaction type references — TaxMaxi Legal API

Send a transaction type key to POST /v1/legal/references/transaction-type and receive the set of legal rules that determine how that transaction is treated under German tax law, each with the clause-level statutory citations that back it. Use this endpoint to render “why is this taxed this way?” explanations in your product UI, or to give an AI agent grounding references before it answers a user’s tax question. The endpoint does not require authentication.

POST /v1/legal/references/transaction-type

Returns deterministic legal rules and their statutory citations for a given transaction type.

Request body

string

required

The transaction type to look up. Must be a non-empty string. Examples: "spot_trade", "staking_reward", "airdrop", "nft_sale".

string

The jurisdiction to query. Defaults to the German jurisdiction ("DE") when omitted.

string

Pin the response to a specific ruleset version. When omitted, the latest active ruleset is used. Pinning a version ensures reproducible responses across requests.

integer

Maximum number of legal rules to return. Must be between 1 and 20. Omit to use the server default.

integer

Maximum number of statutory citations to include per rule. Must be between 1 and 20. Omit to use the server default.

Response — 200 OK

string

required

The jurisdiction that was queried (e.g. "DE").

string | null

required

The version identifier of the ruleset used to resolve the references, or null if no versioned ruleset was active.

string | null

required

The human-readable name of the active ruleset, or null if unavailable.

object[]

required

The legal rules that apply to the requested transaction type, ordered by relevance.

Show properties

string

required

Opaque unique identifier for the rule.

string

required

Stable machine-readable key for the rule (e.g. "de.staking_reward.income_tax").

string

required

Short human-readable title of the rule.

string

required

Plain-language description of what the rule governs.

string

required

The scope or context in which the rule applies.

string

required

The tax treatment category this rule produces (e.g. "taxable_income", "capital_gain", "exempt").

number

required

Relevance score for this rule relative to the requested transaction type. Higher values indicate stronger relevance.

object[]

required

The statutory clauses that support this rule.

Show properties

string

required

Stable identifier for the cited clause within the ruleset.

string | null

required

The section code of the cited provision (e.g. "§ 22 Nr. 3 EStG"), or null if not applicable.

string | null

required

The heading of the cited provision, or null if the source does not include one.

string

required

The marginal number (Randnummer) used to locate this passage within the source document.

string | null

required

A short plain-language summary of the cited clause, or null if not available.

string

required

The full statutory text of the cited clause.

object

required

Metadata about the legal source document.

Show properties

string

required

Stable identifier for the source document within the ruleset.

string

required

Full title of the source document (e.g. "Einkommensteuergesetz").

string | null

required

Abbreviated title (e.g. "EStG"), or null if not available.

string

required

The type of legal source (e.g. "statute", "guidance", "ruling").

string

required

The issuing authority (e.g. "Bundesministerium der Finanzen").

string | null

required

A URL to the authoritative source document, or null if not publicly available.

Errors

Status	Error	Description
400	`LegalReferenceValidationError`	A required field is missing or invalid. The `message` property describes the failure.
500	`LegalReferenceInternalError`	The server failed to resolve references. The `message` property provides detail.

curl --request POST \
  --url https://api.taxmaxi.com/v1/legal/references/transaction-type \
  --header 'Content-Type: application/json' \
  --data '{
    "transactionTypeKey": "staking_reward",
    "jurisdictionCode": "DE",
    "maxReferences": 3,
    "maxCitationsPerReference": 2
  }'

Response

{
  "jurisdictionCode": "DE",
  "ruleSetVersion": "2024.1",
  "ruleSetName": "German Crypto Tax Ruleset 2024",
  "references": [
    {
      "ruleId": "rul_01hx4k9p2n8e7fvz3wqm",
      "ruleKey": "de.staking_reward.income_tax",
      "title": "Staking rewards as miscellaneous income",
      "description": "Staking rewards received by German tax residents are treated as miscellaneous income under § 22 Nr. 3 EStG in the year they are received.",
      "scope": "staking_reward",
      "outcomeCategory": "taxable_income",
      "relevance": 0.97,
      "citations": [
        {
          "clauseKey": "estg.22.3.rn45",
          "sectionCode": "§ 22 Nr. 3 EStG",
          "heading": "Sonstige Einkünfte",
          "randnummer": "45",
          "summary": "Income from other recurring sources not covered by §§ 13–21 is taxable as miscellaneous income.",
          "clauseText": "Einkünfte aus Leistungen, soweit sie weder zu anderen Einkunftsarten (§ 2 Abs. 1 Satz 1 Nr. 1 bis 6) noch zu den Einkünften im Sinne der Nummern 1, 1a, 2 oder 4 gehören ...",
          "source": {
            "sourceKey": "de.estg",
            "title": "Einkommensteuergesetz",
            "shortTitle": "EStG",
            "sourceType": "statute",
            "authority": "Bundesministerium der Justiz",
            "sourceUrl": "https://www.gesetze-im-internet.de/estg/"
          }
        },
        {
          "clauseKey": "bmf.2022.crypto.rn58",
          "sectionCode": null,
          "heading": "Einkünfte aus der Validierungstätigkeit",
          "randnummer": "58",
          "summary": "The BMF 2022 letter confirms that staking rewards are taxable at receipt for validators and delegators alike.",
          "clauseText": "Die für die Blockerstellung erhaltenen Belohnungen (Block Rewards) und Transaktionsgebühren stellen im Zeitpunkt des Zuflusses steuerpflichtige Einnahmen dar.",
          "source": {
            "sourceKey": "de.bmf.2022.crypto",
            "title": "BMF-Schreiben zur ertragsteuerrechtlichen Behandlung von virtuellen Währungen",
            "shortTitle": "BMF 2022",
            "sourceType": "guidance",
            "authority": "Bundesministerium der Finanzen",
            "sourceUrl": "https://www.bundesfinanzministerium.de/Content/DE/Downloads/BMF_Schreiben/Steuerarten/Einkommensteuer/2022-05-09-Einzelfragen-zur-ertragsteuerrechtlichen-Behandlung-von-virtuellen-Waehrungen.html"
          }
        }
      ]
    }
  ]
}

Auth

Sources

Legal References

Transaction type references — TaxMaxi Legal API

POST /v1/legal/references/transaction-type

Request body

Response — 200 OK

Errors

​POST /v1/legal/references/transaction-type

​Request body

​Response — 200 OK

​Errors

POST /v1/legal/references/transaction-type

Request body

Response — 200 OK

Errors