Price API

The Ecosmart app already shows the live wholesale price and the hours ahead. This API is that same feed, for anything that can make an HTTPS request — Home Assistant, a Sigenergy / Tesla / other battery, or a script.

If you want sensors in Home Assistant, skip to Home Assistant. 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: lines charges, 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. In the app: More → Settings → Advanced → API keys. Creating a new key revokes the previous one, so only one secret is live. The new secret is shown once.

If you do not see that screen yet, update the app, or ask us 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: lines 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 lines, 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.