# Hedging Session API Contracts

**Feature**: Pacifica Multi-Account Hedging System  
**Date**: 2024-12-19  
**Status**: Complete

## Hedging Session Management Endpoints

### 1. Create Hedging Session

**Endpoint**: `POST /hedging-sessions`  
**Purpose**: Create a new hedging session with multiple accounts

**Request Schema**:
```typescript
interface CreateHedgingSessionRequest {
  name: string;                    // Session name (3-50 chars)
  accountIds: string[];            // Array of account IDs (min 2)
  volumeTarget: number;            // Target trading volume
  strategy: {
    symbol: string;                // Trading pair (e.g., "ETH/USD")
    volumeDistribution: 'equal' | 'weighted'; // Volume distribution method
    priceRange: {
      min: number;                 // Minimum price deviation
      max: number;                 // Maximum price deviation
    };
    timing: {
      minInterval: number;         // Minimum seconds between orders
      maxInterval: number;         // Maximum seconds between orders
      orderSize: {
        min: number;               // Minimum order size
        max: number;               // Maximum order size
      };
    };
    riskLimits: {
      maxPositionSize: number;     // Max position size per account
      stopLossThreshold: number;   // Portfolio loss % to trigger halt
      maxSlippage: number;         // Maximum acceptable slippage
    };
  };
}
```

**Response Schema**:
```typescript
interface CreateHedgingSessionResponse {
  success: boolean;
  session: {
    id: string;
    name: string;
    status: 'pending';
    accounts: string[];
    strategy: HedgingStrategy;
    volumeTarget: number;
    volumeGenerated: number;
    startTime: string;             // ISO timestamp
    riskBreaches: [];
    orders: [];
  };
  message?: string;
}
```

**Validation Rules**:
- Session name: 3-50 characters
- At least 2 accounts required
- Volume target must be positive
- All strategy parameters within valid ranges
- All accounts must be active and have sufficient balance

### 2. List Hedging Sessions

**Endpoint**: `GET /hedging-sessions`  
**Purpose**: Retrieve all hedging sessions

**Request Schema**: None (query parameters optional)

**Response Schema**:
```typescript
interface ListHedgingSessionsResponse {
  success: boolean;
  sessions: Array<{
    id: string;
    name: string;
    status: SessionStatus;
    accounts: string[];
    volumeTarget: number;
    volumeGenerated: number;
    startTime: string;
    endTime?: string;
  }>;
  total: number;
}
```

**Query Parameters**:
- `status`: Filter by session status
- `accountId`: Filter by participating account
- `limit`: Maximum number of sessions to return
- `offset`: Number of sessions to skip

### 3. Get Hedging Session Details

**Endpoint**: `GET /hedging-sessions/{id}`  
**Purpose**: Retrieve detailed information for a specific session

**Request Schema**: Session ID in URL path

**Response Schema**:
```typescript
interface GetHedgingSessionResponse {
  success: boolean;
  session: {
    id: string;
    name: string;
    status: SessionStatus;
    accounts: string[];
    strategy: HedgingStrategy;
    volumeTarget: number;
    volumeGenerated: number;
    startTime: string;
    endTime?: string;
    riskBreaches: Array<{
      id: string;
      breachType: string;
      severity: 'warning' | 'critical';
      timestamp: string;
      resolved: boolean;
    }>;
    orders: Array<{
      id: string;
      accountId: string;
      symbol: string;
      side: 'buy' | 'sell';
      size: number;
      price: number;
      status: string;
      createdAt: string;
    }>;
  };
}
```

### 4. Start Hedging Session

**Endpoint**: `POST /hedging-sessions/{id}/start`  
**Purpose**: Start a pending hedging session

**Request Schema**: Session ID in URL path

**Response Schema**:
```typescript
interface StartHedgingSessionResponse {
  success: boolean;
  session: {
    id: string;
    status: 'active';
    startTime: string;
  };
  message?: string;
}
```

**Validation Rules**:
- Session must be in 'pending' status
- All participating accounts must be active
- Sufficient balance in all accounts
- No active risk breaches

### 5. Pause Hedging Session

**Endpoint**: `POST /hedging-sessions/{id}/pause`  
**Purpose**: Pause an active hedging session

**Request Schema**: Session ID in URL path

**Response Schema**:
```typescript
interface PauseHedgingSessionResponse {
  success: boolean;
  session: {
    id: string;
    status: 'paused';
    pausedAt: string;
  };
  message?: string;
}
```

**Validation Rules**:
- Session must be in 'active' status
- All pending orders will be cancelled
- Positions remain open

### 6. Resume Hedging Session

**Endpoint**: `POST /hedging-sessions/{id}/resume`  
**Purpose**: Resume a paused hedging session

**Request Schema**: Session ID in URL path

**Response Schema**:
```typescript
interface ResumeHedgingSessionResponse {
  success: boolean;
  session: {
    id: string;
    status: 'active';
    resumedAt: string;
  };
  message?: string;
}
```

**Validation Rules**:
- Session must be in 'paused' status
- All participating accounts must still be active
- No new risk breaches since pause

### 7. Stop Hedging Session

**Endpoint**: `POST /hedging-sessions/{id}/stop`  
**Purpose**: Stop a hedging session (active or paused)

**Request Schema**: Session ID in URL path

**Response Schema**:
```typescript
interface StopHedgingSessionResponse {
  success: boolean;
  session: {
    id: string;
    status: 'completed';
    endTime: string;
    finalVolume: number;
  };
  message?: string;
}
```

**Validation Rules**:
- Session must be in 'active' or 'paused' status
- All pending orders will be cancelled
- Session marked as completed

### 8. Get Session Orders

