> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alterscope.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Score a vault before depositing

> Pre-flight risk score for a hypothetical position.

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

<CodeGroup>
  ```python python theme={null}
  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}
  ```

  ```bash curl theme={null}
  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"
  ```
</CodeGroup>

## 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.