⚡ DEMO MODE: This is a static demonstration for API documentation. All trading buttons and data updates are simulated. No real trades will be executed.

WEBSOCKET CONNECTED

Session: OPTIMUS_TRADING_001 | Market: PSX | T+2 Settlement Active

LATENCY

12ms

SYMBOLS

540

TICKS/SEC

TRADING ORDER TYPES MARKET DATA HOLDINGS WEBSOCKET REST APIS RISK APIS SETTLEMENT CORPORATE WEBHOOK PSX RULES

KSE 100

100 Largest companies

KSE 30

Top 30 Liquid

KMI 30

Shariah Compliant

KSE ALL

All Companies

KMI ALL

All Shariah

PSXDIV20

Dividend Paying

TRADING INTERFACE

MEBL - Meezan Bank Ltd

MEBL

Meezan Bank Limited

187.50 ▲ 2.30 (1.24%)

09:30 10:00 10:30 11:00 11:30 12:00 12:30 13:00 13:30 14:00 14:30 15:00

Shares 1,000

Market value PKR 187,500

Average cost PKR 180.50

Portfolio diversity 14.2%

                        Today's return
                        +PKR 100 (+0.05%)
                    

                        Total return
                        +PKR 7,000 (+3.88%)
                    

Price (PKR) Size Value (PKR)

187.00 Spread: 0.60 (0.32%) 187.60

Spread 0.60 (0.32%)

Open185.20

High188.00

Low185.10

Volume1,520,000

Total Bid Vol18,500

Total Ask Vol19,700

🔄 API INTEGRATION FLOW: Optimus → Vision Max

📱

Optimus

Application
Sends Trading Requests

→

⚡

Vision Max

Validates & Processes
Trading Requests

⚡ All orders from Optimus Processed through Vision Max with Local Pre-Trade Validation

Optimus: Trading Application

Vision Max: Trading Engine

ORDER TYPES

All POST · PSX Compatible

🔹 LIMIT ORDER POST /orders

MEBL

Meezan Bank Ltd

Bid: 187.00 Ask: 187.60

Quantity (lots of 500)

Limit Price (PKR)

Total Value: PKR 93,750.00

{
  "symbol": "MEBL",
  "side": "buy",
  "order_type": "limit",
  "quantity": 500,
  "price": 187.50,
  "time_in_force": "day"
}

📋 When to use:

Execute trade at a specific price or better. Used when price certainty is more important than immediate execution.

// Used by: Day traders, institutional investors for precise entries

⚡ MARKET ORDER POST /orders

MEBL

Meezan Bank Ltd

⚠️ Executes immediately at best available price

Quantity (lots of 500)

Estimated price range: 187.00 - 187.60

{
  "symbol": "MEBL",
  "side": "buy",
  "order_type": "market",
  "quantity": 500,
  "time_in_force": "day"
}

📋 When to use:

Execute immediately at current market price. Used when speed of execution is critical.

// Used by: Retail investors, urgent trade requirements

🛑 STOP LOSS POST /orders

MEBL

Meezan Bank Ltd

Quantity (lots of 500)

Stop Price (Trigger)

Limit Price (Optional)

🔒 PSX Rule: Trigger price must be below market for sell orders

{
  "symbol": "MEBL",
  "side": "sell",
  "order_type": "stop_loss",
  "quantity": 500,
  "trigger_price": 185.00,
  "price": 184.50,
  "time_in_force": "gtc"
}

📋 When to use:

Protect profits or limit losses by triggering a sale when price drops to a specified level.

// Used by: Risk-averse investors, portfolio protection

🎯 MIT / MTL POST /orders

MEBL

Meezan Bank Ltd

ℹ️ Market If Touched / Market To Limit (PSX Specific)

Quantity (lots of 500)

Trigger Price

{
  "symbol": "MEBL",
  "side": "buy",
  "order_type": "mit",
  "quantity": 500,
  "trigger_price": 188.50,
  "time_in_force": "day"
}

📋 When to use:

Execute when price touches a specific level. MIT becomes market order, MTL becomes limit order after trigger.

// Used by: Technical traders, breakout strategies

MARKET DATA

Real-time Indices · PSX

📊 KSE-100 Index

Value67,890.12

Change+120.45 (0.18%)

High67,950.00

Low67,700.00

Volume15.0M

📊 KSE-30 Index

Value22,345.67

Change+45.67 (0.20%)

High22,400.00

Low22,300.00

Volume8.5M

📊 KMI-30 Index

Value45,678.90

Change+89.12 (0.20%)

High45,700.00

Low45,600.00

Volume12.0M

📌 OPTIMUS API ECOSYSTEM - Complete Overview

🔐

Authentication APIs

POST /auth/login POST /auth/refresh POST /auth/logout

Secure user authentication and session management. Every trading session begins here.

// Used in: Mobile apps, web platforms, desktop trading applications

