1gateway Time API

openapi: 3.2.0
info:
  title: 1gateway Time 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: Time
paths:
  /v1/time/convert:
    get:
      operationId: time_convert
      summary: 'Time-zone conversion: one instant in many zones, DST-aware, offsets, business…'
      description: 'Use when scheduling across time zones or turning a local time into UTC without guessing DST. Input: to (IANA zones or KST, PST, CET...), optional from (zone of a local time, default UTC), time (ISO 8601, Unix seconds, or now). Output: JSON UTC instant, Unix time, and per zone: local ISO time with offset, weekday, abbreviation, DST and business-hours flags, day difference. Example: ?time=2026-10-12T09:00&from=Asia/Seoul&to=America/New_York,Europe/London'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002000'
        protocols:
        - x402: {}
      x-x402:
        price: $0.002
        scheme: exact
        network: eip155:8453
        networks:
        - eip155:8453
        - solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
        asset: USDC
        kind: single
        source: IANA time-zone database (runtime ICU); no upstream
      parameters:
      - name: to
        in: query
        required: true
        description: 1–25 target zones, comma-separated (IANA names like Asia/Seoul, UTC, or abbreviations like KST, PST, CET)
        schema:
          type: string
          pattern: ^[A-Za-z0-9_+\-/]+(\s*,\s*[A-Za-z0-9_+\-/]+){0,24}$
          example: America/New_York,Europe/London
      - name: from
        in: query
        required: false
        description: Zone of the input local time (default UTC; ignored when time has an offset)
        schema:
          type: string
          pattern: ^[A-Za-z0-9_+\-/]+$
          default: UTC
          example: Asia/Seoul
      - name: time
        in: query
        required: false
        description: ISO 8601 date-time (2026-10-12T09:00, 2026-10-12T09:00:00+09:00), Unix seconds/ms, or now
        schema:
          type: string
          pattern: ^(now|\d{9,13}|\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?)?\s*(Z|z|[+-]\d{2}:?\d{2})?)$
          default: now
          example: 2026-10-12T09:00
      responses:
        '200':
          description: OK (payment settled). Example is a trimmed real output.
          content:
            application/json:
              schema:
                type: object
                properties:
                  input:
                    type: string
                  utc:
                    type: string
                  unix:
                    type: integer
                  from:
                    type: object
                    properties:
                      zone:
                        type: string
                      local:
                        type: string
                      date:
                        type: string
                      time:
                        type: string
                      weekday:
                        type: string
                      utcOffset:
                        type: string
                      utcOffsetMinutes:
                        type: integer
                      abbreviation:
                        type: string
                      isDst:
                        type: boolean
                      businessHours:
                        type: boolean
                  to:
                    type: array
                    items:
                      type: object
                      properties:
                        zone:
                          type: string
                        local:
                          type: string
                        date:
                          type: string
                        time:
                          type: string
                        weekday:
                          type: string
                        utcOffset:
                          type: string
                        utcOffsetMinutes:
                          type: integer
                        abbreviation:
                          type: string
                        isDst:
                          type: boolean
                        businessHours:
                          type: boolean
                        dayDiff:
                          type: integer
                        hoursAheadOfSource:
                          type: integer
                  notes:
                    type: array
                    items:
                      type: string
                required:
                - input
                - utc
                - unix
                - from
                - to
                - notes
              example:
                input: 2026-10-12T09:00
                utc: '2026-10-12T00:00:00.000Z'
                unix: 1791763200
                from:
                  zone: Asia/Seoul
                  local: '2026-10-12T09:00:00+09:00'
                  date: '2026-10-12'
                  time: 09:00:00
                  weekday: Monday
                  utcOffset: +09:00
                  utcOffsetMinutes: 540
                  abbreviation: GMT+9
                  isDst: false
                  businessHours: true
                to:
                - zone: America/New_York
                  local: '2026-10-11T20:00:00-04:00'
                  date: '2026-10-11'
                  time: '20:00:00'
                  weekday: Sunday
                  utcOffset: -04:00
                  utcOffsetMinutes: -240
                  abbreviation: EDT
                  isDst: true
                  businessHours: false
                  dayDiff: -1
                  hoursAheadOfSource: -13
                notes:
                - Uses the IANA time-zone database bundled with the runtime (ICU).
        '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
        '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
      tags:
      - Time
  /v1/time/overlap:
    get:
      operationId: time_overlap
      summary: 'Meeting time finder: working-hour overlap across time zones, ranked slots…'
      description: 'Use when scheduling a meeting across time zones. Input: zones (2-10, IANA or KST/PST/CET), date, work_start/work_end (default 09:00-18:00), include_weekends. Output: JSON overlap windows in UTC and every zone''s local time, top 3 one-hour slots ranked by distance from each zone''s day edges, partial windows when no full overlap, next DST change per zone. Example: ?zones=America/New_York,Europe/London,Asia/Seoul&date=2026-11-03'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002000'
        protocols:
        - x402: {}
      x-x402:
        price: $0.002
        scheme: exact
        network: eip155:8453
        networks:
        - eip155:8453
        - solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
        asset: USDC
        kind: single
        source: IANA time-zone database (runtime ICU); no upstream
      parameters:
      - name: zones
        in: query
        required: true
        description: 2–10 time zones, comma-separated; the first is the anchor whose local date is scanned
        schema:
          type: string
          pattern: ^[A-Za-z0-9_+\-/]+(\s*,\s*[A-Za-z0-9_+\-/]+){1,9}$
          example: America/New_York,Europe/London,Asia/Seoul
      - name: date
        in: query
        required: false
        description: Meeting date YYYY-MM-DD in the anchor zone (default today UTC)
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          example: '2026-11-03'
      - name: work_start
        in: query
        required: false
        description: Local start of working hours, HH:MM
        schema:
          type: string
          pattern: ^([01]\d|2[0-3]):[0-5]\d$
          default: 09:00
          example: 09:00
      - name: work_end
        in: query
        required: false
        description: Local end of working hours, HH:MM
        schema:
          type: string
          pattern: ^([01]\d|2[0-3]):[0-5]\d$
          default: '18:00'
          example: '18:00'
      - name: include_weekends
        in: query
        required: false
        description: Count Saturday/Sunday as working days
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          default: 'false'
          example: 'false'
      responses:
        '200':
          description: OK (payment settled). Example is a trimmed real output.
          content:
            application/json:
              schema:
                type: object
                properties:
                  date:
                    type: string
                  anchorZone:
                    type: string
                  workHours:
                    type: object
                    properties:
                      start:
                        type: string
                      end:
                        type: string
                      includeWeekends:
                        type: boolean
                  fullOverlap:
                    type: boolean
                  overlapWindows:
                    type: array
                    items:
                      type: object
                      properties:
                        startUtc:
                          type: string
                        endUtc:
                          type: string
                        minutes:
                          type: integer
                        zonesInWorkHours:
                          type: array
                          items:
                            type: string
                        local:
                          type: array
                          items:
                            type: object
                            properties:
                              zone:
                                type: string
                              start:
                                type: string
                              end:
                                type: string
                  partialWindows:
                    type: array
                    items:
                      type: object
                      properties:
                        startUtc:
                          type: string
                        endUtc:
                          type: string
                        minutes:
                          type: integer
                        zonesInWorkHours:
                          type: array
                          items:
                            type: string
                        local:
                          type: array
                          items:
                            type: object
                            properties:
                              zone:
                                type: string
                              start:
                                type: string
                              end:
                                type: string
                  bestSlots:
                    type: array
                    items:
                      type: object
                      properties:
                        startUtc:
                          type: string
                        durationMinutes:
                          type: integer
                        zonesInWorkHours:
                          type: array
                          items:
                            type: string
                        local:
                          type: array
                          items:
                            type: object
                            properties:
                              zone:
                                type: string
                              local:
                                type: string
                              weekday:
                                type: string
                  zones:
                    type: array
                    items:
                      type: object
                      properties:
                        zone:
                          type: string
                        utcOffset:
                          type: string
                        nextOffsetChange:
                          type:
                          - object
                          - 'null'
                          properties:
                            at:
                              type: string
                            fromOffsetMinutes:
                              type: integer
                            toOffsetMinutes:
                              type: integer
                  notes:
                    type: array
                    items:
                      type: string
                required:
                - date
                - anchorZone
                - workHours
                - fullOverlap
                - overlapWindows
                - partialWindows
                - bestSlots
                - zones
                - notes
              example:
                date: '2026-11-03'
                anchorZone: America/New_York
                workHours:
                  start: 09:00
                  end: '18:00'
                  includeWeekends: false
                fullOverlap: true
                overlapWindows:
                - startUtc: '2026-11-03T14:00:00.000Z'
                  endUtc: '2026-11-03T18:00:00.000Z'
                  minutes: 240
                  zonesInWorkHours:
                  - America/New_York
                  local:
                  - zone: America/New_York
                    start: '2026-11-03T09:00:00-05:00'
                    end: '2026-11-03T13:00:00-05:00'
                partialWindows: []
                bestSlots:
                - startUtc: '2026-11-03T15:30:00.000Z'
                  durationMinutes: 60
                  zonesInWorkHours:
                  - America/New_York
                  local:
                  - zone: America/New_York
                    local: '2026-11-03T10:30:00-05:00'
                    weekday: Tuesday
                zones:
                - zone: America/New_York
                  utcOffset: -05:00
                  nextOffsetChange:
                    at: '2027-03-14T07:00:00.000Z'
                    fromOffsetMinutes: -300
                    toOffsetMinutes: -240
                notes:
                - Scanned the anchor zone's (America/New_York) local day in 15-minute steps; a slot counts when it lies inside work hours in a zone's own local time.
        '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
        '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
      tags:
      - Time
  /v1/time/business-days:
    get:
      operationId: time_business_days
      summary: 'Business-day calculator: add or count working days, skipping weekends and…'
      description: 'Use when computing due dates, SLAs, settlement or delivery dates. Input: start date, then days (add -260..260 business days) or end (count business days between), optional country KR, US, GB, DE, FR or JP for public holidays (omit = weekends only). Output: JSON result date or business/calendar day counts, holidays skipped on the way, holiday scope. Example: ?start=2026-12-22&days=5&country=US'
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      x-x402:
        price: $0.003
        scheme: exact
        network: eip155:8453
        networks:
        - eip155:8453
        - solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
        asset: USDC
        kind: single
        source: Statutory holiday rules computed by 1gateway (US federal, England & Wales, DE national, FR, JP); KR from KASI via data.go.kr
      parameters:
      - name: start
        in: query
        required: true
        description: Start date YYYY-MM-DD (2004–2099)
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          example: '2026-12-22'
      - name: days
        in: query
        required: false
        description: Business days to add (negative = go back); give days or end (days wins if both)
        schema:
          type: integer
          minimum: -260
          maximum: 260
          example: 5
      - name: end
        in: query
        required: false
        description: Count business days from start (excluded) to end (included), at most 2 years apart; ignored when days is given
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          example: '2027-01-15'
      - name: country
        in: query
        required: false
        description: Public holiday calendar (omit for weekends only)
        schema:
          type: string
          enum:
          - KR
          - US
          - GB
          - DE
          - FR
          - JP
          example: US
      responses:
        '200':
          description: OK (payment settled). Example is a trimmed real output.
          content:
            application/json:
              schema:
                type: object
                properties:
                  start:
                    type: string
                  country:
                    type: string
                  mode:
                    type: string
                  days:
                    type: integer
                  resultDate:
                    type: string
                  resultWeekday:
                    type: string
                  startIsBusinessDay:
                    type: boolean
                  holidaysSkipped:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                        name:
                          type: string
                  holidayScope:
                    type: string
                  supportedCountries:
                    type: array
                    items:
                      type: string
                  notes:
                    type: array
                    items:
                      type: string
                  attribution:
                    type: string
                  end:
                    type: string
                  businessDays:
                    type: integer
                  calendarDays:
                    type: integer
                  countRule:
                    type: string
                required:
                - start
                - country
                - mode
                - holidaysSkipped
                - holidayScope
                - supportedCountries
                - notes
                - attribution
              example:
                start: '2026-12-22'
                country: US
                mode: add
                days: 5
                resultDate: '2026-12-30'
                resultWeekday: Wednesday
                startIsBusinessDay: true
                holidaysSkipped:
                - date: '2026-12-25'
                  name: Christmas Day
                holidayScope: US federal holidays (observed dates)
                supportedCountries:
                - KR
                notes:
                - Weekends are Saturday and Sunday.
                attribution: Computed by 1gateway from statutory holiday rules
        '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:
      - Time
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.