Bismillah. Chalo bachon, course ke ek aur important lesson mein khushamdeed.

COURSE: Pakistan Ka Pehla Professional Trading Bot Course

MODULE 6: Execution Engine — Automatically Orders Place Karna

LESSON 6.4: Balance Tracking Aur Portfolio Overview

Assalam-o-Alaikum! Umeed hai sab aag laga rahay ho. Pichlay lessons mein humne execution.py ka basic structure set kiya tha. Ab waqt hai usko aqal denay ka. Bot ko sirf order place karna nahi aana chahiye; usko yeh bhi pata hona chahiye ke "bhai, jaib mein paisay kitnay hain?"

Agar aapka bot andhadhund orders place karta raha, to woh uss dost jaisa hai jo har cheez pe "scene on hai" bol deta hai, aur end mein bill aapko bharna parta hai. Aaj hum apne bot ko aisi harkaton se bachayenge. We will teach it financial discipline.

Kyun Zaroori Hai Yeh Sab? (The Hook)

Simple si baat hai. Paisa kahan se aa raha hai aur kahan ja raha hai, agar yeh nahi pata, toh trading nahi, juaa khel rahay ho. Acha bot wo nahi jo 100 trades le, acha bot wo hai jo profitable trades le aur capital ko smartly manage karay. $30 ke account pe agar tum 15 positions khol ke baith gaye, toh har position mein $2 lage hongay. Itna kum capital spread karoge toh fees hi tumhara profit kha jayegi. This lesson is about building the brain of your bot that manages the money.

Concept 1: Deployed Capital vs. Free Capital

Yeh sab se bunyadi (fundamental) concept hai.

• Total Capital: Yeh woh total raqam hai jo aapne bot ko di hai. For example, $30. Yeh hum ORACLE_CAPITAL environment variable mein set karte hain.
• Deployed Capital: Yeh woh paisa hai jo already market mein laga hua hai. Yani, aapki open positions ki total cost. Agar aapne 5 YES shares khareeday hain $3 ke, toh aapka deployed capital $3 hai.
• Free/Available Capital: Yeh woh paisa hai jo bot abhi mazeed trades ke liye istemal kar sakta hai. Total Capital - Deployed Capital = Free Capital. (Is mein ek chota sa twist hai reserve ka, jo aage dekhenge).

Apne bot ke execution.py ko koi bhi trade lene se pehle yeh check karna LAZMI hai. "Kya mere paas is trade ke liye sufficient available capital hai?"

Chalo, is sab ko code mein daaltay hain. Hum ek function banayenge jo hamare portfolio ka poora hisaab kitab rakhega. Yeh function hum execution.py mein call karenge, lekin iska data aayega db.py se, jahan hum apni saari positions save karte hain.

The Heart of Our Portfolio: get_portfolio_summary

Yeh function hamare bot ka "accountant" hai. Isko hum list of positions denge (jo database se aayengi), aur yeh hamein ek saaf suthri summary dega. Let's break it down.

import os

def get_portfolio_summary(positions):
    """
    Portfolio ka complete overview. Yeh function batata hai kitna paisa
    laga hua hai, kitna baaki hai, aur reserve kitna hai.
    
    Args:
        positions (list): A list of position dictionaries from our database.
    
    Returns:
        dict: A summary of the portfolio.
    """
    # Step 1: Total capital kitna hai? Environment variable se uthao.
    # Default 30 rakha hai, chotay accounts ke liye.
    total_capital = float(os.environ.get('ORACLE_CAPITAL', '30'))
    
    # Step 2: Deployed capital calculate karo. Sirf 'open' positions count hongi.
    # Jo positions close ho chuki hain, unka paisa wapis aa chuka hai.
    deployed = sum(p['cost_eur'] for p in positions if p['status'] == 'open')
    
    # Step 3: Reserve manage karo. Yeh hamara emergency fund hai.
    reserve = total_capital * 0.05  # 5% hamesha side pe rakho
    
    # Step 4: Available capital nikalo. Deployed aur reserve, dono minus karo.
    # max(0, ...) isliye ke ghalti se bhi available capital negative na ho jaye.
    available = max(0, total_capital - deployed - reserve)
    
    # Step 5: Har strategy ne kitna paisa lagaya hai, uska hisaab.
    # Yeh dekhne ke liye ke koi ek strategy saara paisa toh nahi khaa rahi.
    by_strategy = {}
    for p in positions:
        if p['status'] != 'open':
            continue  # Sirf open positions mein interest hai
        
        s = p['strategy']
        if s not in by_strategy:
            # Agar is strategy ka entry pehli baar ho raha hai
            by_strategy[s] = {'count': 0, 'deployed': 0}
        
        # Count aur deployed amount update karo
        by_strategy[s]['count'] += 1
        by_strategy[s]['deployed'] += p['cost_eur']
    
    # Step 6: Sab kuch ek saaf dictionary mein daal ke wapis bhejo.
    return {
        'total_capital': total_capital,
        'deployed': round(deployed, 2),
        'available': round(available, 2),
        'reserve': round(reserve, 2),
        'open_positions': len([p for p in positions if p['status'] == 'open']),
        'by_strategy': by_strategy
    }

# --- Example Usage ---
# Farz karo, yeh data hamare db.py se aa raha hai
mock_positions_from_db = [
    {'strategy': 'theta_sniper', 'cost_eur': 5.50, 'status': 'open'},
    {'strategy': 'geo_scout', 'cost_eur': 4.25, 'status': 'open'},
    {'strategy': 'theta_sniper', 'cost_eur': 8.00, 'status': 'open'},
    {'strategy': 'theta_sniper', 'cost_eur': 3.10, 'status': 'closed'}, # Yeh count nahi hogi
    {'strategy': 'ai_momentum', 'cost_eur': 6.75, 'status': 'open'}
]