📈

Market Data APIs

WebSocket Streams market_watch symbol_detail

Real-time market data streaming for prices, order books, trades, and indices.

// Used in: Live charts, trading terminals, price alerts

📝

Trading APIs

POST /orders POST /orders/cancel POST /orders/status

Core trading functionality - place, modify, cancel orders with PSX rule validation.

// Used in: Order entry systems, algorithmic trading

💰

Portfolio APIs

POST /portfolio/summary POST /portfolio/holdings POST /account/buying-power

Account management - view holdings, portfolio performance, and buying power.

// Used in: Portfolio dashboards, risk management systems

🔔

Webhook Notifications

POST /webhook/visionmax

Real-time event notifications for order executions, rejections, and account alerts.

// Used in: Alert systems, trade confirmations

🏛️

PSX Compliance

Circuit Breakers Lot Size Rules T+2 Settlement

Pakistan Stock Exchange specific rules and validations applied to all orders.

// Used in: Pre-trade validation, compliance checks

1. WEBSOCKET MARKET DATA STREAMS

Real-Time · JWT Required

📡 What are WebSocket streams?

WebSocket connections provide real-time, bidirectional communication. Unlike REST APIs where you request data, WebSockets push data to your application as soon as it's available. Perfect for live trading screens, charts, and order books.

// Used in: Live price feeds, real-time charts, instant order updates

WS wss://md.optimuscapital.com/ws?token={jwt_token} General Connection

WS market_watch Top-level data stream

📤 Subscribe

{
  "action": "subscribe",
  "stream": "market_watch",
  "symbols": ["MEBL", "SYS", "ENGRO", "OGDC"],
  "client_id": "user_12345"
}

📥 Update

{
  "stream": "market_watch",
  "timestamp": "2024-05-20T10:15:30.123Z",
  "data": [
    {
      "symbol": "MEBL",
      "symbol_name": "Meezan Bank Ltd",
      "last_trade_price": 187.50,
      "change": 2.30,
      "change_percent": 1.24,
      "volume": 1520000,
      "high_24h": 188.00,
      "low_24h": 185.10,
      "open_price": 185.50,
      "close_price": 185.20,
      "upper_circuit": 203.72,
      "lower_circuit": 166.68,
      "status": "T"
    }
  ]
}

📋 What this is for:

Real-time updates for multiple symbols simultaneously. Used for market watch lists and overview screens.

// Used in: Dashboard overview, market monitor

WS symbol_detail Detailed symbol information

📤 Subscribe

{
  "action": "subscribe",
  "stream": "symbol_detail",
  "symbol": "MEBL"
}

📥 Update

{
  "stream": "symbol_detail",
  "symbol": "MEBL",
  "timestamp": "2024-05-20T10:15:31.456Z",
  "data": {
    "company_name": "Meezan Bank Ltd",
    "sector": "Commercial Banks",
    "ltp": 187.50,
    "change": 2.30,
    "change_percent": 1.24,
    "open": 185.20,
    "high": 188.00,
    "low": 185.10,
    "close": 185.20,
    "volume": 1520000,
    "turnover": 284050000.50,
    "market_cap": 375000000000,
    "pe_ratio": 6.50,
    "dividend_yield": 8.5,
    "upper_circuit": 203.72,
    "lower_circuit": 166.68,
    "lot_size": 500,
    "bid": 187.00,
    "bid_volume": 1500,
    "ask": 187.60,
    "ask_volume": 800
  }
}

📋 What this is for:

Comprehensive symbol information including fundamentals, circuit breakers, and real-time quote data.

// Used in: Stock detail pages, research screens

WS order_book Market depth - Level 2

📤 Subscribe

{
  "action": "subscribe",
  "stream": "order_book",
  "symbol": "MEBL",
  "depth": 10
}

📥 Update

{
  "stream": "order_book",
  "symbol": "MEBL",
  "timestamp": "2024-05-20T10:15:32.789Z",
  "data": {
    "bids": [
      {"price": 187.50, "volume": 10500, "orders": 5},
      {"price": 187.40, "volume": 8000, "orders": 3}
    ],
    "asks": [
      {"price": 187.60, "volume": 7200, "orders": 4},
      {"price": 187.70, "volume": 12500, "orders": 7}
    ],
    "total_bid_volume": 18500,
    "total_ask_volume": 19700,
    "sequence": 123456789
  }
}

📋 What this is for:

Real-time market depth showing all buy and sell orders. Essential for understanding supply/demand dynamics.

// Used in: Professional trading interfaces, depth charts

WS trade_tape Recent trades

📤 Subscribe

{
  "action": "subscribe",
  "stream": "trade_tape",
  "symbol": "MEBL"
}

📥 Update

