FiatDock Weather API

openapi: 3.2.0
info:
  title: FiatDock Weather API
  version: 1.16.1
  contact:
    name: FiatDock
    email: osama@fiatdock.com
    url: https://fiatdock.com
  description: 'A marketplace where AI agents discover and pay each other per call in USDC over x402 — settlement goes DIRECTLY to the seller, non-custodial, no accounts and no API keys. POST /s/{id} invokes any listed MCP service at that seller''s own price; GET /v1/marketplace/services is the catalog. Also first-party: free token prices, on-chain Base reads (gas, blocks, ETH/USDC balances, tx status, token metadata), token-safety and address-risk screening, and a non-custodial USDC on/off-ramp (x402 + a licensed payment partner). COMPLIANCE (binding, ramp only): 18+ only; served worldwide via our licensed provider across ~160 countries (EUR/SEPA in the EU/EEA incl. Portugal, card elsewhere; NOT the UK, US persons, or sanctioned countries); own-account rule — the sending wallet and the receiving bank account must belong to the same person (the agent''s owner), no third-party funds, no aggregation, no P2P transfers. Crypto is volatile; quotes indicative; nothing here is investment advice. RETRIES: GET endpoints are idempotent — repeat freely. Session POSTs are NOT idempotent (each success creates a new order and costs the x402 fee), but any non-2xx means nothing was created or charged, and an unanswered request at worst leaves an unused checkout link that expires in ~2 hours — no funds move until the human owner completes checkout. Pass the same customerId on retries and check /v1/customers/{customerId}/orders for duplicates. On 429, sleep Retry-After seconds.'
  termsOfService: https://fiatdock.com/terms.html
  x-guidance: 'Start FREE: GET /v1/token/price?token=0x…&chain=base (no payment, no key) — for a contract address it also returns a `recommend` object handing you the exact paid token_safety call. Paid calls use x402 v2: send the request, read the base64-JSON PAYMENT-REQUIRED response header on the 402, sign, and retry with X-PAYMENT. Nothing is charged on a 402. Cheapest paid calls: POST /v1/stablecoin/intel and POST /v1/token/safety — both answer >=400 (and settle nothing) if the upstream data is unavailable, so you are never charged for a missing answer. Everything here is also exposed as MCP tools at https://fiatdock.com/mcp (Streamable HTTP) or `npx fiatdock-mcp` (stdio, pays automatically).'
  x-agent-rules:
    neverChargedFor:
    - A 402 — that is the price quote, not a charge. Retrying is always safe.
    - Any 4xx. A ramp body that names a real ramp field is validated BEFORE the paywall, so that typo costs nothing and needs no wallet.
    - A 5xx or an upstream failure on a paid data route — x402 settles only on <400.
    beforeYouPayAnything:
    - GET /v1/quote?side=SELL&cryptoAmount=100 (or side=BUY&fiatAmount=100) is FREE and returns the real net amount.
    - 'POST the session body with no payment header. A 400 means fix the body. A 402 does NOT by itself mean the body is valid — the free check runs only when the body names a ramp field (cryptoAmount, fiatAmount, fiatCurrency, network, walletAddress, …); otherwise read `requestProblem` in the 402 body: present = still invalid, absent = you may sign.'
    inputWeAccept:
      amounts: Numbers or strings. "100,50", "1.234,56", "1,234.56", "١٠٠", "€100" are all understood.
      walletAddress: 0x + 40 hex. A bare 40-hex string (no 0x) and surrounding whitespace are accepted.
      fiatCurrency: 'ISO code, any case. "eur", "€", "euro" → EUR. 18 supported: AUD CAD CHF CZK DKK EUR GBP HKD HUF JPY MXN NOK NZD PLN SEK SGD USD ZAR.'
      network: base | ethereum | polygon | arbitrum | optimism | avalanche | bsc. Chain ids (8453, eip155:8453) and short forms (eth, arb, op, avax, bnb) also work.
      side: Exactly "SELL" or "BUY". Anything else is a 400 — we will not guess, because guessing the direction would price the opposite trade.
    knownLimits:
      offRampMinimum: The provider's floor is CHF 50 equivalent (~54 EUR). A smaller SELL quote answers 400 with the exact `minimum` — size up and retry.
      orderStatus: Orders stay SESSION_CREATED. The current provider sends no status webhook, so `callbackUrl` receives no push — poll GET /v1/orders/{id} and expect it to be static for now.
      checkoutTtl: checkoutUrl is valid ~2 hours. Forward it to the human owner promptly.
      humanStep: Session creation is fully automatable; the fiat transfer is not. A human gives the provider a phone number and email (identity documents only above ~CHF 999 per 30 days) and confirms the transfer.
    ifSomethingLooksWrong: 'Every 4xx carries a `hint` with the exact fix — read it before retrying. Live health: GET https://fiatdock.com/status. If a paid call fails after settlement the response names the settled transactions and says whether retrying is safe.'
