DEV Community

이창은
이창은

Posted on

Your agent doesn't know Korea's 2026 holidays. Here's a $0.003 fix over x402

#x402 #ai #api #agents

In April 2026 South Korea made two more days public holidays: Labor Day (노동절, May 1) and Constitution Day (제헌절, July 17). A model trained before that will tell you May 1 is a normal working day in Korea. It isn't anymore.

That matters the moment an agent does anything with dates: payment due dates, delivery estimates, contract deadlines, "3 business days after signing". Korea also has substitute holidays (대체공휴일) whose rules differ by holiday, plus lunar holidays (설날, 추석) that move every year. Getting this right from memory is unreliable.

So we built KoreaKit: a small API that answers these questions deterministically, with the legal basis and a data date in every response. Agents pay per call with x402 (USDC on Base). No signup, no API key.

What it answers

Is May 1, 2026 a business day in Korea?

GET https://koreakit.celee.workers.dev/v1/holidays/check?date=2026-05-01
Enter fullscreen mode Exit fullscreen mode 
{
  "date": "2026-05-01",
  "weekday": "Fri",
  "is_holiday": true,
  "is_business_day": false,
  "holidays": [{ "date": "2026-05-01", "name": "노동절", "name_en": "Labor Day", "type": "public" }],
  "meta": { "as_of": "2026-10-28", "basis": "공휴일에 관한 법률 · 관공서의 공휴일에 관한 규정 …" }
}
Enter fullscreen mode Exit fullscreen mode

Three business days after Wednesday, Sep 23, 2026? Chuseok (Sep 24–26) and the weekend get skipped:

GET /v1/business-days/add?date=2026-09-23&days=3   →   "result": "2026-09-30"
Enter fullscreen mode Exit fullscreen mode

Business days between Sep 21 and Oct 9, 2026 (both inclusive)? 15 weekdays, minus two Chuseok days, the substitute holiday for National Foundation Day (Oct 5), and Hangul Day (Oct 9):

GET /v1/business-days/count?from=2026-09-21&to=2026-10-09   →   "business_days": 11
Enter fullscreen mode Exit fullscreen mode

Other endpoints:

Endpoint What it does
/v1/holidays?year=2026 All holidays of a year (2015–2050), Korean and English names
/v1/lunar/to-solar, /v1/lunar/from-solar Korean lunar ↔ Gregorian, with 간지 names
/v1/text/amount?n=1234500 Amount in words for invoices: 금 일백이십삼만사천오백원정, 壹佰貳拾參萬肆仟伍佰
/v1/text/romanize Revised Romanization incl. sound changes (종로 → jongno)
/v1/validate/brn Business registration number (사업자등록번호) checksum

How payment works

Every endpoint is a plain GET. Without payment you get 402 Payment Required with a PAYMENT-REQUIRED header (x402 v2). Any x402 client pays and retries:

import { wrapFetchWithPaymentFromConfig } from '@x402/fetch';
import { ExactEvmScheme } from '@x402/evm';

const pay = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: 'eip155:8453', client: new ExactEvmScheme(account) }],
});
const res = await pay('https://koreakit.celee.workers.dev/v1/holidays/check?date=2026-05-01');
console.log(await res.json());
Enter fullscreen mode Exit fullscreen mode
  • Price: 0.003 USDC per call on Base mainnet.
  • Bad input is free. Parameters are validated before any payment is verified or settled, so a malformed request returns a free 400 with an error message and is never charged.
  • Discoverable: listed in the Coinbase x402 Bazaar and on Agentic.Market, with OpenAPI at /openapi.json and /llms.txt.

For humans: free calculators

The same engine powers two free pages (Korean UI):

  • Business-day calculator: N business days later, and business days in a range, showing which weekday holidays were skipped
  • Amount in words: how to read a number, the contract form 금○○원정, and 갖은자 hanja

Limits, stated plainly

  • Temporary holidays (임시공휴일) are designated ad hoc by the government. We add them when announced; nobody can predict them in advance. Every response carries as_of so you know how fresh the data is.
  • Lunar conversion follows KASI data for 1000–2050.
  • No personal data is processed.

KoreaKit is operated by WiseLake Inc. Questions or a holiday we missed: wiselake@wiselake.ai.

Top comments (0)