{
  "stream": "trade_tape",
  "symbol": "MEBL",
  "timestamp": "2024-05-20T10:15:33.012Z",
  "data": {
    "trade_id": "1098765",
    "price": 187.50,
    "volume": 500,
    "value": 93750,
    "trade_time": "2024-05-20T10:15:32.500Z",
    "buyer_broker": "127",
    "seller_broker": "56"
  }
}

📋 What this is for:

Real-time trade execution feed showing every transaction as it happens on the exchange.

// Used in: Trade surveillance, market analysis

WS ohlc Candlestick data

📤 Subscribe

{
  "action": "subscribe",
  "stream": "ohlc",
  "symbol": "MEBL",
  "interval": "1m"
}

📥 Update

{
  "stream": "ohlc",
  "symbol": "MEBL",
  "interval": "1m",
  "timestamp": "2024-05-20T10:16:00.000Z",
  "data": {
    "open": 187.20,
    "high": 187.60,
    "low": 187.15,
    "close": 187.50,
    "volume": 85000,
    "is_closed": false
  }
}

📋 What this is for:

Real-time candlestick data for charting. Supports multiple timeframes from 1 minute to 1 day.

// Used in: Trading charts, technical analysis

WS index Market indices

📤 Subscribe

{
  "action": "subscribe",
  "stream": "index",
  "indices": ["KSE100", "KSE30", "KMI30"]
}

📥 Update

{
  "stream": "index",
  "timestamp": "2024-05-20T10:15:35.500Z",
  "data": [
    {
      "index_code": "KSE100",
      "index_name": "KSE-100 Index",
      "value": 67890.12,
      "change": 120.45,
      "change_percent": 0.18,
      "high": 67950.00,
      "low": 67700.00,
      "volume": 15000000
    }
  ]
}

📋 What this is for:

Real-time index values for market benchmarks like KSE-100, KSE-30, and KMI-30.

// Used in: Market overview, sentiment indicators

WS market_status Market status with PSX sessions

📤 Subscribe

{
  "action": "subscribe",
  "stream": "market_status"
}

📥 Update (PSX Specific)

{
  "stream": "market_status",
  "timestamp": "2024-05-20T09:30:00.000Z",
  "data": {
    "status": "CONTINUOUS_TRADING",
    "session": "MORNING",
    "current_time": "2024-05-20T10:30:00+05:00",
    "market_sessions": {
      "pre_open": {"start": "09:15", "end": "09:30", "active": false},
      "continuous": {"start": "09:30", "end": "15:30", "active": true},
      "post_close": {"start": "15:30", "end": "15:35", "active": false}
    },
    "next_event": {
      "type": "SESSION_END",
      "time": "2024-05-20T15:30:00+05:00",
      "name": "Market Close"
    },
    "is_trading_day": true,
    "message": "Regular Trading Session"
  }
}

📋 What this is for:

Real-time market status updates with PSX-specific sessions - pre-open, continuous trading, post-close sessions. Critical for order validation.

// Used in: Trading hours validation, market countdowns

2. TRADING REST APIS

Base: https://api.optimuscapital.com/v1 · ALL POST

🔌 What are REST APIs?

REST APIs follow a request-response pattern. Your application sends a request, and the server responds with data. Unlike WebSockets, these are not real-time - you ask for data when you need it. Perfect for account management, placing orders, and fetching historical data.

// Used in: Order placement, portfolio views, account management

POST /auth/login User authentication

📤 Request

{
  "login_id": "user@email.com",
  "password": "user_password",
  "device_id": "unique_device_fingerprint",
  "device_type": "mobile"
}

📥 Success (200)

{
  "status": "success",
  "code": 200,
  "message": "Authentication successful.",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "dGhpc2lzYXJlZnJlc2h0b2tlbg==",
    "token_type": "Bearer",
    "expires_in": 3600,
    "user": {
      "user_id": "12345",
      "full_name": "Alex Peter",
      "email": "alexpeter@gmail.com",
      "account_status": "active",
      "kyc_status": "approved"
    }
  },
  "request_id": "req-123e4567-e89b-12d3-a456-426614174000"
}

📋 What this is for:

Authenticates user and returns JWT token for subsequent API calls. Used at the start of every trading session.

// Used in: App login screens, session initialization

POST /auth/refresh Refresh token

📤 Request

{
  "refresh_token": "dGhpc2lzYXJlZnJlc2h0b2tlbg=="
}

📥 Response

{
  "status": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 3600
  },
  "request_id": "req-123e4567-e89b-12d3-a456-426614174002"
}

📋 What this is for:

Obtains a new access token when current one expires. Keeps user sessions alive without requiring re-login.

// Used in: Background session management, long-running applications

POST /auth/logout Logout

📤 Request

{
  "refresh_token": "dGhpc2lzYXJlZnJlc2h0b2tlbg=="
}

📥 Response

{
  "status": "success",
  "code": 200,
  "message": "Successfully logged out.",
  "request_id": "req-123e4567-e89b-12d3-a456-426614174003"
}

