# Quickstart Guide: Pacifica Multi-Account BTC Wash Trading System

**Date**: 2024-12-29  
**Feature**: Multi-account wash trading system for BTC pairs  
**Status**: Complete

## Prerequisites

### System Requirements
- Node.js 18+ 
- TypeScript 5.0+
- Pacifica DEX API access
- Multiple Pacifica trading accounts

### Environment Setup
```bash
# Clone repository
git clone <repository-url>
cd pacifica-wash-trading

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration
```

### Environment Variables
```bash
# Pacifica API Configuration
PACIFICA_API_KEY=your_api_key_here
PACIFICA_BASE_URL=https://api.pacifica.fi
WEBSOCKET_URL=wss://ws.pacifica.fi

# System Configuration
PORT=3000
LOG_LEVEL=info
ENCRYPTION_KEY=your_encryption_key_here

# Database Configuration (if using persistent storage)
DATABASE_URL=postgresql://user:password@localhost:5432/wash_trading
```

## Installation

### 1. Install Dependencies
```bash
npm install
```

### 2. Build the Project
```bash
npm run build
```

### 3. Run Tests
```bash
npm test
```

## Configuration

### 1. Account Configuration
Create `config/accounts.json`:
```json
{
  "accounts": [
    {
      "id": "account-1",
      "name": "Primary Trading Account",
      "apiKey": "encrypted_api_key_1",
      "privateKey": "encrypted_private_key_1",
      "address": "0x1234567890abcdef1234567890abcdef12345678",
      "riskLimits": {
        "maxPositionSize": 0.1,
        "stopLossThreshold": 0.05,
        "maxSlippage": 0.02
      },
      "isActive": true
    },
    {
      "id": "account-2",
      "name": "Secondary Trading Account",
      "apiKey": "encrypted_api_key_2",
      "privateKey": "encrypted_private_key_2",
      "address": "0xabcdef1234567890abcdef1234567890abcdef12",
      "riskLimits": {
        "maxPositionSize": 0.1,
        "stopLossThreshold": 0.05,
        "maxSlippage": 0.02
      },
      "isActive": true
    }
  ]
}
```

### 2. Trading Strategies Configuration
Create `config/trading-strategies.json`:
```json
{
  "strategies": [
    {
      "id": "equal-volume-btc",
      "name": "Equal Volume BTC Strategy",
      "type": "equal_volume",
      "symbol": "BTC/USD",
      "parameters": {
        "volumeDistribution": "equal",
        "priceRange": {
          "min": 0.001,
          "max": 0.01
        },
        "timing": {
          "minInterval": 30000,
          "maxInterval": 120000,
          "orderSize": {
            "min": 0.1,
            "max": 0.5
          }
        },
        "riskLimits": {
          "maxPositionSize": 0.1,
          "stopLossThreshold": 0.05,
          "maxSlippage": 0.02
        }
      },
      "isActive": true
    }
  ]
}
```

### 3. Risk Limits Configuration
Create `config/risk-limits.json`:
```json
{
  "globalLimits": {
    "maxTotalExposure": 1000000,
    "maxDrawdown": 0.1,
    "maxCorrelation": 0.95,
    "maxVolatility": 0.5
  },
  "accountLimits": {
    "maxPositionSize": 0.1,
    "stopLossThreshold": 0.05,
    "maxSlippage": 0.02,
    "minMarginRatio": 0.1
  },
  "sessionLimits": {
    "maxDuration": 7200000,
    "maxOrderPairs": 1000,
    "maxConcurrentSessions": 5
  }
}
```

## Basic Usage

### 1. Start the System
```bash
# Start the wash trading system
npm start

# Or run in development mode
npm run dev
```

### 2. CLI Commands

#### Create a New Session
```bash
# Create a wash trading session
npx tsx src/cli/commands/create-session.ts \
  --name "BTC Wash Trading Session 1" \
  --strategy "equal-volume-btc" \
  --accounts "account-1,account-2,account-3" \
  --target-volume 10.5 \
  --duration 3600000
```

#### Start a Session
```bash
# Start an existing session
npx tsx src/cli/commands/start-session.ts --session-id "session-123"
```

#### Monitor Session Status
```bash
# Get session status
npx tsx src/cli/commands/status.ts --session-id "session-123"

# Get all active sessions
npx tsx src/cli/commands/status.ts --all
```

#### Pause/Resume Session
```bash
# Pause a session
npx tsx src/cli/commands/pause-session.ts --session-id "session-123"

# Resume a session
npx tsx src/cli/commands/resume-session.ts --session-id "session-123"
```

