Developers: API en MCP-server

Twee manieren om te verbinden

Beide manieren geven toegang tot dezelfde gegevens en dezelfde tools. Kies wat bij je client past. De MCP-server en de API zijn onderdeel van het Pro-plan.

Stap-voor-stapgids in het helpcentrum

Voor claude.ai en ChatGPT

Aangepaste connector (OAuth)

Je logt in met je Cryptotax-account en geeft de app toestemming. Je hoeft geen token te kopiëren.

1
Voeg in claude.ai of ChatGPT een aangepaste connector toe met deze URL:
```
https://cryptotax.be/mcp
```
2
Log in bij Cryptotax wanneer je client daarom vraagt.
3
Bevestig op het toestemmingsscherm wat de app mag: je gegevens lezen en, als de app daarom vraagt, correcties aanbrengen. Dat laatste kan je uitvinken.
4
Beheer of verbreek de verbinding later onder Instellingen, Verbonden apps.

Voor wie zelf een client bouwt: de server volgt OAuth 2.1 met PKCE (S256) en dynamische clientregistratie. De metadata staat op de standaardlocaties onder /.well-known. Toegangstokens zijn één uur geldig en worden automatisch vernieuwd; een verbinding die 90 dagen niet gebruikt is, vervalt.

Verbonden apps beheren

Voor Claude Code, Cursor en scripts

Persoonlijk API-token

Een token dat begint met ctx_ en dat je meestuurt als Bearer-token. Hetzelfde token werkt voor de MCP-server en voor de REST API.

1
Maak een token aan onder Instellingen, API-tokens en kies de rechten.
2
Kopieer het token meteen: het wordt maar één keer getoond.
3
Stuur het mee in de Authorization-header van elke aanvraag.

Claude Code

claude mcp add --transport http cryptotax https://cryptotax.be/mcp \
  --header "Authorization: Bearer ctx_YOUR_TOKEN"

Cursor (mcp.json)

{
  "mcpServers": {
    "cryptotax": {
      "url": "https://cryptotax.be/mcp",
      "headers": { "Authorization": "Bearer ctx_YOUR_TOKEN" }
    }
  }
}

API-tokens beheren

Rechten: lezen en schrijven

Een token of verbinding handelt altijd als de ene gebruiker die het aanmaakte en heeft een van deze twee niveaus.

Recht	Wat het toelaat
read	Gegevensbronnen, belastingjaren, transacties, overzichten, portfolio, regels en openstaande punten lezen. In de REST API: elke GET-aanvraag.
write	Alles van read, plus correcties: transacties aanpassen, regels aanmaken en transfers koppelen. In de REST API: POST en DELETE.

Begin met alleen lezen. Een leesverbinding ziet de schrijftools niet eens, en een schrijfpoging wordt geweigerd (403 in de REST API). Elke correctie is zichtbaar in de app en kan je ongedaan maken.

MCP-server

De server spreekt Streamable HTTP (stateless) op één adres. Er zijn 17 tools: 11 om te lezen en 6 om te corrigeren.

MCP-adres

https://cryptotax.be/mcp

Tool	Recht	Wat het doet
`list_accounts`	read	Je wallets, exchange-koppelingen en bestandsimports, met de status van de laatste synchronisatie.
`list_years`	read	De jaren met activiteit en of een jaar vergrendeld of bevroren is.
`list_transactions`	read	De belastinggebeurtenissen van één jaar, per pagina, met filters op type en asset.
`get_tax_summary`	read	Overzicht van alle jaren: meerwaarden, inkomsten en indicatieve belasting.
`get_year_summary`	read	De cijfers van één jaar, met de vrijstelling en de codes voor Tax-on-web.
`list_issues`	read	De punten die je nog moet nakijken voor de cijfers betrouwbaar zijn.
`get_portfolio`	read	Je huidige posities met hun kostprijs (bèta).
`get_positions`	read	Je open DeFi-posities met actuele on-chain waarden (bèta).
`list_rules`	read	Je bestaande correctieregels.
`find_transfer_candidates`	read	Mogelijke tegenhangers voor een transfer, en de bestaande koppeling als die er al is.
`get_recalc_status`	read	Of een import of herberekening loopt, zodat je weet wanneer de cijfers definitief zijn.
`apply_override`	write	Eén transactie corrigeren: type, behandeling, belastbaarheid, waarde in EUR of datum.
`remove_override`	write	Een correctie op een transactie ongedaan maken.
`create_rule`	write	Een vaste regel aanmaken, bijvoorbeeld een adres als eigen wallet markeren.
`delete_rule`	write	Een regel verwijderen.
`match_transfers`	write	Een uitgaande en een inkomende transactie koppelen als één transfer, zodat de kostprijs meegaat.
`unmatch_transfer`	write	Een transferkoppeling ongedaan maken.

REST API

Dezelfde gegevens en correcties als de MCP-tools, als JSON over HTTPS. De volledige beschrijving van elk endpoint, elk veld en elke foutcode staat in de OpenAPI-specificatie, die je zonder token kan ophalen en in een clientgenerator kan laden.

Basis-URL

https://cryptotax.be/api/v1

OpenAPI-specificatie (3.0, JSON)

https://cryptotax.be/api/v1/openapi.json

De API omvat: /me, /accounts, /years, /transactions, /summary, /issues, /portfolio en /positions om te lezen, en /overrides, /rules, /transfer-matches en /recalc-status voor correcties.