📋 What this is for:

Terminates user session and invalidates tokens. Used when user explicitly logs out.

// Used in: Logout buttons, session cleanup

POST /orders Place order (Idempotency-Key required)

📤 Request

{
  "symbol": "MEBL",
  "side": "buy",
  "order_type": "limit",
  "quantity": 500,
  "price": 187.50,
  "trigger_price": 185.00,
  "time_in_force": "day",
  "display_quantity": 100,
  "client_order_id": "my_order_ref_123"
}

📥 Success (202)

{
  "status": "accepted",
  "code": 202,
  "message": "Order placed successfully and sent to exchange.",
  "data": {
    "order_id": "ODR123456789",
    "client_order_id": "my_order_ref_123",
    "symbol": "MEBL",
    "side": "buy",
    "order_type": "limit",
    "quantity": 500,
    "price": 187.50,
    "status": "pending",
    "reject_reason": null,
    "order_time": "2024-05-20T10:20:00.123Z"
  },
  "request_id": "req-123e4567-e89b-12d3-a456-426614174004"
}

📋 What this is for:

Core trading endpoint - submits orders to the exchange with PSX rule validation (lot size, circuit breakers, market timings).

// Used in: Order entry screens, algorithmic trading systems

POST /orders/cancel Cancel existing order

📤 Request

{
  "order_id": "ODR123456789",
  "client_order_id": "my_order_ref_123",
  "reason": "user_requested"
}

📥 Response

{
  "status": "success",
  "code": 200,
  "message": "Order cancelled successfully",
  "data": {
    "order_id": "ODR123456789",
    "cancel_time": "2024-05-20T10:25:00.123Z"
  },
  "request_id": "req-123e4567-e89b-12d3-a456-426614174006"
}

📋 What this is for:

Cancels an open order before it executes. Used to modify trading strategy or remove unwanted orders.

// Used in: Order management, risk control

POST /orders/status Check order status

📤 Request

{
  "order_id": "ODR123456789",
  "include_details": true
}

📥 Response

{
  "status": "success",
  "data": {
    "order_id": "ODR123456789",
    "symbol": "MEBL",
    "side": "buy",
    "order_type": "limit",
    "quantity": 500,
    "executed_quantity": 200,
    "remaining_quantity": 300,
    "price": 187.50,
    "average_price": 187.48,
    "status": "partially_filled",
    "order_time": "2024-05-20T10:20:00.123Z",
    "last_update": "2024-05-20T10:21:00.123Z"
  },
  "request_id": "req-123e4567-e89b-12d3-a456-426614174007"
}

📋 What this is for:

Retrieves current status of an order - pending, filled, partially filled, or cancelled.

// Used in: Order tracking, trade confirmation screens

POST /portfolio/summary Get portfolio summary

📤 Request

{
  "user_id": "12345",
  "client_id": "optimus_001",
  "include_details": true,
  "as_of_date": "2024-05-20",
  "request_timestamp": "2024-05-20T10:30:00.000Z"
}

📥 Response

{
  "status": "success",
  "code": 200,
  "message": "Portfolio summary retrieved successfully",
  "data": {
    "user_id": "12345",
    "account_number": "A12345678",
    "total_investment": 1250000.00,
    "current_value": 1320000.00,
    "total_pnl": 70000.00,
    "total_pnl_percent": 5.6,
    "day_change": 2500.00,
    "day_change_percent": 0.19,
    "unrealized_pnl": 45000.00,
    "realized_pnl": 25000.00,
    "as_of": "2024-05-20T10:30:00.000Z"
  },
  "request_id": "req-123e4567-e89b-12d3-a456-426614174020"
}

📋 What this is for:

Provides overview of entire portfolio - total value, profit/loss, daily performance with T+2 settlement considerations.

// Used in: Dashboard views, performance reports

POST /portfolio/holdings Get user holdings

📤 Request

{
  "user_id": "12345",
  "client_id": "optimus_001",
  "filter": {
    "symbols": ["MEBL", "SYS"],
    "sector": "Banks",
    "include_zero": false,
    "sort_by": "value",
    "sort_order": "desc"
  },
  "pagination": {
    "page": 1,
    "limit": 50
  },
  "as_of_date": "2024-05-20",
  "request_timestamp": "2024-05-20T10:30:00.000Z"
}

📥 Response

