OctopusEnergy.Client

Unofficial .NET SDK for the Octopus Energy customer APIs

View the Project on GitHub markheydon/octopus-energy-dotnet

Getting started

OctopusEnergy.Client is an unofficial, stable customer REST client for the Octopus Energy customer APIs. It is not affiliated with Octopus Energy Limited, and the website terms of use are not a developer licence.

A dashboard API key exposes your account structure and smart-meter consumption. Treat it as a secret and do not share it with third-party services you do not trust. Partner enrolment, quoting, and operations APIs are out of scope - see customer vs partner.

1. Create an API key

Generate a key in the Octopus dashboard.

2. Install the package

dotnet add package OctopusEnergy.Client

3. Construct the client

Pass your API key for account, consumption, and other authenticated calls:

using OctopusEnergy.Client;

const string apiKey = "sk_test_not_a_real_key";
using var client = new OctopusEnergyClient(apiKey);

Public catalogue endpoints work without authentication:

using var client = new OctopusEnergyClient();

See authentication for custom base URLs and supplying your own HttpClient.

Testability with interfaces

Depend on IOctopusEnergyClient and the resource service interfaces (IAccountService, IConsumptionService, and so on) in application code so unit tests can substitute behaviour. Construct OctopusEnergyClient at the composition root; the concrete client implements IOctopusEnergyClient and exposes interface-typed resource properties.

public sealed class AccountSummaryService(IOctopusEnergyClient client)
{
    public Task<Account> GetAsync(string accountNumber, CancellationToken cancellationToken = default) =>
        client.Accounts.GetAsync(accountNumber, cancellationToken);
}

4. List products

The products catalogue is public - no API key required when you use the parameterless constructor:

using OctopusEnergy.Client.Models.Products;

await foreach (Product product in client.Products.ListAsync())
{
    Console.WriteLine(product.DisplayName);
}

Pagination is automatic. See products for filters and product detail.

5. Fetch account detail

Account calls require an API key and your account number (A-XXXXXXXX):

using OctopusEnergy.Client.Models.Accounts;

Account account = await client.Accounts.GetAsync("A-12345678");
Console.WriteLine($"{account.Number}: {account.Properties.Count} properties");

See account detail. Electricity and gas consumption are on client.Consumption — see consumption.

Next steps