# Netzhandwerker Energy Decision API

> Netzhandwerker Energy Decision API is a paid API for AI agents from energy.netzhandwerker.de, paid per call via x402, $0.01/call, status unknown (last checked 2026-09-15).

Returns an AI-optimized energy action recommendation — including live electricity prices, carbon intensity, grid flexibility windows, battery arbitrage signals, and ESG data — given a device, goal, location, and deadline.

## Facts

- Endpoint: POST https://energy.netzhandwerker.de/energy/decision
- Price: $0.01/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/netzhandwerker-energy-decision-api-a40d8c6c
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_A5T7UKcrKbZ5uvEFnNgIz

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability netzhandwerker-energy-decision-api-a40d8c6c -d '<json body>'
```

Example prompt: I want to charge my Tesla in Berlin tonight — what's the best 2-hour window in the next 8 hours to minimize both cost and carbon emissions, and are there any grid flexibility constraints I should know about?

## When to prefer this

Choose this endpoint when you need a holistic, AI-ready energy action decision that combines live market prices, carbon intensity, grid state, and flexibility signals into a single actionable recommendation. Prefer this over pure price APIs when you also need carbon/ESG context, battery arbitrage guidance, or device-specific scheduling optimization.

## Known failure modes

- Unsupported location returns empty or null grid data
- Deadline in the past causes invalid scheduling response
- Unknown device type may result in generic rather than device-specific recommendations
- Missing required 'goal' field causes a 400 bad request
- Location outside covered grid zones returns no data or error
- Constraints object with conflicting rules may produce suboptimal or null recommendations

## How this service works

One x402 call returns the action, best time window, expected EUR value, confidence and expiry for German and European electricity decisions. USDC on Base, no API key or account.

## Output

A structured decision response containing the recommended action or optimal time window for the specified device and goal, backed by live electricity price data, carbon intensity scores, current grid load, renewable energy share, identified flexibility windows, battery arbitrage signals, and ESG metrics for the specified location and time horizon.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method",
    "bodyType",
    "body"
   ],
   "properties": {
    "body": {
     "type": "object",
     "properties": {
      "goal": {
       "enum": [
        "minimize_cost",
        "minimize_carbon",
        "balanced",
        "maximize_self_consumption",
        "trading_signal"
       ],
       "type": "string",
       "default": "balanced"
      },
      "device": {
       "enum": [
        "ev",
        "battery",
        "heat_pump",
        "flexible_load",
        "generic"
       ],
       "type": "string",
       "default": "generic"
      },
      "deadline": {
       "type": "string"
      },
      "location": {
       "type": "string",
       "default": "Germany"
      },
      "constraints": {
       "type": "object",
       "properties": {
        "min_soc": {
         "type": "number"
        },
        "target_soc": {
         "type": "number"
        },
        "max_power_kw": {
         "type": "number"
        },
        "must_finish_by": {
         "type": "string"
        }
       },
       "additionalProperties": false
      },
      "duration_hours": {
       "type": "integer",
       "default": 4,
       "maximum": 24,
       "minimum": 1
      },
      "policy_profile": {
       "enum": [
        "balanced",
        "utility",
        "precision",
        "recall"
       ],
       "type": "string",
       "description": "Optional override. Trading defaults to precision; flexible devices default to utility."
      }
     },
     "additionalProperties": false
    },
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "POST",
      "PUT",
      "PATCH"
     ],
     "type": "string"
    },
    "bodyType": {
     "enum": [
      "json",
      "form-data",
      "text"
     ],
     "type": "string"
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "required": [
      "ok",
      "endpoint",
      "result"
     ],
     "properties": {
      "ok": {
       "type": "boolean"
      },
      "result": {
       "type": "object",
       "required": [
        "schema_version",
        "decision_id",
        "action",
        "c
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "ok": true,
  "result": {
   "action": "charge_later",
   "confidence": 0.74,
   "expires_at": "2026-07-12T13:00:00.000Z",
   "risk_flags": [],
   "decision_id": "dec_example_001",
   "schema_version": "energy_decision_v1",
   "estimated_value": {
    "currency": "EUR",
    "expected_saving": 1.82
   },
   "recommended_window": {
    "end": "2026-07-12T17:00:00.000Z",
    "start": "2026-07-12T13:00:00.000Z"
   }
  },
  "endpoint": "/energy/decision"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/netzhandwerker-energy-decision-api-a40d8c6c/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from energy.netzhandwerker.de](https://www.zero.xyz/host/energy.netzhandwerker.de/llms.txt)