# Laravel MT5 Investment Platform - API Documentation

## Base URL
```
Production: https://api.yourdomain.com/api/v1
Staging: https://staging-api.yourdomain.com/api/v1
Local: http://localhost:8000/api/v1
```

## Authentication
All endpoints (except MT5 sync) require authentication via Laravel Sanctum.

### Headers
```
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
```

### Token Management
```bash
# Create token (via Breeze or custom endpoint)
POST /api/v1/auth/login
{
  "email": "investor@example.com",
  "password": "password"
}

Response:
{
  "success": true,
  "message": "Login successful",
  "data": {
    "token": "1|xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "user": { ... }
  }
}
```

---

## Investor API Endpoints

### Dashboard
```
GET /api/v1/investor/dashboard
```

**Response:**
```json
{
  "success": true,
  "message": "Dashboard data retrieved successfully",
  "data": {
    "investor": { ... },
    "total_distributions": 45,
    "total_profit_received": "12500.00",
    "latest_distribution": { ... },
    "recent_distributions": [ ... ]
  },
  "timestamp": "2026-05-11T12:00:00Z"
}
```

### Profile
```
GET /api/v1/investor/profile
```

### Balance
```
GET /api/v1/investor/balance
```

**Response:**
```json
{
  "success": true,
  "message": "Balance retrieved successfully",
  "data": {
    "available_balance": "5000.00",
    "total_profit": "12500.00",
    "equity": "5500.00",
    "units": 11,
    "unit_value": "500.00",
    "unit_value_equivalent": "5500.00",
    "profit_percentage": "227.27%"
  }
}
```

### Profit History
```
GET /api/v1/investor/profit-history
Query Parameters:
  - page: integer (default: 1)
  - per_page: integer (default: 15)
  - from_date: date (YYYY-MM-DD)
  - to_date: date (YYYY-MM-DD)
```

### Distributions
```
GET /api/v1/investor/distributions
GET /api/v1/investor/distributions/{id}
```

### Trades
```
GET /api/v1/investor/trades
Query Parameters:
  - page: integer (default: 1)
  - per_page: integer (default: 20)
  - mt5_account_id: integer (required)
  - from_date: date (YYYY-MM-DD)
  - to_date: date (YYYY-MM-DD)
  - symbol: string
  - type: BUY|SELL
```

### Referrals
```
GET /api/v1/investor/referrals
Query Parameters:
  - page: integer (default: 1)
  - per_page: integer (default: 15)
  - from_date: date (YYYY-MM-DD)
  - to_date: date (YYYY-MM-DD)
  - status: PENDING|PAID
```

### Safety Fund Summary
```
GET /api/v1/investor/safety-fund-summary
```

---

## Admin API Endpoints

### Dashboard
```
GET /api/v1/admin/dashboard
```

**Response:**
```json
{
  "success": true,
  "message": "Admin dashboard data retrieved successfully",
  "data": {
    "total_investors": 150,
    "active_investors": 120,
    "total_equity": "825000.00",
    "total_available_balance": "750000.00",
    "total_profit_distributed": "1250000.00",
    "total_distributions": 45,
    "completed_distributions": 42,
    "failed_distributions": 3,
    "safety_fund_balance": "250000.00",
    "latest_distribution": { ... },
    "recent_investors": [ ... ]
  }
}
```

### Investors
```
GET /api/v1/admin/investors
GET /api/v1/admin/investors/{id}
POST /api/v1/admin/recalculate-units
```

**Query Parameters (index):**
- page: integer (default: 1)
- per_page: integer (default: 20)
- is_active: boolean
- search: string (searches name/email)
- sort_by: string (default: created_at)
- sort_order: asc|desc (default: desc)

### Distributions
```
GET /api/v1/admin/distributions
GET /api/v1/admin/distributions/{id}
```

**Query Parameters (index):**
- page: integer (default: 1)
- per_page: integer (default: 20)
- from_date: date (YYYY-MM-DD)
- to_date: date (YYYY-MM-DD)
- status: PENDING|PROCESSING|COMPLETED|FAILED
- mt5_account_id: integer

### Reconciliation
```
GET /api/v1/admin/reconciliation
GET /api/v1/admin/reconciliation/{distributionId}
POST /api/v1/admin/reconciliation/run
```

**POST /api/v1/admin/reconciliation/run:**
```json
{
  "distribution_id": 123
}
// OR
{
  "from_date": "2026-05-01",
  "to_date": "2026-05-10"
}
```

### Settlement
```
GET /api/v1/admin/settlement-logs
POST /api/v1/admin/manual-settlement
```

