# API Request/Response Logging Implementation

**Date**: 2026-01-21  
**Status**: ✅ Implemented  
**Version**: 1.0

---

## Overview

All order API requests and responses are now automatically stored in the database for debugging, auditing, and compliance purposes.

---

## Database Schema

### New Columns in `orders` Table

| Column | Type | Description |
|--------|------|-------------|
| `api_request_payload` | JSON | Complete API request payload sent to exchange |
| `api_response_data` | JSON | Complete API response received from exchange |
| `api_request_timestamp` | BIGINT | Unix timestamp when request was sent |
| `api_response_timestamp` | BIGINT | Unix timestamp when response was received |
| `api_http_status` | INT | HTTP status code from API response |

---

## What Gets Logged

### For Every Order:

1. **Request Payload**
   - All parameters sent to exchange API
   - Symbol, side, quantity, price, order type
   - Market-specific fields (e.g., market name for CoinDCX)

2. **Response Data**
   - Complete API response
   - Order ID, status, filled price
   - Error messages (if any)

3. **Timing Information**
   - Request timestamp
   - Response timestamp
   - HTTP status code

4. **Includes Both**:
   - ✅ **Successful orders** (PLACED, EXECUTED)
   - ✅ **Rejected orders** (REJECTED, errors)
   - ✅ **Live orders** (real money)
   - ✅ **Mock orders** (test mode)

---

## Example Log Entry

```json
{
  "api_request_payload": {
    "side": "buy",
    "order_type": "market_order",
    "market": "BTCINR",
    "total_quantity": "0.0001"
  },
  "api_response_data": {
    "id": "ecdbe6b4-ae6c-4f9e-b5e9-6d44d5f2f3e2",
    "side": "buy",
    "status": "filled",
    "market": "BTCINR",
    "filled_quantity": "0.0001",
    "average_price": "7500000.5"
  },
  "api_request_timestamp": 1737566400,
  "api_response_timestamp": 1737566401,
  "api_http_status": 200
}
```

---

## Viewing API Logs

### Option 1: Command-Line Tool

```bash
php bin/view-order-api-logs.php
```

**Output**:
```
╔════════════════════════════════════════════════════════════════╗
║                    ORDER API LOGS VIEWER                       ║
╚════════════════════════════════════════════════════════════════╝

Found 5 order(s) with API logs:

════════════════════════════════════════════════════════════════
✅ Order #123 - BTCINR
════════════════════════════════════════════════════════════════

📊 Order Details:
   Symbol: BTCINR
   Side: BUY
   Quantity: 0.0001
   Price: 7500000.5
   Status: PLACED
   Broker Order ID: ecdbe6b4-ae6c-4f9e-b5e9-6d44d5f2f3e2
   Created: 2026-01-21 20:00:00

📤 API Request:
   Timestamp: 2026-01-21 20:00:00
   Payload:
      side: buy
      order_type: market_order
      market: BTCINR
      total_quantity: 0.0001

📥 API Response:
   Timestamp: 2026-01-21 20:00:01
   HTTP Status: 200
   Data:
      id: ecdbe6b4-ae6c-4f9e-b5e9-6d44d5f2f3e2
      status: filled
      filled_quantity: 0.0001
      average_price: 7500000.5

⏱️  API Response Time: 1000ms
```

### Option 2: Direct SQL Query

```sql
SELECT 
    id,
    symbol,
    side,
    status,
    api_request_payload,
    api_response_data,
    api_http_status,
    created_at
FROM orders
WHERE api_request_payload IS NOT NULL
ORDER BY created_at DESC
LIMIT 10;
```

---

## Benefits

### 1. **Debugging**
- See exactly what was sent to the exchange
- Identify parameter errors
- Compare request vs response

### 2. **Auditing**
- Complete audit trail of all API calls
- Compliance with financial regulations
- Historical record of all orders

### 3. **Performance Monitoring**
- Track API response times
- Identify slow exchanges
- Optimize order placement

