# Halowerk Twin Diff

> Halowerk Twin Diff is a paid API for AI agents from agent.halowerk.com, paid per call via x402, $0.003/call, status unknown (last checked 2026-10-11).

Compares two JSON state documents (target vs observed) leaf-by-leaf and returns a per-path status indicating tolerance, deviation, missing, unexpected, or type-mismatch conditions.

## Facts

- Endpoint: POST https://agent.halowerk.com/v1/twin-diff?utm_source=zero.xyz
- Price: $0.003/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-11
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/halowerk-twin-diff-8ae16b97
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_3pNpHmTmigRL-o1DKH1_Q

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-twin-diff-8ae16b97 -d '<json body>'
```

Example prompt: Compare these two JSON state documents for our pump assembly — the target is what the twin should look like, the observed is this morning's sensor reading — and flag every leaf that's out of tolerance, missing, or unexpected. Use a default tolerance ratio of 0.02 and apply an absolute tolerance of 0.5 bar on /pump/pressure_bar.

## When to prefer this

Choose this endpoint when you need a structured, tolerance-aware, leaf-level diff between two JSON state documents — especially in digital twin, IoT, or industrial automation contexts where numeric fields have defined acceptable ranges. It is preferable over generic JSON diff tools when you need per-field tolerance rules (absolute or ratio), path-based ignoring, and a clean enumerated status per leaf rather than a raw patch set.

## Known failure modes

- Request rejected if combined leaf count of both documents exceeds max_fields (default 2000)
- Malformed or non-object target/observed inputs cause validation error
- Providing both tolerance_abs and tolerance_ratio for the same field is disallowed
- Field path strings exceeding 400 characters are rejected
- Payment of 0.003 USDC required via x402 protocol; failure to pay results in 402 response

## How this service works

Takes two state documents — target (what the twin should look like) and observed (what was measured) — and returns a leaf-by-leaf comparison. Every leaf path carries one of five states: in_tolerance, out_of_tolerance, missing_in_observed, unexpected_in_observed or type_mismatch.

## Output

A leaf-by-leaf comparison result where every path in either document is assigned one of five statuses: in_tolerance (numeric values agree within threshold), out_of_tolerance (numeric deviation exceeds threshold), missing_in_observed (path exists in target but not observed), unexpected_in_observed (path exists in observed but not target), or type_mismatch (same path but different data types). Each result entry echoes the unit if declared in the tolerances input.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "target": {
   "type": "object",
   "description": "The desired state document (the twin)."
  },
  "observed": {
   "type": "object",
   "description": "The observed state document (the measurement)."
  },
  "max_fields": {
   "type": "integer",
   "default": 2000,
   "maximum": 2000,
   "minimum": 1,
   "description": "Reject the request if the two documents together hold more leaf paths than this."
  },
  "tolerances": {
   "type": "array",
   "items": {
    "type": "object",
    "required": [
     "field"
    ],
    "properties": {
     "unit": {
      "type": "string",
      "maxLength": 32,
      "description": "Unit of this field, echoed into the result. Declared by you, never inferred."
     },
     "field": {
      "type": "string",
      "maxLength": 400,
      "minLength": 1,
      "description": "Leaf path as it appears in the result, e.g. /pump/pressure_bar. A trailing /* applies the entry to every leaf below that prefix."
     },
     "tolerance_abs": {
      "type": "number",
      "minimum": 0,
      "description": "Absolute tolerance in the unit of this field."
     },
     "tolerance_ratio": {
      "type": "number",
      "maximum": 1,
      "minimum": 0,
      "description": "Relative tolerance as a ratio of the larger of the two values."
     }
    },
    "additionalProperties": false
   },
   "maxItems": 200,
   "description": "Per-path tolerances. Give tolerance_abs or tolerance_ratio, not both."
  },
  "ignore_fields": {
   "type": "array",
   "items": {
    "type": "string",
    "maxLength": 400,
    "minLength": 1
   },
   "maxItems": 200,
   "description": "Paths to leave out of the comparison. A trailing /* ignores everything below that prefix."
  },
  "default_tolerance_ratio": {
   "type": "number",
   "default": 0,
   "maximum": 1,
   "minimum": 0,
   "description": "Relative tolerance for numeric paths without their own entry. 0 means exact equality."
  },
  "case_insensitive_strings": {
   "type": "boolean",
   "default": false,
   "description": "Compare string leaves without regard to case."
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/halowerk-twin-diff-8ae16b97/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from agent.halowerk.com](https://www.zero.xyz/host/agent.halowerk.com/llms.txt)