# Risk API

#### GET /risk-score

Returns the 4-pillar risk score for a user. Requires an active VIP report. If no VIP exists, the endpoint returns a `404` with `error_code: ERR_NO_VIP`.

http

```http
GET /risk-score?user_id=usr_01J2K...
Authorization: Bearer sk_live_xxxx
```

**Query parameters**

| Parameter | Type   | Description                                                          |
| --------- | ------ | -------------------------------------------------------------------- |
| `user_id` | string | Required.                                                            |
| `vip_id`  | string | Optional. Use a specific VIP report ID. Defaults to the most recent. |

**Response**

json

```json
{
  "risk_score": {
    "id": "rsk_8PwK...",
    "user_id": "usr_01J2K...",
    "vip_id": "vip_4DrM...",
    "generated_at": "2024-12-01T09:01:00Z",
    "composite_score": 812,
    "score_range": { "min": 0, "max": 1000 },
    "recommendation": "approve",
    "suggested_credit_limit_usd": 9000.00,
    "pillars": {
      "consistency": {
        "weight": 0.40,
        "score": 850,
        "weighted_contribution": 340,
        "details": {
          "periods_verified": 6,
          "periods_missed": 0,
          "consistency_rate": 1.0,
          "longest_streak_months": 6
        },
        "explanation": "Income verified for all 6 requested periods with no gaps."
      },
      "volume": {
        "weight": 0.25,
        "score": 790,
        "weighted_contribution": 197,
        "details": {
          "verified_monthly_income_usd": 4500.00,
          "annualized_income_usd": 54000.00,
          "income_tier": "mid"
        },
        "explanation": "Verified monthly income of $4,500 USDC supports moderate credit exposure."
      },
      "liquidity_buffer": {
        "weight": 0.20,
        "score": 810,
        "weighted_contribution": 162,
        "details": {
          "average_usdc_balance": 8820.50,
          "income_multiple": 1.96,
          "buffer_months": 1.96
        },
        "explanation": "Average wallet balance represents approximately 1.96x monthly verified income."
      },
      "leverage": {
        "weight": 0.15,
        "score": 730,
        "weighted_contribution": 109,
        "details": {
          "estimated_monthly_obligations_usd": 0.00,
          "dti_ratio": 0.00,
          "on_chain_debt_signals": []
        },
        "explanation": "No on-chain debt obligations detected. DTI ratio is 0%."
      }
    },
    "fraud_flags": [],
    "adverse_action_reasons": []
  }
}
```

**Recommendation values**

| Value                     | Meaning                                                                             |
| ------------------------- | ----------------------------------------------------------------------------------- |
| `approve`                 | Score and income profile support credit issuance.                                   |
| `approve_with_conditions` | Score is acceptable but lender should apply conditions (lower limit, shorter term). |
| `refer`                   | Score requires human review before a credit decision.                               |
| `decline`                 | Score does not meet minimum threshold for credit issuance.                          |

**Score calculation**

```
composite_score = (consistency.score × 0.40)
                + (volume.score × 0.25)
                + (liquidity_buffer.score × 0.20)
                + (leverage.score × 0.15)
```

**Suggested credit limit**

The `suggested_credit_limit_usd` is a reference value calculated as:

```
suggested_limit = verified_monthly_income × 2.0
```

Lenders are not required to use this value. It is provided as a starting point for lender risk models.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rupi.global/core-documentation/markdown/risk-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.