1gateway Calendar API

openapi: 3.2.0
info:
  title: 1gateway Calendar API
  version: 0.1.1
  description: '1gateway lets AI agents buy the data and APIs they need, one call at a time: no signup, no API key, paid per request with USDC on Base or Solana via x402. Coverage: company and compliance checks (sanctions, KYB, SEC filings, Korean companies), Korean real estate, trade and macro data, onchain and market data, and agent utilities such as document-to-Markdown. Every response names its source. Failed calls are never charged.'
  x-guidance: 'Use this API when an agent needs data as English JSON with pay-per-call access and no signup. Common tasks: Korea apartment sale transactions and district price summaries, Korean public holidays, Korea company KYB (company resolve, profile, NTS business status, DART filings, supplier check), Korean HWP/HWPX to Markdown, web page to Markdown (web read), and document extract (PDF, DOCX, HWP/HWPX or web page to structured JSON). Current coverage is South Korea: apartment sale prices (MOLIT), exports/imports and 10-day export flash (Korea Customs), Bank of Korea statistics (ECOS), weather forecast by lat/lon (KMA), holidays (KASI); more APIs and countries are coming. Base onchain reads: token risk, wallet balances, token info, transaction status. Also: document → Markdown conversion for web pages, PDF, DOCX and Korean HWP/HWPX (price by detected type, decided before payment). Every /v1 endpoint is paid: call it, receive HTTP 402 with PAYMENT-REQUIRED, pay with an x402 client (USDC on Base or Solana, same price) and retry. No charge on failure: settlement happens only on 2xx; 4xx/5xx are never charged. Agent guide: https://1gateway.dev/agents.md. Status: https://1gateway.dev/status. MCP (Streamable HTTP) is available at https://1gateway.dev/mcp: initialize and tools/list are free, tools/call is paid via x402 _meta.'
  contact:
    email: contact@1gateway.dev
servers:
- url: https://1gateway.dev
tags:
- name: Calendar
paths:
  /v1/calendar/holidays:
    get:
      operationId: kr_public_holidays
      summary: 'Korean public holidays for a year (KASI): South Korea holiday calendar with…'
      description: 'Use when you need South Korea''s official public holidays for a year (business-day calculation, scheduling, settlement and payroll calendars). Data: KASI (Korea Astronomy and Space Science Institute) special-day register, incl. substitute and temporary holidays once promulgated. Input: year (YYYY, 2004-2100). Output: JSON list with date, weekday, Korean and English name, isPublicHoliday, kind. Example: ?year=2026'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002700'
        protocols:
        - x402: {}
      x-x402:
        price: $0.0027
        scheme: exact
        network: eip155:8453
        networks:
        - eip155:8453
        - solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
        asset: USDC
        kind: single
        source: 'KASI via data.go.kr #15012690'
      parameters:
      - name: year
        in: query
        required: true
        description: Year YYYY (2004–2100)
        schema:
          type: integer
          minimum: 2004
          maximum: 2100
          example: 2026
      responses:
        '200':
          description: OK (payment settled). Example is a trimmed real output.
          content:
            application/json:
              schema:
                type: object
                properties:
                  year:
                    type: integer
                  country:
                    type: string
                  timezone:
                    type: string
                  count:
                    type: integer
                  publicHolidayCount:
                    type: integer
                  notes:
                    type: array
                    items:
                      type: string
                  attribution:
                    type: string
                  cache:
                    type: string
                  holidays:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                        dayOfWeek:
                          type: string
                        nameKo:
                          type: string
                        nameEn:
                          type: string
                        isPublicHoliday:
                          type: boolean
                        kind:
                          type: string
                        kindCode:
                          type: string
                required:
                - year
                - country
                - timezone
                - count
                - publicHolidayCount
                - notes
                - attribution
                - cache
                - holidays
              example:
                year: 2026
                country: KR
                timezone: Asia/Seoul
                count: 22
                publicHolidayCount: 22
                notes:
                - isPublicHoliday reflects 공공기관 휴일여부 (government office holiday). Substitute holidays appear only after official promulgation.
                attribution: 'Source: Korea Astronomy and Space Science Institute (한국천문연구원) special-day data via data.go.kr (dataset 15012690, no usage restriction). Translated by this serv…'
                cache: miss
                holidays:
                - date: '2026-01-01'
                  dayOfWeek: Thursday
                  nameKo: 1월1일
                  nameEn: New Year's Day
                  isPublicHoliday: true
                  kind: national_holiday_or_public_holiday
                  kindCode: '01'
        '400':
          description: Invalid or missing parameters, or URL/domain not allowed (validated before payment where possible; not charged)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code, e.g. bad_request, not_found, upstream_error, upstream_unreachable, upstream_not_configured
                    examples:
                    - bad_request
                  message:
                    type: string
                    description: Human-readable explanation
                    examples:
                    - month must be YYYYMM (e.g. 202409)
                required:
                - error
        '402':
          description: Payment Required (x402 v2). Returned for every unpaid request. PAYMENT-REQUIRED response header carries base64 JSON PaymentRequired; retry with PAYMENT-SIGNATURE.
        '500':
          description: Unexpected server error (not charged)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code, e.g. bad_request, not_found, upstream_error, upstream_unreachable, upstream_not_configured
                    examples:
                    - bad_request
                  message:
                    type: string
                    description: Human-readable explanation
                    examples:
                    - month must be YYYYMM (e.g. 202409)
                required:
                - error
        '502':
          description: Upstream source returned an error or an unreadable response (not charged)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code, e.g. bad_request, not_found, upstream_error, upstream_unreachable, upstream_not_configured
                    examples:
                    - bad_request
                  message:
                    type: string
                    description: Human-readable explanation
                    examples:
                    - month must be YYYYMM (e.g. 202409)
                required:
                - error
        '503':
          description: Endpoint temporarily disabled or upstream not configured on this server; no 402 is issued (not charged). Check /status, retry later
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code, e.g. bad_request, not_found, upstream_error, upstream_unreachable, upstream_not_configured
                    examples:
                    - bad_request
                  message:
                    type: string
                    description: Human-readable explanation
                    examples:
                    - month must be YYYYMM (e.g. 202409)
                required:
                - error
        '504':
          description: Upstream source timed out or was unreachable (not charged). Retry after 1-5 min with backoff
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code, e.g. bad_request, not_found, upstream_error, upstream_unreachable, upstream_not_configured
                    examples:
                    - bad_request
                  message:
                    type: string
                    description: Human-readable explanation
                    examples:
                    - month must be YYYYMM (e.g. 202409)
                required:
                - error
      tags:
      - Calendar