{
  "status": "success",
  "code": 200,
  "data": {
    "user_id": "12345",
    "account_number": "A12345678",
    "holdings": [
      {
        "symbol": "MEBL",
        "symbol_name": "Meezan Bank Ltd",
        "sector": "Commercial Banks",
        "quantity": 1000,
        "available_quantity": 1000,
        "locked_quantity": 0,
        "average_price": 180.50,
        "ltp": 187.50,
        "current_value": 187500,
        "investment_value": 180500,
        "unrealized_pnl": 7000,
        "unrealized_pnl_percent": 3.88,
        "day_change": 100,
        "day_change_percent": 0.05,
        "portfolio_weight": 0.142
      }
    ],
    "summary": {
      "total_holdings_value": 1875000.00,
      "total_investment": 1750000.00,
      "total_unrealized_pnl": 125000.00
    },
    "pagination": {
      "current_page": 1,
      "total_pages": 1,
      "total_records": 12
    },
    "as_of": "2024-05-20T10:30:00.000Z"
  },
  "request_id": "req-123e4567-e89b-12d3-a456-426614174022"
}

📋 What this is for:

Lists all securities currently held in portfolio with detailed P&L, valuation, and available quantities.

// Used in: Portfolio management, tax calculations

3. PRE-TRADE VALIDATION & RISK APIS

Local Validation Before Vision Max

⚠️ CRITICAL: These APIs run locally before sending to Vision Max

Vision Max does NOT validate buying power, exposure limits, or circuit breakers. These checks must be performed locally to prevent order rejections and ensure compliance.

POST /risk/pre-trade-validate Complete pre-trade validation

📤 Request

{
  "user_id": 12345,
  "symbol": "MEBL",
  "side": "buy",
  "order_type": "limit",
  "quantity": 500,
  "price": 187.50
}

📥 Response

{
  "status": "success",
  "data": {
    "is_valid": true,
    "checks": {
      "symbol_active": {
        "valid": true,
        "message": "Symbol MEBL is active"
      },
      "market_open": {
        "valid": true,
        "current_session": "CONTINUOUS_TRADING",
        "message": "Market is open for trading"
      },
      "lot_size": {
        "valid": true,
        "lot_size": 500,
        "message": "Quantity is multiple of lot size"
      },
      "circuit_breaker": {
        "valid": true,
        "current_price": 187.50,
        "upper_limit": 203.72,
        "lower_limit": 166.68,
        "message": "Price within circuit breaker limits"
      },
      "buying_power": {
        "sufficient": true,
        "required": 93750.00,
        "available": 250000.00,
        "message": "Sufficient buying power available"
      },
      "position_limits": {
        "valid": true,
        "current_position": 1000,
        "max_allowed": 50000,
        "new_position": 1500,
        "message": "Within position limits"
      }
    },
    "estimated_cost": 93750.00,
    "estimated_brokerage": 187.50,
    "total_required": 93937.50,
    "validation_id": "val_240226_001234"
  }
}

📋 What this is for:

Validates order against all PSX rules before submission. If any check fails, order is rejected locally and never sent to Vision Max, saving time and preventing rejections.

// Called automatically by /orders endpoint before Vision Max submission

4. BUYING POWER & T+2 SETTLEMENT APIS

PSX Settlement Rules

POST /account/buying-power Real-time available funds

📤 Request

{
  "user_id": 12345,
  "account_type": "margin",
  "include_settlement": true,
  "for_symbol": "MEBL",
  "for_quantity": 500,
  "for_price": 188.00
}

📥 Response

{
  "status": "success",
  "data": {
    "user_id": 12345,
    "account_number": "A12345678",
    "account_type": "margin",
    "net_equity": 1500000.00,
    "cash_balance": 250000.00,
    "available_margin": 1250000.00,
    "used_margin": 250000.00,
    "maintenance_margin": 75000.00,
    "margin_ratio": 0.167,
    "unsettled_funds": {
      "incoming": 75000.00,
      "outgoing": 50000.00,
      "net_unsettled": 25000.00
    },
    "blocked_funds": {
      "open_orders": 93750.00,
      "withdrawal_requests": 50000.00,
      "total_blocked": 143750.00
    },
    "buying_power": {
      "intraday": 2500000.00,
      "delivery": 1250000.00,
      "margin_multiplier": 2.0,
      "cash_available": 250000.00,
      "margin_available": 1000000.00,
      "available_now": 156250.00
    },
    "as_of": "2024-05-20T10:30:00.000Z"
  }
}

📋 What this is for:

Calculates available funds considering T+2 settlement, blocked orders, and margin. PSX uses T+2 - funds from sales are unavailable for 2 days.

// Used in: Pre-trade validation, order entry screens

POST /settlement/unsettled T+2 settlement tracking

📤 Request

{
  "user_id": 12345,
  "as_of_date": "2024-05-20"
}

📥 Response