servers:
- url: https://fiatdock.com
tags:
- name: Weather
paths:
  /v1/weather/forecast:
    post:
      operationId: weatherForecast
      description: 'Forecast for any coordinate from MET Norway''s Locationforecast 2.0 (global): the current hour (temperature, humidity, wind, cloud, next-hour rain, symbol), rows up to `hours` ahead (1 h steps ~2.5 days, then 6 h, each stating its period), and up to 9 UTC-day rows with min/max (incl. MET''s 6-hour extremes), total precipitation and the main condition. Times UTC; MET''s CC BY 4.0 attribution included. No air quality or alerts. Upstream failure is not charged. Paid $0.0018 USDC via x402. MCP tool: weather_forecast.'
      requestBody:
        required: false
        content:
          application/json:
            example:
              lat: 24.7136
              lon: 46.6753
              hours: 3
              days: 2
            schema:
              type: object
              properties:
                lat:
                  description: Latitude in decimal degrees, -90 to 90 (required with lon; an empty body answers the published example point)
                  type: number
                  minimum: -90
                  maximum: 90
                  example: 24.7136
                lon:
                  description: Longitude in decimal degrees, -180 to 180 (required with lat)
                  type: number
                  minimum: -180
                  maximum: 180
                  example: 46.6753
                hours:
                  description: How many hours ahead the `hourly` rows reach, 1-72 (default 24). Steps are 1 h for about the first 2.5 days and 6 h after
                  type: integer
                  minimum: 1
                  maximum: 72
                  example: 24
                days:
                  description: How many daily summary rows (UTC calendar days, today first), 1-9 (default 3)
                  type: integer
                  minimum: 1
                  maximum: 9
                  example: 3
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeatherForecast'
          description: Weather forecast for any point (MET Norway, 9 days)
        '400':
          description: an input the tool cannot use, or a field it does not read (not charged)
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
          description: 'x402 v2 Payment Required: the exact requirements arrive base64-JSON in the PAYMENT-REQUIRED response header (pay $0.0018 USDC on base = CAIP-2 eip155 id), then retry with the PAYMENT-SIGNATURE header (x402 v2; the v1 name X-PAYMENT is also accepted). Nothing is charged on a 402 — retrying is always safe.'
        '404':
          description: nothing to answer for this input — e.g. an unknown coin, currency, ticker or token, or a search with no match (not charged)
        '429':
          description: Rate limited (global 120/min/IP; stricter buckets on /mcp, webhook, auth). Sleep exactly Retry-After seconds, then retry.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds until the window resets — sleep this long, then retry
            RateLimit-Limit:
              schema:
                type: integer
              description: Requests allowed per window in this bucket
            RateLimit-Remaining:
              schema:
                type: integer
              description: Requests left in the current window (0 on 429)
            RateLimit-Reset:
              schema:
                type: integer
              description: Seconds until the window resets
        '502':
          description: the upstream source did not answer (not charged)
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.001800'
        protocols:
        - x402: {}
      tags:
      - Weather
      summary: Weather forecast
      x-summary-source: derived
    get:
      operationId: weatherForecastGet
      description: 'Forecast for any coordinate from MET Norway''s Locationforecast 2.0 (global): the current hour (temperature, humidity, wind, cloud, next-hour rain, symbol), rows up to `hours` ahead (1 h steps ~2.5 days, then 6 h, each stating its period), and up to 9 UTC-day rows with min/max (incl. MET''s 6-hour extremes), total precipitation and the main condition. Times UTC; MET''s CC BY 4.0 attribution included. No air quality or alerts. Upstream failure is not charged. Paid $0.0018 USDC via x402. MCP tool: weather_forecast. Also payable with GET: send the same inputs as query parameters (ADR-0175).'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeatherForecast'
          description: Weather forecast for any point (MET Norway, 9 days)
        '400':
          description: an input the tool cannot use, or a field it does not read (not charged)
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
          description: 'x402 v2 Payment Required: the exact requirements arrive base64-JSON in the PAYMENT-REQUIRED response header (pay $0.0018 USDC on base = CAIP-2 eip155 id), then retry with the PAYMENT-SIGNATURE header (x402 v2; the v1 name X-PAYMENT is also accepted). Nothing is charged on a 402 — retrying is always safe.'
        '404':
          description: nothing to answer for this input — e.g. an unknown coin, currency, ticker or token, or a search with no match (not charged)
        '429':
          description: Rate limited (global 120/min/IP; stricter buckets on /mcp, webhook, auth). Sleep exactly Retry-After seconds, then retry.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds until the window resets — sleep this long, then retry
            RateLimit-Limit:
              schema:
                type: integer
              description: Requests allowed per window in this bucket
            RateLimit-Remaining:
              schema:
                type: integer
              description: Requests left in the current window (0 on 429)
            RateLimit-Reset:
              schema:
                type: integer
              description: Seconds until the window resets
        '502':
          description: the upstream source did not answer (not charged)
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.001800'
        protocols:
        - x402: {}
      parameters:
      - name: lat
        in: query
        required: false
        schema:
          type: number
        description: Latitude in decimal degrees, -90 to 90 (required with lon; an empty body answers the published example point)
      - name: lon
        in: query
        required: false
        schema:
          type: number
        description: Longitude in decimal degrees, -180 to 180 (required with lat)
      - name: hours
        in: query
        required: false
        schema:
          type: integer
        description: How many hours ahead the `hourly` rows reach, 1-72 (default 24). Steps are 1 h for about the first 2.5 days and 6 h after
      - name: days
        in: query
        required: false
        schema:
          type: integer
        description: How many daily summary rows (UTC calendar days, today first), 1-9 (default 3)
      tags:
      - Weather
      summary: Weather forecast get
      x-summary-source: derived
