openapi: 3.2.0
info:
  title: 2s — the (most) everything Energy API
  version: '1'
  summary: The (most) everything API.
  description: 'The (most) everything API for AI agents: 575+ pay-per-call endpoints on one origin.'
  contact:
    name: 2s
    url: https://2s.io
    email: alley@2s.io
  x-logo:
    url: https://2s.io/icon-512.png
    altText: 2s
  x-guidance: 'Pay-per-call REST API for AI agents — hundreds of endpoints returning ground-truth data (US public records, company & legal identifiers, finance/SEC, crypto/web3, security & CVEs, medical codes, weather & geocoding, agriculture, energy, maritime, music, and more). Every endpoint is paid per call in USDC via x402 (Base or Solana) — no API key, no signup. Call any endpoint with no auth to get a 402 PaymentRequirements envelope, sign it (EIP-3009 on Base, partial SPL transfer on Solana), and retry with the PAYMENT-SIGNATURE header. Add ?trial=1 for one free real call per endpoint per hour to test before paying. To discover the right endpoint: GET https://2s.io/api/directory for the full catalog, or GET https://2s.io/api/search/endpoints?q=<natural-language task> for a ranked match. Per-call price is on each operation as x-payment-info (from $0.001). Batch up to 50 calls behind one payment via POST https://2s.io/api/batch/run.'
