---
name: energy
description: Energy math on the person's own numbers. Convert units, measure a load and price it on their tariff, move flexible jobs to cheaper or cleaner hours, size solar and batteries, compare fixed and floating supply and settle hedges, work out generation cost, and run mining or other flexible loads only when they pay. Never invent a price, sign, trade or wire anything. Use when a task converts energy units, measures or prices a load, schedules a flexible job, sizes solar or batteries, compares supply contracts or hedges, works out generation cost, or runs mining or another flexible load.
license: MIT
metadata:
  version: "1.0"
  homepage: https://energy.md
  api: https://energy.md/api/v1 (optional, no key, stores nothing)
  mcp: https://energy.md/mcp
  terms: https://energy.md/terms
---

# Energy

Provided as is, at your own risk: figures are estimates from the numbers you use and may be wrong, and nothing here is trading, investment, legal, tax, engineering, electrical or safety advice, a quote, or an offer. Terms: https://energy.md/terms.

Work out energy, power, cost and emissions with the person's own numbers: their tariffs, prices, quotes, profiles and factors. Show your math once, in a short block. Say what is cheaper, cleaner or within limits on the numbers given; never say what the person should buy, sign or trade. Skip routine narration.

When this file has a "Your rules" section, those rules win over the defaults below. Each rule there ends with its setting key in brackets, like (hedge_ratio_max), and this file names rules by that key. Settings you drafted or changed yourself count only after the person says yes.

The tools are optional and do arithmetic only. Call them by GET or POST at `https://energy.md/api/v1/<tool>`, or as MCP tools at `https://energy.md/mcp`. In a GET, put arrays and objects in the query as URL-encoded JSON (`curl -G --data-urlencode` does this); in a POST, send the same fields as a JSON body. Every result has a `summary`, the `formula` used, `assumptions` and `not_checked`. Read `not_checked` before you report.

## 1. Units first

- Power is a rate (W, kW, MW). Energy is an amount (Wh, kWh, MWh). Energy = power x hours. A 7 kW charger running 3 hours uses 21 kWh.
- A bill charges kWh for energy and, on many business tariffs, $ per kW for the highest demand in the period. Keep the two apart.
- MW vs MWh is the most common mix-up in plant, contract and battery figures. A "100 MW / 400 MWh" battery delivers 100 MW for about 4 hours. Ask which one a number is when the text is unclear.
- Heat and fuel: 1 therm = 100,000 BTU. 1 MMBtu = 1,000,000 BTU = 10 therms. 1 kWh = 3,412 BTU. 1 MWh = 3.412 MMBtu.
- Fuel to energy uses typical heat contents. Real fuel varies; say "typical" and use the person's own figure when they have one.
- Optional tool: `energy_units`. It converts energy, power and fuel units, and flags a power-to-energy conversion that has no hours.

```bash
curl -s "https://energy.md/api/v1/energy_units?value=1500&from=kWh&to=MMBtu"
```

## 2. Measure the load

- List every device: count, watts, hours per day, and duty (the share of those hours it actually draws). Use nameplate or measured watts from the person; say which.
- Daily kWh = count x watts x hours per day x duty / 1,000. Multiply by the overhead factor for cooling or facility overhead (a PUE-style multiplier: 1.3 means 30% on top).
- Peak kW is the running draw of everything that can be on at once (count x watts x duty x overhead / 1,000 for each device on in the same hour), not daily kWh spread over the day. Average kW = daily kWh / 24. Load factor = average kW / peak kW. A low load factor means demand charges weigh more.
- Give on_hours (like "8-18") for every device that doesn't run all day: it makes time-of-use and demand bills exact. Without it, the tool spreads that device's energy over 24 hours for time-of-use pricing, counts its full draw as on at the peak, and says so in `not_checked`.
- Servers, GPUs and other compute are loads like any other: watts x hours. Use the measured draw under the real workload when the person has it, not only the rated maximum.
- Optional tool: `load_energy`. It returns kWh per day, month and year, peak and average kW, load factor, a bill for each tariff and emissions.

```bash
curl -sG "https://energy.md/api/v1/load_energy" \
  --data-urlencode 'devices=[{"label":"GPU server","count":4,"watts":1500,"hours_per_day":24,"duty":0.8},{"label":"office","count":1,"watts":2000,"hours_per_day":10,"on_hours":"8-18"}]' \
  --data-urlencode 'tariffs=[{"label":"flat","fixed_usd_per_month":20,"flat_usd_per_kwh":0.15},{"label":"time of use","fixed_usd_per_month":20,"tou":[{"label":"peak","hours":[16,17,18,19,20],"usd_per_kwh":0.3},{"label":"off-peak","hours":[0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,21,22,23],"usd_per_kwh":0.1}]}]' \
  --data-urlencode 'overhead_factor=1.2' --data-urlencode 'grid_kg_co2e_per_kwh=0.4'
```

## 3. Price it with the person's tariff

