Skip to content

Poseidon - Risk Engine Service

Overview

Poseidon is a high-performance risk engine service for the Kyan exchange that calculates comprehensive risk metrics for margin portfolios in cryptocurrency trading. It provides fast, vectorized calculations for maintenance margin requirements, portfolio greeks, and risk assessments across complex options and perpetual futures positions.

💡 Beginner Tip: Think of Poseidon as the "safety inspector" of the exchange. Before trades are executed, it quickly analyzes positions to calculate how much collateral (margin) traders need to keep their positions secure, especially during market volatility. This helps prevent liquidations and ensures the exchange remains financially stable.

Features

  • Fast, vectorized calculation of risk metrics
  • Support for both internal (margin accounts) and external (user portfolios) risk calculations
  • Portfolio-level greeks calculation (delta, gamma, vega, theta, rho)
  • Maintenance margin calculations including:
  • Matrix risk (worst-case loss scenarios)
  • Delta risk (systemic risk adjustments)
  • Roll risk (expiration-related risk)
  • Vectorized risk calculations - Fast, matrix-based computation of risk metrics
  • Portfolio-level greeks - Delta, gamma, vega, theta, and rho calculations
  • Advanced margin models - Matrix risk, delta risk, and roll risk components
  • Dual-mode operation - Internal (margin accounts) and external (user portfolios) calculations
  • Stress testing - Multiple market shock scenarios for robust risk assessment
  • Real-time calculations - Optimized for low-latency processing

Margin Model Validation

Deribit Benchmark Comparison

The evaluate.py script in the margin_comparison directory allows for systematic comparison between Poseidon's internal risk model and Deribit's margin calculation API. This tool helps validate our risk model accuracy against industry standards.

Features

  • Side-by-side comparison of margin requirements
  • Systematic testing with random and structured portfolios
  • Statistical analysis of margin differences
  • Visual representation via scatter plots and histograms
  • The exploratory data analysis notebook (eda.ipynb) can be used to further compare the two risk models, and allows cherry picking of portfolios with a large discrepancy.

Usage

# Set required environment variables
export DERIBIT_API_KEY=your_api_key
export DERIBIT_API_SECRET=your_api_secret

# Run from the margin_comparison directory
cd margin_comparison
python evaluate.py

Output

The script generates:

  • Detailed comparison data saved as JSON (margin_comparison_results_YYYYMMDD_HHMMSS.json)
  • Visual representations of margin differences (margin_comparison.pdf)
  • Distribution analysis of calculation differences (margin_comparison_histogram.pdf)

Implementation Details

The benchmark utility uses Deribit's API to:

  1. Fetch real-time mark prices and implied volatilities
  2. Submit test portfolios for margin calculation
  3. Compare results with Poseidon's internal calculations
  4. Generate statistical summaries of differences

This validation process ensures our risk model remains properly calibrated against industry standards while maintaining the performance benefits of our vectorized implementation.

Technical Specifications

Core Technology Stack

  • Runtime: Python 3.9+
  • Primary Frameworks: FastAPI, NumPy, Pandas
  • Build System: Poetry with NX
  • Testing: Pytest
  • Formatting: Ruff, Black
  • Database: PostgreSQL (via SQLAlchemy)
  • Version: 0.1.0

Dependencies

  • Core:

  • fastapi - API framework for endpoints

  • numpy/pandas - Vectorized mathematical operations
  • pydantic - Data validation and modeling
  • uvicorn - ASGI server
  • faststream - Stream processing

  • sqlalchemy/sqlmodel - Database ORM

  • Testing:

  • pytest - Testing framework

  • pytest-asyncio - Async test support

  • pytest-cov - Test coverage

  • Internal Libraries:

  • commons - Shared Python utilities
  • chainpyon - Blockchain interaction utilities

Getting Started

Prerequisites

  • Python 3.9-3.10
  • Poetry package manager
  • PostgreSQL database
  • Redis instance
  • Numpy and other scientific libraries

Environment Setup

# Copy and configure environment variables
cp .env.example .env
# Edit .env with appropriate values

Required environment variables:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/exchange # Database URL
REDIS_URL=redis://localhost:6379/0 # Redis URL
LOG_LEVEL=info # Logging level
MATRIX_RISK_ENABLED=true # Enable matrix risk calculations

Installation

# Install dependencies
nx run poseidon:install

# Run tests
nx run poseidon:test

Development

# Run linting
nx run poseidon:lint

# Run type checking
nx run poseidon:typecheck

# Start development server
nx run poseidon:serve

Service Architecture

Component Overview

┌───────────────┐         ┌───────────────┐         ┌───────────────┐
│               │         │               │         │               │
│  FastAPI      │◄───────►│  Portfolio    │◄───────►│  Risk Model   │
│  Service      │         │  Processor    │         │  Calculator   │
│               │         │               │         │               │
└───────────────┘         └───────────────┘         └───────────────┘
        │                         │                         │
        │                         │                         │
        ▼                         ▼                         ▼
┌───────────────┐         ┌───────────────┐         ┌───────────────┐
│               │         │               │         │               │
│  Data         │         │  Greeks       │         │  Market Shock │
│  Models       │         │  Calculator   │         │  Generator    │
│               │         │               │         │               │
└───────────────┘         └───────────────┘         └───────────────┘

