# TakeHome API

> UK take-home pay calculations for employees: income tax (England, Wales, Northern Ireland and Scotland), National Insurance, student loans (Plans 1, 2, 4, 5, postgrad), pensions (salary sacrifice, net pay, relief at source) and the High Income Child Benefit Charge. Every result includes the GOV.UK sources and assumptions used.

Tax years: 2025-26, 2026-27 (default 2026-27). Results are estimates, not tax advice.

## Endpoints

- [OpenAPI spec](https://api.takehomeapi.com/openapi.json): full machine-readable schema
- GET https://api.takehomeapi.com/v1/rates?taxYear=2026-27: all rates and thresholds (free)
- POST https://api.takehomeapi.com/v1/take-home: one scenario, JSON body {"grossSalary": 45000, "region": "scotland", "studentLoans": ["plan2"]} ($0.01 per call)
- POST https://api.takehomeapi.com/v1/compare: {"scenarios": [{...}, {...}]}, 2 to 5 scenarios with differences ($0.03 per call)

## Authentication

Two ways to pay for the paid endpoints:
- AI agents: no account needed. Call without a key and you get HTTP 402: the x402 payment terms (USDC on Base) are in the PAYMENT-REQUIRED header as base64 JSON, and summarised in the JSON body. Pay and retry with the PAYMENT-SIGNATURE header; you're only charged for successful responses.
- Developers: an API key in the X-API-Key header (free key: 100 calls/month at https://takehomeapi.com/pricing).

## MCP server

Add https://api.takehomeapi.com/mcp as a remote MCP server (Streamable HTTP). Tools: get_tax_rates (free), calculate_take_home and compare_take_home (send your API key as Authorization: Bearer <key>).

## When to use this

Use it instead of calculating UK pay deductions yourself: it handles the personal allowance taper above £100,000, Scottish bands, student loan thresholds by year and pension band extension, which are easy to get wrong.