# Function ko call karo
summary = get_portfolio_summary(mock_positions_from_db)

# Result ko print karo
import json
print(json.dumps(summary, indent=2))

Code ka Breakdown:

1. total_capital: Hum os.environ.get() use kar rahay hain. Yeh professional tareeqa hai. Apne bot ki configuration (jaise total capital, API keys, etc.) ko code mein hardcode nahi karna chahiye. ORACLE_CAPITAL naam ka ek environment variable set karo, aur bot wahan se value utha lega. Agar set nahi hai, toh default $30 use karega.
2. deployed: Yeh Python ki ek khoobsurat one-liner hai. Isko "list comprehension" kehte hain. Yeh positions list mein har position p ke liye check karta hai if p['status'] == 'open'. Agar open hai, toh uska cost_eur uthaata hai. sum() in sab costs ko jama kar deta hai. Simple and powerful.
3. reserve: Is pe aglay section mein detail mein baat karte hain.
4. available: Seedha sa hisaab hai. total - deployed - reserve. max(0, ...) ek safety check hai. Kabhi kabhi floating point math ki wajah se ya kisi bug ki wajah se value -0.00001 jaisi ho sakti hai. Yeh usko 0 kar dega.
5. by_strategy: Yeh loop har open position ko dekhta hai. Uski strategy ka naam (theta_sniper, geo_scout, etc.) nikalta hai aur ek dictionary by_strategy mein uss strategy ke naam se entry daalta hai. Har baar jab ussi strategy ki position milti hai, toh woh count (kitni positions) aur deployed (kitna paisa) update kar deta hai. Is se aapko pata chalta hai ke theta_sniper.py ne $13.50 lagaye hue hain 3 positions mein.
6. return: Aakhir mein, ek saaf suthri dictionary return hoti hai jisko humara baaki ka code aasani se istemal kar sakta hai.

Concept 2: Reserve Management - The 5% Rule

Cricket mein jaise aakhri overs ke liye best bowler ko bacha ke rakhte ho, waise hi trading mein thora capital hamesha reserve mein rakhna chahiye. Kyun?

1. Market Crashes & Opportunities: Market kabhi kabhi achanak crash karti hai (ya pump hoti hai). Woh "once in a blue moon" opportunity hoti hai jahan aap saste mein maal utha sakte ho. Agar aapka saara capital already deployed hai, toh aap sirf dekhte reh jao ge. Yeh 5% reserve uss din ke liye hai.
2. Fees & Slippage: Exchanges fees leti hain. Kabhi kabhi aap jis price pe order place karte ho, woh uss price pe fill nahi hota (isko slippage kehte hain). Yeh reserve in chotay motay extra kharchon ko cover karne ke liye bhi hota hai.
3. Psychological Safety: Jab aapko pata hota hai ke aap 100% all-in nahi ho, toh aap behtar فیصلے (decisions) lete ho. Aap panic nahi karte.

Hamare code mein yeh line bilkul simple hai: reserve = total_capital * 0.05

Yeh 5% koi pathar pe lakeer nahi hai. Agar aapka risk appetite zyada hai, aap isko 2% kar sakte ho. Agar aap bohat conservative ho, toh 10% bhi kar sakte ho.

Tracking portfolio health ensures your bot never overleverages and maintains risk discipline.

📺 Recommended Videos & Resources

• Portfolio Management Basics — Understanding portfolios
  • Type: Wikipedia
  • Link description: Learn portfolio concepts and diversification
• Position Sizing in Trading — Calculating optimal position sizes
  • Type: YouTube
  • Link description: Search "position sizing and Kelly criterion"
• Risk Metrics (VaR, Sharpe, Drawdown) — Measuring risk
  • Type: Wikipedia
  • Link description: Learn key risk metrics
• Wallet APIs (Ethers.js, Web3.py) — Blockchain balance queries
  • Type: Official Documentation
  • Link description: Reference for checking wallet balances
• Cash Management for Bots — Liquidity planning
  • Type: YouTube
  • Link description: Search "trading bot cash management"

🎯 Mini-Challenge

5-Minute Practical Task: Create a portfolio tracking function that: (1) Fetches wallet balance, (2) Calculates max position size (5% per trade), (3) Tracks open positions, (4) Returns available capital. Test with a sample wallet and verify balance calculations are correct.

🖼️ Visual Reference

📊 Portfolio Risk Management
Initial Capital: $10,000
┌──────────────────────────┐
│ Position Size Limits:    │
│ - Per trade: 5% = $500   │
│ - Max exposure: 25%      │
│ - Keep reserve: 75%      │
└──────────────────────────┘

Trade Examples:
┌──────────────────────────┐
│ Trade 1: BUY $500        │
│ Remaining: $9,500        │
│ Exposure: 5%             │
├──────────────────────────┤
│ Trade 2: BUY $500        │
│ Remaining: $9,000        │
│ Exposure: 10%            │
├──────────────────────────┤
│ Trade 3: BUY $500        │
│ Remaining: $8,500        │
│ Exposure: 15%            │
├──────────────────────────┤
│ Trade 4: BUY $500        │
│ Remaining: $8,000        │
│ Exposure: 20%            │
├──────────────────────────┤
│ Trade 5: BUY $500        │
│ Remaining: $7,500        │
│ Exposure: 25%            │
│ (MAX REACHED - STOP)     │
└──────────────────────────┘