Loans API
Endpoints for managing peer-to-peer loans.Create Loan Request
Request a new loan based on your Trust Score.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"
}'
{
"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"
}
}
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.curl -X GET "https://api.usmewe.com/v1/loans/{loanId}" \
-H "Authorization: Bearer YOUR_TOKEN"
{
"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..."
}
}
List User Loans
Get all loans for the authenticated user.curl -X GET "https://api.usmewe.com/v1/loans?status=active&limit=10" \
-H "Authorization: Bearer YOUR_TOKEN"
{
"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
}
}
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.curl -X GET "https://api.usmewe.com/v1/loans/eligibility" \
-H "Authorization: Bearer YOUR_TOKEN"
{
"success": true,
"data": {
"eligible": true,
"trustScore": 56,
"tier": "Established",
"maxAmount": 100,
"maxDuration": 30,
"currentLoans": 1,
"maxActiveLoans": 3,
"interestRate": 0.03,
"restrictions": []
}
}
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.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
}'
{
"success": true,
"data": {
"loanId": "loan_xyz789",
"amountPaid": 51.35,
"remainingBalance": 0,
"status": "repaid",
"trustScoreChange": 2,
"xpEarned": 20,
"txHash": "0x..."
}
}
Partial Repayment
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.curl -X GET "https://api.usmewe.com/v1/loans/{loanId}/payoff" \
-H "Authorization: Bearer YOUR_TOKEN"
{
"success": true,
"data": {
"loanId": "loan_xyz789",
"originalTotal": 51.35,
"earlyPayoffAmount": 50.75,
"interestSaved": 0.60,
"daysEarly": 7
}
}
Cancel Loan Request
Cancel a pending loan request.curl -X POST "https://api.usmewe.com/v1/loans/{loanId}/cancel" \
-H "Authorization: Bearer YOUR_TOKEN"
{
"success": true,
"data": {
"loanId": "loan_xyz789",
"status": "cancelled",
"cancelledAt": "2024-01-15T12:30:00Z"
}
}
Only
pending loans can be cancelled. Funded loans must be repaid.Request Extension
Request a loan extension (if eligible).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"
}'
{
"success": true,
"data": {
"loanId": "loan_xyz789",
"extensionGranted": true,
"newDueDate": "2024-02-05T12:05:00Z",
"additionalInterest": 0.35
}
}
Webhook Events
// 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 |