- Use only prices from the person: their bill, tariff sheet, contract or a quote they received. Write down where each price came from.
- Never invent a price, and never look one up on your own. If a price is missing, follow the missing_prices rule; by default, ask. The tools take no default prices and list what they couldn't price under `not_checked`.
- Flat tariff: energy cost = kWh x $/kWh, plus the fixed monthly charge.
- Time-of-use: split the kWh by hour band and price each band. The same kWh can cost very different amounts by hour.
- Demand charge: highest kW in the period x $/kW. One short spike sets it for the whole month. Check the peak before adding a load.
- Compare up to four tariffs at once in `load_energy`. The cheapest one on the person's load is arithmetic, not a switch: changing tariffs or suppliers is the person's call.
- Taxes, riders and fees on a real bill vary. If the person gives them, add them; if not, say the total leaves them out.

## 4. Shift what can wait

- A flexible job is one that only needs to finish by a deadline: charging, batch compute, pumping, heating water, washing. Get its energy (or power and run hours), the earliest start, the deadline, the most it may draw, and whether it may pause.
- Get the person's 24 hourly prices for the day (and hourly carbon factors, if they have them). Never fill in an hour yourself.
- Pick the cheapest hours inside the window. If the job can pause, those can be separate hours; if not, use the cheapest unbroken block.
- Respect the price cap: never use an hour priced above it. If the job can't finish under the cap before the deadline, say so and ask. Never miss a deadline to save money unless the person says yes.
- Compare against starting now, and report the saving in dollars and kg.
- Follow the shift_flexible rule. If it says ask, show the window and wait. Even when it says always, you only plan the hours: set them only through scheduling controls or apps the person gave you for that, never switch equipment yourself, and tell the person what moved.
- Optional tool: `shift_load`. It returns the cheapest window, the cleanest window, and their cost and emissions against starting now.

```bash
curl -sG "https://energy.md/api/v1/shift_load" \
  --data-urlencode 'energy_kwh=60' --data-urlencode 'max_power_kw=20' \
  --data-urlencode 'earliest_hour=6' --data-urlencode 'deadline_hour=18' --data-urlencode 'start_now_hour=6' \
  --data-urlencode 'interruptible=true' --data-urlencode 'max_price_usd_per_kwh=0.25' \
  --data-urlencode 'prices_usd_per_kwh=[0.12,0.11,0.1,0.1,0.1,0.11,0.14,0.18,0.2,0.16,0.12,0.09,0.08,0.08,0.09,0.12,0.22,0.3,0.34,0.32,0.26,0.2,0.16,0.13]'
```

## 5. Carbon

- Emissions = kWh x the person's grid factor (kg CO2e per kWh). Use their factor; there is no built-in one. If they have none, report kWh and say emissions weren't counted.
- When the person gives 24 hourly factors, use them: the cleanest hours are often not the cheapest. Show both windows.
- Keep under the monthly carbon cap if one is set. Report kg per day and per month.
- Say whether a factor is an average or a marginal figure if the person told you. Don't claim a job is "carbon free" or "green"; give the kg.

## 6. Solar and storage

- Size PV from the person's daily load, the share of it to cover, and their site's peak sun hours. PV kW DC = daily kWh x share / (peak sun hours x (1 - system losses)). Losses default to 14%.
- Size the battery for backup (backup load kW x hours) or for an evening shift (kWh moved from day to night). Usable kWh = nominal kWh x depth of discharge. Energy out = energy in x round-trip efficiency.
- Inverter kW must cover the largest load it serves at once.
- Money only on the person's numbers: install cost, battery cost, their tariff and export rate, the share they use on site, degradation, years and discount rate. Simple payback = net cost / first-year savings. NPV discounts each year's savings.
- Incentives, credits and tax treatment depend on the person and where they are. Use only the share they or their tax professional give you.
- A licensed installer, permits and interconnection approval are needed before anything is installed or connected. Sizing here is a first estimate, not a design.
- Optional tool: `solar_storage`.

```bash
curl -s "https://energy.md/api/v1/solar_storage?daily_load_kwh=30&peak_sun_hours=4.5&backup_hours=8&backup_load_kw=1.5&install_usd_per_w=2.5&battery_usd_per_kwh=600&tariff_usd_per_kwh=0.2&export_usd_per_kwh=0.05&self_consumption_share=0.7&discount_rate=0.06"
```

## 7. Procurement and hedges

- Get the volume (MWh, per year or per month), the fixed price the person was offered, and their own floating price scenarios (low, base, high). Never supply a scenario or a forward price yourself.
- Fixed cost = volume x fixed price. Floating cost = volume x (floating price + any adder). Blend = hedge ratio x fixed + (1 - hedge ratio) x floating.
- Break-even: the floating price at which fixed and floating cost the same. Below it, floating is cheaper; above it, fixed is. Show the range of outcomes across the scenarios.
- Contract for difference or virtual PPA, from the buyer's side: settlement to the buyer = (market - strike) x volume. Positive: the seller pays the buyer. Negative: the buyer pays the seller. The seller's figure is the same with the opposite sign. The buyer still buys its power at market, so market cost minus settlement comes to about strike x volume for the hedged volume. hedge_math shows it from `cfd_side` (default buyer) and names the payer in `cfd_payer`: quote that field, and say whose side each sign is from.
- Keep within the hedge_ratio_max rule if set.
- This is educational arithmetic. Never sign, accept, negotiate, trade or commit to anything. At most, prepare the numbers for a person, and only if the contracts rule allows it.
- Optional tool: `hedge_math`.

