# Exchange trading calendar (28 stock exchanges) + Public holidays and business days (247 countries)

> Pay-per-call data APIs for AI agents. Payment per request with x402 (USDC, network eip155:8453) – no account, no API key, no subscription.

## How to call
- Send GET with query parameters. Without payment the answer is HTTP 402 with the x402 payment requirements; pay with any x402 client and repeat the request.
- Invalid input is rejected with HTTP 400 BEFORE payment. Not found (404) and source outages (503/504) are never charged.
- Every answer names its official source (attribution).

## Endpoints

### GET /v1/trading-day – 0.002 USDC
Use when an agent needs to know if a stock exchange trades on a given day (default today) before scheduling orders, reports or alerts. 28 exchanges incl. NYSE, Nasdaq, LSE, Xetra, Euronext, SIX, Tokyo, HKEX, Shanghai, ASX. Returns holiday name, hours in local time + UTC, half days, lunch breaks, pre/after-market (Nasdaq, Xetra), live status, next open/close, previous/next trading day. Official exchange calendars only; bad input: HTTP 400, no charge.
- `exchange` (required): Exchange MIC code, e.g. XNYS (NYSE), XNAS (Nasdaq), XLON (London), XETR (Xetra), XPAR (Paris), XTKS (Tokyo), XHKG (Hong Kong). Common names also work (NYSE, Xetra, LSE). Free list: GET /v1/exchanges.
- `date`: Day as YYYY-MM-DD. Optional, default: today in the exchange's time zone.
- Example: https://handelskalender-api.pages.dev/v1/trading-day?exchange=XWBO&date=2026-10-26

### GET /v1/trading-calendar – 0.002 USDC
Use when an agent plans ahead and needs every closure of a stock exchange for a whole year: holiday names, half days, late openings, regular hours, count of trading days. 28 exchanges incl. NYSE, Nasdaq, LSE, Xetra, Euronext, SIX, Tokyo, HKEX, Shanghai, ASX. Official exchange calendars only; bad input or uncovered year: HTTP 400, no charge.
- `exchange` (required): Exchange MIC code, e.g. XNYS (NYSE), XNAS (Nasdaq), XLON (London), XETR (Xetra), XPAR (Paris), XTKS (Tokyo), XHKG (Hong Kong). Common names also work (NYSE, Xetra, LSE). Free list: GET /v1/exchanges.
- `year`: Year, e.g. 2026. Optional, default: current year.
- Example: https://handelskalender-api.pages.dev/v1/trading-calendar?exchange=XNYS&year=2026

### GET /v1/market-status – 0.002 USDC
Use when an agent needs to know right now which stock exchanges are open: open, lunch break, pre-market, after-hours or closed (with holiday name), local time, exact next open and close in UTC. One call checks up to 28 exchanges (default all) incl. NYSE, Nasdaq, LSE, Xetra, Euronext, Tokyo, HKEX, Shanghai, ASX. Official exchange calendars only; unknown exchange: HTTP 400, no charge.
- `exchanges`: Comma-separated MIC codes or names, e.g. XNYS,XETR,XTKS. Optional, default: all exchanges.
- Example: https://handelskalender-api.pages.dev/v1/market-status?exchanges=XNAS%2CXETR

### GET /v1/public-holidays – 0.002 USDC
Use when an agent needs all public holidays of a country for a year (planning deliveries, payments, deadlines, staffing). 247 countries, 2026-2028, optional state/province (region=) for regional holidays. English and local names, weekend days of the country, moon-dependent dates flagged as estimated. Bad input: HTTP 400 before payment, no charge.
- `country` (required): 2-letter ISO country code, e.g. AT, DE, US, GB, FR, JP, IN, BR, AE. 247 countries; free list: GET /v1/holiday-countries.
- `year`: Year, e.g. 2027. Optional, default: current year. Covered: 2026-2028.
- `region`: Optional state/province for regional holidays, e.g. BY or DE-BY (Bavaria), CA (California), 9 (Vienna). Listed per country in GET /v1/holiday-countries.
- Example: https://handelskalender-api.pages.dev/v1/public-holidays?country=AT&year=2027

### GET /v1/business-day – 0.002 USDC
Use when an agent must know if a date is a business day in a country, or compute a due date: weekend or holiday (with name), previous/next business day, date plus N business days (add=), business days until a date (to=). 247 countries, 2026-2028, optional state/province (region=), local weekends (e.g. Fri-Sat). Bad input: HTTP 400, no charge.
- `country` (required): 2-letter ISO country code, e.g. AT, DE, US, GB, FR, JP, IN, BR, AE. 247 countries; free list: GET /v1/holiday-countries.
- `date`: Day as YYYY-MM-DD. Optional, default: today (UTC).
- `region`: Optional state/province for regional holidays, e.g. BY or DE-BY (Bavaria), CA (California), 9 (Vienna). Listed per country in GET /v1/holiday-countries.
- `add`: Optional: number of business days to add (negative = go back), -260 to 260.
- `to`: Optional end date YYYY-MM-DD (>= date): count business days from date to it, both included.
- Example: https://handelskalender-api.pages.dev/v1/business-day?country=DE&date=2027-01-06&region=BY&add=10

## Machine-readable
- [MCP server](https://handelskalender-api.pages.dev/mcp): every endpoint as an MCP tool (Streamable HTTP, POST; x402 payment in _meta["x402/payment"])
- [OpenAPI 3.1](https://handelskalender-api.pages.dev/openapi.json): all endpoints with prices, parameters and example answers
- [x402 discovery](https://handelskalender-api.pages.dev/.well-known/x402): list of paid resources

Contact: Stockwerk Studio, stockwerkstudio@gmail.com