Risk Rail

Risk Rail

Risk assessment, monitoring, and management.

Overview

The Risk Rail provides endpoints for assessing credit risk, market risk, operational risk, and managing exposure limits.

Base URL

/api/v1/risk

Endpoints

Assess Credit Risk

POST /api/v1/risk/credit/assess

Perform credit risk assessment.

Request Body:

{
  "subjectId": "cust_123",
  "subjectType": "INDIVIDUAL",
  "assessmentType": "NEW_FACILITY",
  "facilityAmount": "500000.00",
  "currency": "SAR",
  "tenor": 60
}

Response:

{
  "data": {
    "assessmentId": "ra_abc123",
    "subjectId": "cust_123",
    "riskScore": 720,
    "riskGrade": "A",
    "pdScore": 0.02,
    "lgd": 0.35,
    "ead": "500000.00",
    "expectedLoss": "3500.00",
    "recommendation": "APPROVE",
    "conditions": ["Collateral required", "Annual review"],
    "validUntil": "2025-04-15"
  }
}

Get Risk Score

GET /api/v1/risk/scores/:subjectId

Get current risk score for a subject.

List Risk Assessments

GET /api/v1/risk/assessments

Query Parameters:

Parameter	Type	Description
subjectId	string	Filter by subject
riskGrade	string	Filter by grade
status	string	Filter by status

Create Exposure Limit

POST /api/v1/risk/limits

Create a risk exposure limit.

Request Body:

{
  "limitType": "COUNTERPARTY",
  "subjectId": "cust_123",
  "limitAmount": "10000000.00",
  "currency": "SAR",
  "utilizationType": "REVOLVING",
  "reviewDate": "2025-12-31"
}

Check Limit

POST /api/v1/risk/limits/check

Check if transaction is within limits.

Request Body:

{
  "subjectId": "cust_123",
  "transactionAmount": "500000.00",
  "currency": "SAR",
  "limitType": "COUNTERPARTY"
}

Response:

{
  "data": {
    "withinLimit": true,
    "currentUtilization": "2500000.00",
    "availableLimit": "7500000.00",
    "utilizationPercent": 0.25,
    "postTransactionUtilization": 0.3
  }
}

Calculate VaR

POST /api/v1/risk/var/calculate

Calculate Value at Risk.

Request Body:

{
  "portfolioId": "pf_abc123",
  "confidenceLevel": 0.99,
  "holdingPeriod": 10,
  "method": "HISTORICAL"
}

Response:

{
  "data": {
    "portfolioId": "pf_abc123",
    "var": "125000.00",
    "confidenceLevel": 0.99,
    "holdingPeriod": 10,
    "method": "HISTORICAL",
    "calculatedAt": "2025-01-15T10:00:00Z"
  }
}

Run Stress Test

POST /api/v1/risk/stress-tests

Run a stress test scenario.

Request Body:

{
  "portfolioId": "pf_abc123",
  "scenario": "MARKET_CRASH",
  "parameters": {
    "equityShock": -0.3,
    "spreadWidening": 0.02,
    "fxShock": -0.15
  }
}

Risk Grades

Grade	PD Range	Description
AAA	0-0.01%	Exceptional
AA	0.01-0.05%	Excellent
A	0.05-0.15%	Strong
BBB	0.15-0.50%	Adequate
BB	0.50-2.00%	Speculative
B	2.00-10.00%	Highly speculative
CCC	>10.00%	Distressed

Limit Types

Type	Description
COUNTERPARTY	Single counterparty exposure
SECTOR	Industry sector limit
COUNTRY	Country risk limit
PRODUCT	Product type limit
CONCENTRATION	Concentration limit

Events

Event	Description
risk.assessment.completed	Risk assessment done
risk.limit.breach	Limit breached
risk.limit.warning	Limit warning threshold
risk.score.changed	Risk score updated

See Also

• Limits Rail - Transaction limits
• Compliance Rail - Compliance checks