Business days by country
GET /api/country-business-daysHoliday-aware business days for a country or region: check whether a date is a business day, add or subtract N business days, or count business days between two dates. Send GET /api/country-business-days with the required field country and pay $0.002 per call over x402 or MPP (there is no free tier). It returns a JSON object with country, subdivision, op, date, days and 5 more.
Uses the country's public (or bank) holidays, a published observance rule where one exists (US federal, UK substitute days, Japan substitute holidays), and a weekend you can override. ?country=US&op=add&date=2026-07-02&days=1. Holiday data by Nager.Date.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
country | string | yes | ISO 3166-1 alpha-2 country code Also accepted as countryCode, country_code, cc, iso, nation. |
subdivision | string | no | optional ISO 3166-2 region whose own holidays also close business |
op | string (one of: check, add, count) | no | check a date, add N business days, or count between from and to (default check) |
date | string | no | YYYY-MM-DD for check and add |
days | integer | no | business days to add (negative subtracts), -1000 to 1000 |
from | string | no | count: start date, counted |
to | string | no | count: end date, not counted (at most 3 years after from) |
basis | string (one of: public, bank) | no | which holidays close business (default public; bank falls back to public where none are tagged) |
weekend | string | no | optional weekend days, e.g. Fri,Sat (default Sat,Sun) |
Example request
curl -i "https://agent402.tools/api/country-business-days?country=US&op=add&date=2026-07-02&days=1"
Without payment this returns HTTP 402 Payment Required with the exact price for country-business-days; any x402 v2 or MPP client pays it and retries.
Watch a call get paid
GET /api/country-business-days$0.002 USDCPAYMENT-SIGNATUREon 14 chains200 OKAgent402-ReceiptEd25519Example response
{
"country": "US",
"subdivision": null,
"op": "add",
"date": "2026-07-02",
"days": 1,
"result": "2026-07-06",
"skipped": [
{
"date": "2026-07-03",
"reason": "holiday",
"name": "Independence Day",
"observedFrom": "2026-07-04"
},
{
"date": "2026-07-04",
"reason": "holiday",
"name": "Independence Day"
},
{
"date": "2026-07-05",
"reason": "weekend"
}
],
"basis": "public",
"weekend": [
"Sat",
"Sun"
],
"observance": {
"id": "us-federal",
"rule": "Saturday holiday observed the preceding Friday; Sunday holiday observed the following Monday",
"source": "https://www.opm.gov/policy-data-oversight/pay-leave/federal-holidays/"
}
}| Field | Type | Always present | In the example |
|---|---|---|---|
country | string | yes | US |
subdivision | null | no | null |
op | string | yes | add |
date | string | yes | 2026-07-02 |
days | number | yes | 1 |
result | string | yes | 2026-07-06 |
skipped | array of objects | yes | 3 items in the example |
basis | string | yes | public |
weekend | array of string | yes | 2 items in the example |
observance | object | yes | 3 fields: id, rule, source |
From an MCP client
catalog.call {
"slug": "country-business-days",
"params": {
"country": "US",
"op": "add",
"date": "2026-07-02",
"days": 1
}
}The hosted connector at https://agent402.tools/mcp needs a payment for country-business-days; the stdio package pays it from a wallet or from an AGENT402_CREDITS_KEY issued earlier. Local install: npx -y agent402-mcp@0.14.0.
Errors and behavior
countryis required. An input the tool rejects returns an HTTP 4xx whose body carrieserror,tool,expected,requiredandexample, so the caller can correct it.- A paid call that ends in any status of 400 or above is not charged over x402, MPP or a prepaid credits key: settlement runs after the tool and only on a successful response. The exception is a Tempo push credential, a transfer the buyer sent before the call: it settles before the tool runs, so if the tool then fails the payment is recorded as a refund owed to the paying wallet.
- Wallet-only: this tool reaches the network or stored state, so it has no proof-of-work tier. A prepaid card-credits key issued earlier (
Authorization: Bearer a402_...) also pays it. - A
POSTwith a JSON body to /api/country-business-days is served as this GET, with the body as the input. - An
Idempotency-Keyheader makes a retried paid call replay the first 200 instead of charging again (an answer larger than 1 MB is not replayed).
Paid call (JavaScript agent)
import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
const client = new x402Client();
client.setSpendControls?.({ maxAmountPerPayment: "$0.002" }); // refuse any quote above this tool's price
registerExactEvmScheme(client, { signer: privateKeyToAccount(KEY) });
const payFetch = wrapFetchWithPayment(fetch, client);
const res = await payFetch("https://agent402.tools/api/country-business-days?country=US&op=add&date=2026-07-02&days=1");Related tools
Bank holidays
Bank holidays for a country and year (optionally one region): the days the holiday dataset tags as bank holidays.
Cross-border business-day planner
First dates on or after a start date that are business days in every listed country or region at once (up to 6, e.g.
Long weekends
Long weekends in a country's year, computed from its public holidays: every run of 3 or more consecutive days off that.
Next holidays
Upcoming holidays in a country over the next 365 days, soonest first, optionally narrowed to one region and to holiday.
Public holidays
Public holidays for a country and year from an open public-holiday dataset (keyless, 100+ countries): observed date.
School holidays
School holiday days for a country and year (optionally one region): the single days the holiday dataset tags as school.