```bash
curl -sG "https://energy.md/api/v1/hedge_math" \
  --data-urlencode 'volume_mwh=1000' --data-urlencode 'fixed_usd_per_mwh=60' --data-urlencode 'hedge_ratio=0.7' \
  --data-urlencode 'scenarios_usd_per_mwh=[40,60,90]' --data-urlencode 'strike_usd_per_mwh=55'
```

## 8. Generation cost

- Annual MWh = capacity MW x capacity factor x 8,760.
- Capital recovery factor (CRF) = r(1+r)^n / ((1+r)^n - 1), with r the discount rate and n the life in years.
- LCOE ($/MWh) = (capex x CRF + fixed O&M) / annual MWh + variable O&M + fuel. Fuel ($/MWh) = heat rate (MMBtu per MWh) x fuel price ($/MMBtu). A heat rate of 7,000 BTU/kWh is 7 MMBtu/MWh.
- Spark spread (gas) or dark spread (coal) = power price - heat rate x fuel price. Positive means the fuel costs less than the power sells for, before other costs.
- It works the same for solar, wind, hydro, nuclear, gas, coal or anything else; renewables just have no fuel line. All numbers come from the person.
- LCOE leaves out taxes, financing structure, grid costs and revenue timing. Say so.
- Optional tool: `generation_cost`.

```bash
curl -s "https://energy.md/api/v1/generation_cost?capacity_mw=100&capacity_factor=0.55&capex_usd_per_kw=1000&fixed_om_usd_per_kw_year=20&variable_om_usd_per_mwh=3&fuel_usd_per_mmbtu=3&heat_rate_btu_per_kwh=7000&discount_rate=0.07&life_years=30&power_usd_per_mwh=45"
```

## 9. Flexible loads and mining

- Any machine that can stop is a flexible load: hash mining, batch compute, electrolysis, pumping. Run it only in hours where it earns more than its power costs.
- Machine kW = hashrate (TH/s) x efficiency (J/TH) / 1,000, or the person's measured watts. Multiply by the overhead factor for cooling.
- Daily power cost = kW x 24 x uptime x $/kWh. Daily revenue = hashrate x the person's revenue per TH per day. Margin = revenue - power cost.
- Break-even power price = daily revenue / daily kWh. Curtail (switch off) in every hour priced above it.
- Revenue comes only from the person. Never estimate it, and never look up a coin price, a network figure or a pool rate.
- Optional tool: `mining_power`. With 24 hourly prices, it returns the curtailed margin and the hours to run. Switching machines stays with the person's own controls.
- On the round illustrative numbers below (not market data): 26.25 kW, 630 kWh a day, a $49.60 daily margin at $0.08/kWh, break-even $0.1587/kWh, and on the hourly prices it runs 19 of 24 hours (not 16:00 to 21:00) for a $41.37 margin.

```bash
curl -sG "https://energy.md/api/v1/mining_power" \
  --data-urlencode 'machines=10' --data-urlencode 'hashrate_th_per_machine=100' --data-urlencode 'efficiency_j_per_th=25' \
  --data-urlencode 'overhead_factor=1.05' --data-urlencode 'power_usd_per_kwh=0.08' --data-urlencode 'revenue_usd_per_th_day=0.1' \
  --data-urlencode 'prices_usd_per_kwh=[0.06,0.05,0.05,0.04,0.04,0.05,0.07,0.09,0.1,0.09,0.08,0.07,0.07,0.08,0.1,0.12,0.16,0.2,0.24,0.22,0.16,0.12,0.09,0.07]'
```

## 10. Backup and availability

- Runtime (hours) = usable kWh / critical load kW. Size the critical load from the devices that must stay on, not the whole site.
- Battery usable kWh = nominal kWh x depth of discharge; allow for inverter losses.
- Generator runtime = fuel on hand / burn rate at the expected load, from the person's or the maker's figures.
- Check the result against the backup_min_hours rule, and flag any gap.
- Generators, batteries, transfer switches and fuel storage need licensed installation, local codes and safe fuel storage. Never tell anyone how to wire, back-feed or connect a generator or battery.

## 11. Report

- Five to eight lines: what was measured, the key numbers (kWh, peak kW, cost, kg CO2e), the option that is cheapest or cleanest on the numbers given, what is over a limit or needs a yes, what wasn't priced or checked, and the formula used.
- Name the source of every price and factor ("your tariff", "your quote of ...", "typical heat content").
- Call every figure an estimate. Never present it as a quote, a bill or a forecast.
- If a rule needs a yes (a cap, the budget, approval_usd, a contract), stop and ask before anything else happens.

## Never

