# Analytics

Understand market signals, routing decisions and modeled outcomes.

Signals depend on available observations. Empty series and null metrics are meaningful states. Modeled uplift and advisor output do not represent executed transactions. See [monitoring](/operate/monitoring/).

[Authentication](/build/authentication/) · [Errors](/build/errors/) · [Amounts and units](/build/units/)


Response examples below come from a local test account. IDs, balances and timestamps are sample data. Replace IDs and credentials with values from your account.


## Risk-adjusted venue signals from observed APY history

`GET /analytics/signals`


Scope: `read` or `partner:read` (protocol-level, same answer for every caller). Volatility/trend fields are null with `insufficient_history: true` until enough hourly snapshots exist.


**Access:** `read`, `partner:read`.


**SDK methods:** TypeScript `client.analytics.signals(…)`; Python `client.analytics.signals(…)`.


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `asset` | query | `"USDC"`, `"USDT0"` | No | Filter by asset symbol. |

### Request example

```bash
curl --fail-with-body -X GET "$THESAUROS_API_BASE/analytics/signals" \
  -H "Authorization: Bearer $THESAUROS_API_KEY"
```

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [SignalDto](/api/partner-models/#signaldto)[] | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "list",
  "data": [
    {
      "object": "signal",
      "vault_id": "vault_plasma_usdt0",
      "name": "Thesauros USDT0 Vault",
      "provider": "morpho",
      "asset": "USDT0",
      "chain": "plasma",
      "risk_tier": "core",
      "apy": 0.076,
      "volatility": null,
      "trend_slope_bps_day": null,
      "forecast_apy": null,
      "risk_factor": 0.92,
      "risk_adjusted_apy": 0.0699,
      "observations": 0,
      "insufficient_history": true,
      "rank": 1,
      "recommendation": "overweight"
    },
    {
      "object": "signal",
      "vault_id": "vault_morpho_base_usdc",
      "name": "Morpho Blue USDC Yield",
      "provider": "morpho",
      "asset": "USDC",
      "chain": "base",
      "risk_tier": "core",
      "apy": 0.068,
      "volatility": null,
      "trend_slope_bps_day": null,
      "forecast_apy": null,
      "risk_factor": 0.92,
      "risk_adjusted_apy": 0.0626,
      "observations": 0,
      "insufficient_history": true,
      "rank": 2,
      "recommendation": "neutral"
    },
    {
      "object": "signal",
      "vault_id": "vault_aave_base_usdc",
      "name": "Aave V3 USDC Core",
      "provider": "aave",
      "asset": "USDC",
      "chain": "base",
      "risk_tier": "bluechip",
      "apy": 0.052,
      "volatility": null,
      "trend_slope_bps_day": null,
      "forecast_apy": null,
      "risk_factor": 1,
      "risk_adjusted_apy": 0.052,
      "observations": 0,
      "insufficient_history": true,
      "rank": 3,
      "recommendation": "neutral"
    },
    {
      "object": "signal",
      "vault_id": "vault_compound_arb_usdc",
      "name": "Compound V3 USDC",
      "provider": "compound",
      "asset": "USDC",
      "chain": "arbitrum",
      "risk_tier": "bluechip",
      "apy": 0.045,
      "volatility": null,
      "trend_slope_bps_day": null,
      "forecast_apy": null,
      "risk_factor": 1,
      "risk_adjusted_apy": 0.045,
      "observations": 0,
      "insufficient_history": true,
      "rank": 4,
      "recommendation": "neutral"
    },
    {
      "object": "signal",
      "vault_id": "vault_compound_base_usdc",
      "name": "Compound V3 USDC Base",
      "provider": "compound",
      "asset": "USDC",
      "chain": "base",
      "risk_tier": "core",
      "apy": 0.048,
      "volatility": null,
      "trend_slope_bps_day": null,
      "forecast_apy": null,
      "risk_factor": 0.92,
      "risk_adjusted_apy": 0.0442,
      "observations": 0,
      "insufficient_history": true,
      "rank": 5,
      "recommendation": "neutral"
    },
    {
      "object": "signal",
      "vault_id": "vault_treasury_base_usdc",
      "name": "Tokenized Treasury USDC",
      "provider": "treasury",
      "asset": "USDC",
      "chain": "base",
      "risk_tier": "bluechip",
      "apy": 0.039,
      "volatility": null,
      "trend_slope_bps_day": null,
      "forecast_apy": null,
      "risk_factor": 1,
      "risk_adjusted_apy": 0.039,
      "observations": 0,
      "insufficient_history": true,
      "rank": 6,
      "recommendation": "underweight"
    }
  ]
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## Current rate regime and per-asset trend

`GET /analytics/regime`


Scope: `read` or `partner:read` (protocol-level). `regime` is "unknown" until enough observations exist — never guessed.


**Access:** `read`, `partner:read`.


**SDK methods:** TypeScript `client.analytics.regime(…)`; Python `client.analytics.regime(…)`.


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `asset` | query | `"USDC"`, `"USDT0"` | No | Filter by asset symbol. |

### Request example

```bash
curl --fail-with-body -X GET "$THESAUROS_API_BASE/analytics/regime" \
  -H "Authorization: Bearer $THESAUROS_API_KEY"
```

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [RegimeDto](/api/partner-models/#regimedto) | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "regime",
  "data": {
    "object": "regime",
    "as_of": "2026-09-07T14:42:45.708Z",
    "regime": "unknown",
    "description": "Not enough observed rate history yet to classify a regime.",
    "per_asset": [
      {
        "asset": "USDC",
        "regime": "unknown",
        "blend_apy": null,
        "trend_slope_bps_day": null,
        "volatility": null,
        "observations": 0
      },
      {
        "asset": "USDT0",
        "regime": "unknown",
        "blend_apy": null,
        "trend_slope_bps_day": null,
        "volatility": null,
        "observations": 0
      }
    ]
  }
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## Routed value vs the passive baseline, realized and projected

`GET /analytics/uplift`


Scope: `partner:read` only — computed over the calling partner’s attributed positions. `user_id` must be a user attributed to the caller.


**Access:** `read`, `partner:read`.


**SDK methods:** TypeScript `client.analytics.uplift(…)`; Python `client.analytics.uplift(…)`.


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `asset` | query | `"USDC"`, `"USDT0"` | No | Filter by asset symbol. |

| `user_id` | query | `string` | No | Restrict to one end-user (usr_…). |

| `position_id` | query | `string` | No | Restrict to one position (pos_…). |

### Request example

```bash
curl --fail-with-body -X GET "$THESAUROS_API_BASE/analytics/uplift" \
  -H "Authorization: Bearer $THESAUROS_API_KEY"
```

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [UpliftDto](/api/partner-models/#upliftdto) | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "uplift",
  "data": {
    "object": "uplift",
    "as_of": "2026-09-07T14:42:45.798Z",
    "scope": "partner:ptn_seed_acme",
    "totals": {
      "principal": 85000,
      "current_value": 85919.34,
      "aave_baseline": 75667.23,
      "hold_baseline": 85919.34,
      "uplift_vs_aave": 118.61,
      "uplift_vs_hold": 0,
      "uplift_vs_aave_pct": 0.1568,
      "baseline_coverage": 0.6667
    },
    "positions": [
      {
        "object": "uplift_row",
        "position_id": "pos_seed_alpha",
        "user_id": "usr_seed_nova",
        "asset": "USDC",
        "vault_id": "vault_aave_base_usdc",
        "principal": 25000,
        "current_value": 25281.77,
        "apy": 0.052,
        "aave_baseline": 25281.77,
        "baseline_provider": "aave",
        "baseline_apy": 0.052,
        "hold_baseline": 25281.77,
        "uplift_vs_aave": 0,
        "uplift_vs_hold": 0,
        "realized_uplift": 0,
        "projected_uplift_annual": 0
      },
      {
        "object": "uplift_row",
        "position_id": "pos_seed_beta",
        "user_id": "usr_seed_orbit",
        "asset": "USDT0",
        "vault_id": "vault_plasma_usdt0",
        "principal": 10000,
        "current_value": 10133.5,
        "apy": 0.076,
        "aave_baseline": null,
        "baseline_provider": "aave",
        "baseline_apy": null,
        "hold_baseline": 10133.5,
        "uplift_vs_aave": null,
        "uplift_vs_hold": 0,
        "realized_uplift": null,
        "projected_uplift_annual": null
      },
      {
        "object": "uplift_row",
        "position_id": "pos_seed_gamma",
        "user_id": "usr_seed_nova",
        "asset": "USDC",
        "vault_id": "vault_morpho_base_usdc",
        "principal": 50000,
        "current_value": 50504.07,
        "apy": 0.068,
        "aave_baseline": 50385.46,
        "baseline_provider": "aave",
        "baseline_apy": 0.052,
        "hold_baseline": 50504.07,
        "uplift_vs_aave": 118.61,
        "uplift_vs_hold": 0,
        "realized_uplift": 118.61,
        "projected_uplift_annual": 800
      }
    ]
  }
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## Executed routing and rebalance decisions with rationale

`GET /analytics/decisions`


Scope: `partner:read` only — the caller sees decisions on its own positions. Paginated: pass `limit` and the previous page’s `meta.next_cursor` as `cursor`.


**Access:** `read`, `partner:read`.


**SDK methods:** TypeScript `client.analytics.decisions(…)`; Python `client.analytics.decisions(…)`.


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `asset` | query | `"USDC"`, `"USDT0"` | No | Filter by asset symbol. |

| `user_id` | query | `string` | No | Restrict to one end-user (usr_…). |

| `position_id` | query | `string` | No | Restrict to one position (pos_…). |

| `limit` | query | `string` | No | Page size, 1–200 (default 50). |

| `cursor` | query | `string` | No | Opaque cursor from the previous page’s meta.next_cursor. Omit for the first page. |

### Request example

```bash
curl --fail-with-body -X GET "$THESAUROS_API_BASE/analytics/decisions" \
  -H "Authorization: Bearer $THESAUROS_API_KEY"
```

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [DecisionDto](/api/partner-models/#decisiondto)[] | Yes |   |
| `meta` | [ListMetaDto](/api/partner-models/#listmetadto) | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "list",
  "data": [
    {
      "id": "dec_evt_seed_gamma_dep",
      "object": "decision",
      "at": "2026-07-15T12:00:00.000Z",
      "position_id": "pos_seed_gamma",
      "user_id": "usr_seed_nova",
      "asset": "USDC",
      "type": "initial_routing",
      "from_vault": null,
      "to_vault": "vault_morpho_base_usdc",
      "apy_before": null,
      "apy_after": 0.068,
      "expected_uplift_bps": null,
      "reason": "Initial deposit routed to vault",
      "alternatives": [
        {
          "vault_id": "vault_morpho_base_usdc",
          "name": "Morpho Blue USDC Yield",
          "provider": "morpho",
          "apy": 0.068,
          "risk_tier": "core"
        },
        {
          "vault_id": "vault_aave_base_usdc",
          "name": "Aave V3 USDC Core",
          "provider": "aave",
          "apy": 0.052,
          "risk_tier": "bluechip"
        },
        {
          "vault_id": "vault_compound_base_usdc",
          "name": "Compound V3 USDC Base",
          "provider": "compound",
          "apy": 0.048,
          "risk_tier": "core"
        },
        {
          "vault_id": "vault_compound_arb_usdc",
          "name": "Compound V3 USDC",
          "provider": "compound",
          "apy": 0.045,
          "risk_tier": "bluechip"
        },
        {
          "vault_id": "vault_treasury_base_usdc",
          "name": "Tokenized Treasury USDC",
          "provider": "treasury",
          "apy": 0.039,
          "risk_tier": "bluechip"
        }
      ],
      "rationale": "Routed USDC deposit to Morpho Blue USDC Yield at 6.80%. Initial deposit routed to vault",
      "status": "executed"
    },
    {
      "id": "dec_evt_seed_beta_dep",
      "object": "decision",
      "at": "2026-07-05T12:00:00.000Z",
      "position_id": "pos_seed_beta",
      "user_id": "usr_seed_orbit",
      "asset": "USDT0",
      "type": "initial_routing",
      "from_vault": null,
      "to_vault": "vault_plasma_usdt0",
      "apy_before": null,
      "apy_after": 0.076,
      "expected_uplift_bps": null,
      "reason": "Initial deposit routed to vault",
      "alternatives": [
        {
          "vault_id": "vault_plasma_usdt0",
          "name": "Thesauros USDT0 Vault",
          "provider": "morpho",
          "apy": 0.076,
          "risk_tier": "core"
        }
      ],
      "rationale": "Routed USDT0 deposit to Thesauros USDT0 Vault at 7.60%. Initial deposit routed to vault",
      "status": "executed"
    },
    {
      "id": "dec_evt_seed_alpha_dep",
      "object": "decision",
      "at": "2026-06-20T12:00:00.000Z",
      "position_id": "pos_seed_alpha",
      "user_id": "usr_seed_nova",
      "asset": "USDC",
      "type": "initial_routing",
      "from_vault": null,
      "to_vault": "vault_aave_base_usdc",
      "apy_before": null,
      "apy_after": 0.052,
      "expected_uplift_bps": null,
      "reason": "Initial deposit routed to vault",
      "alternatives": [
        {
          "vault_id": "vault_morpho_base_usdc",
          "name": "Morpho Blue USDC Yield",
          "provider": "morpho",
          "apy": 0.068,
          "risk_tier": "core"
        },
        {
          "vault_id": "vault_aave_base_usdc",
          "name": "Aave V3 USDC Core",
          "provider": "aave",
          "apy": 0.052,
          "risk_tier": "bluechip"
        },
        {
          "vault_id": "vault_compound_base_usdc",
          "name": "Compound V3 USDC Base",
          "provider": "compound",
          "apy": 0.048,
          "risk_tier": "core"
        },
        {
          "vault_id": "vault_compound_arb_usdc",
          "name": "Compound V3 USDC",
          "provider": "compound",
          "apy": 0.045,
          "risk_tier": "bluechip"
        },
        {
          "vault_id": "vault_treasury_base_usdc",
          "name": "Tokenized Treasury USDC",
          "provider": "treasury",
          "apy": 0.039,
          "risk_tier": "bluechip"
        }
      ],
      "rationale": "Routed USDC deposit to Aave V3 USDC Core at 5.20%. Initial deposit routed to vault",
      "status": "executed"
    }
  ],
  "meta": {
    "total": 3,
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  }
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).


## Current recommendations with rationale

`GET /analytics/advisor`


Scope: `partner:read` only — the portfolio section reflects the calling partner’s positions.


**Access:** `read`, `partner:read`.


**SDK methods:** TypeScript `client.analytics.advisor(…)`; Python `client.analytics.advisor(…)`.


### Parameters

| Name | Location | Type | Required | Description |

| --- | --- | --- | --- | --- |

| `asset` | query | `"USDC"`, `"USDT0"` | No | Filter by asset symbol. |

### Request example

```bash
curl --fail-with-body -X GET "$THESAUROS_API_BASE/analytics/advisor" \
  -H "Authorization: Bearer $THESAUROS_API_KEY"
```

### Response · 200

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `string` | Yes |   |
| `data` | [AdvisorDto](/api/partner-models/#advisordto) | Yes |   |


<details><summary>View example response</summary>

```json
{
  "object": "advisor",
  "data": {
    "object": "advisor",
    "as_of": "2026-09-07T14:42:46.010Z",
    "headline": "Routing is beating the passive baseline; hold the strategy and keep monitoring the regime.",
    "regime": "unknown",
    "bullets": [
      "Market regime is unknown. Not enough observed rate history yet to classify a regime.",
      "Best risk-adjusted venue right now: Thesauros USDT0 Vault (USDT0) at 6.99% risk-adjusted, 7.60% raw, core tier.",
      "Routed capital is outperforming the aave-only baseline by +$118.61 (0.1568%) on $85919.34 of value.",
      "No rebalance has been executed on these positions yet.",
      "6 of 6 venues have under 3 recorded observations; their trend and volatility are withheld rather than estimated."
    ],
    "top_opportunities": [
      {
        "vault_id": "vault_plasma_usdt0",
        "name": "Thesauros USDT0 Vault",
        "asset": "USDT0",
        "risk_adjusted_apy": 0.0699,
        "forecast_apy": null,
        "recommendation": "overweight"
      },
      {
        "vault_id": "vault_morpho_base_usdc",
        "name": "Morpho Blue USDC Yield",
        "asset": "USDC",
        "risk_adjusted_apy": 0.0626,
        "forecast_apy": null,
        "recommendation": "neutral"
      },
      {
        "vault_id": "vault_aave_base_usdc",
        "name": "Aave V3 USDC Core",
        "asset": "USDC",
        "risk_adjusted_apy": 0.052,
        "forecast_apy": null,
        "recommendation": "neutral"
      }
    ],
    "portfolio": {
      "current_value": 85919.34,
      "uplift_vs_aave": 118.61,
      "uplift_vs_aave_pct": 0.1568,
      "positions": 3
    },
    "disclaimer": "Derived from recorded vault APY observations and your own position history. Deterministic statistics, not an ML model or LLM, and not financial advice."
  }
}
```

</details>


For failed requests, inspect `error.code`, `error.message` and the request ID. [Error handling](/build/errors/).