> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taxmaxi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaction type references — TaxMaxi Legal API

> Retrieve the legal rules and statutory citations that govern a specific crypto transaction type under German tax law, for explainability and AI grounding.

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

<ParamField body="transactionTypeKey" type="string" required>
  The transaction type to look up. Must be a non-empty string. Examples: `"spot_trade"`, `"staking_reward"`, `"airdrop"`, `"nft_sale"`.
</ParamField>

<ParamField body="jurisdictionCode" type="string">
  The jurisdiction to query. Defaults to the German jurisdiction (`"DE"`) when omitted.
</ParamField>

<ParamField body="ruleSetVersion" type="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.
</ParamField>

<ParamField body="maxReferences" type="integer">
  Maximum number of legal rules to return. Must be between 1 and 20. Omit to use the server default.
</ParamField>

<ParamField body="maxCitationsPerReference" type="integer">
  Maximum number of statutory citations to include per rule. Must be between 1 and 20. Omit to use the server default.
</ParamField>

### Response — 200 OK

<ResponseField name="jurisdictionCode" type="string" required>
  The jurisdiction that was queried (e.g. `"DE"`).
</ResponseField>

<ResponseField name="ruleSetVersion" type="string | null" required>
  The version identifier of the ruleset used to resolve the references, or `null` if no versioned ruleset was active.
</ResponseField>

<ResponseField name="ruleSetName" type="string | null" required>
  The human-readable name of the active ruleset, or `null` if unavailable.
</ResponseField>

<ResponseField name="references" type="object[]" required>
  The legal rules that apply to the requested transaction type, ordered by relevance.

  <Expandable title="properties">
    <ResponseField name="ruleId" type="string" required>
      Opaque unique identifier for the rule.
    </ResponseField>

    <ResponseField name="ruleKey" type="string" required>
      Stable machine-readable key for the rule (e.g. `"de.staking_reward.income_tax"`).
    </ResponseField>

    <ResponseField name="title" type="string" required>
      Short human-readable title of the rule.
    </ResponseField>

    <ResponseField name="description" type="string" required>
      Plain-language description of what the rule governs.
    </ResponseField>

    <ResponseField name="scope" type="string" required>
      The scope or context in which the rule applies.
    </ResponseField>

    <ResponseField name="outcomeCategory" type="string" required>
      The tax treatment category this rule produces (e.g. `"taxable_income"`, `"capital_gain"`, `"exempt"`).
    </ResponseField>

    <ResponseField name="relevance" type="number" required>
      Relevance score for this rule relative to the requested transaction type. Higher values indicate stronger relevance.
    </ResponseField>

    <ResponseField name="citations" type="object[]" required>
      The statutory clauses that support this rule.

      <Expandable title="properties">
        <ResponseField name="clauseKey" type="string" required>
          Stable identifier for the cited clause within the ruleset.
        </ResponseField>

        <ResponseField name="sectionCode" type="string | null" required>
          The section code of the cited provision (e.g. `"§ 22 Nr. 3 EStG"`), or `null` if not applicable.
        </ResponseField>

        <ResponseField name="heading" type="string | null" required>
          The heading of the cited provision, or `null` if the source does not include one.
        </ResponseField>

        <ResponseField name="randnummer" type="string" required>
          The marginal number (Randnummer) used to locate this passage within the source document.
        </ResponseField>

        <ResponseField name="summary" type="string | null" required>
          A short plain-language summary of the cited clause, or `null` if not available.
        </ResponseField>

        <ResponseField name="clauseText" type="string" required>
          The full statutory text of the cited clause.
        </ResponseField>

        <ResponseField name="source" type="object" required>
          Metadata about the legal source document.

          <Expandable title="properties">
            <ResponseField name="sourceKey" type="string" required>
              Stable identifier for the source document within the ruleset.
            </ResponseField>

            <ResponseField name="title" type="string" required>
              Full title of the source document (e.g. `"Einkommensteuergesetz"`).
            </ResponseField>

            <ResponseField name="shortTitle" type="string | null" required>
              Abbreviated title (e.g. `"EStG"`), or `null` if not available.
            </ResponseField>

            <ResponseField name="sourceType" type="string" required>
              The type of legal source (e.g. `"statute"`, `"guidance"`, `"ruling"`).
            </ResponseField>

            <ResponseField name="authority" type="string" required>
              The issuing authority (e.g. `"Bundesministerium der Finanzen"`).
            </ResponseField>

            <ResponseField name="sourceUrl" type="string | null" required>
              A URL to the authoritative source document, or `null` if not publicly available.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

### 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.      |

<CodeGroup>
  ```bash Request theme={null}
  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
    }'
  ```
</CodeGroup>

```json Response theme={null}
{
  "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"
          }
        }
      ]
    }
  ]
}
```