# Date Math

> Deterministic date and time math for AI agents: business days with country holidays, date arithmetic, DST-aware time-zone conversion, meeting-time overlap, cron schedules and natural-language date parsing. Use it instead of computing dates yourself; LLM date math is error-prone.

Base URL: https://date-math.datemath.workers.dev
Payment: x402 v2, $0.001 per call in USDC on Base (eip155:8453). An unpaid call returns HTTP 402 with terms in the PAYMENT-REQUIRED header; pay and retry with PAYMENT-SIGNATURE. Any x402 client (e.g. @x402/fetch) handles this automatically.
MCP: https://date-math.datemath.workers.dev/mcp (Streamable HTTP). Same tools, paid per call via x402 MCP (e.g. @x402/mcp client).
All HTTP calls: POST a JSON body, get a JSON object back. Errors: {"error":{"code","message"}}.

## Tools

- [POST /v1/diff](https://date-math.datemath.workers.dev/openapi.json) (MCP: date_diff): Difference between two dates or datetimes: calendar (Y/M/D), total days/weeks/hours, and business days (weekdays in [from, to) minus holidays; pass country to exclude its public holidays). Example body: {"from":"2026-01-31","to":"2026-03-15","country":"US"}
- [POST /v1/add](https://date-math.datemath.workers.dev/openapi.json) (MCP: date_add): Add or subtract years/months/weeks/days/business days/hours/minutes/seconds. Month-end clamping; business days skip weekends, given holidays, and the public holidays of an optional country. Example body: {"date":"2026-12-22","business_days":5,"country":"PH"}
- [POST /v1/convert](https://date-math.datemath.workers.dev/openapi.json) (MCP: timezone_convert): Convert an instant or local wall-clock time between IANA time zones (DST-aware). Example body: {"datetime":"2026-11-07T14:30:00","from_timezone":"Asia/Manila","to_timezone":"America/New_York"}
- [POST /v1/info](https://date-math.datemath.workers.dev/openapi.json) (MCP: date_info): Calendar facts for a date: weekday, ISO week, quarter, day of year, leap year, weekend. Example body: {"date":"2026-11-07"}
- [POST /v1/holidays](https://date-math.datemath.workers.dev/openapi.json) (MCP: public_holidays): Public holidays for a country and year: 207 countries, 2000–2050. Lunar or government-proclaimed dates are rule-based estimates. Example body: {"country":"PH","year":2026}
- [POST /v1/overlap](https://date-math.datemath.workers.dev/openapi.json) (MCP: working_hours_overlap): Find when working hours overlap across time zones (meeting windows). Per-participant hours optional; skips weekends by default; up to 14 days. Example body: {"timezones":["Asia/Manila","Europe/London"],"date":"2026-11-10","work_start":"09:00","work_end":"18:00"}
- [POST /v1/cron](https://date-math.datemath.workers.dev/openapi.json) (MCP: cron_schedule): Explain a cron expression in plain English and list its next run times in any time zone. Example body: {"expression":"0 9 * * 1-5","timezone":"Asia/Manila","count":3}
- [POST /v1/parse](https://date-math.datemath.workers.dev/openapi.json) (MCP: parse_date_text): Resolve natural-language dates like "next Friday at 3pm", "in 2 weeks" or "Dec 25 to Jan 2" to exact datetimes, relative to a reference time and time zone. Example body: {"text":"next friday at 3pm","timezone":"Asia/Manila","reference":"2026-11-07T14:00:00+08:00"}
- [POST /v1/city](https://date-math.datemath.workers.dev/openapi.json) (MCP: city_time): Find the IANA time zone and current local time for up to 10 cities by name ("Cebu", "São Paulo", "Springfield" + country). 7,000+ cities. Example body: {"cities":["Cebu","London","New York"]}
- [POST /v1/recurrence](https://date-math.datemath.workers.dev/openapi.json) (MCP: recurring_dates): Expand an iCalendar RRULE ("every 2nd Tuesday", "Mon/Wed until June") into concrete dates and times in a time zone, DST-aware, with optional excluded dates. Example body: {"rrule":"FREQ=MONTHLY;BYDAY=2TU","start":"2026-01-01T10:00","timezone":"Asia/Manila","count":3}
- [POST /v1/business_hours](https://date-math.datemath.workers.dev/openapi.json) (MCP: business_hours_deadline): SLA math in working hours: the deadline N business hours after a start time, or business time elapsed between two times. Custom hours and workdays, holidays, country public holidays, DST-aware. Example body: {"start":"2026-11-06T16:00","hours":2,"timezone":"Asia/Manila","work_start":"09:00","work_end":"17:00","country":"PH"}

## Free

- [OpenAPI spec](https://date-math.datemath.workers.dev/openapi.json)
- [x402 resources](https://date-math.datemath.workers.dev/.well-known/x402)
- GET /v1/health, GET /v1/version