{
  "status": "success",
  "data": {
    "user_id": 12345,
    "unsettled_purchases": [
      {
        "trade_id": "TRD_123456",
        "symbol": "MEBL",
        "quantity": 500,
        "price": 187.50,
        "amount": 93750.00,
        "trade_date": "2024-05-20",
        "settlement_date": "2024-05-22",
        "days_remaining": 2,
        "status": "pending"
      }
    ],
    "unsettled_sales": [
      {
        "trade_id": "TRD_123457",
        "symbol": "SYS",
        "quantity": 200,
        "price": 432.10,
        "amount": 86420.00,
        "trade_date": "2024-05-19",
        "settlement_date": "2024-05-21",
        "days_remaining": 1,
        "status": "pending"
      }
    ],
    "summary": {
      "total_unsettled_purchases": 93750.00,
      "total_unsettled_sales": 86420.00,
      "net_unsettled": -7330.00,
      "next_settlement_date": "2024-05-21",
      "next_settlement_amount": 86420.00
    }
  }
}

📋 What this is for:

Tracks T+2 settlement cycle. Funds from sales are not available until settlement date. Purchases block funds until settled.

// Used in: Fund ledger, buying power calculation

5. EXPOSURE & RISK LIMITS APIS

Per-Symbol, Per-Sector, Global Limits

GET /risk/exposure/{user_id} User exposure summary

📥 Response

{
  "status": "success",
  "data": {
    "user_id": 12345,
    "global_exposure": 1320000.00,
    "global_limit": 5000000.00,
    "global_utilization": "26.4%",
    "by_sector": [
      {
        "sector": "Commercial Banks",
        "exposure": 375000.00,
        "limit": 1000000.00,
        "utilization": "37.5%",
        "symbols": ["MEBL", "HBL", "UBL"]
      },
      {
        "sector": "Oil & Gas",
        "exposure": 444000.00,
        "limit": 1000000.00,
        "utilization": "44.4%",
        "symbols": ["PSO", "SHEL", "APL"]
      }
    ],
    "by_symbol": [
      {
        "symbol": "MEBL",
        "exposure": 187500.00,
        "limit": 500000.00,
        "utilization": "37.5%",
        "sector": "Commercial Banks"
      },
      {
        "symbol": "PSO",
        "exposure": 225400.00,
        "limit": 500000.00,
        "utilization": "45.1%",
        "sector": "Oil & Gas"
      }
    ],
    "risk_flags": []
  }
}

📋 What this is for:

Monitors concentration risk across sectors and symbols. Prevents over-exposure to single stock or sector.

// Used in: Risk management, compliance monitoring

GET /risk/position-limits/{user_id} PSX position limits

📥 Response

{
  "status": "success",
  "data": {
    "user_id": 12345,
    "limits": [
      {
        "symbol": "MEBL",
        "current_position": 1500,
        "max_position": 50000,
        "utilization": "3%",
        "status": "normal"
      },
      {
        "symbol": "PSO",
        "current_position": 3000,
        "max_position": 50000,
        "utilization": "6%",
        "status": "normal"
      }
    ],
    "exceeded_limits": []
  }
}

6. ORDER-VISION MAX MAPPING

ID Reconciliation

POST /orders/mapping Get Vision Max ID for internal order

📤 Request

{
  "order_id": "ORD_240226_001234"
}

📥 Response

{
  "status": "success",
  "data": {
    "internal_order_id": "ORD_240226_001234",
    "vision_max_order_id": "VM_987654321",
    "vision_max_status": "ACK",
    "mapped_at": "2024-05-20T10:20:05.123Z",
    "executions": [
      {
        "internal_execution_id": "EXEC_001",
        "vision_max_exec_id": "VM_EXEC_12345",
        "quantity": 200,
        "price": 187.50,
        "executed_at": "2024-05-20T10:21:00.123Z"
      }
    ]
  }
}

7. ORDER RECONCILIATION WEBHOOK

Vision Max → Optimus Callback

🔔 Vision Max sends execution updates to this endpoint

Configure Vision Max to send POST requests to this URL whenever order status changes. Your system must acknowledge within 5 seconds.

POST https://api.optimuscapital.com/webhook/vision-max/order-update IP Whitelist Required

📤 Vision Max Payload

{
  "vision_max_order_id": "VM_987654321",
  "event_type": "EXECUTION",
  "timestamp": "2024-05-20T10:21:00.123Z",
  "data": {
    "executed_quantity": 200,
    "executed_price": 187.50,
    "remaining_quantity": 300,
    "execution_id": "VM_EXEC_12345",
    "order_status": "PARTIALLY_FILLED",
    "reject_reason": null
  },
  "signature": "sha256_hash_for_verification"
}

📥 Your Acknowledgment

{
  "status": "received",
  "vision_max_order_id": "VM_987654321",
  "processed_at": "2024-05-20T10:21:00.500Z"
}

POST https://api.optimuscapital.com/webhook/vision-max/trade Trade confirmation webhook

📤 Vision Max Payload

{
  "vision_max_trade_id": "VM_TRADE_54321",
  "vision_max_order_id": "VM_987654321",
  "timestamp": "2024-05-20T10:21:00.123Z",
  "data": {
    "symbol": "MEBL",
    "side": "BUY",
    "quantity": 200,
    "price": 187.50,
    "value": 37500.00,
    "brokerage": 75.00,
    "trade_date": "2024-05-20",
    "settlement_date": "2024-05-22"
  }
}