- Never invent, guess or look up a price, tariff, rate, emission factor, market figure or revenue. Ask, or list it as not priced.
- Never buy, sell or trade energy, capacity, certificates, contracts or derivatives. Never place a bid, an offer or an order.
- Never sign, accept, renew or negotiate a supply contract, PPA or hedge. Any purchase, contract, order or commitment is the person's to make, at any amount; you only prepare the numbers.
- Never wire, physically switch or connect equipment, or give instructions for electrical work. That is licensed professionals' work. Change a schedule only through controls or apps the person gave you, as shift_flexible allows.
- Never present an estimate as a quote, a bill, a forecast, a design or approval to connect.
- Never tell the person what to buy, sign or trade. Say what is cheaper, cleaner or within limits on the numbers given.

## Defaults

When a rule isn't set: ask for any missing price; ask before moving a job's timing; get the person's yes on any plan that spends or commits money, which they then carry out themselves; bill on 30 days; overhead factor 1 for most loads and 1.05 for mining; system losses 14%, depth of discharge 0.9, round-trip efficiency 0.9 and PV degradation 0.5% a year, each labeled as a default; no emissions without the person's factor; never a contract or a trade.

---

# Reference

Use at your own risk. energy.md is provided as is, without warranty. Information here may be inaccurate, incomplete or not current, and is not verified; figures are estimates from the numbers you send and the formulas stated. Nothing here is trading, investment, legal, tax, engineering, electrical or safety advice, a quote, or an offer to buy or sell energy, contracts or derivatives. energy.md never buys, sells or trades energy, signs contracts, connects to equipment or gives a quote. Check everything yourself before you act on it. Terms: https://energy.md/terms

## Tools

Every tool is read-only, takes GET query parameters or a POST JSON body at https://energy.md/api/v1/<tool>, and is also an MCP tool at https://energy.md/mcp. Every response carries a disclaimer and the terms link.

### load_energy: Measure a load and price it on your tariffs

Adds up a list of devices (count, watts, hours a day, duty and optional on-hours) with a cooling or PUE-style overhead into kWh per day, month and year, peak and average kW and the load factor. Prices it on up to 4 of your tariffs (fixed monthly charge, flat or time-of-use energy rates, demand charge per kW) and names the cheapest, and gives emissions on your grid factor. Servers and GPUs work the same as any device. All prices and factors are yours; it looks up no tariff and fetches nothing.

- `devices` (array, required): The devices: [{label, count (default 1), watts (draw while on), hours_per_day (0-24), duty (0-1 share of on-time at full draw, default 1), on_hours (optional: when it runs, like "18-23" or a list of hours. Without it, a device under 24 h/day has its energy spread evenly over the day for time-of-use pricing, and its full draw is assumed to run at the same time as every other device for peak kW and demand charges; send on_hours to make time-of-use and demand bills exact)}].
- `overhead_factor` (number, min 1, max 5): A multiplier on every device for cooling, power conversion or a PUE-style overhead. 1 means none. Default 1.
- `days` (number, min 1, max 366): Days in the billing month. Default 30.
- `tariffs` (array): Up to 4 of your tariffs: [{label, fixed_usd_per_month, flat_usd_per_kwh, tou: [{label, hours: "16-21" or a list of hours, usd_per_kwh}], demand_usd_per_kw}]. Each needs a flat rate or time-of-use periods; a flat rate also covers hours no period lists. Charges you leave out are not counted. Optional.
- `grid_kg_co2e_per_kwh` (number, min 0, max 3): Your grid emissions factor, kg CO2e per kWh. Optional.
- `demand_limit_kw` (number, min 0, max 10000000): Your demand limit, kW. The peak is checked against it. Optional.
- `budget_usd_per_month` (number, min 0, max 10000000000): Your monthly energy budget, $. The cheapest bill is checked against it. Optional.
- `carbon_cap_kg_per_month` (number, min 0, max 10000000000): Your monthly carbon cap, kg CO2e. Needs grid_kg_co2e_per_kwh. Optional.

Illustrative example: `POST https://energy.md/api/v1/load_energy` with `{"devices":[{"label":"GPU server","count":2,"watts":1500,"hours_per_day":24,"duty":0.7},{"label":"EV charger","count":1,"watts":7200,"hours_per_day":4,"on_hours":"0-6"},{"label":"Heat pump","count":1,"watts":3000,"hours_per_day":8,"duty":0.6,"on_hours":"6-22"}],"overhead_factor":1.1,"days":30,"tariffs":[{"label":"Flat","fixed_usd_per_month":15,"flat_usd_per_kwh":0.16},{"label":"Time of use","fixed_usd_per_month":15,"flat_usd_per_kwh":0.14,"tou":[{"label":"Peak","hours":"16-21","usd_per_kwh":0.32},{"label":"Night","hours":"0-6","usd_per_kwh":0.08}]}],"grid_kg_co2e_per_kwh":0.4}`. Round illustrative numbers, not market data, a price or a quote; send your own.

### shift_load: Shift a flexible job to cheaper or cleaner hours

