{
  "openapi": "3.1.0",
  "info": {
    "title": "GridPulse API",
    "description": "Global energy grid intelligence API. NREL + EIA + Open-Meteo data synthesis. Home solar feasibility, electricity rate analysis, time-of-use optimization, EV charging cost modeling, battery storage ROI, renewable energy comparison, natural gas pricing, and community solar enrollment guidance. Covers all 50 US states with expanding international coverage (EU, AU, CA). EnergySage solar quotes, Jackery portable power, ChargePoint EV charging, and Palmetto solar affiliate links included. All endpoints support any language via ?lang=. Pricing: $0.08\u2013$0.20 USDC/call via x402 micropayment.",
    "version": "1.2.0",
    "contact": {
      "url": "https://gridpulse.vercel.app"
    }
  },
  "servers": [
    {
      "url": "https://gridpulse.vercel.app"
    }
  ],
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 payment signature. Send a GET request without this header to receive a 402 with payment requirements. Sign and retry with PAYMENT-SIGNATURE."
      }
    }
  },
  "security": [
    {
      "x402": []
    }
  ],
  "paths": {
    "/api/energy/prices": {
      "get": {
        "summary": "Electricity prices by state",
        "description": "Retail electricity rates (residential, commercial, industrial), trend vs national average, monthly bill estimate, price drivers, 90-day outlook.",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "2-letter US state code (TX, CA, NY, etc.)"
          }
        ],
        "responses": {
          "200": {
            "description": "Electricity price briefing"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.08,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Electricity rate analysis \u2014 chain before /api/energy/solar for payback period accuracy; chain with /api/energy/tou for TOU optimization"
      }
    },
    "/api/energy/grid": {
      "get": {
        "summary": "Power grid status by region",
        "description": "Grid demand, capacity utilization, generation mix by fuel, and stress level for major US ISOs.",
        "parameters": [
          {
            "name": "region",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "ercot | caiso | pjm | miso | isone | nyiso | spp"
          }
        ],
        "responses": {
          "200": {
            "description": "Grid status briefing"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.08,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Grid reliability and outage intelligence \u2014 pairs with /api/energy/battery for backup power sizing"
      }
    },
    "/api/energy/renewable": {
      "get": {
        "summary": "Renewable energy profile by state",
        "description": "Generation mix percentages, carbon intensity rating, national ranking, clean energy trend, and best EV charging window.",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "2-letter US state code"
          }
        ],
        "responses": {
          "200": {
            "description": "Renewable energy profile"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Renewable energy mix analysis \u2014 chain with /api/energy/solar for portfolio diversification; green power program enrollment"
      }
    },
    "/api/energy/natural-gas": {
      "get": {
        "summary": "Henry Hub natural gas briefing",
        "description": "Spot price, week-over-week change, storage vs 5-year average, supply/demand balance, electricity and heating cost impact, 90-day outlook.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Natural gas market briefing"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.08,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Natural gas pricing and efficiency \u2014 chain with /api/energy/prices for total energy bill optimization"
      }
    },
    "/api/energy/forecast": {
      "get": {
        "summary": "90-day energy forecast by state",
        "description": "Electricity price direction and range, demand outlook, peak risk periods, natural gas linkage, grid reliability outlook, consumer and business actions.",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "2-letter US state code"
          }
        ],
        "responses": {
          "200": {
            "description": "90-day energy forecast"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Energy demand and rate forecast \u2014 chain with /api/energy/tou for forward TOU optimization"
      }
    },
    "/api/energy/ev-cost": {
      "get": {
        "summary": "EV charging cost vs gasoline",
        "description": "Cost per mile, annual charging cost, gas comparison, annual savings, off-peak strategy, home charger recommendation.",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "2-letter US state code"
          },
          {
            "name": "miles",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 12000
            },
            "description": "Annual miles (1,000-100,000)"
          }
        ],
        "responses": {
          "200": {
            "description": "EV cost analysis"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.08,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "EV charging cost analysis \u2014 ChargePoint affiliate included; pairs with AutoPulse for EV purchase decision"
      }
    },
    "/api/energy/solar": {
      "get": {
        "summary": "Home solar feasibility analysis",
        "description": "NREL production estimate, system cost, IRA 30% tax credit, payback period, 25-year savings, net metering, EnergySage quote link.",
        "parameters": [
          {
            "name": "zip",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "US ZIP code (preferred)"
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "2-letter state code (if no zip)"
          },
          {
            "name": "system_kw",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number",
              "default": 6
            },
            "description": "System size in kW (2-20)"
          }
        ],
        "responses": {
          "200": {
            "description": "Solar feasibility analysis"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Solar feasibility analysis \u2014 EnergySage + Palmetto affiliate links auto-appended; start here for any solar query"
      }
    },
    "/api/energy/appliance": {
      "get": {
        "summary": "Home appliance energy cost calculator",
        "description": "Annual electricity cost for any major home appliance, cost vs national average, Energy Star upgrade ROI (payback period, 10-year savings), and most cost-effective upgrade sequence for a typical household. Covers HVAC, water heater, refrigerator, washer/dryer, dishwasher, and lighting.",
        "parameters": [
          {
            "name": "appliance",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Appliance type (hvac, water-heater, refrigerator, washer, dryer, dishwasher, lighting)"
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "2-letter US state code for local electricity rates"
          },
          {
            "name": "usage_hours",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Daily usage hours (default varies by appliance)"
          },
          {
            "name": "age_years",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Appliance age in years (affects upgrade ROI calculation)"
          }
        ],
        "responses": {
          "200": {
            "description": "Appliance energy cost analysis with upgrade ROI"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.05,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Appliance energy consumption ranking \u2014 chain with /api/energy/prices for cost calculation; Amazon affiliate for efficient replacements"
      }
    },
    "/api/energy/battery": {
      "get": {
        "summary": "Home battery storage analysis",
        "description": "Battery storage sizing and ROI \u2014 Tesla Powerwall, Enphase IQ, and Generac PWRcell comparison, total installed cost before IRA 30% tax credit, TOU arbitrage savings, payback period, outage backup duration for critical loads, and whether solar + battery or battery-only makes financial sense.",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "2-letter US state code"
          },
          {
            "name": "monthly_bill",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Average monthly electricity bill in USD"
          },
          {
            "name": "has_solar",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "true if existing or planned solar system"
          },
          {
            "name": "outage_priority",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Priority for outage backup (essential-only, whole-home, ev-charging)"
          }
        ],
        "responses": {
          "200": {
            "description": "Home battery storage analysis with ROI and system recommendations"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Home battery storage ROI \u2014 chain after /api/energy/solar for solar+storage combined analysis; Jackery affiliate included"
      }
    },
    "/api/energy/carbon": {
      "get": {
        "summary": "Household electricity carbon footprint",
        "description": "Annual carbon footprint from household electricity use \u2014 tCO2e per year, comparison vs state and national average, verified carbon offset cost and marketplace options (Gold Standard, Verra VCS), and a prioritized carbon reduction roadmap with cost and impact per action.",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "2-letter US state code"
          },
          {
            "name": "monthly_kwh",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Average monthly electricity consumption in kWh"
          },
          {
            "name": "household_size",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Number of people in household"
          }
        ],
        "responses": {
          "200": {
            "description": "Carbon footprint analysis with offset cost and reduction roadmap"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.08,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Carbon footprint of energy usage \u2014 pairs with ClimatePulse for full environmental impact assessment"
      }
    },
    "/api/energy/community-solar": {
      "get": {
        "summary": "Community solar enrollment by ZIP code",
        "description": "Community solar availability by ZIP code \u2014 utility-specific programs and independent aggregators (Arcadia, EnergySage), bill credit rate (typically 10\u201315%), estimated annual savings, waitlist status, and enrollment guide. Best option for renters or households where rooftop solar is not feasible.",
        "parameters": [
          {
            "name": "zip",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "US ZIP code"
          },
          {
            "name": "monthly_bill",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Average monthly electricity bill in USD"
          },
          {
            "name": "credit_preference",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Preference for bill credit vs. direct payment programs"
          }
        ],
        "responses": {
          "200": {
            "description": "Community solar programs with availability, savings estimates, and enrollment steps"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.08,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Community solar enrollment \u2014 no-install option; pairs with /api/energy/solar for comparison"
      }
    },
    "/api/energy/tou": {
      "get": {
        "summary": "Time-of-use rate optimization",
        "description": "TOU rate availability and optimization for a US state \u2014 peak and off-peak windows by season, estimated annual savings vs flat rate, optimal appliance scheduling (dishwasher, laundry, EV charging, pool pump), and whether switching to a TOU plan makes financial sense for the household load profile.",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "2-letter US state code"
          },
          {
            "name": "utility",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Utility name (e.g., PGE, SCE, ConEd) for utility-specific TOU plans"
          },
          {
            "name": "has_ev",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "true if household has an EV (major TOU savings driver)"
          },
          {
            "name": "has_solar",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "true if household has solar (affects TOU export credit optimization)"
          },
          {
            "name": "monthly_bill",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Average monthly electricity bill in USD"
          }
        ],
        "responses": {
          "200": {
            "description": "TOU rate analysis with peak windows, scheduling recommendations, and savings estimate"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.08,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Time-of-use rate optimization \u2014 chain after /api/energy/prices for shift savings; pairs with /api/energy/ev-cost for EV charging scheduling"
      }
    }
  }
}