#### Stop Session
```bash
# Stop a session
npx tsx src/cli/commands/stop-session.ts --session-id "session-123"
```

### 3. Dashboard Interface
```bash
# Launch the CLI dashboard
npx tsx src/cli/dashboard.ts
```

The dashboard provides:
- Real-time session status
- Account balance monitoring
- Risk metrics display
- Order execution tracking
- Performance analytics

## API Usage

### 1. REST API

#### Create Session
```bash
curl -X POST http://localhost:3000/api/v1/sessions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_token_here" \
  -d '{
    "name": "BTC Wash Trading Session 1",
    "strategyId": "equal-volume-btc",
    "accountIds": ["account-1", "account-2"],
    "targetVolume": 5.0,
    "duration": 1800000
  }'
```

#### Get Session Status
```bash
curl -X GET http://localhost:3000/api/v1/sessions/session-123 \
  -H "Authorization: Bearer your_token_here"
```

#### Start Session
```bash
curl -X POST http://localhost:3000/api/v1/sessions/session-123/start \
  -H "Authorization: Bearer your_token_here"
```

### 2. WebSocket API

#### Connect to WebSocket
```javascript
const ws = new WebSocket('ws://localhost:3000/ws');

ws.on('open', () => {
  console.log('Connected to wash trading system');
});

ws.on('message', (data) => {
  const message = JSON.parse(data);
  console.log('Received:', message);
});
```

#### Subscribe to Session Updates
```javascript
// Subscribe to session updates
ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'session_updates',
  sessionId: 'session-123'
}));

// Subscribe to risk alerts
ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'risk_alerts',
  sessionId: 'session-123'
}));
```

## Advanced Examples

### 1. Multi-Account Coordination

#### Initialize Multiple Accounts
```typescript
import { AccountManager } from './src/services/AccountManager';
import { OrderCoordinator } from './src/services/OrderCoordinator';

// Initialize account manager
const accountManager = new AccountManager();
await accountManager.loadAccounts('config/accounts.json');

// Initialize order coordinator
const orderCoordinator = new OrderCoordinator(accountManager);

// Create wash trading session
const session = await orderCoordinator.createSession({
  name: 'Multi-Account BTC Session',
  strategyId: 'equal-volume-btc',
  accountIds: ['account-1', 'account-2', 'account-3'],
  targetVolume: 15.0,
  duration: 3600000
});

// Start session
await orderCoordinator.startSession(session.id);
```

### 2. Risk Management

#### Monitor Risk Metrics
```typescript
import { RiskManager } from './src/services/RiskManager';

const riskManager = new RiskManager();

// Set up risk monitoring
riskManager.on('riskAlert', (alert) => {
  console.log('Risk Alert:', alert);
  
  if (alert.severity === 'critical') {
    // Auto-pause session on critical alerts
    orderCoordinator.pauseSession(session.id);
  }
});

// Get current risk metrics
const metrics = await riskManager.getRiskMetrics(session.id);
console.log('Risk Score:', metrics.riskScore);
console.log('Total Exposure:', metrics.totalExposure);
```

### 3. Custom Trading Strategy

#### Create Custom Strategy
```typescript
import { BaseStrategy } from './src/strategies/BaseStrategy';

class CustomBTCStrategy extends BaseStrategy {
  async generateOrderPair(session: WashTradingSession): Promise<OrderPair> {
    // Custom logic for generating order pairs
    const accounts = session.accounts;
    const buyAccount = accounts[0];
    const sellAccount = accounts[1];
    
    const volume = this.calculateVolume(session);
    const price = await this.getCurrentPrice('BTC/USD');
    const spread = this.calculateSpread(price);
    
    return {
      id: this.generateId(),
      sessionId: session.id,
      buyOrder: {
        id: this.generateId(),
        accountId: buyAccount,
        symbol: 'BTC/USD',
        side: 'buy',
        type: 'limit',
        size: volume,
        price: price - spread / 2,
        status: 'pending',
        createdAt: new Date()
      },
      sellOrder: {
        id: this.generateId(),
        accountId: sellAccount,
        symbol: 'BTC/USD',
        side: 'sell',
        type: 'limit',
        size: volume,
        price: price + spread / 2,
        status: 'pending',
        createdAt: new Date()
      },
      status: 'pending',
      volume,
      price,
      createdAt: new Date()
    };
  }
  
  private calculateVolume(session: WashTradingSession): number {
    // Custom volume calculation logic
    const remainingVolume = session.targetVolume - session.currentVolume;
    const timeRemaining = session.duration - (Date.now() - session.startTime.getTime());
    const timeRatio = timeRemaining / session.duration;
    
    return Math.min(remainingVolume * 0.1, 0.5) * timeRatio;
  }
}
```

