pacifica/specs/001-ts-pacifica-perp/contracts/hedging-contracts.md

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

Message Schema:

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:

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:

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:

interface AcknowledgeRiskBreachRequest {
  action: 'resolve' | 'ignore';
  comment?: string;
}

Response Schema:

interface AcknowledgeRiskBreachResponse {
  success: boolean;
  breach: {
    id: string;
    resolved: boolean;
    acknowledgedAt: string;
    action: string;
  };
  message?: string;
}

Error Handling

Standard Error Response

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