8. CORPORATE ACTIONS HANDLER

Dividends, Bonuses, Splits

POST /corporate-actions/pending Pending corporate actions

📤 Request

{
  "user_id": 12345
}

📥 Response

{
  "status": "success",
  "data": {
    "pending_actions": [
      {
        "symbol": "MEBL",
        "action_type": "DIVIDEND",
        "amount_per_share": 5.50,
        "ex_date": "2024-06-01",
        "record_date": "2024-06-02",
        "payment_date": "2024-06-15",
        "holding_quantity": 1000,
        "expected_amount": 5500.00,
        "currency": "PKR",
        "status": "ANNOUNCED"
      },
      {
        "symbol": "SYS",
        "action_type": "BONUS",
        "ratio": "1:4",
        "ex_date": "2024-06-05",
        "record_date": "2024-06-06",
        "holding_quantity": 500,
        "new_shares": 125,
        "status": "APPROVED"
      }
    ]
  }
}

9. RISK MANAGEMENT DASHBOARD

Real-time Risk Monitoring

GET /risk/dashboard/{user_id} Complete risk profile

📥 Response

{
  "status": "success",
  "data": {
    "user_id": 12345,
    "margin_status": {
      "margin_ratio": 0.167,
      "maintenance_margin": 75000.00,
      "margin_call_threshold": 0.80,
      "status": "healthy"
    },
    "exposure_summary": {
      "global_utilization": "26.4%",
      "top_exposure": {
        "symbol": "PSO",
        "utilization": "45.1%"
      },
      "sector_concentration": {
        "highest": "Oil & Gas",
        "utilization": "44.4%"
      }
    },
    "risk_flags": [],
    "alerts": [
      {
        "type": "info",
        "message": "Portfolio diversity within limits",
        "timestamp": "2024-05-20T10:30:00Z"
      }
    ],
    "as_of": "2024-05-20T10:30:00.000Z"
  }
}

10. NOTIFICATION WEBHOOK

Vision Max ← Optimus · POST

🔔 What are Webhooks?

Webhooks are HTTP callbacks - Optimus sends real-time notifications to your Vision Max endpoint when events occur. Unlike polling, you don't need to constantly check for updates.

// Used in: Real-time trade confirmations, instant alerts

POST https://notifications.optimuscapital.com/webhook/visionmax IP Whitelist / X-API-Key

📤 Webhook Payload

{
  "event_id": "evt_abc123def",
  "event_type": "order.execution",
  "timestamp": "2024-05-20T10:21:00.000Z",
  "data": {
    "user_id": "12345",
    "order_id": "ODR123456789",
    "execution_details": {
      "execution_id": "EXE987654",
      "executed_quantity": 200,
      "executed_price": 187.50,
      "execution_time": "2024-05-20T10:20:59.500Z",
      "remaining_quantity": 300,
      "order_status": "partially_filled"
    }
  },
  "version": "1.0"
}

📥 Acknowledgement

{
  "status": "received",
  "event_id": "evt_abc123def"
}

📋 Event Types

order.confirmed  - Order accepted by exchange
order.rejected   - Order rejected by pre-trade checks
order.cancelled  - Order cancelled by user
order.execution  - Partial or full fill
margin.call      - Margin call threshold hit
account.alert    - Deposit/withdrawal status

📋 What this is for:

Real-time event notifications from Optimus to Vision Max. Ensures your application stays synchronized with order status changes.

// Used in: Push notifications, real-time UI updates

🏛️

PAKISTAN STOCK EXCHANGE (PSX) - RULES & REGULATIONS

⏰ Market Timings

Pre-open Session: 9:15 AM – 9:30 AM
Continuous Trading: 9:30 AM – 3:30 PM
Post-close Session: 3:30 PM – 3:35 PM
All orders validated against market hours

🔄 Settlement Cycle

T+2 Settlement: All cash and security balances reflect T+2 cycle
Unsettled Funds: Not available for trading until T+2
Affects buying power calculations

⚡ Circuit Breakers

Upper Circuit: +10% from last close
Lower Circuit: -10% from last close
Orders rejected: Outside these limits
Automatically enforced by Optimus

📊 Lot Size Requirements

Board Lots: Standard trading units
Odd Lots: Not permitted for orders
Multiple: Must be in multiples of lot size
Example: MEBL lot size = 500 shares

🚫 Trading Restrictions

Short Selling: Not permitted for retail investors
Day Trading: Allowed with margin accounts
Position Limits: Per exchange regulations
Compliance checks on all orders

📋 Order Types

MIT: Market If Touched
MTL: Market To Limit
IOC: Immediate or Cancel
FOK: Fill or Kill
PSX-specific order types supported

