API Reference

Programmatic access to the Fourth Stomach framework. Portfolio optimisation, thermodynamic index computation, and circuit graph analysis. Requires an API key obtained through licensing.

Authentication

All requests require an API key in the header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.fourthstomach.io/v1/portfolio/optimize

Portfolio Optimisation

POST/v1/portfolio/optimize

Run trajectory completion on a portfolio circuit graph. Returns the unique fixed-point optimal allocation.

Parameters

{
  "assets": [
    { "name": "AAPL", "value": 150.0, "uncertainty": 10.0 },
    { "name": "GOOGL", "value": 2800.0, "uncertainty": 50.0 }
  ],
  "couplings": [
    { "from": "AAPL", "to": "GOOGL", "conductance": 0.7 }
  ],
  "max_iterations": 500,
  "tolerance": 1e-8
}

Response

{
  "fixed_point": {
    "AAPL": { "weight": 0.45, "centroid": 148.3, "support_width": 4.2 },
    "GOOGL": { "weight": 0.55, "centroid": 2790.1, "support_width": 18.7 }
  },
  "iterations": 47,
  "contraction_rate": 0.72,
  "fiedler_value": 1.4,
  "fuzzy_risk": 0.0083
}

GET/v1/portfolio/fiedler

Compute the Fiedler value (algebraic connectivity) of the portfolio graph.

Parameters

{ "portfolio_id": "pf_abc123" }

Response

{ "fiedler_value": 2.34, "spectral_gap": 1.87 }

POST/v1/portfolio/shock

Simulate shock propagation from a boundary node through the circuit graph.

Parameters

{
  "portfolio_id": "pf_abc123",
  "shock_node": "AAPL",
  "shock_magnitude": 25.0
}

Response

{
  "propagation": [
    { "node": "AAPL", "distance": 0, "amplitude": 25.0 },
    { "node": "GOOGL", "distance": 1, "amplitude": 9.55 },
    { "node": "MSFT", "distance": 2, "amplitude": 3.65 }
  ],
  "decay_rate": 0.963
}

Distributed Thermodynamic Index

POST/v1/dti/compute

Compute the full thermodynamic state of a market gas from transaction data.

Parameters

{
  "stocks": ["AAPL", "GOOGL", "MSFT", "AMZN"],
  "transactions": "timeseries_id_xyz",
  "window_days": 30
}

Response

{
  "temperature": 5.23,
  "pressure": 0.047,
  "entropy": 1842.5,
  "free_energy": -9632.1,
  "phase": "liquid",
  "critical_distance": 0.34,
  "per_stock_entropy": {
    "AAPL": { "S_k": 0.42, "S_t": 0.61, "S_e": 0.38 },
    "GOOGL": { "S_k": 0.55, "S_t": 0.47, "S_e": 0.52 }
  }
}

GET/v1/dti/chemical-potential

Compute the chemical potential (true thermodynamic valuation) for each stock.

Parameters

{ "market_id": "mkt_sp500" }

Response

{
  "chemical_potentials": {
    "AAPL": -2.31,
    "GOOGL": -1.87,
    "TSLA": 0.45
  },
  "spontaneous_inclusions": ["AAPL", "GOOGL"],
  "spontaneous_exclusions": ["TSLA"]
}

GET/v1/dti/phase

Determine the current market phase (gas/liquid/crystal) and distance from critical point.

Parameters

{ "market_id": "mkt_sp500" }

Response

{
  "phase": "liquid",
  "T_over_Tc": 0.87,
  "gibbs_degrees_freedom": 1,
  "carnot_bound": 0.72
}

Circuit Graph Analysis

POST/v1/circuit/build

Construct a portfolio circuit graph from asset data and correlation matrix.

Parameters

{
  "assets": [...],
  "correlation_source": "returns_60d",
  "conductance_weights": {
    "statistical": 0.4, "economic": 0.3,
    "structural": 0.2, "information": 0.1
  }
}

Response

{
  "graph_id": "cg_def456",
  "n_nodes": 50,
  "n_edges": 234,
  "fiedler_value": 3.12,
  "connected_components": 1
}

POST/v1/circuit/harmonic

Detect harmonic coincidences in the asset return spectra and build the shadow portfolio network.

Parameters

{
  "graph_id": "cg_def456",
  "fft_window": 60,
  "tolerance": 0.05
}

Response

{
  "shadow_edges": 187,
  "coincidences": [
    { "pair": ["AAPL", "MSFT"], "order": [2, 3], "correlation": 0.84 }
  ],
  "regime": "stable"
}

Rate Limits

Research

100 requests/day

Commercial

10,000 requests/day

Enterprise

Unlimited