components:
  schemas:
    PaymentRequired:
      type: object
      description: The 402 body (ADR-0045). Nothing is charged and nothing is created on a 402 — retrying is always safe.
      properties:
        error:
          type: string
        priceUsd:
          type: number
          description: Price in dollars. Present on single-leg challenges; multi-leg challenges omit it — read `accepts`.
        accepts:
          type: array
          description: The exact payment terms to sign, mirrored from the PAYMENT-REQUIRED header.
          items:
            type: object
        hint:
          type: string
          description: How to pay, and what to do if you have no wallet.
        docs:
          type: string
      required:
      - error
      - accepts
      - hint
    WeatherForecast:
      type: object
      description: Paid. Weather forecast for any point (MET Norway, 9 days).
      properties:
        location:
          type: object
          properties:
            lat:
              type: number
            lon:
              type: number
            elevationM:
              type:
              - number
              - 'null'
          required:
          - lat
          - lon
          - elevationM
          description: The point forecast (rounded to 4 decimals) and its elevation above sea level as MET models it
        current:
          type: object
          properties:
            time:
              type: string
            airTemperatureC:
              type:
              - number
              - 'null'
            relativeHumidityPct:
              type:
              - number
              - 'null'
            windSpeedMs:
              type:
              - number
              - 'null'
            windFromDeg:
              type:
              - number
              - 'null'
            cloudCoverPct:
              type:
              - number
              - 'null'
            precipitationNext1hMm:
              type:
              - number
              - 'null'
            symbol:
              type:
              - string
              - 'null'
          required:
          - time
          - airTemperatureC
          - relativeHumidityPct
          - windSpeedMs
          - windFromDeg
          - cloudCoverPct
          - precipitationNext1hMm
          - symbol
          description: The forecast for the hour now falls in (a forecast, not an observation)
        hourly:
          type: array
          items:
            type: object
            properties:
              time:
                type: string
                description: Start of the period (UTC, ISO 8601)
              airTemperatureC:
                type:
                - number
                - 'null'
              precipitationMm:
                type:
                - number
                - 'null'
                description: Precipitation over the next periodHours hours
              periodHours:
                type:
                - number
                - 'null'
                description: '1 or 6: the period precipitationMm and symbol cover; null when MET gives none for this row'
              windSpeedMs:
                type:
                - number
                - 'null'
              symbol:
                type:
                - string
                - 'null'
                description: MET weather symbol code for the period, e.g. partlycloudy_day
            required:
            - time
            - airTemperatureC
            - precipitationMm
            - periodHours
            - windSpeedMs
            - symbol
          description: 'Forecast rows from now for `hours` hours: 1-hour steps for about 2.5 days, then 6-hour steps'
        daily:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                description: UTC calendar date (YYYY-MM-DD)
              minTempC:
                type:
                - number
                - 'null'
              maxTempC:
                type:
                - number
                - 'null'
              precipitationMm:
                type:
                - number
                - 'null'
                description: Total over the covered hours; null if a period had no amount
              hoursCovered:
                type: number
                description: Hours of this UTC day the forecast covers (the first day starts now)
              symbol:
                type:
                - string
                - 'null'
                description: The condition covering the most hours, without its _day/_night variant
            required:
            - date
            - minTempC
            - maxTempC
            - precipitationMm
            - hoursCovered
            - symbol
          description: 'One row per UTC day, today first: min/max temperature, total precipitation, main condition'
        units:
          type: object
          properties:
            airTemperature:
              type: string
            precipitation:
              type: string
            windSpeed:
              type: string
            windFromDirection:
              type: string
            relativeHumidity:
              type: string
            cloudCover:
              type: string
          required:
          - airTemperature
          - precipitation
          - windSpeed
          - windFromDirection
          - relativeHumidity
          - cloudCover
          description: The unit of every number
        modelUpdatedAt:
          type:
          - string
          - 'null'
          description: When MET last updated this forecast (meta.updated_at)
        forecastEndsAt:
          type: string
          description: The last forecast time MET publishes for this point (about 9-10 days ahead)
        attribution:
          type: string
          description: The credit MET Norway's licence (CC BY 4.0 / NLOD 2.0) requires — keep it beside any use of the data
        source:
          type: string
          description: Where the data came from
        asOf:
          type: string
          description: ISO time the forecast was read from MET (or revalidated as unchanged)
        note:
          type: string
          description: How to read the rows (UTC times, step lengths, daily rules) and their limits
        defaulted:
          type: object
          properties:
            field:
              type: string
            to:
              type: string
            value:
              type: string
            note:
              type: string
          required:
          - field
          - to
          - value
          - note
          description: 'Present only when the body was empty: which point the answer is for, and why'
      required:
      - location
      - current
      - hourly
      - daily
      - units
      - modelUpdatedAt
      - forecastEndsAt
      - attribution
      - source
      - asOf
      - note