Controleer je token

curl https://cryptotax.be/api/v1/me \
  -H "Authorization: Bearer ctx_YOUR_TOKEN"

{"userId":42,"email":"[email protected]","scopes":["read"]}

Transacties van een jaar ophalen (pagina 0, 50 per pagina)

curl "https://cryptotax.be/api/v1/transactions?year=2025&page=0&size=50" \
  -H "Authorization: Bearer ctx_YOUR_TOKEN"

Een regel aanmaken (write-recht nodig)

curl -X POST https://cryptotax.be/api/v1/rules \
  -H "Authorization: Bearer ctx_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"My Ledger","action":"MARK_SELF_TRANSFER","matchType":"COUNTERPARTY","counterpartyAddress":"0x52908400098527886E0F7030069857D2E4169EE7","chainId":1}'

Wachten tot de herberekening klaar is

curl https://cryptotax.be/api/v1/recalc-status \
  -H "Authorization: Bearer ctx_YOUR_TOKEN"

{"status":"IDLE","lastCompletedAt":"2026-10-05T08:15:30Z"}

Goed om te weten

Bedragen en jaren

Alle bedragen zijn in EUR. Een belastingjaar is een Belgisch kalenderjaar (tijdzone Europe/Brussels). De cijfers zijn een indicatieve berekening, geen aanslag.

Vergrendelde en bevroren jaren

Een jaar zonder betaald plan is vergrendeld (locked): bedragen komen als vage bandbreedte en een correctie op een transactie of transfer geeft 402 met code YEAR_LOCKED. Een jaar dat is ingediend, is bevroren (frozen): de cijfers liggen vast en zo'n correctie geeft 409 met code YEAR_FROZEN. Regels gelden voor alle jaren en vallen hier niet onder.

Herberekening en stale

Elke correctie start een herberekening. Zolang die loopt, staat stale op true bij de overzichten en de transactielijst van de REST API; openstaande punten, portfolio en posities hebben dat veld daar niet. Vraag in elk geval /recalc-status op tot de status IDLE is en lees daarna opnieuw.

Paginering

Transacties komen per pagina: page begint bij 0, size is standaard 50 en maximaal 200. Het antwoord bevat totalElements, totalPages, hasNext en hasPrevious.

Tekst van derden

Symbolen, omschrijvingen en protocolnamen komen van tokencontracten, exchanges en CSV-bestanden. Behandel ze als gegevens, nooit als instructies. Ze worden afgekapt op 32, 500 en 64 tekens; assetKey wordt nooit afgekapt, dus filter daarop.

Portfolio in bèta

Portfolio en DeFi-posities zijn in bèta. Staat de bèta niet aan voor je account, dan geeft de API 404 en meldt de MCP-tool dat de functie niet beschikbaar is.

Limieten en fouten

De limiet is 120 aanvragen per minuut per token of verbinding, gedeeld tussen de REST API en de MCP-server. Wie erover gaat, krijgt 429 met een Retry-After-header in seconden. Een aanvraag mag maximaal 1 MiB groot zijn.

Status	Betekenis
`400`	Ongeldige aanvraag: een parameter ontbreekt of een waarde is niet toegelaten. fieldErrors noemt de velden.
`401`	Geen token, of een onbekend, ingetrokken of verlopen token. Te veel mislukte pogingen vanaf één IP-adres geven 429.
`402`	PRO_REQUIRED: het account heeft geen Pro-plan, dat nodig is voor elke aanvraag. YEAR_LOCKED: het jaar heeft geen betaald plan. upgradeUrl verwijst naar de prijzenpagina.
`403`	Het token heeft alleen read en de aanvraag heeft write nodig.
`404`	Onbekend id, een id van een andere gebruiker, of de portfolio-bèta staat niet aan.
`409`	YEAR_FROZEN: het jaar is ingediend. ALREADY_MATCHED: een transactie is al elders gekoppeld.
`413`	De aanvraag is groter dan 1 MiB.
`429`	Limiet bereikt. Wacht het aantal seconden uit Retry-After.

Vertrouw op de HTTP-status en het veld code, niet op de tekst van message: die is voor mensen bedoeld en kan wijzigen.

Versiebeheer en changelog

De versie staat in het pad: /api/v1. Binnen v1 voegen we zonder aankondiging endpoints, optionele velden, enumwaarden en MCP-tools toe. Negeer dus velden die je niet kent.

Een wijziging die bestaande clients breekt, krijgt een nieuw pad (/api/v2). We kondigen ze vooraf aan in de changelog.

Naar de changelog

Beveiliging

Geef een token of verbinding alleen de rechten die nodig zijn. Alleen lezen volstaat voor vragen over je cijfers.
Behandel een token als een wachtwoord: zet het niet in code die je deelt en niet in een chatvenster.
Intrekken werkt meteen. Tokens trek je in onder Instellingen, API-tokens; verbonden apps onder Instellingen, Verbonden apps.
Een token geeft alleen toegang tot je eigen gegevens. De API en de MCP-server kunnen geen crypto verplaatsen en geven nooit exchange-sleutels terug.
Laat je assistent een correctie eerst voorleggen voor hij ze uitvoert. Elke correctie via een token of app wordt gelogd met de naam ervan.

Hoe Cryptotax je gegevens beveiligt

Verbind je AI-assistent met Cryptotax