### 4. Performance Monitoring

#### Monitor System Performance
```typescript
import { PerformanceMonitor } from './src/utils/PerformanceMonitor';

const monitor = new PerformanceMonitor();

// Monitor order execution latency
monitor.on('orderExecuted', (metrics) => {
  console.log('Order Execution Time:', metrics.executionTime, 'ms');
  console.log('Slippage:', metrics.slippage, '%');
  console.log('Fees:', metrics.fees, 'USD');
});

// Monitor system health
monitor.on('healthCheck', (health) => {
  console.log('System Health:', health.status);
  console.log('Active Sessions:', health.activeSessions);
  console.log('Orders per Minute:', health.ordersPerMinute);
});
```

## Testing

### 1. Unit Tests
```bash
# Run all unit tests
npm run test:unit

# Run specific test file
npm run test:unit -- --testNamePattern="AccountManager"
```

### 2. Integration Tests
```bash
# Run integration tests
npm run test:integration

# Run with coverage
npm run test:coverage
```

### 3. Contract Tests
```bash
# Run contract tests
npm run test:contract

# Test specific API endpoint
npm run test:contract -- --testNamePattern="POST /sessions"
```

### 4. Performance Tests
```bash
# Run performance benchmarks
npm run test:performance

# Load test with multiple sessions
npm run test:load -- --sessions=10 --duration=300000
```

## Troubleshooting

### Common Issues

#### 1. API Connection Failed
```bash
# Check API connectivity
curl -X GET https://api.pacifica.fi/health

# Verify API key
curl -X GET https://api.pacifica.fi/account/info \
  -H "X-API-Key: your_api_key_here"
```

#### 2. Account Balance Insufficient
```bash
# Check account balances
npx tsx src/cli/commands/check-balances.ts --account-id "account-1"

# Update account configuration
npx tsx src/cli/commands/update-account.ts --account-id "account-1" --balance 100000
```

#### 3. Risk Limits Exceeded
```bash
# Check risk metrics
npx tsx src/cli/commands/risk-status.ts --session-id "session-123"

# Acknowledge risk alerts
npx tsx src/cli/commands/acknowledge-alert.ts --alert-id "alert-1"
```

#### 4. WebSocket Connection Issues
```bash
# Test WebSocket connection
npx tsx src/cli/commands/test-websocket.ts

# Check WebSocket status
npx tsx src/cli/commands/websocket-status.ts
```

### Debug Mode
```bash
# Run with debug logging
DEBUG=* npm start

# Run with specific debug modules
DEBUG=pacifica:api,pacifica:websocket npm start
```

### Log Files
```bash
# View system logs
tail -f logs/system.log

# View error logs
tail -f logs/error.log

# View audit logs
tail -f logs/audit.log
```

## Security Considerations

### 1. Private Key Management
- Private keys are encrypted using AES-256
- Keys are stored locally, never transmitted
- Use strong encryption keys
- Regularly rotate encryption keys

### 2. API Security
- Use HTTPS for all API communications
- Implement rate limiting
- Validate all input parameters
- Log all API requests and responses

### 3. Risk Management
- Set appropriate risk limits
- Monitor positions continuously
- Implement automatic stop-loss
- Regular risk assessments

### 4. Compliance
- Maintain audit trails
- Log all trading activities
- Implement position reporting
- Regular compliance reviews

## Performance Optimization

### 1. System Tuning
```bash
# Increase Node.js memory limit
node --max-old-space-size=4096 src/index.js

# Enable cluster mode
npm run start:cluster
```

### 2. Database Optimization
```bash
# Optimize database connections
# Set connection pool size
# Enable query caching
```

### 3. Network Optimization
```bash
# Use connection pooling
# Implement request batching
# Enable compression
```

## Support

### Documentation
- [API Documentation](./contracts/wash-trading-api.md)
- [Data Model](./data-model.md)
- [Research Findings](./research.md)

### Community
- GitHub Issues: [Report bugs and request features]
- Discord: [Join the community]
- Email: [support@example.com]

### Professional Support
- Enterprise support available
- Custom strategy development
- Performance optimization consulting
- Security audits and compliance reviews