servers:
- url: https://2s.io
tags:
- name: Energy
paths:
  /api/energy/carbon-intensity-uk:
    get:
      tags:
      - Energy
      summary: Great Britain electricity grid carbon intensity (current
      description: Great Britain electricity grid carbon intensity (current half-hour) from National Grid ESO. Returns the forecast and actual carbon intensity in grams of CO2 per kWh, the qualitative index (very low / low / moderate / high / very high), and the live generation mix by fuel (gas, wind, nuclear, solar, imports, etc.). Free, CC BY / Open Government Licence. Live grid-decarbonisation signal an LLM cannot recall — for energy, sustainability, and demand-shifting agents. Complements our US energy.* set.
      operationId: energy_carbon-intensity-uk
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [one current intensity + mix snapshot]; total = 1.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            period:
                              type: object
                              properties:
                                from:
                                  type: string
                                  nullable: true
                                to:
                                  type: string
                                  nullable: true
                              required:
                              - from
                              - to
                              additionalProperties: false
                            intensity:
                              type: object
                              properties:
                                forecastGCO2PerKWh:
                                  type: number
                                  nullable: true
                                actualGCO2PerKWh:
                                  type: number
                                  nullable: true
                                index:
                                  type: string
                                  nullable: true
                              required:
                              - forecastGCO2PerKWh
                              - actualGCO2PerKWh
                              - index
                              additionalProperties: false
                            generationMix:
                              type: array
                              items:
                                type: object
                                properties:
                                  fuel:
                                    type: string
                                  percent:
                                    type: number
                                required:
                                - fuel
                                - percent
                                additionalProperties: false
                            source:
                              $ref: '#/components/schemas/Source'
                            note:
                              type: string
                          required:
                          - period
                          - intensity
                          - generationMix
                          - source
                          - note
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: energy.carbon-intensity-uk
      x-2s-version: null
      x-2s-price:
        usd: 0.0025
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002500'
        protocols:
        - x402: {}
      parameters:
      - $ref: '#/components/parameters/TrialMode'
  /api/energy/electricity-rates:
    get:
      tags:
      - Energy
      summary: Retail electricity price and sales for a US state by
      description: Retail electricity price and sales for a US state by customer sector (residential, commercial, industrial, transportation, all), monthly, newest first, from EIA. Returns average price (cents/kWh), sales (MWh), revenue ($M), and customer count per month. Public-domain, live-wrap. More granular than energy.prices (which is the national all-sector benchmark only).
      operationId: energy_electricity-rates
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = monthly retail-rate rows (newest first); total = month count; meta carries state + sector.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            period:
                              type: string
                              nullable: true
                            priceCentsPerKWh:
                              type: number
                              nullable: true
                            salesMWh:
                              type: number
                              nullable: true
                            revenueMillionUSD:
                              type: number
                              nullable: true
                            customers:
                              type: number
                              nullable: true
                          required:
                          - period
                          - priceCentsPerKWh
                          - salesMWh
                          - revenueMillionUSD
                          - customers
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          state:
                            type: string
                          sector:
                            type: string
                        required:
                        - state
                        - sector
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: energy.electricity-rates
      x-2s-version: null
      x-2s-price:
        usd: 0.0025
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002500'
        protocols:
        - x402: {}
      parameters:
      - name: state
        in: query
        required: true
        description: US state — two-letter postal abbreviation (e.g. CA) or full name.
        schema:
          type: string
          minLength: 2
          maxLength: 2
      - name: sector
        in: query
        required: false
        description: Sector.
        schema:
          type: string
          enum:
          - residential
          - commercial
          - industrial
          - transportation
          - all
      - name: months
        in: query
        required: false
        description: Months.
        schema:
          type: integer
          minimum: 1
          maximum: 120
      - $ref: '#/components/parameters/TrialMode'
  /api/energy/fuel-stations:
    get:
      tags:
      - Energy
      summary: Locate alternative-fuel stations across the US via NREL
      description: Locate alternative-fuel stations across the US via NREL Alternative Fuels Data Center. Search by lat/lon + radius (miles), state, or zip. Filter by fuelType (BD=Biodiesel | CNG=Compressed Natural Gas | ELEC=Electric vehicle charging | E85=Ethanol | HY=Hydrogen | LNG=Liquefied Natural Gas | LPG=Propane | RD=Renewable Diesel), status (E=Available | P=Planned | T=Temporarily Unavailable), access (public/private), and EV network. For EV chargers, returns connector types (J1772, CHAdeMO, Tesla, etc.), Level 1/2/DC-fast counts, pricing, and access hours. Indispensable for trip-planning agents, fleet logistics, EV-adoption analysis.
      operationId: energy_fuel-stations
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = matched alternative-fuel stations; total = upstream total result count; meta.stationLocatorUrl = AFDC map link.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: AFDC station id.
                            name:
                              type: string
                              nullable: true
                            fuelType:
                              type: string
                              nullable: true
                              description: BD | CNG | ELEC | E85 | HY | LNG | LPG | RD.
                            status:
                              type: string
                              nullable: true
                              description: E=Available, P=Planned, T=Temporarily Unavailable.
                            access:
                              type: string
                              nullable: true
                              description: public | private.
                            accessDaysTime:
                              type: string
                              nullable: true
                            address:
                              type: object
                              properties:
                                street:
                                  type: string
                                  nullable: true
                                city:
                                  type: string
                                  nullable: true
                                state:
                                  type: string
                                  nullable: true
                                zip:
                                  type: string
                                  nullable: true
                                country:
                                  type: string
                                  nullable: true
                              required:
                              - street
                              - city
                              - state
                              - zip
                              - country
                              additionalProperties: false
                            lat:
                              type: number
                              nullable: true
                            lon:
                              type: number
                              nullable: true
                            phone:
                              type: string
                              nullable: true
                            groupsWithAccess:
                              type: string
                              nullable: true
                            cardsAccepted:
                              type: string
                              nullable: true
                            evNetwork:
                              type: string
                              nullable: true
                            evNetworkWeb:
                              type: string
                              nullable: true
                            evConnectorTypes:
                              type: array
                              items:
                                type: string
                              description: J1772, CHAdeMO, TESLA, etc. Empty for non-EV stations.
                            evDcFastNum:
                              type: number
                              nullable: true
                            evLevel2EvseNum:
                              type: number
                              nullable: true
                            evLevel1EvseNum:
                              type: number
                              nullable: true
                            evPricing:
                              type: string
                              nullable: true
                            distanceMiles:
                              type: number
                              nullable: true
                              description: Distance from the query point; null for state/zip searches.
                            updatedAt:
                              type: string
                              nullable: true
                          required:
                          - id
                          - name
                          - fuelType
                          - status
                          - access
                          - accessDaysTime
                          - address
                          - lat
                          - lon
                          - phone
                          - groupsWithAccess
                          - cardsAccepted
                          - evNetwork
                          - evNetworkWeb
                          - evConnectorTypes
                          - evDcFastNum
                          - evLevel2EvseNum
                          - evLevel1EvseNum
                          - evPricing
                          - distanceMiles
                          - updatedAt
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          stationLocatorUrl:
                            type: string
                            nullable: true
                        required:
                        - stationLocatorUrl
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: energy.fuel-stations
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: lat
        in: query
        required: false
        description: Latitude in decimal degrees (WGS84).
        schema:
          type: number
          minimum: -90
          maximum: 90
      - name: lon
        in: query
        required: false
        description: Longitude in decimal degrees (WGS84).
        schema:
          type: number
          minimum: -180
          maximum: 180
      - name: radius
        in: query
        required: false
        description: Search radius around the given point.
        schema:
          type: number
          minimum: 0.1
          maximum: 500
      - name: fuelType
        in: query
        required: false
        description: Fuel type.
        schema:
          type: string
      - name: state
        in: query
        required: false
        description: US state — two-letter postal abbreviation (e.g. CA) or full name.
        schema:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Za-z]{2}$
      - name: zip
        in: query
        required: false
        description: US ZIP code.
        schema:
          type: string
          pattern: ^\d{5}$
      - name: status
        in: query
        required: false
        description: Filter results by status.
        schema:
          type: string
          enum:
          - all
          - E
          - P
          - T
      - name: accessCode
        in: query
        required: false
        description: Access code.
        schema:
          type: string
          enum:
          - all
          - public
          - private
      - name: network
        in: query
        required: false
        description: Network.
        schema:
          type: string
          minLength: 1
          maxLength: 80
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 25
      - $ref: '#/components/parameters/TrialMode'
  /api/energy/generation-mix:
    get:
      tags:
      - Energy
      summary: Electricity generation mix by fuel type for a US state
      description: Electricity generation mix by fuel type for a US state (2-letter) or "US", from EIA — the most recent monthly net generation (thousand MWh) broken out by fuel (natural gas, coal, nuclear, solar, wind, hydro, etc.) with each fuel's percent share and the all-fuels total. Public-domain, live-wrap. Use for grid carbon-intensity, decarbonization, and energy-policy reasoning. (For benchmark energy prices use energy.prices; for retail electricity rates by state/sector use energy.electricity-rates.)
      operationId: energy_generation-mix
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [one generation mix for the location/latest month]; total = 1.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            location:
                              type: string
                            period:
                              type: string
                              nullable: true
                            units:
                              type: string
                            totalThousandMWh:
                              type: number
                              nullable: true
                            fuels:
                              type: array
                              items:
                                type: object
                                properties:
                                  fuelTypeId:
                                    type: string
                                  fuelType:
                                    type: string
                                    nullable: true
                                  generationThousandMWh:
                                    type: number
                                    nullable: true
                                  sharePct:
                                    type: number
                                    nullable: true
                                required:
                                - fuelTypeId
                                - fuelType
                                - generationThousandMWh
                                - sharePct
                                additionalProperties: false
                          required:
                          - location
                          - period
                          - units
                          - totalThousandMWh
                          - fuels
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: energy.generation-mix
      x-2s-version: null
      x-2s-price:
        usd: 0.0025
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002500'
        protocols:
        - x402: {}
      parameters:
      - name: location
        in: query
        required: true
        description: Location.
        schema:
          type: string
          minLength: 2
          maxLength: 3
      - $ref: '#/components/parameters/TrialMode'
  /api/energy/prices:
    get:
      tags:
      - Energy
      summary: US energy benchmark prices from the EIA (Energy Information
      description: 'US energy benchmark prices from the EIA (Energy Information Administration) open data API. Omit series for a one-call snapshot of the latest value of every benchmark; pass series for its recent time series (newest first). Benchmarks: wti_crude / brent_crude ($/barrel), henry_hub_gas ($/MMBtu), gasoline_regular / diesel ($/gallon), electricity_retail (cents/kWh). Each observation has date, value, units, and frequency. Public-domain US government data.'
      operationId: energy_prices
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = energy-price observations (snapshot = latest per benchmark; series = recent observations newest-first); meta.mode + meta.query describe the request.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            series:
                              type: string
                            label:
                              type: string
                            date:
                              type: string
                              nullable: true
                            value:
                              type: number
                              nullable: true
                            units:
                              type: string
                            frequency:
                              type: string
                          required:
                          - series
                          - label
                          - date
                          - value
                          - units
                          - frequency
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                      meta:
                        type: object
                        properties:
                          mode:
                            type: string
                            enum:
                            - snapshot
                            - series
                          query:
                            type: object
                            properties:
                              series:
                                type: string
                                nullable: true
                              limit:
                                type: integer
                            required:
                            - series
                            - limit
                            additionalProperties: false
                        required:
                        - mode
                        - query
                        additionalProperties: false
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: energy.prices
      x-2s-version: null
      x-2s-price:
        usd: 0.0072
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.007200'
        protocols:
        - x402: {}
      parameters:
      - name: series
        in: query
        required: false
        description: 'Optional benchmark id. Omit for a snapshot of all benchmarks. One of: wti_crude, brent_crude, henry_hub_gas, gasoline_regular, diesel, electricity_retail.'
        schema:
          type: string
          enum:
          - wti_crude
          - brent_crude
          - henry_hub_gas
          - gasoline_regular
          - diesel
          - electricity_retail
      - name: limit
        in: query
        required: false
        description: Observations to return in single-series mode (1-100). Default 12. Ignored in snapshot mode.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 12
      - $ref: '#/components/parameters/TrialMode'
  /api/energy/solar-forecast:
    get:
      tags:
      - Energy
      summary: Solar irradiance + PV-yield forecast for any coordinate
      description: 'Solar irradiance + PV-yield forecast for any coordinate (free/keyless, global). Returns a daily 1-16 day forecast: GHI (kWh/m²), peak sun hours, sunshine hours, and estimated yield per kWp of panels (at a 0.75 performance ratio). For rooftop-solar planning, agrivoltaics, and EV-charge scheduling. Complements energy.solar-resource (NREL long-run averages, US).'
      operationId: energy_solar-forecast
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized: items = [{ location + daily solar forecast }].'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            latitude:
                              type: number
                            longitude:
                              type: number
                            timezone:
                              type: string
                              nullable: true
                            performanceRatio:
                              type: number
                            days:
                              type: array
                              items:
                                type: object
                                properties:
                                  date:
                                    type: string
                                  ghiKwhPerM2:
                                    type: number
                                    nullable: true
                                  peakSunHours:
                                    type: number
                                    nullable: true
                                  sunshineHours:
                                    type: number
                                    nullable: true
                                  estYieldKwhPerKwp:
                                    type: number
                                    nullable: true
                                required:
                                - date
                                - ghiKwhPerM2
                                - peakSunHours
                                - sunshineHours
                                - estYieldKwhPerKwp
                                additionalProperties: false
                          required:
                          - latitude
                          - longitude
                          - timezone
                          - performanceRatio
                          - days
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: energy.solar-forecast
      x-2s-version: null
      x-2s-price:
        usd: 0.0036
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003600'
        protocols:
        - x402: {}
      parameters:
      - name: latitude
        in: query
        required: true
        description: Latitude in decimal degrees (WGS84).
        schema:
          type: number
          minimum: -90
          maximum: 90
      - name: longitude
        in: query
        required: true
        description: Longitude in decimal degrees (WGS84).
        schema:
          type: number
          minimum: -180
          maximum: 180
      - name: days
        in: query
        required: false
        description: Look-back window, in days.
        schema:
          type: integer
          minimum: 1
          maximum: 16
      - $ref: '#/components/parameters/TrialMode'
  /api/energy/solar-resource:
    get:
      tags:
      - Energy
      summary: Get average solar resource estimates for any
      description: 'Get average solar resource estimates for any latitude/longitude via NREL. Returns annual + monthly averages for: Direct Normal Irradiance (DNI, kWh/m²/day — solar concentrators), Global Horizontal Irradiance (GHI, kWh/m²/day — flat-plate panels), and Tilted-At-Latitude irradiance (optimal fixed-panel orientation). Sourced from NREL National Solar Radiation Database (NSRDB). Useful for rooftop solar feasibility, off-grid design, and renewable-energy modeling.'
      operationId: energy_solar-resource
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [one solar-resource reading for the point] (annual + monthly DNI/GHI/tilted irradiance); total = 1.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            lat:
                              type: number
                            lon:
                              type: number
                            outputs:
                              type: object
                              properties:
                                directNormalIrradianceKWhM2Day:
                                  type: object
                                  properties:
                                    annual:
                                      type: number
                                      nullable: true
                                    monthly:
                                      type: object
                                      additionalProperties:
                                        type: number
                                  required:
                                  - annual
                                  - monthly
                                  additionalProperties: false
                                globalHorizontalIrradianceKWhM2Day:
                                  type: object
                                  properties:
                                    annual:
                                      type: number
                                      nullable: true
                                    monthly:
                                      type: object
                                      additionalProperties:
                                        type: number
                                  required:
                                  - annual
                                  - monthly
                                  additionalProperties: false
                                tiltedAtLatitudeKWhM2Day:
                                  type: object
                                  properties:
                                    annual:
                                      type: number
                                      nullable: true
                                    monthly:
                                      type: object
                                      additionalProperties:
                                        type: number
                                  required:
                                  - annual
                                  - monthly
                                  additionalProperties: false
                              required:
                              - directNormalIrradianceKWhM2Day
                              - globalHorizontalIrradianceKWhM2Day
                              - tiltedAtLatitudeKWhM2Day
                              additionalProperties: false
                            sources:
                              type: array
                              items:
                                type: string
                            warnings:
                              type: array
                              items:
                                type: string
                          required:
                          - lat
                          - lon
                          - outputs
                          - sources
                          - warnings
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: energy.solar-resource
      x-2s-version: null
      x-2s-price:
        usd: 0.003
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.003000'
        protocols:
        - x402: {}
      parameters:
      - name: lat
        in: query
        required: true
        description: Latitude in decimal degrees (WGS84).
        schema:
          type: number
          minimum: -90
          maximum: 90
      - name: lon
        in: query
        required: true
        description: Longitude in decimal degrees (WGS84).
        schema:
          type: number
          minimum: -180
          maximum: 180
      - $ref: '#/components/parameters/TrialMode'
  /api/energy/utility-rates:
    get:
      tags:
      - Energy
      summary: Which electric utility serves a US latitude/longitude, and
      description: Which electric utility serves a US latitude/longitude, and a summary of its published rate plans, from the OpenEI Utility Rate Database (URDB, CC0). Each plan returns the utility, rate name, customer sector, EIA utility id, fixed monthly charge, the first-tier energy rate ($/kWh), and a link to the full tariff. Use for solar/EV/storage economics, bill estimation, and "who is my utility" lookups. (For average state retail prices use energy.electricity-rates.)
      operationId: energy_utility-rates
      deprecated: false
      security:
      - x402Payment: []
      responses:
        '200':
          description: 'Normalized envelope: items = [serving utilities + rate-plan summaries for the point]; total = 1.'
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: object
                    properties:
                      ok:
                        type: boolean
                        enum:
                        - true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            lat:
                              type: number
                            lon:
                              type: number
                            utilities:
                              type: array
                              items:
                                type: string
                            plans:
                              type: array
                              items:
                                type: object
                                properties:
                                  rateName:
                                    type: string
                                    nullable: true
                                  utility:
                                    type: string
                                    nullable: true
                                  sector:
                                    type: string
                                    nullable: true
                                  eiaId:
                                    type: string
                                    nullable: true
                                  fixedChargeAmount:
                                    type: number
                                    nullable: true
                                  fixedChargeUnits:
                                    type: string
                                    nullable: true
                                  energyRateUSDPerKWh:
                                    type: number
                                    nullable: true
                                  effectiveDate:
                                    type: string
                                    nullable: true
                                  uri:
                                    type: string
                                    nullable: true
                                required:
                                - rateName
                                - utility
                                - sector
                                - eiaId
                                - fixedChargeAmount
                                - fixedChargeUnits
                                - energyRateUSDPerKWh
                                - effectiveDate
                                - uri
                                additionalProperties: false
                          required:
                          - lat
                          - lon
                          - utilities
                          - plans
                          additionalProperties: false
                      total:
                        type: integer
                        nullable: true
                        description: Total matching rows upstream; null when unknown.
                      source:
                        $ref: '#/components/schemas/Source'
                    required:
                    - ok
                    - items
                    - total
                    - source
                    additionalProperties: false
                  meta:
                    $ref: '#/components/schemas/CallMeta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '500':
          $ref: '#/components/responses/ServerError'
        '502':
          $ref: '#/components/responses/UpstreamError'
      x-2s-id: energy.utility-rates
      x-2s-version: null
      x-2s-price:
        usd: 0.0025
      x-2s-accepts:
      - x402
      x-2s-response-shape: normalized
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: '0.002500'
        protocols:
        - x402: {}
      parameters:
      - name: lat
        in: query
        required: true
        description: Latitude in decimal degrees (WGS84).
        schema:
          type: number
          minimum: -90
          maximum: 90
      - name: lon
        in: query
        required: true
        description: Longitude in decimal degrees (WGS84).
        schema:
          type: number
          minimum: -180
          maximum: 180
      - name: limit
        in: query
        required: false
        description: Maximum number of results to return.
        schema:
          type: integer
          minimum: 1
          maximum: 25
      - $ref: '#/components/parameters/TrialMode'
components:
  schemas:
    Source:
      type: object
      description: 'Provenance of the data: upstream provider, source URL, and license.'
      properties:
        provider:
          type: string
          description: Upstream data provider.
        url:
          type: string
          description: Source URL or documentation link.
        license:
          type: string
          description: License / usage terms for the data.
    CallMeta:
      type: object
      description: Per-call meta envelope — endpoint id, cost, caller kind, settlement details.
    X402PaymentRequiredV2:
      type: object
      description: x402 v2 PaymentRequired envelope. Pick any entry from accepts[], sign for that rail, retry with the PAYMENT-SIGNATURE header.
      required:
      - x402Version
      - accepts
      properties:
        x402Version:
          type: integer
          const: 2
        error:
          type: string
          description: Human-readable reason payment is required.
        resource:
          type: string
          description: The resource URL being purchased.
        accepts:
          type: array
          description: Payment requirement options, one per supported network (Base USDC, Solana USDC).
          items:
            type: object
            required:
            - scheme
            - network
            - amount
            - asset
            - payTo
            - maxTimeoutSeconds
            properties:
              scheme:
                type: string
                enum:
                - exact
              network:
                type: string
                description: CAIP-2 network id, e.g. "eip155:8453" (Base) or "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp".
              amount:
                type: string
                description: Price in atomic asset units (USDC has 6 decimals).
              asset:
                type: string
                description: Asset contract address / mint.
              payTo:
                type: string
                description: Treasury address to pay.
              maxTimeoutSeconds:
                type: integer
              extra:
                type: object
                description: 'Rail-specific extras (EVM: EIP-712 domain name/version; Solana: feePayer).'
                additionalProperties: true
        extensions:
          type: object
          description: Optional discovery metadata (e.g. bazaar input/output schemas).
          additionalProperties: true
  responses:
    PaymentRequired:
      description: Payment required. Body contains the x402 PaymentRequirements envelope with a multi-network accepts array; the per-call price is in accepts[].amount (and on the operation as x-2s-price). Sign for whichever rail you hold USDC on (EIP-3009 for Base, partial SPL transfer for Solana) and retry with the PAYMENT-SIGNATURE header (X-PAYMENT also accepted for v1 clients).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/X402PaymentRequiredV2'
    UpstreamError:
      description: Upstream provider error.
    MethodNotAllowed:
      description: Method not allowed — see `Allow` header for the supported method.
    ServerError:
      description: Internal server error.
    BadRequest:
      description: Bad request — invalid parameters.
  parameters:
    TrialMode:
      name: trial
      in: query
      required: false
      description: 'Try before you buy. Set to 1 for one free real call per endpoint per hour — no wallet or payment needed — to verify the endpoint before paying. Equivalent to sending the "X-2s-Trial: 1" request header. Works on every endpoint.'
      schema:
        type: integer
        enum:
        - 1
  securitySchemes:
    x402Payment:
      type: apiKey
      in: header
      name: PAYMENT-SIGNATURE
      description: 'x402 protocol v2: base64-encoded PaymentPayload. Call any paid endpoint without auth to receive a 402 with a multi-network PaymentRequirements envelope. Sign for either rail: EIP-3009 transferWithAuthorization (Base USDC) OR a partial SPL token transfer (Solana USDC). Retry with PAYMENT-SIGNATURE header. X-PAYMENT is also accepted for v1 buyer clients. See https://x402.org.'