Price API
Live wholesale spot prices and forecasts for Home Assistant, a battery, or your own script. An API key is required.
Built into Home Assistant since 2026.11The Ecosmart app at my.ecosmart.co.nz already shows the live wholesale price and the hours ahead. This API serves prices built from the same market data (WITS, where the wholesale market publishes its prices), for anything that can make an HTTPS request — Home Assistant, a Sigenergy / Tesla / other battery, or a script.
Using Home Assistant? Ecosmart ships with Home Assistant from version 2026.11, so add the integration and paste your key; no YAML needed. The endpoint list is the full contract.
We publish prices. We do not control your inverter, battery, EV charger or hot water cylinder. What your equipment does with the signal is yours.
These are wholesale energy prices at the grid exit point (GXP). They are not a complete retail rate: network losses, lines charges (and on Vector networks, transmission), metering, levies and our service fee are not in them. Forecasts are indicative, not a promise. The authoritative public market source remains WITS.
Usage, invoices and account balance stay in the app for now.
Get a key
You need to be an Ecosmart electricity customer. A new customer’s key works once their switch to Ecosmart completes. In the Ecosmart app at my.ecosmart.co.nz: More → Settings → API keys (under the Advanced heading). Creating a new key revokes the previous one, so only one secret is live. The new secret is shown once.
Can’t see that screen? Ask us for a key via the contact form.
A key looks like ecos_live_…. We store only a hash, so a lost key is revoked and replaced, never recovered. Treat it like a password: it belongs in Home Assistant secrets.yaml (or your password manager), not in a screenshot, a Git repo, or a forum post.
Each key may look up the ICPs we attached when we minted it, and may read wholesale prices at any GXP. The default budget is 12 requests per minute (a burst of 12, then one every five seconds). That is plenty for Home Assistant polling every few minutes. Stuck retry loops are stopped quickly.
Authenticate
Base URL: https://api.ecosmart.co.nz/rest/v1
That path is the REST API. Other protocols on the same host (MCP later) will not live under /rest.
Every request:
Authorization: Bearer ecos_live_…
First call
GET /rest/v1/me tells you what the key can do. The poc on each allowed ICP is the GXP code you will put in the other URLs (for example HAY2201).
curl -sS -H "Authorization: Bearer $ECOS_KEY" \
"https://api.ecosmart.co.nz/rest/v1/me"
{
"keyPrefix": "ecos_live_7Kd2mQ8x",
"label": "Home Assistant",
"accountRef": "10042",
"allowedIcps": [
{
"icp": "0000123456ABCDE",
"poc": "HAY2201",
"network": "VECT",
"priceCategoryCode": "WRUC"
}
],
"rateLimitPerMinute": 12,
"gstRatePercent": 15.0,
"pricesAre": "Wholesale energy prices at the grid exit point. Not a retail price: network losses, lines and transmission charges, metering, levies and retailer margin are not included."
}
What this is not
- Not the app login. Do not put your Ecosmart account password in Home Assistant. This key is the credential for machines.
- Not usage, invoices or your account balance. Those stay in the app. A broader customer API is planned; this feed is prices.
- Not a control channel. We will not start, stop or set the mode of your inverter.
- Not a savings guarantee. What an automation earns depends on your equipment, your usage, and a market that spikes. Model your own numbers.
- Not a complete retail rate. Add network losses, lines charges (and on Vector networks, transmission), metering, levies and our fee (and GST, if you used the exclusive column) before comparing with a bill.
Questions: contact us, or phone 07 595 0001.