externalDocs:
  description: Agent skill file — what to run before acting on a token, an address or a counterparty (text/markdown, live prices and catalog)
  url: https://fiatdock.com/skill.md
x-payment-protocol:
  protocol: x402
  version: 2
  network: base
  asset: USDC
  payTo: '0xeB12bB2f52EeD33DBa6A00774E48324032Fd87C6'
  mode: per-call
  paid:
  - path: /v1/offramp/session
    method: POST
    priceUsd: 0.01
  - path: /v1/onramp/session
    method: POST
    priceUsd: 0.01
  - path: /v1/token/safety
    method: POST
    priceUsd: 0.0045
  - path: /v1/stablecoin/intel
    method: POST
    priceUsd: 0.002
  - path: /v1/chain/token-metadata
    method: POST
    priceUsd: 0.002
  - path: /v1/chain/gas-price
    method: POST
    priceUsd: 0.001
  - path: /v1/chain/block
    method: POST
    priceUsd: 0.001
  - path: /v1/chain/eth-balance
    method: POST
    priceUsd: 0.001
  - path: /v1/chain/usdc-balance
    method: POST
    priceUsd: 0.001
  - path: /v1/chain/tx-status
    method: POST
    priceUsd: 0.001
  - path: /v1/chain/address-intel
    method: POST
    priceUsd: 0.0045
  - path: /v1/chain/token-report
    method: POST
    priceUsd: 0.0045
  - path: /v1/web/read
    method: POST
    priceUsd: 0.0018
  - path: /v1/email/check
    method: POST
    priceUsd: 0.001
  - path: /v1/market/perp
    method: POST
    priceUsd: 0.001
  - path: /v1/markets/prediction
    method: POST
    priceUsd: 0.0045
  - path: /v1/defi/yields
    method: POST
    priceUsd: 0.001
  - path: /v1/fx/rates
    method: POST
    priceUsd: 0.001
  - path: /v1/chain/portfolio
    method: POST
    priceUsd: 0.0045
  - path: /v1/token/holders
    method: POST
    priceUsd: 0.0027
  - path: /v1/domain/intel
    method: POST
    priceUsd: 0.0045
  - path: /v1/web/contacts
    method: POST
    priceUsd: 0.0027
  - path: /v1/news/crypto
    method: POST
    priceUsd: 0.001
  - path: /v1/sec/filings
    method: POST
    priceUsd: 0.0027
  - path: /v1/text/prompt-check
    method: POST
    priceUsd: 0.0045
  - path: /v1/token/screener
    method: POST
    priceUsd: 0.009
  - path: /v1/papers/search
    method: POST
    priceUsd: 0.009
  - path: /v1/geo/satellite
    method: POST
    priceUsd: 0.009
  - path: /v1/web/seo-audit
    method: POST
    priceUsd: 0.009
  - path: /v1/x402/top
    method: POST
    priceUsd: 0.009
  - path: /v1/chain/ens
    method: POST
    priceUsd: 0.0027
  - path: /v1/time/convert
    method: POST
    priceUsd: 0.001
  - path: /v1/calendar/holidays
    method: POST
    priceUsd: 0.001
  - path: /v1/weather/forecast
    method: POST
    priceUsd: 0.0018
  - path: /v1/wiki/summary
    method: POST
    priceUsd: 0.0018
  - path: /v1/news/hackernews
    method: POST
    priceUsd: 0.0027
  - path: /v1/feed/read
    method: POST
    priceUsd: 0.0022
  - path: /v1/dev/package
    method: POST
    priceUsd: 0.0027
  - path: /v1/sec/financials
    method: POST
    priceUsd: 0.0045
  - path: /v1/token/verdict
    method: POST
    priceUsd: 0.009
  - path: /v1/market/backtest
    method: POST
    priceUsd: 0.009
  - path: /s/{id}
    method: POST
    priceUsd: null
    note: per-listing price; the 402 is authoritative
  free:
  - /v1/quote
  - /v1/token/price
  - /v1/orders/{partnerOrderId}
  - /v1/marketplace/services
  - /v1/marketplace/services/{id}
  - /v1/marketplace/demand
  - /v1/x402/search
  relay:
  - path: /v1/x402/call
    method: POST
    priceUsd: null
    note: carries the caller's PAYMENT-SIGNATURE to an index-listed x402 endpoint; that endpoint's 402 is authoritative and its payTo receives the money — FiatDock charges nothing here