Core Components

  1. FastAPI Service (poseidon/main.py)

  2. API endpoints for risk calculations

  3. Request validation and handling

  4. Service health monitoring

  5. Portfolio Processor (poseidon/processor.py)

  6. Processes input portfolios

  7. Computes equity and unrealized PnL

  8. Vectorized position data preparation

  9. Risk Model Calculator (poseidon/margin_calculator.py)

  10. Maintenance margin calculations

  11. Matrix risk algorithms

  12. Roll risk and delta risk computations

  13. Greeks Calculator

  14. Portfolio-level greeks computation

  15. Options sensitivity metrics

  16. Exposure analytics

  17. Data Models (poseidon/models.py)

  18. Position and portfolio schemas
  19. API request/response models
  20. Risk metric definitions

Project Structure

poseidon/
├── poseidon/             # Source code
│   ├── margin_calculator.py  # Risk model implementation
│   ├── models.py         # Data structures
│   ├── processor.py      # Portfolio processing
│   ├── config.py         # Configuration settings
│   └── main.py           # FastAPI application
├── tests/                # Test suite
│   ├── test_margin_calculator.py  # Risk model tests
│   ├── test_processor.py # Processor tests
│   └── test_main.py      # API endpoint tests
├── pyproject.toml        # Poetry configuration
└── pyrightconfig.json    # Type checking configuration

Risk Calculation Methodology

Maintenance Margin Components

  1. Matrix Risk

  2. Stress-tests portfolios across price and volatility scenarios

  3. Identifies worst-case loss scenarios

  4. Calculates required collateral to cover these losses

  5. Delta Risk

  6. Addresses systemic market exposure

  7. Applies beta adjustments for large delta exposure

  8. Scales with portfolio size and market concentration

  9. Roll Risk

  10. Adds protection for near-expiry options
  11. Increases as options approach expiration
  12. Prevents liquidity issues during settlement

Calculation Process

  1. Positions are converted to a standardized matrix format
  2. Market scenarios are generated (price shocks, volatility changes)
  3. Portfolio value is calculated under each scenario
  4. Worst-case losses are identified
  5. Additional risk components are added
  6. Final maintenance margin requirement is computed

API Reference

Endpoint Method Description Request Body Response
/private/calculate_margin_risk POST Calculate risk metrics for margin accounts Array of margin portfolios Risk metrics with success/failure status
/public/calculate_portfolio_risk POST Calculate risk metrics for external portfolios Array of user portfolios Risk metrics without equity
/private/health GET Service health check N/A Service status

Request Example (Margin Portfolio)

{
  "pair": "BTC_USDC",
  "positions": [
    {
      "instrument": "BTC_USDC-28JUN24-80000-C",
      "size": 1.5,
      "average_price": 0.015
    }
  ],
  "marginAccountId": 123,
  "marginAccount": {
    "total_deposits": 100.0,
    "total_withdrawals": 20.0,
    "accrued_funding": 0.5,
    "realised_pnl": 15.0
  }
}

Response Example

{
  "status": "success",
  "data": {
    "equity": 95.5,
    "unrealizedPnl": 2.0,
    "maintenanceMargin": 8.5,
    "initialMargin": 17.0,
    "greeks": {
      "delta": 0.35,
      "gamma": 0.0002,
      "vega": 0.15,
      "theta": -0.08,
      "rho": 0.03
    }
  }
}

Integration Points

External Dependencies

  • Exchange Data Store: Market data and instrument information
  • Sequencer Service: Position and account data
  • SQL Database: Persistent storage of risk parameters

Internal Dependencies

  • Orderbook Service: Pre-trade risk checking
  • UI Components: Portfolio risk display

Performance Considerations

  • Vectorized calculations using NumPy for maximum efficiency
  • Optimized position matrix handling
  • Caching of intermediate results
  • Parallel processing for multiple portfolios
  • Efficient market data processing

Monitoring and Health

  • FastAPI built-in health check endpoint: /private/health
  • Performance metrics for calculation latency
  • Error monitoring and alerting

Troubleshooting

Common Issues

Issue Possible Cause Solution
High calculation latency Large portfolio size 1. Check portfolio size
2. Verify NumPy optimization
3. Consider batching calculations
Incorrect risk values Market data issues 1. Verify market data sources
2. Check instrument parameters
3. Validate volatility inputs
Memory errors Portfolio matrix size 1. Monitor memory usage
2. Implement garbage collection
3. Consider splitting large portfolios

Debugging Tips

  • Enable debug logging by setting LOG_LEVEL=debug in .env
  • Use pandas profiling to identify bottlenecks: 
    import pandas as pd
profile = pd.DataFrame(position_data).profile_report()
  • Monitor NumPy array shapes and memory usage: 
    import numpy as np
print(f"Shape: {array.shape}, Memory: {array.nbytes / 1e6} MB")

Future Optimizations

  1. GPU acceleration for matrix operations
  2. Cached scenario generation
  3. Distributed calculation for large portfolios
  4. Advanced calibration for extreme market conditions

Contributing

For guidelines on contributing to this project, please see the CLAUDE.md file in the repository root.

License

Proprietary - All rights reserved

This documentation is generated from the service README. For the most up-to-date information, refer to the original README