# Trading Session API Contracts

## Trading Session Operations

### POST /sessions
**Purpose**: Create a new wash trading session

**Request**:
```json
{
  "name": "string",             // Session identifier
  "accounts": ["string"],       // Array of account IDs to participate
  "strategy": {
    "symbol": "string",         // Trading pair (e.g., "ETH/USD")
    "volumeDistribution": "equal|weighted",
    "priceRange": {
      "min": "number",          // Minimum price deviation %
      "max": "number"           // Maximum price deviation %
    },
    "timing": {
      "minInterval": "number",  // Min seconds between orders
      "maxInterval": "number",  // Max seconds between orders
      "orderSize": {
        "min": "number",        // Min order size
        "max": "number"         // Max order size
      }
    },
    "riskLimits": {
      "maxPositionSize": "number",
      "stopLossThreshold": "number",
      "maxSlippage": "number"
    }
  },
  "volumeTarget": "number"      // Target volume to generate
}
```

**Response** (201 Created):
```json
{
  "id": "string",
  "name": "string",
  "status": "pending",
  "accounts": ["string"],
  "strategy": { /* same as request */ },
  "volumeTarget": "number",
  "volumeGenerated": 0,
  "startTime": "string (ISO 8601)",
  "endTime": null
}
```

**Error Responses**:
- 400 Bad Request: Invalid strategy parameters or insufficient accounts
- 422 Unprocessable Entity: Accounts not available or have insufficient balance

### GET /sessions
**Purpose**: List all trading sessions

**Query Parameters**:
- `status`: Filter by status (pending|active|paused|completed|failed)
- `limit`: Number of sessions to return (default: 50)
- `offset`: Number of sessions to skip (default: 0)

**Response** (200 OK):
```json
{
  "sessions": [
    {
      "id": "string",
      "name": "string",
      "status": "string",
      "accounts": ["string"],
      "volumeTarget": "number",
      "volumeGenerated": "number",
      "startTime": "string (ISO 8601)",
      "endTime": "string (ISO 8601) | null"
    }
  ],
  "totalCount": "number",
  "hasMore": "boolean"
}
```

### GET /sessions/{id}
**Purpose**: Get detailed information about a specific trading session

**Response** (200 OK):
```json
{
  "id": "string",
  "name": "string",
  "status": "pending|active|paused|completed|failed",
  "accounts": ["string"],
  "strategy": { /* TradingStrategy object */ },
  "volumeTarget": "number",
  "volumeGenerated": "number",
  "startTime": "string (ISO 8601)",
  "endTime": "string (ISO 8601) | null",
  "riskBreaches": [
    {
      "id": "string",
      "accountId": "string",
      "breachType": "string",
      "threshold": "number",
      "actual": "number",
      "severity": "warning|critical",
      "action": "string",
      "timestamp": "string (ISO 8601)",
      "resolved": "boolean"
    }
  ],
  "orders": [
    {
      "id": "string",
      "accountId": "string",
      "symbol": "string",
      "side": "buy|sell",
      "type": "market|limit",
      "size": "number",
      "price": "number | null",
      "status": "string",
      "fillPrice": "number | null",
      "fillSize": "number | null",
      "fees": "number",
      "slippage": "number | null",
      "createdAt": "string (ISO 8601)"
    }
  ]
}
```

### POST /sessions/{id}/start
**Purpose**: Start an active trading session

**Response** (200 OK):
```json
{
  "id": "string",
  "status": "active",
  "startTime": "string (ISO 8601)",
  "message": "Trading session started successfully"
}
```

**Error Responses**:
- 400 Bad Request: Session not in pending state
- 422 Unprocessable Entity: Accounts not ready or risk checks failed

### POST /sessions/{id}/pause
**Purpose**: Pause an active trading session

**Response** (200 OK):
```json
{
  "id": "string",
  "status": "paused",
  "message": "Trading session paused"
}
```

### POST /sessions/{id}/resume
**Purpose**: Resume a paused trading session

**Response** (200 OK):
```json
{
  "id": "string",
  "status": "active",
  "message": "Trading session resumed"
}
```

### POST /sessions/{id}/stop
**Purpose**: Stop and complete a trading session

**Response** (200 OK):
```json
{
  "id": "string",
  "status": "completed",
  "endTime": "string (ISO 8601)",
  "volumeGenerated": "number",
  "message": "Trading session completed successfully"
}
```

## Order Operations

### GET /sessions/{id}/orders
**Purpose**: Get all orders for a specific trading session

**Query Parameters**:
- `accountId`: Filter by account ID
- `status`: Filter by order status
- `limit`: Number of orders to return (default: 100)
- `offset`: Number of orders to skip (default: 0)

**Response** (200 OK):
```json
{
  "orders": [
    {
      "id": "string",
      "accountId": "string",
      "symbol": "string",
      "side": "buy|sell",
      "type": "market|limit",
      "size": "number",
      "price": "number | null",
      "status": "pending|filled|partial|cancelled|failed",
      "fillPrice": "number | null",
      "fillSize": "number | null",
      "fees": "number",
      "slippage": "number | null",
      "createdAt": "string (ISO 8601)",
      "updatedAt": "string (ISO 8601)"
    }
  ],
  "totalCount": "number",
  "hasMore": "boolean"
}
```

### GET /sessions/{id}/orders/{orderId}
**Purpose**: Get detailed information about a specific order

**Response** (200 OK):
```json
{
  "id": "string",
  "sessionId": "string",
  "accountId": "string",
  "symbol": "string",
  "side": "buy|sell",
  "type": "market|limit",
  "size": "number",
  "price": "number | null",
  "status": "string",
  "fillPrice": "number | null",
  "fillSize": "number | null",
  "fees": "number",
  "slippage": "number | null",
  "createdAt": "string (ISO 8601)",
  "updatedAt": "string (ISO 8601)",
  "pacificaOrderId": "string | null"
}
```

## Validation Rules

### Session Creation
- Must have at least 2 accounts for wash trading
- Volume target must be positive
- Price range min must be less than max
- Timing intervals must be positive (min ≤ max)
- Order size limits must be positive (min ≤ max)
- All risk limits must be within acceptable ranges

### Session Operations
- Can only start sessions in 'pending' status
- Can only pause/resume sessions in 'active' status
- Can only stop sessions in 'active' or 'paused' status

### Order Filtering
- Account ID must be valid and participating in the session
- Status filters must use valid order status values
- Limit and offset must be non-negative integers