**POST /api/v1/admin/manual-settlement:**
```json
{
  "date": "2026-05-10",
  "triggered_by": 1,
  "notes": "Manual settlement for missing day"
}
```

### MT5 Sync Status
```
GET /api/v1/admin/mt5-sync-status
```

### Safety Fund
```
GET /api/v1/admin/safety-fund
```

**Query Parameters:**
- page: integer (default: 1)
- per_page: integer (default: 20)
- from_date: date (YYYY-MM-DD)
- to_date: date (YYYY-MM-DD)
- transaction_type: CREDIT|DEBIT
- sort_by: string (default: date)
- sort_order: asc|desc (default: desc)

### Failed Settlements
```
GET /api/v1/admin/failed-settlements
```

**Query Parameters:**
- from_date: date (YYYY-MM-DD)
- to_date: date (YYYY-MM-DD)

---

## Internal MT5 Sync Endpoint

### Sync MT5 Data
```
POST /api/v1/mt5/sync
```

**Headers:**
```
X-API-Key: {mt5-bridge-api-key}
Content-Type: application/json
```

**Request Body:**
```json
{
  "api_key": "mt5-bridge",
  "account": {
    "account_number": "12345678",
    "account_name": "MarketsGlobal-Live16",
    "balance": 5500.00,
    "equity": 5500.00,
    "margin": 0,
    "free_margin": 5500.00,
    "floating_profit": 0
  },
  "trades": [
    {
      "ticket": "123456",
      "symbol": "EURUSD",
      "type": "BUY",
      "volume": 1.0,
      "open_price": 1.08500,
      "current_price": 1.08600,
      "profit": 10.00,
      "swap": 0.50,
      "commission": 0.00,
      "open_time": "2026-05-11T10:00:00Z",
      "close_time": "2026-05-11T11:00:00Z",
      "comment": "Trade 123456"
    }
  ]
}
```

---

## Standard Response Format

### Success Response
```json
{
  "success": true,
  "message": "Operation successful",
  "data": { ... },
  "errors": null,
  "timestamp": "2026-05-11T12:00:00Z"
}
```

### Error Response
```json
{
  "success": false,
  "message": "Error message",
  "data": null,
  "errors": {
    "field": ["error message"]
  },
  "timestamp": "2026-05-11T12:00:00Z"
}
```

### Validation Error
```json
{
  "success": false,
  "message": "Validation failed",
  "data": null,
  "errors": {
    "email": ["The email field is required."],
    "password": ["The password must be at least 8 characters."]
  },
  "timestamp": "2026-05-11T12:00:00Z"
}
```

### Paginated Response
```json
{
  "success": true,
  "message": "Data retrieved successfully",
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 100,
    "last_page": 5,
    "from": 1,
    "to": 20,
    "has_more_pages": true
  },
  "timestamp": "2026-05-11T12:00:00Z"
}
```

---

## Error Codes

| Code | Description |
|------|-------------|
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 422 | Validation Error |
| 429 | Too Many Requests (Rate Limit) |
| 500 | Internal Server Error |

---

## Rate Limiting

| Role | Limit | Window |
|------|-------|--------|
| Investor | 100 requests | 1 minute |
| Admin | 200 requests | 1 minute |
| Settlement | 10 requests | 1 minute |
| MT5 Sync | 1000 requests | 1 minute |

Rate limit headers included in responses:
- `X-RateLimit-Limit`: Maximum requests
- `X-RateLimit-Remaining`: Remaining requests
- `X-RateLimit-Reset`: Seconds until reset

---

## Finance Formatting

All financial values are formatted as strings with 2 decimal places:
- Currency: `"1250.00"`
- Percentages: `"25.50%"`
- Decimals: `"0.12345678"`

Timestamps are in ISO 8601 format:
- `"2026-05-11T12:00:00Z"`

---

## Versioning

Current API version: `v1`

Breaking changes will increment the version to `v2`. Old versions will be supported for 6 months after new version release.

---

## Testing with cURL

```bash
# Investor Dashboard
curl -X GET https://api.yourdomain.com/api/v1/investor/dashboard \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

# Admin Dashboard
curl -X GET https://api.yourdomain.com/api/v1/admin/dashboard \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

# MT5 Sync
curl -X POST https://api.yourdomain.com/api/v1/mt5/sync \
  -H "X-API-Key: mt5-bridge" \
  -H "Content-Type: application/json" \
  -d '{"api_key":"mt5-bridge","account":{...},"trades":[...]}'
```