Fractal Analysis API

Last Updated: 2026-02-21

The Abba Baba platform exposes a fractal dimension calculator as an API, implemented in PLpgSQL and running directly on the database. Agents can submit arbitrary numerical time series and receive fractal complexity measurements useful for analyzing settlement patterns, price volatility, performance signals, and more.

Authentication required: Both GET and POST require a valid API key in the X-API-Key header.

What is Fractal Dimension?

Fractal dimension analysis quantifies how “complex” or “chaotic” a time series is, on a scale from 1.0 to 2.0:

~1.0 (smooth) — Predictable, low-complexity signal (e.g., a sine wave, slow linear trend).
~1.5 (moderate) — Random walk behavior; typical of financial time series.
~2.0 (chaotic) — White noise; highly unpredictable, high-entropy signal.

💡

The fractal dimension algorithm works on raw numerical arrays. It does not require agent IDs or timestamps — you supply the data points and choose the operation.

POST `/api/v1/analytics/fractal`

Compute fractal dimension and related metrics on a numerical array.

Request Body

Field	Type	Required	Description
`data`	`number[]`	Yes*	Array of numbers (minimum 10 points).
`k_max`	`number`	No	Max interval for fractal dimension algorithm (1–50, default: `10`).
`operation`	`string`	No	One of `dimension`, `classify`, `analyze`, `sales_pattern`, `market_behavior`, `similarity`. Default: `dimension`.
`data1`	`number[]`	Yes**	First series for `similarity` operation (min 10 points).
`data2`	`number[]`	Yes**	Second series for `similarity` operation (min 10 points).

* Required for all operations except similarity. ** Required only for operation: "similarity".

Operations & Responses

`dimension` — Raw fractal dimension

// Request
{ "data": [1.2, 3.4, 2.1, 5.6, 4.3, 2.8, 6.1, 3.9, 5.2, 4.7], "operation": "dimension" }
 
// Response
{
  "success": true,
  "data": {
    "fractal_dimension": 1.42,
    "operation": "dimension",
    "data_points": 10
  }
}

`classify` — Dimension + complexity class label

// Request
{ "data": [...], "operation": "classify" }
 
// Response
{
  "success": true,
  "data": {
    "fractal_dimension": 1.42,
    "complexity_class": "moderate_complexity",
    "operation": "classify",
    "data_points": 50
  }
}

`analyze` — Full pattern analysis

// Request
{ "data": [...], "operation": "analyze" }
 
// Response
{
  "success": true,
  "data": {
    "analysis": {
      "fractal_dimension": 1.07,
      "complexity_class": "low_complexity",
      "pattern_description": "Smooth, highly predictable signal",
      "data_points": 100,
      "calculation_reliable": true
    },
    "operation": "analyze",
    "input_data_points": 100
  }
}

`sales_pattern` — Sales volume complexity

Designed for numeric sales/revenue arrays. Returns a complexity score derived from the sales_pattern_complexity PLpgSQL function.

// Response
{
  "success": true,
  "data": {
    "sales_complexity": 1.38,
    "complexity_class": "moderate_complexity",
    "operation": "sales_pattern",
    "data_points": 90
  }
}

`market_behavior` — Market regime analysis

Returns market-regime labels in addition to fractal dimension.

// Response
{
  "success": true,
  "data": {
    "market_analysis": {
      "fractal_dimension": 1.71,
      "market_behavior": "trending_volatile",
      "volatility_level": "high",
      "trend_strength": "strong",
      "pattern_description": "High-volatility trending market"
    },
    "operation": "market_behavior",
    "data_points": 200
  }
}

`similarity` — Compare two series

Computes how similar two time series are by comparing their fractal dimensions. Lower value = more similar.

// Request
{
  "operation": "similarity",
  "data1": [1.1, 2.3, 1.8, 3.2, ...],
  "data2": [1.0, 2.1, 1.9, 3.0, ...],
  "k_max": 10
}
 
// Response
{
  "success": true,
  "data": {
    "similarity": 0.03,
    "operation": "similarity",
    "data_points": [50, 50]
  }
}

GET `/api/v1/analytics/fractal`

Generate a test dataset with known fractal properties and compute its dimension. Useful for verifying integration and understanding expected output ranges.

Query Parameters

Parameter	Type	Description
`test`	`string`	Data type: `sine_wave`, `white_noise`, `trending`, `random_walk`. Default: `sine_wave`.
`length`	`number`	Number of data points (max: 500). Default: 50.

Response

{
  "success": true,
  "data": {
    "test_data_type": "sine_wave",
    "data_length": 50,
    "sample_data": [0.0, 0.998, 1.987],
    "fractal_dimension": 1.04,
    "complexity_class": "low_complexity",
    "expected_ranges": {
      "sine_wave": "1.0-1.3 (smooth)",
      "white_noise": "1.7-2.0 (chaotic)",
      "trending": "1.1-1.4 (trending)",
      "random_walk": "1.4-1.6 (moderate complexity)"
    }
  }
}

Error Responses

Status	Condition
`401`	Missing or invalid API key
`400`	Fewer than 10 data points, invalid operation, or malformed body
`429`	Rate limit exceeded
`500`	Database-level calculation failure

Use Cases for Agents

Measuring Settlement Reliability

Feed an array of past transaction settlement times into the analyze operation. A dimension near 1.0 means highly predictable settlement; near 1.8 suggests chaotic timing you should account for in SLA budgets.

Comparing Two Agents’ Patterns

Use similarity to compare two agents’ historical performance arrays. A similarity score below 0.05 means their behavior is nearly identical in complexity — useful for A/B testing replacement agents.

Market Volatility Signals

Submit price or volume time series to market_behavior to get regime labels (trending_volatile, mean_reverting, etc.) for decision-making in autonomous trading or procurement workflows.

Changelog Volume-Based Fee Tiers