Places a flexible job (energy_kwh, or power_kw with run_hours) between earliest_hour and deadline_hour, which may cross midnight, on your 24 hourly prices and optional 24 hourly carbon factors. Finds the cheapest window (or, when the job can pause, the cheapest hours), the cleanest window, and their cost and emissions against starting now. An optional price cap keeps every hour above it out, and the tool says when the job can't finish under the cap. Uses only your prices and factors; it controls no device and fetches nothing.

- `energy_kwh` (number, min 0, max 100000000): Energy the job needs, kWh. Or send power_kw and run_hours.
- `power_kw` (number, min 0, max 10000000): The job's draw while running, kW.
- `run_hours` (number, min 0, max 24): Hours the job runs at power_kw (fractions allowed).
- `max_power_kw` (number, min 0, max 10000000): The most the job or its circuit can draw in an hour, kW. An interruptible job may run at up to this. Optional.
- `interruptible` (boolean): true if the job can pause and resume (charging, batch compute). Default false: it runs in one block.
- `earliest_hour` (integer, min 0, max 23): First hour the job may run, 0-23. Default start_now_hour.
- `deadline_hour` (integer, min 0, max 24): Hour the job must be done by, 0-24. At or before earliest_hour it means the next day. Default: 24 hours after earliest_hour.
- `start_now_hour` (integer, min 0, max 23): The hour it is now, for the start-now comparison. Default earliest_hour, or 0.
- `prices_usd_per_kwh` (array): Your 24 hourly energy prices, $/kWh, hour 0 first. Optional; without them nothing is priced.
- `carbon_kg_per_kwh` (array): Your 24 hourly carbon factors, kg CO2e per kWh, hour 0 first. Optional.
- `grid_kg_co2e_per_kwh` (number, min 0, max 3): One grid factor, kg CO2e per kWh, used when no hourly factors are sent. Optional.
- `max_price_usd_per_kwh` (number, min -10, max 100): Your price cap, $/kWh: hours above it are never used. Optional.

Illustrative example: `POST https://energy.md/api/v1/shift_load` with `{"energy_kwh":40,"max_power_kw":10,"interruptible":true,"earliest_hour":18,"deadline_hour":7,"start_now_hour":18,"prices_usd_per_kwh":[0.1,0.09,0.08,0.08,0.09,0.11,0.15,0.2,0.22,0.2,0.18,0.16,0.15,0.15,0.16,0.2,0.28,0.35,0.4,0.38,0.3,0.22,0.16,0.12],"carbon_kg_per_kwh":[0.42,0.4,0.4,0.41,0.43,0.45,0.48,0.45,0.38,0.3,0.24,0.2,0.18,0.18,0.2,0.26,0.36,0.45,0.5,0.5,0.48,0.46,0.45,0.44],"max_price_usd_per_kwh":0.2}`. Round illustrative numbers, not market data, a price or a quote; send your own.

### solar_storage: Size solar and storage

Sizes a PV array from daily_load_kwh x offset_share and your site's peak_sun_hours after system_losses, and a battery from backup_hours x backup_load_kw or evening_shift_kwh, with depth_of_discharge for nominal size and round_trip_efficiency on the charging side. Returns PV kW DC, yearly kWh, battery usable and nominal kWh and inverter kW. With your install and battery costs and your tariff it adds simple payback and NPV, with degradation. It holds no prices, sun data or incentives of its own, does not design or approve a system, and is not a quote or advice.

- `daily_load_kwh` (number, min 0, max 10000000): Average daily energy use in kWh. Needed to size PV.
- `peak_sun_hours` (number, min 0.1, max 12): Your site's average peak sun hours per day (kWh/m2/day) for the panel tilt and direction. Needed to size PV.
- `system_losses` (number, min 0, max 0.9): Share lost to wiring, inverter, heat, soiling and shading, 0-0.9 (default 0.14).
- `offset_share` (number, min 0, max 1): Share of the daily load the PV should cover, 0-1 (default 1).
- `backup_hours` (number, min 0, max 720): Hours of backup wanted. Needs backup_load_kw.
- `backup_load_kw` (number, min 0, max 1000000): Load to carry during backup, kW. Needs backup_hours.
- `evening_shift_kwh` (number, min 0, max 10000000): Daily solar energy to store for use after sunset, kWh.
- `depth_of_discharge` (number, min 0.1, max 1): Usable share of the battery's nominal capacity, 0.1-1 (default 0.9).
- `round_trip_efficiency` (number, min 0.1, max 1): Battery round-trip efficiency, 0.1-1 (default 0.9). Applied on the charging side.
- `dc_ac_ratio` (number, min 1, max 2): PV DC kW per inverter AC kW (default 1.2).
- `install_usd_per_w` (number, min 0, max 100): Your PV installed cost, USD per W DC. Or send install_usd. No default.
- `install_usd` (number, min 0, max 10000000000): Your total PV installed cost in USD, instead of install_usd_per_w. No default.
- `battery_usd_per_kwh` (number, min 0, max 100000): Your installed battery cost, USD per nominal kWh. No default.
- `incentive_share` (number, min 0, max 1): Share of the cost covered by incentives you qualify for, 0-1 (default 0). Yours to confirm.
- `tariff_usd_per_kwh` (number, min 0, max 100): Your retail price per kWh that self-used solar avoids. No default.
- `export_usd_per_kwh` (number, min 0, max 100): What you are paid per kWh exported. No default; exports are not valued without it.
- `self_consumption_share` (number, min 0, max 1): Share of PV output used on site (default 1); the rest is exported.
- `degradation_per_year` (number, min 0, max 0.1): Yearly PV output loss (default 0.005 = 0.5%).
- `years` (integer, min 1, max 50): Years for payback and NPV (default 25).
- `discount_rate` (number, min 0, max 1): Your discount rate as a decimal for NPV. No default; NPV is skipped without it.

