Analytics · Thesauros Docs

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.

Authentication · Errors · Amounts and 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

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

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[]	Yes

View example response

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"
    }
  ]
}

For failed requests, inspect error.code, error.message and the request ID. Error handling.

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

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

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	Yes

View example response

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
      }
    ]
  }
}

For failed requests, inspect error.code, error.message and the request ID. Error handling.

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

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

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	Yes

View example response

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
      }
    ]
  }
}

For failed requests, inspect error.code, error.message and the request ID. Error handling.

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

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

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
`object`	`string`	Yes
`data`	DecisionDto[]	Yes
`meta`	ListMetaDto	Yes

View example response

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
  }
}

For failed requests, inspect error.code, error.message and the request ID. Error handling.

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

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

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	Yes

View example response

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."
  }
}

For failed requests, inspect error.code, error.message and the request ID. Error handling.

Risk-adjusted venue signals from observed APY history

Parameters

Request example

Response · 200

Current rate regime and per-asset trend

Parameters

Request example

Response · 200

Routed value vs the passive baseline, realized and projected

Parameters

Request example

Response · 200

Executed routing and rebalance decisions with rationale

Parameters

Request example

Response · 200

Current recommendations with rationale

Parameters

Request example

Response · 200

Build with us.