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

# Trust Score API

> Query and understand Trust Scores

# Trust Score API

Endpoints for retrieving and understanding Trust Scores.

## Get Trust Score

Retrieve a user's current Trust Score.

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://api.usmewe.com/v1/trust-score/{userId}" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "userId": "user_abc123",
      "score": 56,
      "tier": "Established",
      "breakdown": {
        "seniority": 6,
        "repaymentHistory": 20,
        "transactionVolume": 10,
        "socialNetwork": 15,
        "levelBonus": 5
      },
      "borrowingPower": {
        "maxAmount": 100,
        "maxDuration": 30,
        "interestRate": 0.03
      },
      "lastUpdated": "2024-01-15T12:00:00Z"
    }
  }
  ```
</CodeGroup>

## Score Breakdown

### Component Details

| Component           | Max Points | Calculation                  |
| ------------------- | ---------- | ---------------------------- |
| `seniority`         | 12         | +1 per month of account age  |
| `repaymentHistory`  | 40         | +2 per on-time repayment     |
| `transactionVolume` | 20         | log(totalVolume), normalized |
| `socialNetwork`     | 15         | +5 per guardian (max 3)      |
| `levelBonus`        | 13         | Based on XP level            |

## Get Score History

Retrieve historical Trust Score data.

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://api.usmewe.com/v1/trust-score/{userId}/history?period=30d" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "userId": "user_abc123",
      "period": "30d",
      "history": [
        {
          "date": "2024-01-15",
          "score": 56,
          "change": 2,
          "reason": "on_time_repayment"
        },
        {
          "date": "2024-01-10",
          "score": 54,
          "change": 5,
          "reason": "guardian_added"
        },
        {
          "date": "2024-01-01",
          "score": 49,
          "change": 1,
          "reason": "seniority_increase"
        }
      ]
    }
  }
  ```
</CodeGroup>

### Period Options

| Period | Description  |
| ------ | ------------ |
| `7d`   | Last 7 days  |
| `30d`  | Last 30 days |
| `90d`  | Last 90 days |
| `1y`   | Last year    |
| `all`  | All time     |

## Calculate Potential Score

Simulate score changes based on actions.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://api.usmewe.com/v1/trust-score/simulate" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "actions": [
        {"type": "repayment", "count": 5},
        {"type": "add_guardian", "count": 1}
      ]
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "currentScore": 56,
      "projectedScore": 71,
      "breakdown": {
        "repayments": "+10",
        "guardian": "+5"
      },
      "newTier": "Trusted",
      "newBorrowingPower": {
        "maxAmount": 200,
        "maxDuration": 60
      }
    }
  }
  ```
</CodeGroup>

### Simulatable Actions

| Action         | Impact                   |
| -------------- | ------------------------ |
| `repayment`    | +2 per on-time repayment |
| `add_guardian` | +5 per guardian (max 3)  |
| `level_up`     | Variable based on level  |
| `deposit`      | Affects volume score     |

## Get Score Requirements

Get requirements for a specific tier.

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://api.usmewe.com/v1/trust-score/tiers"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "tier": "New",
        "minScore": 0,
        "maxScore": 30,
        "borrowingPower": {
          "maxAmount": 20,
          "maxDuration": 7
        }
      },
      {
        "tier": "Building",
        "minScore": 31,
        "maxScore": 50,
        "borrowingPower": {
          "maxAmount": 50,
          "maxDuration": 14
        }
      },
      {
        "tier": "Established",
        "minScore": 51,
        "maxScore": 70,
        "borrowingPower": {
          "maxAmount": 100,
          "maxDuration": 30
        }
      },
      {
        "tier": "Trusted",
        "minScore": 71,
        "maxScore": 85,
        "borrowingPower": {
          "maxAmount": 200,
          "maxDuration": 60
        }
      },
      {
        "tier": "Elite",
        "minScore": 86,
        "maxScore": 100,
        "borrowingPower": {
          "maxAmount": 500,
          "maxDuration": 90
        }
      }
    ]
  }
  ```
</CodeGroup>

## Score Modifiers

Get active modifiers affecting the score.

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://api.usmewe.com/v1/trust-score/{userId}/modifiers" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "userId": "user_abc123",
      "baseScore": 60,
      "finalScore": 56,
      "modifiers": [
        {
          "type": "late_payment",
          "impact": -4,
          "reason": "Payment 3 days late on loan #45",
          "appliedAt": "2024-01-05T00:00:00Z",
          "expiresAt": null
        }
      ]
    }
  }
  ```
</CodeGroup>

### Modifier Types

| Type            | Impact        | Duration      |
| --------------- | ------------- | ------------- |
| `late_payment`  | -5% of score  | Permanent     |
| `default`       | -30% of score | Permanent     |
| `on_time_bonus` | +1% of score  | Per repayment |

## Webhook Events

Subscribe to Trust Score changes:

```json theme={null}
{
  "event": "trust_score.updated",
  "data": {
    "userId": "user_abc123",
    "previousScore": 54,
    "newScore": 56,
    "change": 2,
    "reason": "on_time_repayment",
    "timestamp": "2024-01-15T12:00:00Z"
  }
}
```

## Error Responses

| Code | Error            | Description                |
| ---- | ---------------- | -------------------------- |
| 401  | `UNAUTHORIZED`   | Invalid or missing token   |
| 404  | `USER_NOT_FOUND` | User does not exist        |
| 403  | `SCORE_PRIVATE`  | User's score is not public |

<Card title="Trust Score Overview" icon="star" href="/core-concepts/trust-score/overview">
  Learn how Trust Score works
</Card>