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

Trading Session API Contracts

Trading Session Operations

POST /sessions

Purpose: Create a new wash trading session

Request:

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "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):

{
  "id": "string",
  "status": "paused",
  "message": "Trading session paused"
}

POST /sessions/{id}/resume

Purpose: Resume a paused trading session

Response (200 OK):

{
  "id": "string",
  "status": "active",
  "message": "Trading session resumed"
}

POST /sessions/{id}/stop

Purpose: Stop and complete a trading session

Response (200 OK):

{
  "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):

{
  "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):

{
  "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