Illustrative example: `POST https://energy.md/api/v1/solar_storage` with `{"daily_load_kwh":30,"peak_sun_hours":5,"system_losses":0.14,"offset_share":0.8,"evening_shift_kwh":10,"backup_hours":8,"backup_load_kw":1.5,"install_usd_per_w":2.5,"battery_usd_per_kwh":700,"incentive_share":0.3,"tariff_usd_per_kwh":0.25,"export_usd_per_kwh":0.05,"self_consumption_share":0.85,"discount_rate":0.05}`, or `GET https://energy.md/api/v1/solar_storage?daily_load_kwh=30&peak_sun_hours=5&system_losses=0.14&offset_share=0.8&evening_shift_kwh=10&backup_hours=8&backup_load_kw=1.5&install_usd_per_w=2.5&battery_usd_per_kwh=700&incentive_share=0.3&tariff_usd_per_kwh=0.25&export_usd_per_kwh=0.05&self_consumption_share=0.85&discount_rate=0.05`. Round illustrative numbers, not market data, a price or a quote; send your own.

### hedge_math: Fixed vs floating, and contract-for-difference settlement

Procurement and settlement arithmetic on your own numbers. From your volume (total or a monthly list), your fixed offer, a hedge ratio and your floating price scenarios, it computes the cost of all fixed, all floating and the blend at that ratio for each scenario, the break-even floating price, and the range of outcomes. With a strike it computes contract-for-difference (or virtual PPA) settlement per scenario with the sign convention spelled out, from the buyer's or the seller's side. Every price is yours; it has no prices or market data of its own. It is educational arithmetic: it never suggests a side, a ratio or a trade, and it is not a quote.

- `volume_mwh` (number, min 0, max 1000000000): Total volume for the period, in MWh. Send this or monthly_volumes_mwh.
- `monthly_volumes_mwh` (array): Volume per month in MWh, instead of volume_mwh. The total is their sum.
- `fixed_usd_per_mwh` (number, min -10000, max 100000): Your fixed-price offer, in $/MWh. No default. Without it, only the floating side is priced.
- `hedge_ratio` (number, min 0, max 1): Share of volume at the fixed price, 0 to 1. The rest floats. Default 1.
- `hedge_ratio_max` (number, min 0, max 1): Your own cap on the hedge ratio, from your settings. Optional; flagged when hedge_ratio is above it.
- `scenarios_usd_per_mwh` (array): Your floating price scenarios in $/MWh: numbers, or {label, usd_per_mwh} such as low, base and high. No defaults.
- `adder_usd_per_mwh` (number, min -1000, max 10000): Your adder on the floating price (fees, shaping, delivery), in $/MWh. Optional, default 0. Applied to the floating side only.
- `strike_usd_per_mwh` (number, min -10000, max 100000): Contract-for-difference strike, in $/MWh. Optional; without it no settlement is computed.
- `cfd_volume_mwh` (number, min 0, max 1000000000): Volume the contract for difference settles on, in MWh. Default: the hedged volume (volume x hedge_ratio).
- `cfd_side` (string, one of buyer | seller): Which side the settlement is shown from: buyer (the offtaker, default) or seller (the generator).

Illustrative example: `POST https://energy.md/api/v1/hedge_math` with `{"volume_mwh":10000,"fixed_usd_per_mwh":60,"hedge_ratio":0.6,"scenarios_usd_per_mwh":[{"label":"low","usd_per_mwh":35},{"label":"base","usd_per_mwh":50},{"label":"high","usd_per_mwh":90}],"adder_usd_per_mwh":3,"strike_usd_per_mwh":55}`. Round illustrative numbers, not market data, a price or a quote; send your own.

### generation_cost: Generation cost (LCOE) and spark spread

Simple levelized cost of energy for any plant type from your numbers: capacity_mw and capacity_factor give annual MWh; capex_usd_per_kw is annualized with the capital recovery factor from discount_rate and life_years; fixed and variable O&M and fuel (fuel_usd_per_mmbtu x heat_rate_btu_per_kwh) are added per MWh. With power_usd_per_mwh it gives the spark spread (gas) or dark spread (coal) = power price - heat rate x fuel price, and the margin over LCOE. Costs and prices you leave out are not priced and are listed. It holds no prices of its own, ignores taxes, incentives, financing structure and degradation, and is not a quote or advice.

