---
title: "Get Basic Confluence Matrix"
method: GET
path: "/api/signals/basic/confluence-matrix"
tags: ["Trade Signals"]
---

# Get Basic Confluence Matrix

`GET /api/signals/basic/confluence-matrix`

## Request

- Base URL: `https://api.zerogex.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.zerogex.io/api/signals/basic/confluence-matrix`
- Auth: HTTP bearer

6×6 basic-signal agreement matrix — pairwise directional confluence.

Parallel to `/api/signals/advanced/confluence-matrix`, scoped to the six
Basic Signals persisted by `BasicSignalEngine`. Answers: *which of my
basic signals normally agree, and where is an unusual divergence right now?*
Continuous directional reads (no triggered events) — every non-zero
snapshot contributes to agreement/disagreement counts.

**Logic** (`src/api/database.py`): Joins `signal_scores` ×
`signal_component_scores` for the last `lookback` timestamps, filtered
to the six basic signal names. Each score is bucketed `+1 / 0 / −1`
with `neutral_epsilon = 0.02`. For each ordered pair `(c1, c2)`:
- `observations` = cycles where both signals have data.
- `active_observations` = cycles where both signs are non-zero.
- `agreement` = same non-zero sign; `disagreement` = opposite non-zero signs.

**Params:**
- `symbol` (default `SPY`).
- `lookback` — 10–2000, default 120. Number of recent timestamps.

**Signals (6, fixed order):** `tape_flow_bias`, `skew_delta`,
`vanna_charm_flow`, `dealer_delta_pressure`, `gex_gradient`, `positioning_trap`.

**Returns:**
```json
{
  "underlying": "SPY",
  "lookback": 120,
  "components": ["tape_flow_bias", "skew_delta", "vanna_charm_flow",
                 "dealer_delta_pressure", "gex_gradient", "positioning_trap"],
  "row_order":  ["tape_flow_bias", "skew_delta", "...4 more..."],
  "matrix": {
    "tape_flow_bias": {
      "skew_delta": {
        "observations": 118,
        "active_observations": 92,
        "agreement_count": 74,
        "disagreement_count": 18,
        "neutral_count": 26,
        "agreement_ratio": 0.8043,
        "disagreement_ratio": 0.1957,
        "net_confluence": 0.6087
      }
    }
  },
  "sample_count": 118,
  "latest_timestamp": "2026-04-22T18:55:00Z"
}
```

- `components` / `row_order` — length-6 string array; axis labels.
- `matrix[c1][c2].observations` — int, `[0, lookback]`; cycles where both had data.
- `matrix[c1][c2].active_observations` — int, `[0, observations]`; both non-zero.
- `matrix[c1][c2].agreement_count` — int, `[0, active_observations]`.
- `matrix[c1][c2].disagreement_count` — int, `[0, active_observations]`.
- `matrix[c1][c2].neutral_count` — int, `[0, observations]`; at least one side was 0.
- `matrix[c1][c2].agreement_ratio` — `[0, 1]` | `null` if `active == 0`; 4 decimals.
- `matrix[c1][c2].disagreement_ratio` — `[0, 1]` | `null`.
- `matrix[c1][c2].net_confluence` — `[-1, +1]`; `0.0` if `active == 0`. Heatmap value.
- `sample_count` — int; distinct timestamps aggregated.
- `latest_timestamp` — ISO-8601 UTC | `null` if empty.

**Trader interpretation.**
- `net_confluence > +0.5` — pair agrees > 75% of active cycles. Live
  **disagreement** from such a pair is a flag.
- `net_confluence < −0.3` — pair structurally disagrees. Live
  **agreement** = unusual consensus.
- `active_observations < ~20` — weak sample; discount.
- Diagonal cells always `net_confluence = 1.0`; sanity check only.

**Page design.** 6×6 heatmap with diverging color scale (green = +1
agree, white = 0, red = −1 disagree). Cell tooltip shows
`agreement_ratio / disagreement_ratio / observations`. Sort rows by
average `agreement_ratio` to surface consensus signals at top, outliers
at bottom. Symmetric — render only the upper triangle if space-constrained.

## Query parameters

- `symbol` string
- `lookback` integer

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/zerogex/apis/zerogex-api.md) · [All operations](https://skmtc.dev/zerogex/apis/zerogex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zerogex/apis/zerogex-api/revisions/753b26bf0592?raw)