Octopus Energy España smart home integration, free and open source
Unofficial: Octopus Energy Spain prices by 2.0TD period, hourly use, balances, last bill.
Published by LM1LC3N7
- Devices
- Version 0.1.1
- Requires Gladys >=5.3.0
- ★ 0
Unofficial integration, not affiliated with Octopus Energy, for Octopus
Energy España customers. It reads your account through the official Kraken
GraphQL API of Octopus España (api.oees-kraken.energy) and gives Gladys:
- one device per electricity supply point (CUPS): the price per kWh now and next, the prices of the three 2.0TD periods (taxes included), the surplus compensation per kWh, the hourly consumption for the energy monitoring;
- one device for the account: electricity account balance, Solar Wallet, last bill amount;
- the energy contract template Octopus Energy España electricity.
Read-only: nothing is ever changed on your account; the only request that is not a read is the login. It has never been tested with a real Octopus España account yet: built from the published API and the queries of ha-octopus-spain.
Setup
- Install the integration from the Gladys store, open its configuration.
- Enter the e-mail address and the password you use on the Octopus website, or an API key of your account if Octopus gave you one (used alone when given). Kraken deprecated the e-mail login in 2026: if Octopus removes it, the status says so. The password and the API key are kept by Gladys in its database, never shown again, sent only to Octopus Energy España.
- Account number: only when your login has several accounts (empty: the first one).
- Zone of the supply: peninsula and Balearic Islands (the default), Canary Islands or Ceuta and Melilla. It sets the hours of the periods.
- Save, then Test the connection (at most once a minute).
- In Discovery, add the devices you want.
Devices
Octopus electricity (CUPS …XXXX), the last 4 characters of the CUPS:
| Feature | Unit | Note |
|---|---|---|
| Price per kWh now | EUR/kWh | the price of the current period, taxes included |
| Next price per kWh | EUR/kWh | the next different price within 2 days |
| Price per kWh P1 (punta) | EUR/kWh | taxes included |
| Price per kWh P2 (llano) | EUR/kWh | taxes included |
| Price per kWh P3 (valle) | EUR/kWh | taxes included |
| Surplus compensation per kWh | EUR/kWh | the price of the energy you export |
| Consumption (30 min) | kWh | each hour read split in two equal half hours |
Octopus España account: electricity account balance, Solar Wallet, last bill amount (EUR, as the API gives them). A value the API does not give stays empty, never 0.
The prices are published again at every quarter of an hour from what is held (no request), and no longer once they were read more than 6 hours ago.
The 2.0TD periods
| Days | Peninsula, Balearic and Canary Islands (local time) | Ceuta and Melilla |
|---|---|---|
| Monday to Friday | P1 10-14 and 18-22, P2 8-10, 14-18 and 22-24, P3 0-8 | P1 11-15 and 19-23, P2 8-11, 15-19 and 23-24, P3 0-8 |
| Saturday, Sunday, national holidays of fixed date | P3 all day | P3 all day |
National holidays of fixed date: 1 and 6 January, 1 May, 15 August, 12 October, 1 November, 6, 8 and 25 December (CNMC Circular 3/2020, as of 2026-11). Moving holidays (Good Friday) and regional ones are ordinary days in 2.0TD. A product with the same price in the three periods is priced the same at every hour.
Pace
- The account (supply points, prices, balances, last bill): every hour.
- The consumption of the created supply point: every 6 hours over the last 4 days, and over 14 days once a day after 06:00 and for a new device (the distributor sends the readings a day or more late).
- One request at a time, 2 seconds apart. The time of each read is kept in
/databefore the request: a restart never reads sooner.
The energy contract
Create a contract from the Octopus Energy España electricity template:
- Last 4 characters of the CUPS: empty with a single supply point; required with several (an empty or ambiguous value leaves the contract unpriced, never guessed);
- Fixed charges per month: the power term and the meter rental of your bill, taxes included (the API does not give them).
Every half hour is priced by the integration at the price of its period, taxes included. The API gives the prices in force, never their dates: the integration keeps, at each hourly read, the prices of the next 2 hours (40 days kept). So:
- start the contract on the day after the installation: a half hour before the installation has no price;
- a gap of more than 2 hours without a good read leaves the half hours of the gap without a price: Gladys stopped, Octopus unreachable for about 1 h 30 (the retries after 5, 10, 20 and 40 minutes then fall after the 2 hours kept), a pause after a 429 or a 5xx longer than 2 hours, or a supply point whose prices the API answers in error;
- a price change is seen at the next hourly read;
- changing the zone does not price the past again.
A half hour without a price is never counted 0. Gladys needs a price for every half hour of a request: one missing fails the whole request, and the catch-up of Gladys starts again from the oldest half hour without a cost. A gap therefore delays the costs of the half hours after it, for up to 31 days (the catch-up window of Gladys), until the gap leaves that window. The priced half hours carry no period label.
The template uses the time of Madrid for the days and months of Gladys (billing period, daily totals): in the Canary Islands they start at 23:00 local time. The periods themselves follow the local time of the islands.
Status and errors
| Status | Meaning | What happens |
|---|---|---|
| Octopus refused the login (KT-CT-1138, 1134 or 1135) | the login refused: wrong e-mail, password or API key (1134 and 1135 are documented for refresh tokens; answered to this login, they are taken as a refusal) | no request until you change the credentials or Test succeeds (another account number alone does not lift it) |
| API access is not enabled (KT-CT-11334) | Octopus disabled API access for this user | same |
| Octopus no longer accepts the login by e-mail and password | the schema refuses these fields, or KT-CT-1113 | pause of 1 hour, doubled up to 6 hours; lifted by an API key |
| Octopus blocks the login for now (KT-CT-1136) | a temporary block, seen with valid credentials | pause of 1 hour, doubled up to 6 hours |
| Octopus asked to slow down | HTTP 429 or KT-CT-1199 | pause of Retry-After or 15 minutes, doubled up to 6 hours |
| Octopus is having trouble | HTTP 5xx or KT-CT-7899 | pause of 5 minutes, doubled up to 6 hours |
| Octopus could not be read | network, timeout, unreadable or partial answer, a query refused | tried again after 5, 10, 20, 40 then every 60 minutes |
A 401 or 403 answered to a query (not to the login) is never taken as a
refused password: one new login, then a passing error. The pauses and the
refusal are kept in /data (the refusal as 8 bits of a salted hash of the
credentials, never the credentials).
Other remarks in the status: the prices of a supply point answered in error (the error and the time of the last good read; not kept, not used after 6 hours), prices not given with taxes (not published nor used), several supply points (the consumption is not published), the balances or the consumption not read (the prices go on).
Octopus' new sign-in. If the website accepts your password but the integration says it is refused, your account may use the new sign-in: an API key of the account still works (ask Octopus for one).
What /data holds
/data/octopus-spain.json: the time of the last reads, the pause, the
refusal (8 bits of a salted hash), the supply points seen (at most 8: keyed
hash, last 4 characters, when last seen), the keyed hash of the account and
the prices of the last 40 days. Never the e-mail address, the password, a
token, the id key, the account number nor a whole CUPS.
Limits
- Electricity only, consumption only: the export (surplus) readings are not read in v1.
- The consumption is published only for an account with a single supply point: the readings of the API do not say which supply point they belong to.
- Only the prices taxes included (
variableTermWithTaxes); an indexed product without these three prices has no price in Gladys. - The power term and the contracted power are not read: enter the fixed charges in the contract.
- The times of the status are those of Madrid.
Credits
The GraphQL queries are adapted from ha-octopus-spain (MIT, Miguel Ángel López Vicente). Apache-2.0.
Configuration settings
These are the settings Octopus Energy España asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Octopus Energy España account | section | No | Unofficial connector, not affiliated with Octopus Energy. For Octopus Energy customers in Spain. Log in with the e-mail address and password of the Octopus website, or an API key of your account if Octopus gave you one (Kraken deprecated the e-mail login in 2026 and may remove it). The integration reads your electricity supply points (CUPS), the prices of your contract for the three 2.0TD periods (taxes included), the hourly consumption for the Gladys energy monitoring, your balances (electricity account, Solar Wallet) and your last bill. Read-only: nothing is ever changed on your account. Then create an energy contract from the "Octopus Energy España electricity" template. |
| API key (optional) | secret | No | An API key of your Octopus account, if Octopus gave you one: used alone when given. Kept by Gladys in its database, never shown again, sent only to Octopus Energy España. |
| E-mail address | string | No | The e-mail address you log in with on the Octopus website (not needed with an API key). |
| Password | secret | No | Kept by Gladys in its database, never shown again, sent only to Octopus Energy España (api.oees-kraken.energy) to log in. |
| Account number (optional) | string | No | Only needed when your login has several Octopus accounts: empty, the first one is read. |
| Zone of the supply | select | No | Sets the hours of the 2.0TD periods (punta, llano, valle), in the local time of the zone. |
How to install Octopus Energy España in Gladys
- In Gladys, open Integrations: Octopus Energy España appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/lm1lc3n7/gladys-octopus-spain:0.1.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/LM1LC3N7/gladys-octopus-spain.
Octopus Energy España requires Gladys >=5.3.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Octopus Energy España is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by LM1LC3N7, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation