API & MCP
Everything a person can do on Ledgerly Home Battery Simulator, a program or AI agent can do with the same inputs and get the identical result.
HTTP API
POST https://ledgerlybatterysim.usefulweb.app/api/v1/calculate– run Ledgerly Home Battery SimulatorGET https://ledgerlybatterysim.usefulweb.app/api/v1/tool– inputs, output schema, examples- OpenAPI 3.1: /openapi.json · /openapi.yaml
- Errors:
application/problem+json;422includes per-fielderrors.
Ledgerly Home Battery Simulator
Simulates a year hour by hour: solar power from the offline yield model (or your monthly figures), your consumption from a smart-meter export, hourly values or a simple household profile, and a battery with its capacity, power and losses. Compares several sizes by self-consumption, self-sufficiency, grid import, export, cycles and the money each one saves. Part of Ledgerly’s Solar & Heat.
| Field | Type | Default | Description |
|---|---|---|---|
currency | text | "EUR" | Currency |
latitude | number | 52.52 | Latitude (°, south negative) |
longitude | number | 13.405 | Longitude (°, west negative) |
peakPowerKw | number | 8 | Peak power of the PV system (kWp) |
tilt | number | 35 | Tilt (° from horizontal) |
azimuth | number | 0 | Orientation (° from south: east −90, west 90) |
layout | select (single, east-west) | "single" | Panel layout |
utcOffset | number | 1 | Time zone (hours from UTC, standard time) |
pvMonthlyKwh | text | — | PV yield per month (kWh, 12 values; empty = offline estimate). Paste the monthly figures from the yield calculation or PVGIS; the daily curve still comes from the sun’s path. |
annualLoadKwh | number | — | Electricity use per year (kWh; empty = from the profile). With the built-in profile an empty value means 4,000 kWh. With your own profile it rescales the profile to this total. |
loadProfile | textarea | — | Your load profile: 24, 288 or 8,760 hourly kWh values, or smart-meter readings. Empty = Ledgerly’s simple household profile. Meter readings: one line per reading with date, time and kWh. |
batteryKwh | number | 8 | Usable battery capacity (kWh) |
compareCapacities | text | "0, 5, 10, 15" | Also compare these capacities (kWh) |
batteryPowerKw | number | 4 | Battery charge and discharge power (kW) |
roundTripEfficiencyPercent | number | 90 | Round-trip efficiency (%) |
exportLimitKw | number | 0 | Feed-in limit (kW, 0 = none) |
electricityPrice | number | 0.35 | Electricity price per kWh |
feedInTariff | number | 0.078 | Feed-in payment per kWh |
seed | integer | 1 | Weather sequence (seed). Sunny, mixed and dull days are drawn from this seed; the same seed always gives the same year. |
Example request
8 kWp in Berlin, 4,000 kWh, 8 kWh battery
curl -X POST https://ledgerlybatterysim.usefulweb.app/api/v1/calculate -H 'content-type: application/json' -d '{"latitude":52.52,"longitude":13.405,"peakPowerKw":8,"annualLoadKwh":4000,"batteryKwh":8}'Every result contains
inputs (normalised, defaults applied), summary, result (validated against the published schema), units, assumptions, sources, warnings, computedAt and links.
MCP (Model Context Protocol)
- Streamable HTTP endpoint:
https://ledgerlybatterysim.usefulweb.app/mcp– protocol revisions 2026-07-28 (stateless) and 2025-11-25 / 2025-06-18 / 2025-03-26 (initialize handshake). - Tools:
ledgerly_battery_sim - Local stdio connector:
node src/mcp-stdio.ts --tool=ledgerly-battery-sim
{
"mcpServers": {
"ledgerly-battery-sim": { "type": "http", "url": "https://ledgerlybatterysim.usefulweb.app/mcp" }
}
}