Risk Assessment

Score a transaction for fraud risk before it is confirmed

This endpoint is served by the AI service at http://localhost:8001. It is an internal service and does not require authentication.

POST /ai/risk

Evaluates a pending transaction and returns a risk level with explainable factors. Call this endpoint before presenting the user with the transfer confirmation screen. If the risk level is medium or high, surface a confirmation dialog to the user before calling POST /api/ledger/transactions.

Model accuracy: 0.75.

Request body

amount · number · required

Transaction amount in MXN.

is_new_beneficiary · boolean · required

Whether the recipient has never received a transfer from this user.

hour_of_day · integer · required

Local hour of the transaction (0–23).

num_past_transactions · integer · required

Total number of transactions in the user’s history. Must be ≥ 0.

avg_transaction_amount · number · required

User’s historical average transaction amount.

max_transaction_amount · number · required

User’s historical maximum transaction amount.

num_transactions_to_beneficiary · integer · required

Number of prior transfers to this specific recipient. Must be ≥ 0.

is_new_device · boolean · required

Whether the current device is new or unrecognized.

geolocation_changed · boolean · required

Whether the user’s current location differs from their usual location.

user_id · string

Optional user identifier for logging and analytics.

Response

user_id · string

Echoed user identifier from the request.

model_version · string · required

Version of the risk model that produced the result.

result · object · required

Show result properties

risk_level · string · required

Overall risk classification. See risk levels below.

risk_score · number · required

Continuous risk score between 0.0 (no risk) and 1.0 (maximum risk).

risk_factors · string[] · required

List of contributing risk factor codes. See risk factor codes below.

Risk levels

Level	Recommended action
low	Proceed normally.
medium	Show an explanation and require user confirmation.
high	Require explicit acknowledgment before proceeding.

Risk factor codes

Code	Description
AMOUNT_MUCH_HIGHER_THAN_AVERAGE	Amount is more than 2× the user’s historical average.
NEW_BENEFICIARY	First transfer to this recipient.
UNUSUAL_TIME	Transaction is outside normal hours (06:00–22:00).
NEW_DEVICE	Device has not been seen before.
LOCATION_CHANGED	Geolocation differs from the user’s usual location.
LOW_HISTORY	Fewer than 3 prior transactions on the account.

curl

curl --request POST \
  --url http://localhost:8001/ai/risk \
  --header 'Content-Type: application/json' \
  --data '{
  "user_id": "user-123",
  "amount": 15000.00,
  "is_new_beneficiary": true,
  "hour_of_day": 14,
  "num_past_transactions": 12,
  "avg_transaction_amount": 600.00,
  "max_transaction_amount": 5000.00,
  "num_transactions_to_beneficiary": 0,
  "is_new_device": false,
  "geolocation_changed": false
}'

Response

{
  "user_id": "user-123",
  "model_version": "risk-v1.0",
  "result": {
    "risk_level": "medium",
    "risk_score": 0.62,
    "risk_factors": [
      "NEW_BENEFICIARY",
      "AMOUNT_MUCH_HIGHER_THAN_AVERAGE"
    ]
  }
}