Alterscope Developer API

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}

curl -H "Authorization: Bearer $ALTERSCOPE_API_KEY" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "positions": [
         { "opportunity_id": "aave-usdc-lending",     "notional_usd": 50000 },
         { "opportunity_id": "morpho-usdc-lending",   "notional_usd": 25000 }
       ],
       "include_scenarios": true
     }' \
  "https://api.alterscope.org/v2/yield/portfolio/analyze"

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.

​What you build

​1. Build the request

​2. Read the response

​3. Concentration warnings

​4. Troubleshooting

What you build

1. Build the request

2. Read the response

3. Concentration warnings

4. Troubleshooting