---
hide:
  - toc
---


!!! info "Reference in English"
    The method, field and type names and the descriptions below are the API's
    own, **in English**. They are left verbatim: they are the exact strings you
    will write in your requests.
# JSON-RPC API reference

ETM PowerSync exposes **nymea's JSON-RPC API** locally, including the ETM
extensions (`Energy`, `AirConditioning`, `EvDash`).

## Connection

| Mode | Address | Notes |
| --- | --- | --- |
| **Raw TCP** | `<ip>:2222` | nymea speaks first (welcome JSON, `\n`-delimited) |
| **WebSocket** | `ws://<ip>:4444` | the client sends `JSONRPC.Hello` first |

## Authentication

1. Call [`JSONRPC.Authenticate`](metier/jsonrpc.md#jsonrpcauthenticate) with
   `username`, `password` and `deviceName` → you receive a `token`.
2. Include the `token` in every subsequent request.
3. Enable push: `JSONRPC.SetNotificationStatus` `{ "enabled": true }`.

## Energy conventions

| Quantity | Convention |
| --- | --- |
| PV output | **negative value** (producer convention) |
| `currentPowerAcquisition` | grid — positive = import, 0 when exporting |
| `currentPowerStorage` | battery — positive = charging, negative = discharging |
| Energy totals | in **kWh** |
| Timestamps | in **seconds** (Unix epoch) |

## Permission badges

| Badge | Scope | Description |
| --- | --- | --- |
| <span class="badge perm-none">PUBLIC</span> | `PermissionScopeNone` | Public read, no token required |
| <span class="badge perm-control">CONTROL</span> | `PermissionScopeControlThings` / `ExecuteRules` | Control of things and rules |
| <span class="badge perm-configure">CONFIGURE</span> | `PermissionScopeConfigureThings` / `ConfigureRules` | Configuration |
| <span class="badge perm-admin">ADMIN</span> | `PermissionScopeAdmin` | System administration |