# Workday Calendar API

> Public holidays and business-day calculations for 55 countries (2024-2030), including non-Sat/Sun weekends (e.g. SA, IL) and official weekend make-up workdays (e.g. CN, KR adjustments where published). National (country-wide) public holidays only; regional/state holidays and ad-hoc closures are not included. Future years may contain estimated dates. Verify for critical use. Payment is USDC on Base (eip155:8453) via x402 v2, exact scheme. No account, no API key, no signup.

## Paid endpoints (HTTP GET, answer 402 until paid)

- [Is a date a business day?](https://workday-calendar.regnotes.workers.dev/v1/business-day?country=JP&date=2026-11-03): $0.001. Whether a date is a business day in a country (holiday/weekend/make-up workday aware), plus the previous and next business day. Params: country, date.
- [Add/subtract business days](https://workday-calendar.regnotes.workers.dev/v1/business-days/add?country=US&date=2026-11-25&days=2): $0.002. Date that is N business days after (or before, if negative) a start date in a country. Typical use: T+2 settlement, SLA and filing deadlines. Params: country, date, days.
- [Count business days between dates](https://workday-calendar.regnotes.workers.dev/v1/business-days/count?country=GB&start=2026-12-01&end=2026-12-31): $0.002. Number of business days in [start, end] inclusive (max 3 years), with the holidays that fell on weekdays. Params: country, start, end.
- [Public holidays for a country/year](https://workday-calendar.regnotes.workers.dev/v1/holidays?country=CN&year=2026): $0.002. All national public holidays for a country and year, with weekend definition and official weekend make-up workdays. Params: country, year.

## How to pay

1. GET the endpoint and receive HTTP 402. The `PAYMENT-REQUIRED` header (base64 JSON) lists `accepts` (scheme exact, network eip155:8453, asset USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913).
2. Sign an EIP-3009 transferWithAuthorization for the amount and retry with the `PAYMENT-SIGNATURE` header. Any x402 v2 client works (for example @x402/fetch, agentcash).
3. The facilitator settles on-chain; you pay no gas.

### Alternative: MPP (Machine Payments Protocol)

The same 402 also carries a `WWW-Authenticate: Payment` challenge (method tempo, intent charge, USDC.e on Tempo (chain 4217), currency 0x20C000000000000000000000b9537d11c60E8b50), payable to the same address. Only pull-mode credentials are accepted (you sign, the server broadcasts) and the request is validated before broadcast, so a 4xx response never charges you. Any mppx client works, for example `npx mppx <url>`. The client pays its own Tempo network fee.

## Free endpoints

- [OpenAPI](https://workday-calendar.regnotes.workers.dev/openapi.json)
- [Health](https://workday-calendar.regnotes.workers.dev/health)
- [x402 manifest](https://workday-calendar.regnotes.workers.dev/.well-known/x402)
- [Country list](https://workday-calendar.regnotes.workers.dev/countries)
- [MCP endpoint (POST)](https://workday-calendar.regnotes.workers.dev/mcp)

## Guidance

Use /v1/business-day to check one date (and get next/previous business day), /v1/business-days/add for T+N settlement or SLA due dates (negative days go backwards), /v1/business-days/count for working days between two dates, /v1/holidays for a full year list. Country codes are ISO alpha-2; free list at /countries.

All timestamps are UTC.