JSON Payload Schema

The internal execution engine processes data using Pandas and NumPy. To securely bridge this data to frontends or APIs, the KafalSerializer standardizes all outputs into a strict JSON contract.

Serialization Rules

The serializer enforces specific data coercions to ensure UI stability and optimize response payloads:

Timestamp Conversion: Pandas DatetimeIndex objects are converted directly to Unix milliseconds.
Null Coercion: Values resulting in NaN, NaT, or Inf are omitted or converted to JSON null. Datapoints containing invalid floats are completely removed to reduce payload weight.
Series Format: Time-series data is formatted as arrays of coordinate objects (e.g., { "time": 1672531200000, "value": 150.5 }) rather than parallel arrays.

Payload Structure

The top-level structure remains consistent regardless of the execution mode. Unused components return empty arrays or objects.

{
  "mode": "chart",
  "meta": {
    "name": "My Strategy",
    "overlay": true
  },
  "inputs_schema": {
    "length": { "type": "int", "default": 14 }
  },
  "plots": [
    {
      "id": "Fast EMA",
      "title": "Fast EMA",
      "data": [
        { "time": 1672531200000, "value": 150.5 },
        { "time": 1672617600000, "value": 152.0 }
      ],
      "style": { "color": "green", "width": 2 }
    }
  ],
  "alerts": [
    {
      "signals": [ { "time": 1672617600000 } ],
      "message": "Buy Signal Triggered",
      "severity": "info"
    }
  ],
  "strategy": {
    "stats": {
      "net_profit": 5420.50,
      "max_drawdown": 1200.0,
      "sharpe": 1.45,
      "win_rate": 0.58,
      "trades": 14,
      "exposure": 0.85
    },
    "trades": [
      {
        "symbol": "AAPL",
        "direction": "long",
        "size": 10.0,
        "entry_time": 1672531200000,
        "exit_time": 1672617600000,
        "entry_price": 150.0,
        "exit_price": 155.0,
        "pnl": 50.0,
        "commission": 0.15
      }
    ],
    "equity": [ ... ],
    "position": [ ... ]
  },
  "features": {},
  "shapes": [],
  "fills": [],
  "hlines": [],
  "bgcolors": [],
  "tables": []
}