### 4. **Error Analysis**
- Full error messages from exchanges
- HTTP status codes for troubleshooting
- Request payload when order failed

### 5. **Reconciliation**
- Match internal orders with exchange records
- Verify order execution
- Resolve discrepancies

---

## Implementation Details

### Code Flow

1. **Order Placement**
   ```php
   // Broker captures request
   $requestTimestamp = time();
   $requestPayload = ['side' => 'buy', 'quantity' => 0.001];
   
   // API call
   $response = $this->makeAuthenticatedRequest('/orders', $requestPayload);
   $responseTimestamp = time();
   ```

2. **Result DTO**
   ```php
   return new OrderResultDto(
       $orderId,
       $symbol,
       $timeframe,
       $side,
       $status,
       $price,
       $filledPrice,
       $quantity,
       'LIVE',
       null,
       null,
       'COINDCX',
       $requestPayload,        // API request
       $response,              // API response
       $requestTimestamp,      // Request timestamp
       $responseTimestamp,     // Response timestamp
       200                     // HTTP status
   );
   ```

3. **Database Persistence**
   ```php
   $this->repo->save([
       'symbol' => $symbol,
       'side' => $side,
       'quantity' => $quantity,
       'status' => $status,
       
       // API logging
       'api_request_payload' => $result->apiRequest,
       'api_response_data' => $result->apiResponse,
       'api_request_timestamp' => $result->apiRequestTimestamp,
       'api_response_timestamp' => $result->apiResponseTimestamp,
       'api_http_status' => $result->apiHttpStatus
   ]);
   ```

---

## Files Modified

### 1. Database
- `database/migrations/add_api_logs_to_orders.php` - Migration script
- `orders` table - Added 5 new columns

### 2. DTOs
- `app/Execution/DTO/OrderResultDto.php` - Added API logging fields

### 3. Repository
- `app/Execution/Repository/OrderRepository.php` - Handle JSON encoding

### 4. Brokers
- `app/Execution/Brokers/CoinDCXBroker.php` - Capture request/response
- `app/Execution/Brokers/DeltaBroker.php` - (To be updated)

### 5. Execution Engine
- `app/Execution/Engine/OrderExecutionEngine.php` - Pass API logs to repository

### 6. Tools
- `bin/view-order-api-logs.php` - View logs from command line

---

## Usage Examples

### Debug Failed Order

```bash
# View recent orders
php bin/view-order-api-logs.php

# Check request payload
# See what was actually sent to exchange

# Check response
# See the error message from exchange

# Check HTTP status
# Identify authentication issues (401), rate limits (429), etc.
```

### Audit Trail

```sql
-- Get all orders for a specific symbol
SELECT 
    created_at,
    side,
    quantity,
    status,
    api_request_payload,
    api_response_data
FROM orders
WHERE symbol = 'BTCINR'
    AND created_at >= '2026-01-21'
ORDER BY created_at;
```

### Performance Analysis

```sql
-- Calculate average API response time
SELECT 
    AVG(api_response_timestamp - api_request_timestamp) as avg_response_time_sec
FROM orders
WHERE api_request_timestamp IS NOT NULL
    AND api_response_timestamp IS NOT NULL;
```

### Error Analysis

```sql
-- Find all rejected orders with error messages
SELECT 
    id,
    symbol,
    created_at,
    api_http_status,
    JSON_EXTRACT(api_response_data, '$.message') as error_message
FROM orders
WHERE status = 'REJECTED'
    AND api_response_data IS NOT NULL
ORDER BY created_at DESC;
```

---

## Next Steps

### Immediate:
- ✅ Run test orders to populate logs
- ✅ Verify logs are being saved correctly
- ✅ Test the viewer tool

### Future Enhancements:
- Add DeltaBroker API logging
- Create web-based log viewer
- Add log export functionality
- Implement log rotation/archival
- Add alerting for API errors

---

*Last Updated: January 21, 2026*
*Version: 1.0*