- `capacity_mw` (number, min 0.000001, max 100000, required): Nameplate capacity in MW (AC).
- `capacity_factor` (number, min 0, max 1, required): Share of the year's maximum output actually produced, 0-1 (your site or plant figure).
- `capex_usd_per_kw` (number, min 0, max 100000): Your overnight capital cost, USD per kW. No default; capital is not priced without it.
- `fixed_om_usd_per_kw_year` (number, min 0, max 10000): Your fixed O&M, USD per kW per year. No default.
- `variable_om_usd_per_mwh` (number, min 0, max 10000): Your variable O&M, USD per MWh. No default.
- `fuel_usd_per_mmbtu` (number, min 0, max 1000): Your fuel price, USD per MMBtu. Needs heat_rate_btu_per_kwh. No default.
- `heat_rate_btu_per_kwh` (number, min 3412.14, max 30000): Plant heat rate, Btu of fuel per kWh of power (fuel plants only). 3,412 Btu/kWh would be 100% efficient.
- `discount_rate` (number, min 0, max 1): Your discount rate or cost of capital as a decimal (0.08 = 8%). Needed to annualize capex. No default.
- `life_years` (integer, min 1, max 100): Economic life in years for the capital recovery factor (default 25).
- `power_usd_per_mwh` (number, min -10000, max 100000): Your power price, USD per MWh, for the spread and the margin over LCOE. No default.
- `fuel` (string, one of none | gas | coal | oil | other): Fuel type, used only to name the spread: gas = spark spread, coal = dark spread. Optional.

Illustrative example: `POST https://energy.md/api/v1/generation_cost` with `{"capacity_mw":100,"capacity_factor":0.5,"capex_usd_per_kw":1000,"fixed_om_usd_per_kw_year":20,"variable_om_usd_per_mwh":3,"fuel_usd_per_mmbtu":4,"heat_rate_btu_per_kwh":7000,"discount_rate":0.08,"life_years":25,"power_usd_per_mwh":60,"fuel":"gas"}`, or `GET https://energy.md/api/v1/generation_cost?capacity_mw=100&capacity_factor=0.5&capex_usd_per_kw=1000&fixed_om_usd_per_kw_year=20&variable_om_usd_per_mwh=3&fuel_usd_per_mmbtu=4&heat_rate_btu_per_kwh=7000&discount_rate=0.08&life_years=25&power_usd_per_mwh=60&fuel=gas`. Round illustrative numbers, not market data, a price or a quote; send your own.

### mining_power: Mining and other flexible loads: power, margin, break-even

Flexible-load economics for hash mining or any machine that can stop. From your machine count, hashrate x efficiency in J/TH (or watts per machine), overhead factor and uptime it computes kW and kWh per day; with your power price, the power cost; with your own revenue per TH per day, the revenue, margin and break-even power price, and the curtailment rule (run only in hours priced under break-even). With 24 hourly prices it lists the hours run and the curtailed margin; an optional price cap keeps hours priced above it off (hours at the cap may run). Every price and the revenue figure are yours; it shows no revenue, price or network data of its own and never suggests buying machines or power.

- `machines` (integer, min 1, max 1000000): Number of machines. Default 1.
- `hashrate_th_per_machine` (number, min 0, max 1000000): Hashrate per machine in TH/s. Needed for revenue.
- `efficiency_j_per_th` (number, min 0, max 10000): Efficiency in J/TH. Watts per machine = hashrate x J/TH.
- `watts_per_machine` (number, min 0, max 10000000): Power per machine at the wall, in W, instead of hashrate x J/TH. Any flexible machine works.
- `overhead_factor` (number, min 1, max 3): Cooling and site overhead multiplier on machine power. Default 1.05.
- `uptime` (number, min 0, max 1): Share of time running, 0 to 1. Default 1.
- `power_usd_per_kwh` (number, min -100, max 100): Your all-in power price in $/kWh. No default.
- `revenue_usd_per_th_day` (number, min 0, max 1000): Your own revenue figure per TH/s per day, in $. No default; it moves with conditions this tool can't see.
- `prices_usd_per_kwh` (array): Optional: your 24 hourly prices in $/kWh, hour 0 to 23, for the curtailed day.
- `max_price_usd_per_kwh` (number, min -100, max 100): Optional: your own price cap from settings. Hours priced above it never run, even when under break-even; hours at or under it may run if they are also under break-even.

Illustrative example: `POST https://energy.md/api/v1/mining_power` with `{"machines":100,"hashrate_th_per_machine":100,"efficiency_j_per_th":25,"overhead_factor":1.05,"power_usd_per_kwh":0.08,"revenue_usd_per_th_day":0.1,"prices_usd_per_kwh":[0.06,0.05,0.05,0.04,0.04,0.05,0.07,0.09,0.1,0.09,0.08,0.07,0.07,0.08,0.1,0.12,0.16,0.2,0.24,0.22,0.16,0.12,0.09,0.07]}`. Round illustrative numbers, not market data, a price or a quote; send your own.

### energy_units: Convert energy, power and fuel units