📌 PSX Integration Note:

All orders placed through Optimus are automatically validated against PSX rules. If any rule is violated (market closed, invalid lot size, outside circuit breaker), the order will be rejected with a specific error code before reaching the exchange.

11. SECURITY & COMPLIANCE

TLS 1.2+ Required

🔒 Why security matters:

Trading APIs handle sensitive financial data and real money. These security measures protect user data, prevent abuse, and ensure regulatory compliance.

• Encryption: TLS 1.2+ (HTTPS for REST, WSS for WebSockets)
• Rate Limiting:
  - Authentication APIs: 5 requests per minute per IP
  - Trading APIs: 100 requests per second per user
  - Public Data APIs: 200 requests per minute per IP
• IP Whitelisting: Vision Max whitelists Optimus production IPs
• Audit Logs: All orders/auth logged with request_id, user_id, timestamp
• Idempotency Keys: Prevent duplicate order submissions
• JWT Expiry: 1 hour access tokens, 7 day refresh tokens

12. JSON STANDARDS

snake_case · ISO 8601

📝 Why standards matter:

Consistent JSON formatting ensures your code works reliably across all endpoints and makes integration easier for developers.

• Naming Convention: snake_case for all JSON property names
• Timestamps: ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ)
• Numbers: Use JSON number type (not strings)
• Standard Response Envelope:
  Success: { "status": "success", "code": 200, "data": { ... }, "request_id": "..." }
  Error:   { "status": "error", "code": 400, "message": "Summary", "error_details": { ... }, "request_id": "..." }

13. ERROR CODES

Complete Reference

⚠️ Why error codes matter:

Error codes help your application understand what went wrong and take appropriate action - whether it's retrying, showing user-friendly messages, or escalating issues.

1001 Authentication - Invalid token
1002 Authentication - Token expired
1003 Authorization - Insufficient permissions
2001 Trading - Invalid symbol
2002 Trading - Invalid quantity (lot size)
2003 Trading - Invalid price (outside circuit breaker)
2004 Trading - Insufficient buying power
2005 Trading - Position not held (for sell orders)
2006 Trading - Market closed
2007 Trading - Order type not supported
2008 Trading - Position limit exceeded
2009 Trading - Sector exposure limit exceeded
2010 Trading - Circuit breaker triggered
3001 System - Rate limit exceeded
3002 System - Idempotency key reused
4001 Settlement - Unsettled funds not available
4002 Settlement - T+2 settlement in progress
9001 Vision Max - Backend connectivity issue
9002 Vision Max - Order rejected by exchange

YOUR HOLDINGS

Portfolio Summary · T+2 Settlement

Portfolio Holdings Last Updated: 11:30 AM PKT

Total Value PKR 1,875,000 +2.3%

Today's P&L +PKR 42,500 +2.3%

Total P&L +PKR 125,000 +7.14%

Positions 12 6 Sectors

MEBL 187.50 1,000 PKR 187.5K +3.88%

SYS 432.10 500 PKR 216.1K +1.67%

ENGRO 321.75 800 PKR 257.4K +2.10%

OGDC 109.30 2,000 PKR 218.6K +0.92%

PSO 75.12 3,000 PKR 225.4K +1.61%

KEL 102.50 1,500 PKR 153.8K -1.06%

📊 Progress bars show portfolio weight (% of total) 🟢 Positive P&L 🔴 Negative P&L ⏱️ T+2 Settlement applies

WEBSOCKET CONSOLE

Live Trading Updates

Live Messages (12)

[11:30:00] SYSTEM WebSocket connected - Session ID: ws_optimus_001

[11:30:01] MARKET Subscribed to MEBL, SYS, ENGRO, OGDC

[11:30:02] TRADE MEBL: 187.50 (5,000 shares)

[11:30:03] QUOTE MEBL Bid: 187.00 (1,500) | Ask: 187.60 (800)

[11:30:04] RISK Pre-trade validation passed for order ORD_001

[11:30:05] SETTLEMENT T+2: 50,000 PKR will settle on 2026-02-26

OPTIMUS TRADING PLATFORM

TRADING INTERFACE

MEBL

ORDER TYPES

MARKET DATA

1. WEBSOCKET MARKET DATA STREAMS

2. TRADING REST APIS

3. PRE-TRADE VALIDATION & RISK APIS

4. BUYING POWER & T+2 SETTLEMENT APIS

5. EXPOSURE & RISK LIMITS APIS

6. ORDER-VISION MAX MAPPING

7. ORDER RECONCILIATION WEBHOOK

8. CORPORATE ACTIONS HANDLER

9. RISK MANAGEMENT DASHBOARD

10. NOTIFICATION WEBHOOK

11. SECURITY & COMPLIANCE

12. JSON STANDARDS

13. ERROR CODES

YOUR HOLDINGS

WEBSOCKET CONSOLE