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

# Loans API

> Create, manage, and repay P2P loans

# Loans API

Endpoints for managing peer-to-peer loans.

## Create Loan Request

Request a new loan based on your Trust Score.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://api.usmewe.com/v1/loans" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 50,
      "duration": 14,
      "purpose": "Emergency expense"
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "loan_xyz789",
      "status": "pending",
      "amount": 50,
      "netAmount": 45,
      "insuranceFee": 5,
      "duration": 14,
      "interestRate": 0.03,
      "totalRepayment": 51.35,
      "purpose": "Emergency expense",
      "createdAt": "2024-01-15T12:00:00Z",
      "expiresAt": "2024-01-15T13:00:00Z"
    }
  }
  ```
</CodeGroup>

### Request Parameters

| Parameter  | Type   | Required | Description              |
| ---------- | ------ | -------- | ------------------------ |
| `amount`   | number | Yes      | USDC amount to borrow    |
| `duration` | number | Yes      | Loan term in days (7-90) |
| `purpose`  | string | No       | Reason for loan          |

## Get Loan Details

Retrieve details of a specific loan.

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

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "loan_xyz789",
      "borrower": "user_abc123",
      "status": "active",
      "amount": 50,
      "netAmount": 45,
      "insuranceFee": 5,
      "interestRate": 0.03,
      "totalRepayment": 51.35,
      "amountPaid": 0,
      "remainingBalance": 51.35,
      "duration": 14,
      "createdAt": "2024-01-15T12:00:00Z",
      "fundedAt": "2024-01-15T12:05:00Z",
      "dueDate": "2024-01-29T12:05:00Z",
      "daysRemaining": 14,
      "txHash": "0x..."
    }
  }
  ```
</CodeGroup>

## List User Loans

Get all loans for the authenticated user.

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://api.usmewe.com/v1/loans?status=active&limit=10" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "loan_xyz789",
        "status": "active",
        "amount": 50,
        "remainingBalance": 51.35,
        "dueDate": "2024-01-29T12:05:00Z",
        "daysRemaining": 14
      }
    ],
    "pagination": {
      "total": 3,
      "limit": 10,
      "offset": 0,
      "hasMore": false
    }
  }
  ```
</CodeGroup>

### Query Parameters

| Parameter | Type   | Description                    |
| --------- | ------ | ------------------------------ |
| `status`  | string | Filter by status               |
| `limit`   | number | Results per page (default: 20) |
| `offset`  | number | Pagination offset              |

### Loan Statuses

| Status      | Description              |
| ----------- | ------------------------ |
| `pending`   | Awaiting funding         |
| `active`    | Loan is active           |
| `repaid`    | Successfully repaid      |
| `overdue`   | Past due date            |
| `defaulted` | Default declared         |
| `cancelled` | Cancelled before funding |

## Check Eligibility

Check loan eligibility before requesting.

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

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "eligible": true,
      "trustScore": 56,
      "tier": "Established",
      "maxAmount": 100,
      "maxDuration": 30,
      "currentLoans": 1,
      "maxActiveLoans": 3,
      "interestRate": 0.03,
      "restrictions": []
    }
  }
  ```
</CodeGroup>

### Eligibility Restrictions

| Code                | Description               |
| ------------------- | ------------------------- |
| `SCORE_TOO_LOW`     | Trust Score below minimum |
| `MAX_LOANS_REACHED` | Already at loan limit     |
| `OVERDUE_LOAN`      | Has overdue loan          |
| `RECENT_DEFAULT`    | Defaulted within 90 days  |

## Repay Loan

Make a loan repayment.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://api.usmewe.com/v1/loans/{loanId}/repay" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 51.35
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "loanId": "loan_xyz789",
      "amountPaid": 51.35,
      "remainingBalance": 0,
      "status": "repaid",
      "trustScoreChange": 2,
      "xpEarned": 20,
      "txHash": "0x..."
    }
  }
  ```
</CodeGroup>

### Partial Repayment

```bash theme={null}
curl -X POST "https://api.usmewe.com/v1/loans/{loanId}/repay" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"amount": 25}'
```

## Calculate Early Payoff

Get early payoff amount with interest savings.

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

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "loanId": "loan_xyz789",
      "originalTotal": 51.35,
      "earlyPayoffAmount": 50.75,
      "interestSaved": 0.60,
      "daysEarly": 7
    }
  }
  ```
</CodeGroup>

## Cancel Loan Request

Cancel a pending loan request.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://api.usmewe.com/v1/loans/{loanId}/cancel" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "loanId": "loan_xyz789",
      "status": "cancelled",
      "cancelledAt": "2024-01-15T12:30:00Z"
    }
  }
  ```
</CodeGroup>

<Warning>
  Only `pending` loans can be cancelled. Funded loans must be repaid.
</Warning>

## Request Extension

Request a loan extension (if eligible).

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://api.usmewe.com/v1/loans/{loanId}/extension" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "days": 7,
      "reason": "Medical emergency"
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "loanId": "loan_xyz789",
      "extensionGranted": true,
      "newDueDate": "2024-02-05T12:05:00Z",
      "additionalInterest": 0.35
    }
  }
  ```
</CodeGroup>

## Webhook Events

```json theme={null}
// Loan funded
{
  "event": "loan.funded",
  "data": {
    "loanId": "loan_xyz789",
    "amount": 50,
    "netAmount": 45
  }
}

// Loan repaid
{
  "event": "loan.repaid",
  "data": {
    "loanId": "loan_xyz789",
    "totalPaid": 51.35
  }
}

// Loan overdue
{
  "event": "loan.overdue",
  "data": {
    "loanId": "loan_xyz789",
    "daysOverdue": 1
  }
}
```

## Error Responses

| Code | Error              | Description                |
| ---- | ------------------ | -------------------------- |
| 400  | `INVALID_AMOUNT`   | Amount exceeds limit       |
| 400  | `INVALID_DURATION` | Duration out of range      |
| 403  | `NOT_ELIGIBLE`     | User not eligible for loan |
| 404  | `LOAN_NOT_FOUND`   | Loan does not exist        |
| 409  | `ALREADY_REPAID`   | Loan already repaid        |