Converts a value you send between energy units (J, kJ, MJ, GJ, Wh, kWh, MWh, GWh, BTU, MMBtu, therm, kcal, toe, boe), power units (W, kW, MW, GW, hp, BTU/h) and fuel quantities (natural gas, propane, diesel, gasoline, coal, wood) using typical heat contents, labeled typical. Power times hours is energy: converting a power unit to an energy unit (or back) needs `hours`, and the tool flags the mix-up when hours are missing. Leave out `to` to see every unit of the same kind. It uses no prices and fetches nothing; fuel figures are typical reference values, not a measurement of your fuel.

- `value` (number, min -1000000000000000, max 1000000000000000, required): The amount to convert, in the `from` unit.
- `from` (string, required): The unit of value. Energy: j, kj, mj, gj, wh, kwh, mwh, gwh, btu, mmbtu, therm, kcal, toe, boe. Power: w, kw, mw, gw, hp, btu/h. Fuel (typical heat content): natural_gas_scf, natural_gas_mcf, natural_gas_m3, propane_gal, diesel_gal, diesel_l, gasoline_gal, gasoline_l, coal_short_ton, wood_cord. Case, spaces and plurals don't matter (therms, BTUs, MMBtus); btu/hr and btuh read as btu/h. MBtu is ambiguous and is refused.
- `to` (string): The unit to convert to, from the same list. Optional: leave it out to see the value in every energy (or power) unit.
- `hours` (number, min 0, max 876000): Hours, only for power to energy (energy = power x hours) or energy to power (power = energy / hours). Optional.

Illustrative example: `POST https://energy.md/api/v1/energy_units` with `{"value":250,"from":"kw","to":"mwh","hours":8}`, or `GET https://energy.md/api/v1/energy_units?value=250&from=kw&to=mwh&hours=8`. Round illustrative numbers, not market data, a price or a quote; send your own.

### build_settings: Write your settings into the skill

Takes `preset` plus any setting below, and `format` (section or skill). Returns the sections, the settings as JSON, a skill link and an install line. Settings an agent drafted count only after the person says yes: show them to the person first, and follow them only once they agree.

## Settings

Numbers or fixed choices only. `unset` clears an optional setting. Catalog: https://energy.md/api/v1/settings

- `max_price_usd_per_kwh` (prices): Flexible loads never run above; $/kWh, 0 to 10
- `budget_usd_per_month` (prices): Energy budget per month; $, 0 to 100000000
- `approval_usd` (prices, core): Get a yes on any plan that spends or commits over; $, 0 to 100000000, capped at budget_usd_per_month; default 100
- `budget_alert_pct` (prices): Warn at this share of the budget; %, 10 to 100
- `missing_prices` (prices, core): When a price is missing; ask | leave_unpriced; default ask
- `demand_limit_kw` (loads): Keep total demand under; kW, 0 to 1000000
- `overhead_factor` (loads): Cooling or overhead multiplier; x, 1 to 3
- `backup_min_hours` (loads): Backup must last at least; hours, 0 to 720
- `days` (loads): Days per billing period; days, 1 to 366
- `electrical_work` (loads, core): Electrical work; licensed_only; default licensed_only
- `shift_flexible` (scheduling, core): Move flexible jobs to cheaper or cleaner hours; always | ask | never; default ask
- `earliest_hour` (scheduling): Flexible jobs start no earlier than; hour (0-23), 0 to 23
- `deadline_hour` (scheduling): Flexible jobs finish by; hour (1-24), 1 to 24
- `interruptible` (scheduling): Jobs may pause and resume; yes | no
- `grid_kg_co2e_per_kwh` (carbon): Your grid emission factor; kg CO2e/kWh, 0 to 2
- `carbon_cap_kg_per_month` (carbon): Monthly emissions cap; kg CO2e, 0 to 100000000
- `prefer_clean_hours` (carbon): Cleaner hours first; yes | no
- `contracts` (contracts, core): Supply contracts, PPAs, hedges and derivatives; never | ask; default never
- `hedge_ratio_max` (contracts): Most of the volume a fixed or hedged price may cover; share (0-1), 0 to 1
- `fixed_vs_floating` (contracts): The person's own stance on fixed vs floating; ask | prefer_fixed | prefer_floating
- `discount_rate` (contracts): Discount rate for NPV and LCOE; share a year (0.07 = 7%), 0 to 0.5
- `trading` (contracts, core): Trading; never; default never

## Presets

- `core`: Approval level, missing prices, the shift rule and the fixed rules: no trading, no contracts signed, licensed electrical work. Everything else follows the skill's defaults.
- `home_and_ev`: An example to edit: a household budget, overnight charging that may pause, 8 hours of backup, cleaner hours first and no contracts.
- `compute_jobs`: An example to edit: batch compute with a cooling overhead, jobs that may run any hour and pause, a monthly carbon cap, and unpriced items listed instead of asked.
- `business_site`: An example to edit: a site with a demand limit and 4 hours of backup, daytime jobs that can't pause, contract numbers prepared for a person, at most 80% hedged.