**Endpoint**: `GET /hedging-sessions/{id}/orders`  
**Purpose**: Retrieve all orders for a hedging session

**Request Schema**: Session ID in URL path

**Response Schema**:
```typescript
interface GetSessionOrdersResponse {
  success: boolean;
  orders: Array<{
    id: string;
    accountId: string;
    symbol: string;
    side: 'buy' | 'sell';
    type: 'market' | 'limit';
    size: number;
    price?: number;
    status: OrderStatus;
    fillPrice?: number;
    fillSize?: number;
    fees: number;
    slippage?: number;
    createdAt: string;
    updatedAt: string;
    pacificaOrderId?: string;
  }>;
  total: number;
}
```

**Query Parameters**:
- `status`: Filter by order status
- `accountId`: Filter by account
- `side`: Filter by order side
- `limit`: Maximum number of orders to return
- `offset`: Number of orders to skip

## Real-time Data Endpoints

### 9. Subscribe to Market Data

**Endpoint**: `WebSocket /ws/market-data`  
**Purpose**: Real-time market data streaming

**Connection Schema**:
```typescript
interface MarketDataSubscription {
  type: 'subscribe';
  symbols: string[];              // Trading pairs to subscribe to
  channels: ('price' | 'orderbook' | 'trades')[];
}
```

**Message Schema**:
```typescript
interface MarketDataMessage {
  type: 'price' | 'orderbook' | 'trade';
  symbol: string;
  data: {
    price?: number;
    volume24h?: number;
    change24h?: number;
    bids?: PriceLevel[];
    asks?: PriceLevel[];
    tradePrice?: number;
    tradeSize?: number;
  };
  timestamp: number;
}
```

### 10. Subscribe to Session Updates

**Endpoint**: `WebSocket /ws/sessions/{id}`  
**Purpose**: Real-time session status updates

**Message Schema**:
```typescript
interface SessionUpdateMessage {
  type: 'session_update';
  sessionId: string;
  data: {
    status: SessionStatus;
    volumeGenerated: number;
    volumeTarget: number;
    activeOrders: number;
    riskBreaches: number;
  };
  timestamp: number;
}
```

## Risk Management Endpoints

### 11. Get Risk Status

**Endpoint**: `GET /hedging-sessions/{id}/risk-status`  
**Purpose**: Get current risk status for a session

**Response Schema**:
```typescript
interface RiskStatusResponse {
  success: boolean;
  riskStatus: {
    sessionId: string;
    overallRisk: 'low' | 'medium' | 'high';
    accountRisks: Array<{
      accountId: string;
      riskLevel: 'low' | 'medium' | 'high';
      positionSize: number;
      marginRatio: number;
      pnl: number;
    }>;
    portfolioRisk: {
      totalPnl: number;
      maxDrawdown: number;
      var95: number;
    };
    activeBreaches: Array<{
      id: string;
      breachType: string;
      severity: 'warning' | 'critical';
      timestamp: string;
    }>;
  };
}
```

### 12. Acknowledge Risk Breach

**Endpoint**: `POST /hedging-sessions/{id}/risk-breaches/{breachId}/acknowledge`  
**Purpose**: Acknowledge and resolve a risk breach

**Request Schema**:
```typescript
interface AcknowledgeRiskBreachRequest {
  action: 'resolve' | 'ignore';
  comment?: string;
}
```

**Response Schema**:
```typescript
interface AcknowledgeRiskBreachResponse {
  success: boolean;
  breach: {
    id: string;
    resolved: boolean;
    acknowledgedAt: string;
    action: string;
  };
  message?: string;
}
```

## Error Handling

### Standard Error Response
```typescript
interface ErrorResponse {
  success: false;
  error: {
    code: string;
    message: string;
    details?: any;
  };
  timestamp: string;
}
```

### Hedging-Specific Error Codes
- `SESSION_NOT_FOUND`: Hedging session does not exist
- `INVALID_SESSION_STATUS`: Session not in required status
- `INSUFFICIENT_ACCOUNTS`: Not enough accounts for hedging
- `INSUFFICIENT_BALANCE`: Not enough balance in accounts
- `RISK_LIMIT_EXCEEDED`: Risk limits would be exceeded
- `MARKET_DATA_UNAVAILABLE`: Real-time data not available
- `ORDER_EXECUTION_FAILED`: Order could not be executed

## Rate Limiting

### Limits
- 100 requests per minute per client
- WebSocket connections: 10 per client
- Burst limit: 10 requests per second

### WebSocket Rate Limiting
- Market data updates: 1000 per minute
- Session updates: 100 per minute
- Connection limits enforced

## Authentication

### API Key Authentication
- Required for all REST endpoints
- Passed in `Authorization` header
- Format: `Bearer <api-key>`

### WebSocket Authentication
- API key passed in connection query parameter
- Format: `?api_key=<api-key>`
- Connection rejected if invalid

## Data Validation

### Input Validation
- All input data validated against schemas
- Session parameters within valid ranges
- Account IDs must exist and be active
- Strategy parameters validated for consistency

### Business Logic Validation
- Account balance sufficient for volume targets
- Risk limits not exceeded
- Market data available for trading pairs
- No conflicting sessions for same accounts

## Response Format

### Success Response
- `success: true` for successful operations
- Data included in response body
- Appropriate HTTP status codes

### Error Response
- `success: false` for failed operations
- Error details in standardized format
- Appropriate HTTP status codes

## WebSocket Protocol

### Connection Management
- Automatic reconnection on disconnect
- Heartbeat messages every 30 seconds
- Connection timeout after 60 seconds of inactivity

### Message Format
- JSON format for all messages
- Type field indicates message type
- Timestamp included in all messages
- Error messages for connection issues