This release is a pre-release and may not be stable for production use.
dompower
Async Python client for Dominion Energy API. Retrieves 30-minute interval electricity usage data for Virginia and North Carolina, and 15-minute electric and hourly gas data for South Carolina.
Requirements
- Python 3.12+
- Dominion Energy account (Virginia/North Carolina)
Installation
pip install dompower
Or with uv:
uv add dompower
Authentication
Option 1: Login with Username/Password (Recommended)
The CLI supports direct login with two-factor authentication (TFA):
dompower login -u your.email@example.com
You'll be prompted for your password and then guided through TFA verification (SMS or email). Tokens are saved automatically.
Option 2: Manual Token Extraction
If the login command doesn't work, you can manually extract tokens from a browser session:
- Open https://login.dominionenergy.com/CommonLogin?SelectedAppName=Electric
- Log in with your Dominion Energy credentials
- Open browser DevTools (F12) > Network tab
- Look for requests to
prodsvc-dominioncip.smartcmobile.com - Find the
accessTokenandrefreshTokenin request/response headers
Create a tokens.json file:
{
"access_token": "eyJhbGciOiJodHRwOi...",
"refresh_token": "pd9YAsV9HKNkrECM..."
}
Token Refresh
The library automatically refreshes tokens when they expire (every 30 minutes). Both tokens rotate on each refresh - the library handles this automatically and notifies via callback.
CLI Usage
Get Usage Data
# Last 7 days of 30-minute interval data
dompower --token-file tokens.json usage -a ACCOUNT_NUMBER -m METER_NUMBER
# Custom date range
dompower --token-file tokens.json usage -a 123456 -m 789 \
--start-date 2024-01-01 --end-date 2024-01-31
# Output as JSON
dompower --token-file tokens.json usage -a 123456 -m 789 --json
# Save raw Excel file
dompower --token-file tokens.json usage -a 123456 -m 789 --raw -o usage.xlsx
Login
# Interactive login with TFA support
dompower login -u your.email@example.com
# Specify output file and cookie storage
dompower login -u your.email@example.com -o tokens.json --cookies ~/.dompower/cookies.json
Cookies are saved to enable TFA bypass on subsequent logins.
Account Discovery
# List all accounts and meters
dompower --token-file tokens.json accounts
# Include inactive/closed accounts
dompower --token-file tokens.json accounts --all
# Output as JSON
dompower --token-file tokens.json accounts --json
# Select default account/meter (interactive)
dompower --token-file tokens.json select-account
# Select specific account
dompower --token-file tokens.json select-account -a 123456789
After selecting an account, you can omit -a and -m from usage commands.
Bill Forecast
# Get bill forecast with last bill details and current usage
dompower --token-file tokens.json bill-forecast
# For specific account
dompower --token-file tokens.json bill-forecast -a 123456789
# Output as JSON
dompower --token-file tokens.json bill-forecast --json
Other Commands
# Manually refresh tokens
dompower --token-file tokens.json refresh
# Show authentication instructions
dompower auth-info
Library Usage
Basic Example
import asyncio
from datetime import date, timedelta
import aiohttp
from dompower import DompowerClient
async def main():
async with aiohttp.ClientSession() as session:
client = DompowerClient(
session,
access_token="your_access_token",
refresh_token="your_refresh_token",
)
usage = await client.async_get_interval_usage(
account_number="123456789",
meter_number="000000000123456789",
start_date=date.today() - timedelta(days=7),
end_date=date.today(),
)
for record in usage:
print(f"{record.timestamp}: {record.consumption} {record.unit}")
asyncio.run(main())
With Token Persistence
import json
from pathlib import Path
import aiohttp
from dompower import DompowerClient
TOKEN_FILE = Path("tokens.json")
def load_tokens():
with TOKEN_FILE.open() as f:
return json.load(f)
def save_tokens(access_token: str, refresh_token: str):
with TOKEN_FILE.open("w") as f:
json.dump({"access_token": access_token, "refresh_token": refresh_token}, f)
async def main():
tokens = load_tokens()
async with aiohttp.ClientSession() as session:
client = DompowerClient(
session,
access_token=tokens["access_token"],
refresh_token=tokens["refresh_token"],
token_update_callback=save_tokens, # Called when tokens refresh
)
usage = await client.async_get_interval_usage(...)
Login with Username/Password
import aiohttp
from dompower import GigyaAuthenticator, TFAProvider
async def login_with_tfa():
async with aiohttp.ClientSession() as session:
auth = GigyaAuthenticator(session)
# Initialize session (gets WAF and Gigya cookies)
await auth.async_init_session()
# Submit credentials
result = await auth.async_submit_credentials(
"your.email@example.com", "your_password"
)
if result.tfa_required:
# Get available TFA targets
targets = await auth.async_get_tfa_options(TFAProvider.PHONE)
# Send verification code
await auth.async_send_tfa_code(targets[0])
# Get code from user and verify
code = input(f"Enter code sent to {targets[0].obfuscated}: ")
tokens = await auth.async_verify_tfa_code(code)
else:
# No TFA required
tokens = await auth._async_complete_login()
print(f"Access token: {tokens.access_token[:20]}...")
print(f"Refresh token: {tokens.refresh_token[:20]}...")
Home Assistant Integration Pattern
from homeassistant.helpers.aiohttp_client import async_get_clientsession
from dompower import DompowerClient
async def async_setup_entry(hass, entry):
session = async_get_clientsession(hass)
def token_callback(access_token: str, refresh_token: str):
hass.config_entries.async_update_entry(
entry,
data={
**entry.data,
"access_token": access_token,
"refresh_token": refresh_token,
},
)
client = DompowerClient(
session,
access_token=entry.data["access_token"],
refresh_token=entry.data["refresh_token"],
token_update_callback=token_callback,
)
# Store client for use in sensors/coordinators
hass.data[DOMAIN][entry.entry_id] = client
API Reference
DompowerClient
Main client class for API interaction.
DompowerClient(
session: ClientSession,
*,
access_token: str | None = None,
refresh_token: str | None = None,
token_update_callback: Callable[[str, str], None] | None = None,
)
Methods:
async_get_interval_usage(account_number, meter_number, start_date, end_date)- Get 30-minute usage dataasync_get_raw_excel(account_number, meter_number, start_date, end_date)- Get raw Excel fileasync_get_accounts()- Get all accounts and meters for the authenticated userasync_get_customer_info()- Get customer profile with all accountsasync_get_bill_forecast(account_number)- Get bill forecast with last bill dataasync_login(username, password, tfa_code_callback)- Login with username/passwordasync_set_tokens(access_token, refresh_token)- Set tokens manuallyasync_refresh_tokens()- Force token refresh
GigyaAuthenticator
Handles Gigya/SAP authentication with TFA support. Use for step-by-step login flows.
GigyaAuthenticator(
session: ClientSession,
cookie_file: Path | None = None, # Persist cookies for TFA bypass
)
Methods:
async_init_session()- Initialize WAF and Gigya cookiesasync_submit_credentials(username, password)- Submit login credentialsasync_get_tfa_options(provider)- Get available TFA targets (phone/email)async_send_tfa_code(target)- Send verification code to targetasync_verify_tfa_code(code)- Verify TFA code and get tokensasync_login(username, password, tfa_callback)- Complete login with callbacksave_cookies()/load_cookies()- Persist cookies for TFA bypass
Data Models
@dataclass(frozen=True)
class IntervalUsageData:
timestamp: datetime # Start of 30-minute interval
consumption: float # kWh consumed
generation: float # kWh excess generation returned to grid
unit: str # "kWh"
Exceptions
DompowerError # Base exception
AuthenticationError # Authentication issues
InvalidAuthError # Invalid tokens
TokenExpiredError # Tokens expired, need re-auth
BrowserAuthRequiredError # Initial auth needed
GigyaError # Gigya authentication errors
InvalidCredentialsError # Wrong username/password
TFARequiredError # TFA required (not an error, normal flow)
TFAVerificationError # TFA code verification failed
TFAExpiredError # TFA session expired (~5 min timeout)
CannotConnectError # Network issues
ApiError # API returned error
RateLimitError # Rate limited (429)
South Carolina Accounts
Dominion Energy South Carolina uses a different portal
(account.dominionenergysc.com) and a different data vendor (Bidgely).
Use dompower.sc for SC accounts. DompowerClient and GigyaAuthenticator
work only for Virginia and North Carolina.
CLI
# Log in once. This does TFA and saves a TFA token to ~/.dompower/sc.json.
# Use your SC portal username. It is not always your email address.
dompower sc-login -u your-username
# Show the account, meter registers, daily totals, and bill forecast.
# Set DOMPOWER_SC_PASSWORD to skip the password prompt.
dompower sc-usage --days 3
dompower sc-usage --days 3 --gas --json
# Write a redacted diagnostic report to dompower-sc-report.txt.
dompower sc-report
Diagnostic report
dompower sc-report logs in with the saved TFA token and writes a plain
text file. You can attach it to a GitHub issue. Read the file before you
post it.
The report does not contain your username, password, TFA token, cookies, email address, phone number, service address, account number, or Bidgely user ID. It shows:
- Each request (path and HTTP status) and the JSON field names of each
response. Most values show only as
<string, N chars>or<number>. - The meter registers, readings per day, and daily and hourly totals.
- The structure of the Green Button XML and some raw readings. Entry titles show only if they are generic Green Button titles, such as "Interval Consumption".
- The bill forecast amounts.
If a step fails, the report still includes the error and the responses up to that step.
Library
The portal uses session cookies. Use a dedicated session with
create_sc_cookie_jar(). The default cookie jar quotes cookie values, and the
portal then rejects the session.
import aiohttp
from datetime import date
from dompower import DominionSCClient, SCAuthenticator, create_sc_cookie_jar
async with aiohttp.ClientSession(cookie_jar=create_sc_cookie_jar()) as session:
# First login: interactive TFA gives a TFA token. Save it.
auth = SCAuthenticator(session)
result = await auth.async_submit_credentials(username, password)
if result.tfa_required:
targets = await auth.async_get_tfa_options()
await auth.async_send_tfa_code(targets[0])
tfa_token = await auth.async_verify_tfa_code(input("Code: "))
sc_session = await auth.async_complete_login()
# Later logins: the saved TFA token skips TFA.
client = DominionSCClient(session, username, password, tfa_token=tfa_token)
await client.async_login()
usage = await client.async_get_interval_usage(date(2026, 8, 1), date(2026, 8, 7))
forecast = await client.async_get_bill_forecast()
SC data differs from VA/NC data:
- Electric intervals are 15 minutes (kWh). Gas intervals are 1 hour (ft³).
Use
meter_type=MeterType.GASfor gas. - Solar export is a separate meter register with negative values. The client
puts positive values in
consumptionand negative values ingeneration.async_get_register_usage()returns the raw readings for each register. - Timestamps are in
America/New_York. On the DST fall-back day, the two 01:00-01:59 hours have the same wall times. The second hour hasfold=1(EST), so the day has 25 hours (100 electric intervals). Datetimes that differ only infoldcompare equal. To group or deduplicate intervals, usetimestamp.astimezone(UTC)as the key. On the spring-forward day, 02:00-02:59 does not exist. If Bidgely sends readings for these times, the client moves them to 03:00-03:59 EDT and adds them to those intervals. SCBillForecasthas the cost to date, the forecasted cost, and last year's cost. The dollar values include electric and gas together.- A login with more than one account raises
ApiError. - If the TFA token is not accepted,
async_login()raisesTFARequiredError.
The SC backend is a port of
hype8912/dominion-sc-power
(Apache-2.0). See NOTICE.
Data Format
The API returns 30-minute interval data. Example output:
Timestamp Consumption Generation Unit
---------------------------------------------------------
2024-01-15 00:00 0.45 0.01 kWh
2024-01-15 00:30 0.38 0.00 kWh
2024-01-15 01:00 0.42 0.01 kWh
...
Limitations
- TFA verification codes expire after ~5 minutes
- Refresh tokens may expire after extended periods of inactivity
- API rate limits are not documented; library does not implement rate limiting
Development
With uv (recommended)
git clone https://github.com/YeomansIII/dompower
cd dompower
uv sync --dev
uv run pytest
uv run mypy dompower
uv run ruff check dompower
With pip/venv
git clone https://github.com/YeomansIII/dompower
cd dompower
python3 -m venv .venv
source .venv/bin/activate # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"
pytest
mypy dompower
ruff check dompower
License
MIT
Metadata
Release files for dompower 0.3.0a1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| dompower-0.3.0a1.tar.gz | 140.9 kB | With provenance | Details for dompower-0.3.0a1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| dompower-0.3.0a1-py3-none-any.whl | Python 3 | none | any | Details for dompower-0.3.0a1-py3-none-any.whl |
Total release size: 207.7 kB
Release files / dompower-0.3.0a1.tar.gz
| Download URL | dompower-0.3.0a1.tar.gz |
|---|---|
| Size | 140.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b6a0050853976a1cbdc4c246b3ce8550e46d14586964a0c4b5103285b6e58f5f
|
|
BLAKE2b-256 checksum How to use checksums |
c4c849120b346b418c561ff1d0f79210a2ee1aa7d298519a75f60bfdd75a38a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.
Transparency logRelease files / dompower-0.3.0a1-py3-none-any.whl
| Download URL | dompower-0.3.0a1-py3-none-any.whl |
|---|---|
| Size | 66.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0da035f59a982ab796417b7b1bf3d8369657a742ba4d227366aa709e148de0ca
|
|
BLAKE2b-256 checksum How to use checksums |
7b087e4618e99600e9c081b9a2d4adc0fd73c3787b849d0f21803c8a7a500067
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.
Transparency logSecurity for dompower 0.3.0a1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for dompower-0.3.0a1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.