Skip to main content
A user wants to deposit USDC into a Morpho vault. Before you queue the transaction, you want a current risk score that includes the user’s existing portfolio so concentration shows up.

​
What you build

A pre-deposit check that hits POST /v2/yield/portfolio/analyze with the proposed position appended, and refuses to proceed if the resulting risk band exceeds the user’s tolerance.

​
1. Build the request

from alterscope import AlterscopeClient

client = AlterscopeClient(api_key="sk_live_...")

current_positions = load_user_positions(user_id)
proposed = current_positions + [{
    "opportunity_id": "morpho-usdc-lending",
    "notional_usd": 25_000,
}]

analysis = client.portfolio.analyze(
    positions=proposed,
    include_scenarios=True,
)

if analysis.risk.band > user_max_band:
    return {"approved": False, "reason": analysis.risk.dominant_factors}
return {"approved": True, "expected_apy_net": analysis.expected_apy_net}

​
2. Read the response

The response carries:
  • risk.band (1 to 5; lower is safer).
  • risk.dominant_factors listing the top 3 factors driving the score.
  • expected_apy_net net of fees.
  • scenarios (when include_scenarios=true) with stress-test outputs.

​
3. Concentration warnings

If the same protocol or the same oracle.provider already accounts for more than 40% of the user’s notional, surface a warning regardless of band. The response includes a concentration block; render the top dimension to the user.

​
4. Troubleshooting

  • 422 with “unknown opportunity_id”: the id you pass must match data[].id from the yield list endpoint exactly. Fetch fresh; ids change on protocol upgrades.
  • Stale data: check meta._agentic.freshness.status. If it’s stale, gate the deposit and surface the issue rather than approving on bad data.