hyxi-cloud-api
An asynchronous Python client for interacting with the HYXI Cloud API.
This library was primarily built to power the HYXI Cloud Home Assistant Integration, but it can be used in any Python 3.14 project to fetch telemetry data from HYXI solar inverters and battery systems.
📦 Installation
You can install the package directly from PyPI:
pip install hyxi-cloud-api
🚀 Quick Start
This library uses aiohttp for non-blocking network requests. You will need to provide your Developer API credentials (AK/SK), along with an active aiohttp.ClientSession.
import asyncio
import aiohttp
from hyxi_cloud_api import HyxiApiClient
async def main():
# Replace with your actual HYXi Cloud credentials
ACCESS_KEY = "your_access_key"
SECRET_KEY = "your_secret_key"
BASE_URL = "https://open.hyxicloud.com"
async with aiohttp.ClientSession() as session:
# 1. Initialize the client
client = HyxiApiClient(
access_key=ACCESS_KEY,
secret_key=SECRET_KEY,
base_url=BASE_URL,
session=session,
)
# 2. Fetch device data
try:
device_data = await client.get_all_device_data()
print("Successfully fetched HYXi data:")
print(device_data)
except Exception as e:
print(f"Error communicating with HYXi Cloud: {e}")
if __name__ == "__main__":
asyncio.run(main())
HYXI Open API base URLs vary by region. The examples in this README use the Europe endpoint by default.
| Node | Request Address |
|---|---|
| China | https://open-cn.hyxicloud.com |
| Europe (default) | https://open.hyxicloud.com |
| North America | https://open-or.hyxicloud.com |
After a token is fetched (await client.ensure_token(), or any request), client.authorization_type says which authorization HYXI granted the keys: AuthorizationType.USER, AuthorizationType.VPP or AuthorizationType.PLANT, or None if HYXI's token response didn't report a known type.
🔧 Device Control
You can control inverter operating modes directly through the API. This requires a device serial number, which you can obtain from the device data response above.
async def control_example(client, device_sn):
# Set operating mode
await client.set_mode_self_consume(device_sn)
await client.set_mode_self_consume_with_charging(device_sn)
await client.set_mode_charge(device_sn, watts=3000)
await client.set_mode_discharge(device_sn, watts=2500)
await client.set_mode_idle(device_sn)
# Peak shaving (close, charge, discharge, stop, hold)
await client.set_peak_shaving(device_sn, action="charge")
# Frequency control
await client.set_frequency_control(device_sn, enabled=True)
Control failures raise HyxiApiClient.ControlError:
try:
await client.set_mode_charge(device_sn, watts=3000)
except client.ControlNotForwardedError as e:
print(f"Accepted but not forwarded to the device: {e}")
except client.ControlError as e:
print(f"Control command failed: {e}")
HYXI only forwards its VPP control commands (controlIds 1062-1068; the set_mode_* helpers send 1062-1066) to devices the credentials are VPP-authorized for. With other credentials HYXI accepts the request but answers with a traceId of "SKIPPED" and never sends it on; the client raises ControlNotForwardedError, a subclass of ControlError, in that case, with HYXI's answer (including its requestId) in its response attribute.
Control commands are fire-and-forget; poll query_control_result with the traceId from the response to confirm the device actually applied it:
response = await client.set_mode_charge(device_sn, watts=3000)
trace_id = response["data"][0]["traceId"]
result = await client.query_control_result(trace_id)
# result["data"]["result"]: "2" (issuing), "3" (success), "6" (failure)
🔔 Subscriptions
You can subscribe a callback URL to HYXI push notifications for real-time data, alarms, and FCAS/frequency-modulation real-time data.
The callback URL must use HTTPS and contain no credentials: HYXI sends each push
with your AccessKey in its headers and lists the URL with the subscription, so
subscribe_* raises ValueError for any other URL.
async def subscription_example(client):
callback_url = "https://your-public-callback-host/hyxi/callback"
device_sns = ["60700000000001", "60700000000002"]
real_time = await client.subscribe_real_time_data(
callback_url,
device_sns,
post_rate=60000, # milliseconds, 5000-3600000
)
alarm = await client.subscribe_alarm(
callback_url,
device_sns,
post_rate=60000, # milliseconds, 5000-3600000
)
fcas = await client.subscribe_fm_real_time_data(
callback_url,
device_sns,
post_rate=1, # hours, 1-6
)
await client.cancel_subscription(real_time.subscribe_code)
Each subscribe_* call returns a SubscribeResult with the subscribe_code HYXI gave the subscription, and raises HyxiApiClient.SubscriptionError if HYXI's answer has none.
list_subscriptions() returns the subscriptions HYXI holds for your credentials; pass a device_sn to list only those associated with that device. For example, to see which of them deliver to your callback URL:
async def my_subscriptions(client, callback_url):
return [
sub
for sub in await client.list_subscriptions()
if sub.callback_url == callback_url
]
Each entry is a Subscription with its subscribe_code (for cancel_subscription), subscribe_type (a SubscriptionType, such as SubscriptionType.ALARM), callback_url, create_time and associated devices.
Subscription failures raise HyxiApiClient.SubscriptionError.
🛠️ Requirements
- Python 3.14 (not yet 3.15 — the upper bound lifts once 3.15 is covered by CI)
aiohttp>= 3.13.5
🔐 Privacy & Debug Logging
When debug logging is enabled, this library automatically masks sensitive identifiers before writing them to the log — no manual redaction needed.
| Field | Behaviour |
|---|---|
Serial numbers (deviceSn, parentSn, batSn) |
Hashed securely using SHA-256 (first 8 chars shown) to enable deterministic cross-device tracing without exposing the original identifier, e.g. e3b0c442 |
Plant IDs (plantId) |
Same SHA-256 hashing format |
Home/site address (plantAddress) |
Fully redacted → [REDACTED] |
IMEI (gprsImei) |
Same SHA-256 hashing format |
Masking is deterministic, so parent/child device relationships remain traceable across log lines.
⚠️ Disclaimer
This is an unofficial, community-driven project. It is not affiliated with, endorsed by, or connected to HYXiPower in any official capacity. Use this software at your own risk.
Support
If this library is useful to you and you'd like to support its development:
1 maintainer
Metadata
1 maintainer
Release files for hyxi-cloud-api 1.5.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| hyxi_cloud_api-1.5.6.tar.gz | 116.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| hyxi_cloud_api-1.5.6-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 159.1 kB
Release files / hyxi_cloud_api-1.5.6.tar.gz
| Download URL | hyxi_cloud_api-1.5.6.tar.gz |
|---|---|
| Size | 116.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0468ea6d4b0756d04cb5c3ae5ded4ce6a647cc2275851687efabba76385ab90a
|
|
BLAKE2b-256 checksum How to use checksums |
2fd463751b5cc107969b106b59058be9cb6c5896a9d9f7c8a7920974b73e65a3
|
| 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 15, 2026.
Transparency logRelease files / hyxi_cloud_api-1.5.6-py3-none-any.whl
| Download URL | hyxi_cloud_api-1.5.6-py3-none-any.whl |
|---|---|
| Size | 43.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
875d3eca74abbf85e61d77baf91c274b3238292d8cabc564962af4d437c4c53d
|
|
BLAKE2b-256 checksum How to use checksums |
31da5884a2b3022e0b8e88601c394827cab6f56b719a66bafeed82d1ced84a38
|
| 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 15, 2026.
Transparency log
