# GET /holidays: $0.002 per call

Public holidays for 100+ countries and years, with regional holidays (e.g. DE-BY, US-CA, GB-SCT). Add date= to learn if that day is a working day there, and the next working day. Pass ?country=DE&year=2026 or ?country=GB&date=2026-12-28&region=GB-SCT. Weekends default to Sat–Sun (Fri–Sat for e.g. SA, IL, EG); override with weekend=.

- **Price:** $0.002 in USDC, the same on Base, Solana, Polygon, Arbitrum. Failed calls are never charged.
- **Free trial:** yes, 20 free calls a day from Claude, Cursor or any MCP client ([set-up](/mcp/setup)).
- **Answers cached for:** 1 day(s)
- **Data sources:** Nager.Date public holiday API (free)
- **Lane:** Time, holidays & weather ([OpenAPI](/openapi/world.json))
- **Live health:** [status page](/status)

## Free sample

See an answer for the demo input first, free (no payment, 10 a minute): [https://aayatai.com/sample/holidays](/sample/holidays). It is a stored real answer when we have one, otherwise an example marked `"kind": "illustrative"`.

```bash
curl "https://aayatai.com/sample/holidays"
```

## 1. See the price (free)

Call it without paying: you get `402 Payment Required` and a `PAYMENT-REQUIRED` header with the exact price and where to pay.

```bash
curl -i "https://aayatai.com/holidays?country=GB&date=2026-12-28&region=GB-SCT"
```

## 2. Pay and call (TypeScript)

```bash
npm install @x402/fetch @x402/evm viem
```

```ts
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

// A wallet used only by your agent, holding a little USDC on Base.
const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY as `0x${string}`);
const pay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});

const res = await pay("https://aayatai.com/holidays?country=GB&date=2026-12-28&region=GB-SCT");
console.log(await res.json());
```

## 3. Or as an MCP tool

```ts
// MCP server: https://aayatai.com/mcp (Streamable HTTP). With the x402 MCP client (see /start):
const result = await client.callTool("holidays", {"country":"GB","date":"2026-12-28","region":"GB-SCT"});
```

## Inputs

- `country` **(required)** (string): ISO 3166-1 alpha-2 country code, e.g. GB, US, DE, IN.
- `year` (integer): Year (default: the year of date=, else this year).
- `date` (string): Optional YYYY-MM-DD to check: weekend, holiday, working day, next working day.
- `region` (string): Optional ISO 3166-2 region, e.g. US-CA, DE-BY, GB-SCT: adds that region's own holidays.
- `weekend` (string; one of `sat-sun`, `fri-sat`, `fri`, `sun`, `none`): Override the weekend days used by the working-day check.

Bad inputs are rejected with HTTP 400 before any payment is asked for.

## Example answer

Example only: the shape of an answer, with placeholder addresses and made-up figures. It is not data about any real token or wallet; call the service (or its free sample) for real results.

```json
{
  "country": "GB",
  "year": 2026,
  "region": "GB-SCT",
  "count": 10,
  "holidays": [
    {
      "date": "2026-12-25",
      "weekday": "Friday",
      "name": "Christmas Day",
      "localName": "Christmas Day",
      "nationwide": true,
      "regions": [],
      "types": [
        "Public"
      ]
    },
    {
      "date": "2026-12-28",
      "weekday": "Monday",
      "name": "St. Stephen's Day",
      "localName": "Boxing Day",
      "nationwide": true,
      "regions": [],
      "types": [
        "Public"
      ]
    }
  ],
  "check": {
    "date": "2026-12-28",
    "weekday": "Monday",
    "isWeekend": false,
    "isPublicHoliday": true,
    "holidays": [
      "St. Stephen's Day"
    ],
    "isWorkingDay": false,
    "nextWorkingDay": "2026-12-29",
    "regionalHolidays": []
  },
  "weekend": [
    "Saturday",
    "Sunday"
  ],
  "weekendSource": "default (Saturday–Sunday)",
  "note": "Official public holidays only; company and school closures vary.",
  "source": "Nager.Date (https://date.nager.at)"
}
```

## Related

- [GET /time/convert](/services/time-convert) ($0.001): Convert a date and time between time zones, daylight saving handled.
- [GET /weather](/services/weather) ($0.002): Weather now and forecast for any latitude/longitude on Earth: temperature, feels-like, wind, humidity, cloud, pressure, rain next hour, the next 12 hours, and d
- [GET /postcode/lookup](/services/postcode-lookup) ($0.001): Postal code to place name, region and latitude/longitude in about 60 countries (US ZIP codes, UK postcodes, Canada, Germany, France, India, Japan, Australia...)

New here? [Getting started in 60 seconds](/start). All services: [Aayat AI](/).