# HALOWERK Demand Forecast

> HALOWERK Demand Forecast is a paid API for AI agents from handel.halowerk.com, paid per call via x402, $0.006/call, status unknown (last checked 2026-11-16).

Forecasts future demand for a single SKU using multiplicative or additive decomposition, with the full pipeline logic disclosed in the response.

## Facts

- Endpoint: POST https://handel.halowerk.com/v1/demand-forecast?utm_source=zero.xyz
- Price: $0.006/call
- Payment: x402
- Status: unknown
- Last checked: 2026-11-16
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/halowerk-demand-forecast-b07f5f39
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_JbOo2eS85iodzrVr9J6K1

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 halowerk-demand-forecast-b07f5f39 -d '<json body>'
```

Example prompt: Forecast weekly demand for the next 8 weeks for my product using this sales history — weeks 1 through 52 of last year with quantities, noting that weeks 10 and 24 had promotions and week 15 was a holiday — and backtest against the last 4 periods so I can see how accurate it is.

## When to prefer this

Choose this endpoint when you need a transparent, interpretable single-SKU demand forecast where the pipeline logic (decomposition method, seasonal index calculation) is fully disclosed rather than hidden behind a black-box score. It is especially suited for cases where promotion and holiday periods must be excluded from baseline seasonality estimation, and where backtest comparison against naive baselines is needed to validate forecast quality.

## Known failure modes

- Fewer than 4 history entries provided — returns validation error
- Non-consecutive or non-unique period_start values — returns validation error
- All quantities are zero preventing meaningful decomposition — may return degenerate forecast
- Horizon exceeds 104 periods — returns validation error
- Backtest periods exceed available history — returns validation error
- Unmatched future_events entries reported in response but do not cause failure

## How this service works

Forecasts one SKU from a history you supply. The pipeline is fixed and fully disclosed in the response rather than hidden behind a score. The series is decomposed multiplicatively while every observation is positive and additively as soon as a zero or a negative appears, because a ratio is not defined there; the seasonal index is the median ratio per phase against a centred moving average, estimated only on periods that carry no promotion and no holiday so that a campaign in week twelve does…

## Output

Returns a per-period demand forecast for the requested horizon, the decomposition method used (multiplicative or additive), seasonal indices per phase, trend component, and optionally backtest accuracy metrics comparing the model against held-out periods and baseline models. Any future_events entries that did not match a forecast period are returned as unmatched.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "history": {
   "type": "array",
   "items": {
    "type": "object",
    "required": [
     "period_start",
     "quantity"
    ],
    "properties": {
     "holiday": {
      "type": "boolean",
      "default": false,
      "description": "Whether that period contained a holiday you consider relevant. The calendar is yours; no holiday list is looked up."
     },
     "quantity": {
      "type": "number",
      "maximum": 1000000000,
      "minimum": -1000000000,
      "description": "Units sold in that period. Zero is allowed and switches the decomposition to additive."
     },
     "promotion": {
      "type": "boolean",
      "default": false,
      "description": "Whether the SKU was on promotion in that period."
     },
     "period_start": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First day of the period as YYYY-MM-DD."
     }
    },
    "additionalProperties": false
   },
   "maxItems": 520,
   "minItems": 4,
   "description": "The demand history, one entry per period, oldest first. Periods must be consecutive and each period_start must be unique and ascending."
  },
  "frequency": {
   "enum": [
    "daily",
    "weekly",
    "monthly"
   ],
   "type": "string",
   "description": "Length of one period. Sets the default season length: 7 for daily, 52 for weekly, 12 for monthly."
  },
  "future_events": {
   "type": "array",
   "items": {
    "type": "object",
    "required": [
     "period_start"
    ],
    "properties": {
     "holiday": {
      "type": "boolean",
      "default": false
     },
     "promotion": {
      "type": "boolean",
      "default": false
     },
     "period_start": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First day of the forecast period this applies to."
     }
    },
    "additionalProperties": false
   },
   "maxItems": 104,
   "description": "Promotions and holidays you already know about for the forecast periods. Matched on period_start against the generated periods; an entry that matches no period is reported back as unmatched."
  },
  "horizon_periods": {
   "type": "integer",
   "default": 8,
   "maximum": 104,
   "minimum": 1,
   "description": "How many periods to forecast."
  },
  "backtest_periods": {
   "type": "integer",
   "default": 0,
   "maximum": 52,
   "minimum": 0,
   "description": "How many of the last periods to hold back for the comparison against the baselines. Z
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/halowerk-demand-forecast-b07f5f39/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from handel.halowerk.com](https://www.zero.xyz/host/handel.halowerk.com/llms.txt)