x-x402-network: eip155:8453
x-billing-policy: 'No charge on failure: payment is settled only after the endpoint returns a 2xx response. Any 4xx or 5xx (bad input, no data, upstream error, timeout, disabled endpoint) is not settled, so the signed payment is never collected. Input is validated before the 402 wherever possible. Over MCP, a tool result with isError is not settled either.'
x-error-codes:
- status: 400
  codes:
  - bad_request
  - url_not_allowed
  - bad_checksum
  - not_a_contract
  meaning: Invalid or missing parameters, or a URL/domain that is not allowed.
  retry: Fix the input; do not retry as is.
- status: 402
  codes: []
  meaning: Payment required (x402 v2). The PAYMENT-REQUIRED header holds the exact price.
  retry: Pay with an x402 client and retry with PAYMENT-SIGNATURE.
- status: 403
  codes:
  - not_bok_authored
  meaning: Requested table/resource is not served (e.g. statistics not authored by the Bank of Korea).
  retry: Do not retry.
- status: 404
  codes:
  - not_found
  - tx_not_found
  - tx_not_mined
  meaning: No data for the requested period/code yet.
  retry: Try an earlier period or another code.
- status: 413
  codes:
  - too_large
  meaning: Document is larger than this server's conversion cap (checked before payment).
  retry: Send a smaller document.
- status: 415
  codes:
  - unsupported_type
  - type_mismatch
  meaning: Document type not supported or not matching the declared type (before payment).
  retry: Do not retry as is.
- status: 502
  codes:
  - upstream_error
  - upstream_bad_response
  - upstream_http_error
  - rpc_unavailable
  - source_http_error
  meaning: The upstream source (government API, RPC, target site) returned an error or unreadable data.
  retry: Retry after 30-60 s with backoff.
- status: 503
  codes:
  - endpoint_disabled
  - upstream_not_configured
  - payment_not_configured
  meaning: Endpoint temporarily disabled on this server, or its upstream is not configured. No 402 is issued.
  retry: Check /status; retry later.
- status: 504
  codes:
  - upstream_unreachable
  meaning: The upstream source timed out or was unreachable (Korean public data APIs have occasional outages, esp. holidays).
  retry: Retry after 1-5 min with backoff.