Upload folder using huggingface_hub

.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+ENV/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Logs
+logs/
+*.log
+
+# OS
+.DS_Store
+Thumbs.db

Dockerfile

@@ -0,0 +1,35 @@
+# Hugging Face Spaces Dockerfile for FastAPI Backend
+FROM python:3.10-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    gcc \
+    libffi-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Create non-root user for security (required by HF Spaces)
+RUN useradd -m -u 1000 user
+USER user
+
+# Set environment variables
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    PYTHONUNBUFFERED=1
+
+# Expose port 7860 (Hugging Face Spaces default)
+EXPOSE 7860
+
+# Run FastAPI with uvicorn
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,44 @@
 ---
-title: Atriumchain Api
-emoji: 👀
-colorFrom: yellow
-colorTo: blue
+title: AtriumChain API
+emoji: 🏠
+colorFrom: blue
+colorTo: purple
 sdk: docker
+app_port: 7860
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# AtriumChain Backend API
+
+Real Estate Tokenization Platform API built with FastAPI and XRP Ledger.
+
+## Features
+
+- User authentication with JWT
+- Property tokenization on XRP Ledger
+- Portfolio management
+- KYC verification
+- Admin dashboard APIs
+
+## API Documentation
+
+Once deployed, access the API docs at:
+- Swagger UI: `/docs`
+- ReDoc: `/redoc`
+
+## Environment Variables
+
+Configure these secrets in your Hugging Face Space settings:
+
+| Variable | Description |
+|----------|-------------|
+| `SECRET_KEY` | JWT secret key (min 32 chars) |
+| `MONGODB_URI` | MongoDB Atlas connection string |
+| `MONGODB_DB_NAME` | Database name |
+| `ENVIRONMENT` | `production` |
+| `DEBUG_MODE` | `false` |
+
+## Health Check
+
+- `GET /` - API status
+- `GET /health` - Detailed health check

config.py

@@ -0,0 +1,145 @@
+from pydantic_settings import BaseSettings
+from typing import List, Optional
+from pathlib import Path
+
+class Settings(BaseSettings):
+    # SECURITY: Must be set via .env file. No default for production safety.
+    SECRET_KEY: str  # Required - generate with: openssl rand -base64 32
+    ALGORITHM: str = "HS256"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 60 * 24
+
+    # MongoDB Atlas configuration
+    # Example: mongodb+srv://user:pass@cluster.mongodb.net/
+    # NOTE: Credentials present here only for legacy/dev; MUST be overridden in environment (.env)
+    # Recommendation: remove secrets before committing publicly.
+    # IMPORTANT: Provide via environment (.env). Default points to localhost for safety.
+    MONGODB_URI: str = "mongodb://localhost:27017"  # Override in .env for Atlas or remote
+    MONGODB_DB_NAME: str = "atriumchain"
+    # SECURITY: Explicit allowed origins only - no wildcard "*" for production
+    # Add production domains here when deploying (e.g., "https://yourdomain.com")
+    CORS_ORIGINS: List[str] = [
+        "http://localhost:5173", 
+        "http://127.0.0.1:5173", 
+        "http://localhost:5174", 
+        "http://127.0.0.1:5174", 
+        "http://localhost:5175", 
+        "http://127.0.0.1:5175"
+    ]
+    ALLOWED_ORIGINS: Optional[str] = None  # comma-separated override list; if set replaces CORS_ORIGINS
+
+    XRPL_NETWORK: str = "testnet"  # testnet only
+    ISSUER_SEED: str | None = None  # DEPRECATED: Use admin wallet instead (kept for backward compatibility)
+    
+    # TOKEN MODEL: IOU for fractional real estate ownership
+    # Uses XRPL issued currencies for fungible property tokens
+    XRPL_TOKEN_MODEL: str = "IOU"  # Fixed to IOU - the correct model for fractional ownership
+
+    # Blockchain integration is mandatory for production
+    XRPL_LEDGER_PURCHASE_ENABLED: bool = True
+
+    # Configurable AED to XRP demo conversion rate (used only for displaying estimated costs
+    # and in IOU path cost calculation). Previously hard-coded to 1e-6.
+    # NOTE: This should be replaced with real-time oracle in production
+    XRPL_RATE_AED_TO_XRP: float = 0.000001
+
+    # Unified explorer base (avoid hard-coded duplicates elsewhere)
+    XRPL_EXPLORER_BASE: str = "https://testnet.xrpl.org/transactions/"
+    # Unified RPC URL (replace ad-hoc constants in services)
+    XRPL_RPC_URL: str = "https://s.altnet.rippletest.net:51234/"
+
+    # Optional encryption key (32 byte raw, hex, or Fernet base64). If absent seeds remain legacy/base64.
+    ENCRYPTION_KEY: str | None = None
+
+    # Security Configuration
+    RATE_LIMIT_ENABLED: bool = True
+    MAX_LOGIN_ATTEMPTS: int = 5
+    LOGIN_LOCKOUT_MINUTES: int = 15
+    REQUIRE_STRONG_PASSWORDS: bool = True
+    MIN_PASSWORD_LENGTH: int = 8
+    
+    # Session Configuration
+    SESSION_TIMEOUT_MINUTES: int = 60
+    REFRESH_TOKEN_EXPIRE_DAYS: int = 7
+
+    # IPFS Configuration for Decentralized Document Storage
+    WEB3_STORAGE_API_TOKEN: str | None = None  # Get free token from https://web3.storage
+    PINATA_API_KEY: str | None = None  # Get free API key from https://pinata.cloud
+    PINATA_SECRET_KEY: str | None = None  # Secret key from Pinata dashboard
+    IPFS_GATEWAY: str = "ipfs.io"  # Default public IPFS gateway
+    IPFS_BACKUP_GATEWAY: str = "cloudflare-ipfs.com"  # Backup gateway
+    IPFS_PROVIDER: str = "local_simulation"  # Options: "pinata", "web3storage", "local_simulation"
+
+    # Monitoring and Logging Configuration
+    LOG_LEVEL: str = "INFO"  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+    LOG_FILE_ENABLED: bool = True
+    LOG_FILE_PATH: str = "logs/app.log"
+    LOG_FILE_MAX_SIZE: int = 10485760  # 10MB in bytes
+    LOG_FILE_BACKUP_COUNT: int = 5
+    
+    # Performance Monitoring
+    ENABLE_PERFORMANCE_MONITORING: bool = True
+    SLOW_QUERY_THRESHOLD: float = 1.0  # Log queries taking longer than 1 second
+    
+    # Transaction Monitoring
+    ENABLE_TRANSACTION_MONITORING: bool = True
+    BLOCKCHAIN_TIMEOUT_SECONDS: int = 30
+    
+    # Environment-specific settings
+    ENVIRONMENT: str = "development"  # development, staging, production
+    DEBUG_MODE: bool = True  # Set to False in production
+
+    def encryption_enabled(self) -> bool:
+        return bool(self.ENCRYPTION_KEY)
+    
+    def is_production(self) -> bool:
+        return self.ENVIRONMENT.lower() == "production"
+    
+    def is_development(self) -> bool:
+        return self.ENVIRONMENT.lower() == "development"
+
+    def validate_configuration(self):  # renamed from validate_issuer_seed for clarity
+        """Validate configuration settings and log important information"""
+        
+        # Validate IOU token configuration
+        if not self.ISSUER_SEED:
+            print("[CONFIG][INFO] ISSUER_SEED not set – using admin wallet for token issuance (recommended).")
+            
+        # Configure CORS origins
+        if self.ALLOWED_ORIGINS:
+            self.CORS_ORIGINS = [o.strip() for o in self.ALLOWED_ORIGINS.split(',') if o.strip()]
+            
+        # Validate environment-specific settings
+        if self.is_production():
+            # CRITICAL: Validate production security requirements
+            if self.DEBUG_MODE:
+                print("[CONFIG][ERROR] DEBUG_MODE is enabled in production environment!")
+                print("[CONFIG][ERROR] Set DEBUG_MODE=false in .env file immediately!")
+                raise ValueError("DEBUG_MODE must be disabled in production environment")
+            
+            # H1/H3: Enforce encryption key in production for wallet seed security
+            if not self.ENCRYPTION_KEY:
+                print("[CONFIG][ERROR] ENCRYPTION_KEY not set in production environment!")
+                print("[CONFIG][ERROR] Wallet seeds will not be encrypted. This is a security risk.")
+                print("[CONFIG][INFO] Generate key: python -c \"from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())\"")
+                raise ValueError("ENCRYPTION_KEY is required in production environment")
+            else:
+                print("[CONFIG][INFO] ✅ Encryption enabled for wallet seeds.")
+        else:
+            # Development environment warnings
+            if not self.ENCRYPTION_KEY:
+                print("[CONFIG][WARNING] ENCRYPTION_KEY not set – wallet seeds stored with legacy obfuscation.")
+                print("[CONFIG][WARNING] For production, generate with: python -c \"from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())\"")
+            else:
+                print("[CONFIG][INFO] ✅ Encryption enabled for wallet seeds.")
+                
+        # Log monitoring configuration
+        print(f"[CONFIG][INFO] Logging level: {self.LOG_LEVEL}")
+        print(f"[CONFIG][INFO] Environment: {self.ENVIRONMENT}")
+        print(f"[CONFIG][INFO] Performance monitoring: {'Enabled' if self.ENABLE_PERFORMANCE_MONITORING else 'Disabled'}")
+        print(f"[CONFIG][INFO] Transaction monitoring: {'Enabled' if self.ENABLE_TRANSACTION_MONITORING else 'Disabled'}")
+
+    class Config:
+        env_file = Path(__file__).parent / ".env"
+
+settings = Settings()
+settings.validate_configuration()

create_super_admin.py

@@ -0,0 +1,138 @@
+"""
+Script to create the first Super Admin user
+Run this once to initialize the platform with a Super Admin account
+Usage: python create_super_admin.py
+"""
+import asyncio
+from datetime import datetime
+from pymongo import MongoClient
+from passlib.context import CryptContext
+from config import settings
+
+# Password hashing
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+
+async def create_first_super_admin():
+    """Create the first Super Admin user in the database"""
+    
+    print("\n" + "="*80)
+    print("SUPER ADMIN INITIALIZATION SCRIPT")
+    print("="*80 + "\n")
+    
+    # Connect to MongoDB
+    try:
+        client = MongoClient(settings.MONGODB_URI)
+        db = client[settings.MONGODB_DB_NAME]
+        users_collection = db["users"]
+        print("[[SUCCESS]] Connected to MongoDB successfully")
+    except Exception as e:
+        print(f"[✗] Failed to connect to MongoDB: {str(e)}")
+        return
+    
+    # Check if super admin already exists
+    existing_super_admin = users_collection.find_one({"role": "super_admin"})
+    if existing_super_admin:
+        print(f"\n[!] Super Admin already exists: {existing_super_admin['email']}")
+        print("[!] Aborting to prevent duplicate Super Admin accounts")
+        client.close()
+        return
+    
+    # Get Super Admin credentials
+    print("\nEnter Super Admin credentials:")
+    print("-" * 40)
+    
+    email = input("Email: ").strip()
+    if not email or "@" not in email:
+        print("[✗] Invalid email address")
+        client.close()
+        return
+    
+    # Check if email already exists
+    existing_user = users_collection.find_one({"email": email})
+    if existing_user:
+        print(f"[!] User with email '{email}' already exists")
+        
+        # Ask if want to promote existing user to super_admin
+        promote = input("\nPromote this user to Super Admin? (yes/no): ").strip().lower()
+        if promote == "yes":
+            result = users_collection.update_one(
+                {"email": email},
+                {"$set": {"role": "super_admin", "updated_at": datetime.utcnow()}}
+            )
+            
+            if result.modified_count > 0:
+                print(f"\n[[SUCCESS]] User '{email}' promoted to Super Admin successfully!")
+            else:
+                print("[✗] Failed to promote user")
+            
+            client.close()
+            return
+        else:
+            print("[!] Operation cancelled")
+            client.close()
+            return
+    
+    password = input("Password: ").strip()
+    if len(password) < 8:
+        print("[✗] Password must be at least 8 characters long")
+        client.close()
+        return
+    
+    name = input("Full Name: ").strip()
+    if not name:
+        print("[✗] Full name is required")
+        client.close()
+        return
+    
+    phone = input("Phone (10 digits): ").strip()
+    if not phone or len(phone) != 10 or not phone.isdigit():
+        print("[✗] Phone must be exactly 10 digits")
+        client.close()
+        return
+    
+    # Hash password
+    hashed_password = pwd_context.hash(password)
+    
+    # Create Super Admin user document
+    super_admin_user = {
+        "email": email,
+        "password_hash": hashed_password,
+        "name": name,
+        "phone": phone,
+        "role": "super_admin",
+        "is_active": True,
+        "wallet_id": None,
+        "deleted": False,
+        "kyc_status": "approved",  # Pre-approved
+        "created_at": datetime.utcnow(),
+        "updated_at": datetime.utcnow()
+    }
+    
+    try:
+        # Insert Super Admin
+        result = users_collection.insert_one(super_admin_user)
+        
+        if result.inserted_id:
+            print("\n" + "="*80)
+            print("[SUCCESS] SUPER ADMIN CREATED SUCCESSFULLY!")
+            print("="*80)
+            print(f"\nEmail: {email}")
+            print(f"Name: {name}")
+            print(f"Phone: {phone}")
+            print(f"Role: super_admin")
+            print(f"User ID: {str(result.inserted_id)}")
+            print("\n[!] Please save these credentials securely!")
+            print("="*80 + "\n")
+        else:
+            print("\n[✗] Failed to create Super Admin")
+            
+    except Exception as e:
+        print(f"\n[✗] Error creating Super Admin: {str(e)}")
+    
+    finally:
+        client.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(create_first_super_admin())

db.py

@@ -0,0 +1,429 @@
+"""
+Production Database Initialization
+Sets up MongoDB with proper indexes and collections
+"""
+from typing import Optional
+from pymongo import MongoClient, ASCENDING, DESCENDING, TEXT
+from pymongo.errors import CollectionInvalid
+from config import settings
+from utils.crypto_utils import encrypt_secret, is_encrypted
+import base64
+
+
+_client: Optional[MongoClient] = None
+
+
+def get_client() -> MongoClient:
+    """Get MongoDB client (singleton) with connection pooling"""
+    global _client
+    if _client is None:
+        # Mask credentials in URI for logging
+        uri = settings.MONGODB_URI
+        masked = uri
+        try:
+            if "@" in uri and "://" in uri:
+                scheme_sep = uri.split("://", 1)
+                scheme, rest = scheme_sep[0], scheme_sep[1]
+                if "@" in rest:
+                    creds, host = rest.split("@", 1)
+                    masked_creds = "***:***" if ":" in creds else "***"
+                    masked = f"{scheme}://{masked_creds}@{host}"
+        except Exception:
+            masked = "<redacted>"
+        print(f"[DB] Connecting to MongoDB: {masked}")
+        
+        # Connection pool configuration for production workloads
+        _client = MongoClient(
+            settings.MONGODB_URI,
+            maxPoolSize=50,           # Maximum connections in pool
+            minPoolSize=5,            # Minimum connections to maintain
+            maxIdleTimeMS=30000,      # Close idle connections after 30s
+            serverSelectionTimeoutMS=5000,  # Fast fail on connection issues
+            connectTimeoutMS=10000,   # Connection timeout
+            retryWrites=True,         # Auto-retry on transient errors
+        )
+        # Test connection
+        _client.admin.command('ping')
+        print("[DB] [SUCCESS] MongoDB connection successful (pool: 5-50)")
+    return _client
+
+
+def get_db():
+    """Get database instance"""
+    client = get_client()
+    return client[settings.MONGODB_DB_NAME]
+
+
+def get_mongo():
+    """Generator for FastAPI dependency injection"""
+    db = get_db()
+    try:
+        yield db
+    finally:
+        pass  # Connection pooling handles cleanup
+
+
+def get_next_sequence(db, name: str) -> int:
+    """
+    Get the next sequence number for auto-incrementing IDs.
+    Used for generating unique sequential identifiers.
+    
+    Args:
+        db: Database connection
+        name: Name of the sequence (e.g., 'property_id', 'user_id')
+    
+    Returns:
+        Next sequence number
+    """
+    from pymongo import ReturnDocument
+    doc = db.counters.find_one_and_update(
+        {"_id": name},
+        {"$inc": {"seq": 1}},
+        upsert=True,
+        return_document=ReturnDocument.AFTER,
+    )
+    return int(doc.get("seq", 1))
+
+
+def create_collections(db):
+    """Create all required collections"""
+    print("[DB] Creating collections...")
+    
+    collections = [
+        'users', 'wallets', 'properties', 'property_specifications',
+        'amenities', 'property_images', 'investments', 'transactions',
+        'portfolios', 'documents', 'secondary_market_transactions',
+        'otps', 'sessions', 'certificates', 'rent_distributions', 
+        'rent_payments', 'counters', 'tokens', 'funded_properties'
+    ]
+    
+    existing = db.list_collection_names()
+    
+    for coll_name in collections:
+        if coll_name not in existing:
+            try:
+                db.create_collection(coll_name)
+                print(f"[DB] [SUCCESS] Created collection: {coll_name}")
+            except CollectionInvalid:
+                pass  # Collection already exists
+
+
+def ensure_indexes(db):
+    """Create all database indexes for performance and uniqueness"""
+    print("[DB] Creating indexes...")
+    
+    # ========================================================================
+    # USERS COLLECTION
+    # ========================================================================
+    db.users.create_index([("email", ASCENDING)], unique=True, name="idx_email_unique")
+    db.users.create_index([("role", ASCENDING)], name="idx_role")
+    db.users.create_index([("is_active", ASCENDING)], name="idx_is_active")
+    db.users.create_index([("deleted", ASCENDING)], name="idx_deleted")
+    db.users.create_index([("created_at", DESCENDING)], name="idx_created_at")
+    print("[DB] [SUCCESS] Users indexes created")
+    
+    # ========================================================================
+    # OTPs COLLECTION (for email verification)
+    # ========================================================================
+    db.otps.create_index([("email", ASCENDING), ("purpose", ASCENDING)], name="idx_email_purpose")
+    # TTL index: automatically deletes OTPs after they expire
+    db.otps.create_index([("expires_at", ASCENDING)], name="idx_expires_at_ttl", expireAfterSeconds=0)
+    db.otps.create_index([("verified", ASCENDING)], name="idx_verified")
+    db.otps.create_index([("created_at", DESCENDING)], name="idx_created_at")
+    print("[DB] [SUCCESS] OTPs indexes created (with TTL)")
+    
+    # ========================================================================
+    # WALLETS COLLECTION
+    # ========================================================================
+    db.wallets.create_index([("user_id", ASCENDING)], unique=True, name="idx_user_id_unique")
+    db.wallets.create_index([("is_active", ASCENDING)], name="idx_is_active")
+    print("[DB] [SUCCESS] Wallets indexes created")
+    
+    # ========================================================================
+    # PROPERTIES COLLECTION
+    # ========================================================================
+    db.properties.create_index([("title", TEXT)], name="idx_title_text")
+    db.properties.create_index([("location", ASCENDING)], name="idx_location")
+    db.properties.create_index([("property_type", ASCENDING)], name="idx_property_type")
+    db.properties.create_index([("is_active", ASCENDING)], name="idx_is_active")
+    db.properties.create_index([("deleted", ASCENDING)], name="idx_deleted")
+    db.properties.create_index([("created_by", ASCENDING)], name="idx_created_by")
+    db.properties.create_index([("created_at", DESCENDING)], name="idx_created_at")
+    db.properties.create_index([("funded_date", DESCENDING)], name="idx_funded_date")
+    db.properties.create_index([("available_tokens", ASCENDING)], name="idx_available_tokens")
+    print("[DB] [SUCCESS] Properties indexes created")
+    
+    # ========================================================================
+    # PROPERTY SPECIFICATIONS COLLECTION
+    # ========================================================================
+    db.property_specifications.create_index(
+        [("property_id", ASCENDING)], 
+        unique=True, 
+        name="idx_property_id_unique"
+    )
+    print("[DB] [SUCCESS] Property specifications indexes created")
+    
+    # ========================================================================
+    # AMENITIES COLLECTION
+    # ========================================================================
+    db.amenities.create_index([("property_id", ASCENDING)], name="idx_property_id")
+    db.amenities.create_index([("is_active", ASCENDING)], name="idx_is_active")
+    print("[DB] [SUCCESS] Amenities indexes created")
+    
+    # ========================================================================
+    # PROPERTY IMAGES COLLECTION
+    # ========================================================================
+    db.property_images.create_index([("property_id", ASCENDING)], name="idx_property_id")
+    db.property_images.create_index([("is_main", ASCENDING)], name="idx_is_main")
+    db.property_images.create_index([("is_active", ASCENDING)], name="idx_is_active")
+    print("[DB] [SUCCESS] Property images indexes created")
+    
+    # ========================================================================
+    # INVESTMENTS COLLECTION
+    # ========================================================================
+    db.investments.create_index([("user_id", ASCENDING)], name="idx_user_id")
+    db.investments.create_index([("property_id", ASCENDING)], name="idx_property_id")
+    db.investments.create_index(
+        [("user_id", ASCENDING), ("property_id", ASCENDING)],
+        name="idx_user_property"
+    )
+    db.investments.create_index([("status", ASCENDING)], name="idx_status")
+    db.investments.create_index([("created_at", DESCENDING)], name="idx_created_at")
+    print("[DB] [SUCCESS] Investments indexes created")
+    
+    # ========================================================================
+    # TRANSACTIONS COLLECTION
+    # ========================================================================
+    db.transactions.create_index([("user_id", ASCENDING)], name="idx_user_id")
+    db.transactions.create_index([("wallet_id", ASCENDING)], name="idx_wallet_id")
+    db.transactions.create_index([("property_id", ASCENDING)], name="idx_property_id")
+    db.transactions.create_index([("type", ASCENDING)], name="idx_type")
+    db.transactions.create_index([("status", ASCENDING)], name="idx_status")
+    db.transactions.create_index([("created_at", DESCENDING)], name="idx_created_at")
+    db.transactions.create_index(
+        [("user_id", ASCENDING), ("type", ASCENDING)],
+        name="idx_user_type"
+    )
+    print("[DB] [SUCCESS] Transactions indexes created")
+    
+    # ========================================================================
+    # PORTFOLIOS COLLECTION
+    # ========================================================================
+    db.portfolios.create_index([("user_id", ASCENDING)], unique=True, name="idx_user_id_unique")
+    db.portfolios.create_index([("updated_at", DESCENDING)], name="idx_updated_at")
+    print("[DB] [SUCCESS] Portfolios indexes created")
+    
+    # ========================================================================
+    # DOCUMENTS COLLECTION
+    # ========================================================================
+    db.documents.create_index([("property_id", ASCENDING)], name="idx_property_id")
+    db.documents.create_index([("file_type", ASCENDING)], name="idx_file_type")
+    db.documents.create_index([("uploaded_by", ASCENDING)], name="idx_uploaded_by")
+    print("[DB] [SUCCESS] Documents indexes created")
+    
+    # ========================================================================
+    # SECONDARY MARKET TRANSACTIONS COLLECTION
+    # ========================================================================
+    db.secondary_market_transactions.create_index(
+        [("transaction_id", ASCENDING)], 
+        unique=True, 
+        name="idx_transaction_id_unique"
+    )
+    db.secondary_market_transactions.create_index(
+        [("seller_id", ASCENDING)], 
+        name="idx_seller_id"
+    )
+    db.secondary_market_transactions.create_index(
+        [("buyer_id", ASCENDING)], 
+        name="idx_buyer_id"
+    )
+    db.secondary_market_transactions.create_index(
+        [("property_id", ASCENDING)], 
+        name="idx_property_id"
+    )
+    db.secondary_market_transactions.create_index(
+        [("status", ASCENDING)], 
+        name="idx_status"
+    )
+    db.secondary_market_transactions.create_index(
+        [("transaction_type", ASCENDING)], 
+        name="idx_transaction_type"
+    )
+    db.secondary_market_transactions.create_index(
+        [("initiated_at", DESCENDING)], 
+        name="idx_initiated_at"
+    )
+    db.secondary_market_transactions.create_index(
+        [("seller_id", ASCENDING), ("status", ASCENDING)],
+        name="idx_seller_status"
+    )
+    db.secondary_market_transactions.create_index(
+        [("property_id", ASCENDING), ("status", ASCENDING)],
+        name="idx_property_status"
+    )
+    db.secondary_market_transactions.create_index(
+        [("blockchain_tx_hash", ASCENDING)], 
+        name="idx_blockchain_tx"
+    )
+    print("[DB] [SUCCESS] Secondary market transactions indexes created")
+    
+    # ========================================================================
+    # SESSIONS COLLECTION (Device-bound Authentication)
+    # ========================================================================
+    db.sessions.create_index([("session_id", ASCENDING)], unique=True, name="idx_session_id_unique")
+    db.sessions.create_index([("user_id", ASCENDING)], name="idx_user_id")
+    db.sessions.create_index([("expires_at", ASCENDING)], name="idx_expires_at_ttl", expireAfterSeconds=0)
+    db.sessions.create_index(
+        [("user_id", ASCENDING), ("device_fingerprint", ASCENDING)],
+        name="idx_user_device"
+    )
+    db.sessions.create_index([("is_active", ASCENDING)], name="idx_is_active")
+    print("[DB] [SUCCESS] Sessions indexes created (with TTL)")
+    
+    # ========================================================================
+    # CERTIFICATES COLLECTION (Ownership Certificates)
+    # ========================================================================
+    db.certificates.create_index([("certificate_id", ASCENDING)], unique=True, name="idx_certificate_id_unique")
+    db.certificates.create_index([("user_id", ASCENDING)], name="idx_user_id")
+    db.certificates.create_index(
+        [("user_id", ASCENDING), ("property_details.property_id", ASCENDING)],
+        name="idx_user_property"
+    )
+    db.certificates.create_index([("issued_date", ASCENDING)], name="idx_issued_date")
+    db.certificates.create_index([("is_valid", ASCENDING)], name="idx_is_valid")
+    print("[DB] [SUCCESS] Certificates indexes created")
+    
+    # ========================================================================
+    # RENT DISTRIBUTIONS COLLECTION
+    # ========================================================================
+    db.rent_distributions.create_index([("property_id", ASCENDING)], name="idx_property_id")
+    db.rent_distributions.create_index([("distribution_date", DESCENDING)], name="idx_distribution_date")
+    db.rent_distributions.create_index([("status", ASCENDING)], name="idx_status")
+    db.rent_distributions.create_index([("created_at", DESCENDING)], name="idx_created_at")
+    db.rent_distributions.create_index(
+        [("property_id", ASCENDING), ("status", ASCENDING)],
+        name="idx_property_status"
+    )
+    print("[DB] [SUCCESS] Rent distributions indexes created")
+    
+    # ========================================================================
+    # RENT PAYMENTS COLLECTION
+    # ========================================================================
+    db.rent_payments.create_index([("distribution_id", ASCENDING)], name="idx_distribution_id")
+    db.rent_payments.create_index([("user_id", ASCENDING)], name="idx_user_id")
+    db.rent_payments.create_index([("property_id", ASCENDING)], name="idx_property_id")
+    db.rent_payments.create_index(
+        [("user_id", ASCENDING), ("property_id", ASCENDING)],
+        name="idx_user_property"
+    )
+    db.rent_payments.create_index([("payment_date", DESCENDING)], name="idx_payment_date")
+    db.rent_payments.create_index([("payment_status", ASCENDING)], name="idx_payment_status")
+    print("[DB] [SUCCESS] Rent payments indexes created")
+    
+    # ========================================================================
+    # TOKENS COLLECTION (Property Tokens)
+    # ========================================================================
+    db.tokens.create_index([("property_id", ASCENDING)], unique=True, name="idx_property_id_unique")
+    db.tokens.create_index([("is_active", ASCENDING)], name="idx_is_active")
+    print("[DB] [SUCCESS] Tokens indexes created")
+    
+    # ========================================================================
+    # FUNDED PROPERTIES COLLECTION (Fully Funded Properties Archive)
+    # ========================================================================
+    db.funded_properties.create_index([("property_id", ASCENDING)], unique=True, name="idx_property_id_unique")
+    db.funded_properties.create_index([("funded_date", DESCENDING)], name="idx_funded_date")
+    db.funded_properties.create_index([("funding_status", ASCENDING)], name="idx_funding_status")
+    db.funded_properties.create_index([("is_active", ASCENDING)], name="idx_is_active")
+    db.funded_properties.create_index([("created_at", DESCENDING)], name="idx_created_at")
+    print("[DB] [SUCCESS] Funded properties indexes created")
+    
+    print("[DB] ✅ All indexes created successfully")
+
+
+def init_mongo(app=None):
+    """Initialize MongoDB database"""
+    print("\n" + "="*80)
+    print("INITIALIZING MONGODB DATABASE")
+    print("="*80 + "\n")
+    
+    try:
+        db = get_db()
+        
+        # Create collections
+        create_collections(db)
+        
+        # Create indexes
+        ensure_indexes(db)
+
+        # Optional: migrate legacy wallet seeds to encrypted form if encryption enabled
+        try:
+            if settings.encryption_enabled():
+                wallets = db.wallets.find({"xrp_seed": {"$exists": True, "$ne": None}})
+                migrated = 0
+                for w in wallets:
+                    seed_val = w.get("xrp_seed")
+                    if not seed_val or is_encrypted(seed_val):
+                        continue
+                    # Detect base64 vs plain: attempt decode
+                    try:
+                        decoded = base64.b64decode(seed_val).decode()
+                        candidate = decoded if decoded.startswith("s") else seed_val
+                    except Exception:
+                        candidate = seed_val
+                    new_enc = encrypt_secret(candidate, settings.ENCRYPTION_KEY)
+                    db.wallets.update_one({"_id": w["_id"]}, {"$set": {"xrp_seed": new_enc}})
+                    migrated += 1
+                if migrated:
+                    print(f"[DB] [SUCCESS] Migrated {migrated} wallet seeds to encrypted format")
+        except Exception as mig_err:
+            print(f"[DB][WARNING] Seed encryption migration skipped: {mig_err}")
+        
+        # Attach to FastAPI app if provided
+        if app:
+            app.state.mongo = db
+            print("[DB] [SUCCESS] Database attached to FastAPI app")
+        
+        print("\n[DB] ✅ Database initialization complete!")
+        print("="*80 + "\n")
+        
+        return db
+        
+    except Exception as e:
+        print(f"\n[DB] [ERROR] ERROR during initialization: {str(e)}")
+        import traceback
+        traceback.print_exc()
+        raise
+
+
+def close_mongo():
+    """Close MongoDB connection"""
+    global _client
+    if _client:
+        _client.close()
+        _client = None
+        print("[DB] Connection closed")
+
+
+# Optional: Database health check
+def check_db_health():
+    """Check database connectivity and health"""
+    try:
+        client = get_client()
+        # Ping the database
+        client.admin.command('ping')
+        
+        # Check database exists
+        db = get_db()
+        collections = db.list_collection_names()
+        
+        return {
+            "status": "healthy",
+            "database": settings.MONGODB_DB_NAME,
+            "collections": len(collections),
+            "collection_names": collections
+        }
+    except Exception as e:
+        return {
+            "status": "unhealthy",
+            "error": str(e)
+        }

main.py

@@ -0,0 +1,214 @@
+"""
+Production-Ready FastAPI Application
+Real Estate Tokenization Platform - AtriumChain Platform
+"""
+from fastapi import FastAPI, status, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware
+from fastapi.responses import JSONResponse
+from contextlib import asynccontextmanager
+from slowapi import _rate_limit_exceeded_handler
+from slowapi.errors import RateLimitExceeded
+
+from config import settings
+from db import init_mongo, close_mongo, check_db_health
+from utils.logger import setup_logging
+from middleware.security import SecurityHeadersMiddleware, RequestIDMiddleware, limiter
+
+# Import routes
+from routes import (
+    auth,
+    otp,
+    properties,
+    market,
+    wallet,
+    portfolio,
+    admin,
+    super_admin,
+    secondary_market,
+    profile
+)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifespan events"""
+    print("\n" + "="*80)
+    print("STARTING REAL ESTATE TOKENIZATION PLATFORM")
+    print("="*80 + "\n")
+    
+    # Startup
+    try:
+        # Initialize logging system
+        setup_logging()
+        print("[APP] ✅ Logging system initialized")
+        
+        db = init_mongo(app)
+        print("[APP] ✅ Application startup complete\n")
+    except Exception as e:
+        print(f"[APP] [ERROR] Startup failed: {str(e)}\n")
+        raise
+    
+    yield
+    
+    # Shutdown
+    print("\n[APP] Shutting down...")
+    close_mongo()
+    print("[APP] ✅ Shutdown complete\n")
+
+
+# Create FastAPI app
+app = FastAPI(
+    title="Real Estate Tokenization Platform",
+    description="Production-ready platform for fractional real estate investment using blockchain",
+    version="2.0.0",
+    lifespan=lifespan
+)
+
+# Add HTTPS redirect middleware in production
+if settings.is_production():
+    app.add_middleware(HTTPSRedirectMiddleware)
+    print("[APP] ✅ HTTPS enforcement enabled (production mode)")
+
+# Add security middleware
+app.add_middleware(SecurityHeadersMiddleware)
+app.add_middleware(RequestIDMiddleware)
+
+# Add rate limiter
+app.state.limiter = limiter
+app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
+# CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.CORS_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# Health check endpoint
+@app.get("/", tags=["Health"])
+async def root():
+    """Root endpoint - API health check"""
+    return {
+        "status": "online",
+        "service": "Real Estate Tokenization Platform",
+        "version": "2.0.0",
+        "environment": settings.XRPL_NETWORK
+    }
+
+
+@app.get("/health", tags=["Health"])
+async def health_check():
+    """Detailed health check including database connectivity"""
+    db_health = check_db_health()
+    
+    return {
+        "status": "healthy" if db_health["status"] == "healthy" else "degraded",
+        "api": "online",
+        "database": db_health
+    }
+
+
+# Include routers
+app.include_router(
+    auth.router,
+    prefix="/api/v1/auth",
+    tags=["Authentication"]
+)
+
+app.include_router(
+    otp.router,
+    prefix="/api/v1/otp",
+    tags=["OTP Verification"]
+)
+
+app.include_router(
+    properties.router,
+    prefix="/api/v1",
+    tags=["Properties"]
+)
+
+app.include_router(
+    market.router,
+    prefix="/api/v1",
+    tags=["Market"]
+)
+
+app.include_router(
+    secondary_market.router,
+    prefix="/api/v1",
+    tags=["Secondary Market"]
+)
+
+app.include_router(
+    wallet.router,
+    prefix="/api/v1",
+    tags=["Wallet"]
+)
+
+app.include_router(
+    portfolio.router,
+    prefix="/api/v1",
+    tags=["Portfolio"]
+)
+
+app.include_router(
+    admin.router,
+    prefix="/api/v1",
+    tags=["Admin"]
+)
+
+app.include_router(
+    super_admin.router,
+    prefix="/api/v1",
+    tags=["Super Admin"]
+)
+
+app.include_router(
+    profile.router,
+    prefix="/api/v1/profile",
+    tags=["Profile"]
+)
+
+
+# Global exception handler (sanitized)
+@app.exception_handler(Exception)
+async def global_exception_handler(request, exc):
+    """Handle all unhandled exceptions (hide internals in production)."""
+    # Use structured logging instead of print
+    import logging
+    logger = logging.getLogger(__name__)
+    logger.error(f"Unhandled exception: {exc.__class__.__name__}: {str(exc)}", exc_info=settings.is_development())
+    
+    return JSONResponse(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        content={
+            "detail": "An unexpected error occurred. Please try again later.",
+            "error": str(exc) if settings.is_development() else "Internal server error"
+        }
+    )
+
+
+# Run with: uvicorn main:app --reload --port 8000
+if __name__ == "__main__":
+    import uvicorn
+    
+    print("\n" + "="*80)
+    print("DEVELOPMENT SERVER (LOCAL ONLY)")
+    print("="*80)
+    print("Starting server on http://127.0.0.1:8000")
+    print("API Documentation: http://127.0.0.1:8000/docs")
+    print("NOTE: For production, use: uvicorn main:app --host 0.0.0.0 --port 8000")
+    print("="*80 + "\n")
+    
+    uvicorn.run(
+        "main:app",
+        host="0.0.0.0",  # Bind to localhost only for development security
+        port=8000,
+        reload=True,
+        log_level="info"
+    )
+

middleware/__init__.py

@@ -0,0 +1,4 @@
+"""
+Middleware Package
+Security and request handling middleware
+"""

middleware/security.py

@@ -0,0 +1,488 @@
+"""
+Security Middleware
+Implements rate limiting, input sanitization, CSRF protection, and security headers
+
+SECURITY REQUIREMENTS FOR NEW FEATURES:
+========================================
+1. INPUT VALIDATION:
+   - Always use sanitize_input() for text fields (titles, descriptions, comments)
+   - Use sanitize_dict() for JSON payloads
+   - Validate file uploads: check file type, size, and scan content
+   - Validate ObjectIds before database queries with validate_object_id()
+
+2. AUTHENTICATION & AUTHORIZATION:
+   - Use Depends(get_current_user) for user-only endpoints
+   - Use Depends(get_current_admin) for admin-only endpoints
+   - Never expose user data without authentication
+   - Check ownership before allowing updates/deletes
+
+3. RATE LIMITING:
+   - Apply @limiter.limit() to all write endpoints
+   - Use stricter limits for sensitive operations (login, registration, money transfers)
+   - Example: @limiter.limit("5/minute") for login
+
+4. DATA MASKING:
+   - Use mask_email(), mask_phone(), mask_sensitive_data() for PII
+   - Default to masked view, require explicit permission for full data
+   - Log access to unmasked sensitive data
+
+5. ERROR HANDLING:
+   - Never expose stack traces or internal details to users
+   - Use HTTPException with sanitized messages
+   - Log full errors server-side with request ID
+   - Return consistent error format
+
+6. LOGGING:
+   - Log all security events (failed logins, access denials, suspicious activity)
+   - Include request ID in all logs for tracing
+   - Never log passwords, tokens, or sensitive PII
+
+7. NEW FEATURE CHECKLIST:
+   ☐ Input sanitization implemented
+   ☐ Authentication/authorization configured
+   ☐ Rate limiting applied
+   ☐ PII data masked
+   ☐ Error handling prevents information leakage
+   ☐ Security logging added
+   ☐ Unit tests for security scenarios written
+   ☐ Penetration testing performed
+
+EXAMPLES:
+---------
+Chat/Comments Feature:
+  - Sanitize message content: sanitize_input(message.content)
+  - Rate limit: @limiter.limit("10/minute") for sending messages
+  - Authenticate: current_user = Depends(get_current_user)
+  - Validate: max message length, blocked words list
+  - Mask: user email/phone in chat metadata
+
+File Upload Feature:
+  - Validate file type: allowed_types = ['pdf', 'jpg', 'png']
+  - Validate file size: max_size = 10 * 1024 * 1024  # 10MB
+  - Scan content: virus scan, malicious code detection
+  - Sanitize filename: remove path traversal characters
+  - Store securely: use IPFS or encrypted storage
+"""
+from fastapi import Request, HTTPException, status
+from fastapi.responses import JSONResponse
+from slowapi import Limiter, _rate_limit_exceeded_handler
+from slowapi.util import get_remote_address
+from slowapi.errors import RateLimitExceeded
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.datastructures import Headers
+import bleach
+import re
+from typing import Dict, Any
+import secrets
+from datetime import datetime, timedelta
+import uuid
+import logging
+
+# Initialize rate limiter
+limiter = Limiter(key_func=get_remote_address)
+
+# Configure logger
+logger = logging.getLogger(__name__)
+
+# Failed login attempts tracking (in-memory - replace with Redis in production)
+failed_login_attempts: Dict[str, Dict[str, Any]] = {}
+
+# CSRF token storage (in-memory - replace with Redis in production)
+csrf_tokens: Dict[str, datetime] = {}
+
+
+class SecurityHeadersMiddleware(BaseHTTPMiddleware):
+    """Add security headers to all responses"""
+    
+    async def dispatch(self, request: Request, call_next):
+        response = await call_next(request)
+        
+        # Security Headers
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["X-XSS-Protection"] = "1; mode=block"
+        response.headers["Strict-Transport-Security"] = "max-age=31536000; includeSubDomains"
+        response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+        
+        # Content Security Policy
+        csp = (
+            "default-src 'self'; "
+            "script-src 'self' 'unsafe-inline' 'unsafe-eval'; "
+            "style-src 'self' 'unsafe-inline'; "
+            "img-src 'self' data: https:; "
+            "font-src 'self' data:; "
+            "connect-src 'self' https://s.altnet.rippletest.net:51234 https://testnet.xrpl.org; "
+            "frame-ancestors 'none';"
+        )
+        response.headers["Content-Security-Policy"] = csp
+        
+        return response
+
+
+class RequestIDMiddleware(BaseHTTPMiddleware):
+    """Add unique request ID to each request for tracking and debugging"""
+    
+    async def dispatch(self, request: Request, call_next):
+        # Generate unique request ID
+        request_id = str(uuid.uuid4())
+        
+        # Store request ID in request state for access in route handlers
+        request.state.request_id = request_id
+        
+        # Log request details
+        logger.info(f"[{request_id}] {request.method} {request.url.path} - Client: {request.client.host if request.client else 'unknown'}")
+        
+        try:
+            response = await call_next(request)
+            # Add request ID to response headers for client tracking
+            response.headers["X-Request-ID"] = request_id
+            logger.info(f"[{request_id}] Response status: {response.status_code}")
+            return response
+        except Exception as e:
+            # Log error with request ID
+            logger.error(f"[{request_id}] Error: {str(e)}", exc_info=True)
+            # Return error response without exposing internal details
+            return JSONResponse(
+                status_code=500,
+                content={
+                    "detail": "Internal server error",
+                    "request_id": request_id
+                },
+                headers={"X-Request-ID": request_id}
+            )
+
+
+def sanitize_input(text: str) -> str:
+    """Sanitize user input to prevent XSS attacks"""
+    if not isinstance(text, str):
+        return text
+    
+    # Remove HTML tags and attributes
+    cleaned = bleach.clean(
+        text,
+        tags=[],  # No HTML tags allowed
+        attributes={},
+        strip=True
+    )
+    
+    return cleaned.strip()
+
+
+def sanitize_dict(data: dict) -> dict:
+    """Recursively sanitize all string values in a dictionary"""
+    if not isinstance(data, dict):
+        return data
+    
+    sanitized = {}
+    for key, value in data.items():
+        if isinstance(value, str):
+            sanitized[key] = sanitize_input(value)
+        elif isinstance(value, dict):
+            sanitized[key] = sanitize_dict(value)
+        elif isinstance(value, list):
+            sanitized[key] = [
+                sanitize_input(item) if isinstance(item, str) else item
+                for item in value
+            ]
+        else:
+            sanitized[key] = value
+    
+    return sanitized
+
+
+def validate_object_id(id_string: str) -> bool:
+    """Validate MongoDB ObjectId format"""
+    if not isinstance(id_string, str):
+        return False
+    
+    # ObjectId is 24 character hexadecimal string
+    pattern = re.compile(r'^[0-9a-fA-F]{24}$')
+    return bool(pattern.match(id_string))
+
+
+def validate_name(name: str) -> tuple[bool, str]:
+    """
+    Validate and sanitize user name
+    Returns: (is_valid, error_message or sanitized_name)
+    """
+    if not name:
+        return False, "Name is required"
+    
+    # Sanitize first
+    name = sanitize_input(name).strip()
+    
+    # Check length
+    if len(name) < 2:
+        return False, "Name must be at least 2 characters"
+    if len(name) > 100:
+        return False, "Name must not exceed 100 characters"
+    
+    # Only allow letters, spaces, hyphens, and apostrophes (strict)
+    pattern = re.compile(r"^[a-zA-Z\s\-']+$")
+    if not pattern.match(name):
+        return False, "Name can only contain letters, spaces, hyphens, and apostrophes"
+    
+    # Check for excessive spaces
+    if '  ' in name:
+        return False, "Name cannot contain multiple consecutive spaces"
+    
+    return True, name
+
+
+def validate_phone(phone: str) -> tuple[bool, str]:
+    """
+    Validate and sanitize phone number (REQUIRED, exactly 10 digits)
+    Returns: (is_valid, error_message or sanitized_phone)
+    """
+    if not phone:
+        return False, "Phone number is required"
+    
+    # Sanitize first
+    phone = sanitize_input(phone).strip()
+    
+    # Remove any non-digit characters for validation
+    digits_only = re.sub(r'\D', '', phone)
+    
+    # Must be exactly 10 digits
+    if len(digits_only) != 10:
+        return False, "Phone number must be exactly 10 digits"
+    
+    # Only allow pure digits (no formatting characters)
+    pattern = re.compile(r'^[0-9]{10}$')
+    if not pattern.match(phone):
+        return False, "Phone number must contain only 10 digits (no spaces or special characters)"
+    
+    return True, phone
+
+
+def validate_date(date_str: str) -> tuple[bool, str]:
+    """
+    Validate date string (YYYY-MM-DD format)
+    Returns: (is_valid, error_message or sanitized_date)
+    """
+    if not date_str:
+        return True, None  # Date is optional
+    
+    # Sanitize first
+    date_str = sanitize_input(date_str).strip()
+    
+    # Check format
+    pattern = re.compile(r'^\d{4}-\d{2}-\d{2}$')
+    if not pattern.match(date_str):
+        return False, "Date must be in YYYY-MM-DD format"
+    
+    # Try to parse date
+    try:
+        date_obj = datetime.strptime(date_str, '%Y-%m-%d')
+        
+        # Check if date is not in future
+        if date_obj > datetime.now():
+            return False, "Date cannot be in the future"
+        
+        return True, date_str
+    except ValueError:
+        return False, "Invalid date"
+
+
+def validate_gender(gender: str) -> tuple[bool, str]:
+    """
+    Validate gender selection
+    Returns: (is_valid, error_message or sanitized_gender)
+    """
+    if not gender:
+        return True, None  # Gender is optional
+    
+    # Sanitize first
+    gender = sanitize_input(gender).strip()
+    
+    # Must be from predefined list
+    valid_genders = ['Male', 'Female', 'Other']
+    if gender not in valid_genders:
+        return False, f"Gender must be one of: {', '.join(valid_genders)}"
+    
+    return True, gender
+
+
+def validate_address(address: str) -> tuple[bool, str]:
+    """
+    Validate and sanitize address
+    Returns: (is_valid, error_message or sanitized_address)
+    """
+    if not address:
+        return True, ""  # Address is optional
+    
+    # Sanitize first
+    address = sanitize_input(address).strip()
+    
+    # Check length
+    if len(address) > 500:
+        return False, "Address must not exceed 500 characters"
+    
+    # Only allow letters, numbers, spaces, and common address characters
+    pattern = re.compile(r"^[a-zA-Z0-9\s,.\-'#/()\n]+$")
+    if not pattern.match(address):
+        return False, "Address contains invalid characters"
+    
+    return True, address
+
+
+def validate_redirect_url(url: str, allowed_domains: list = None) -> bool:
+    """
+    Validate redirect URL to prevent open redirect attacks
+    Only allows relative URLs or URLs from whitelisted domains
+    Blocks javascript:, data:, and other dangerous schemes
+    """
+    if not url:
+        return False
+    
+    # Block dangerous schemes
+    dangerous_schemes = ['javascript:', 'data:', 'vbscript:', 'file:', 'about:']
+    url_lower = url.lower().strip()
+    for scheme in dangerous_schemes:
+        if url_lower.startswith(scheme):
+            return False
+    
+    # Default allowed domains (localhost and local dev)
+    if allowed_domains is None:
+        allowed_domains = [
+            'localhost',
+            '127.0.0.1',
+            'localhost:5173',
+            'localhost:5174',
+            'localhost:5175',
+            '127.0.0.1:5173',
+            '127.0.0.1:5174',
+            '127.0.0.1:5175'
+        ]
+    
+    # Check if URL is relative (starts with /)
+    if url.startswith('/') and not url.startswith('//'):
+        return True
+    
+    # Check if URL starts with allowed domain
+    for domain in allowed_domains:
+        if url.startswith(f'http://{domain}') or url.startswith(f'https://{domain}'):
+            return True
+    
+    # Reject all other URLs (external domains)
+    return False
+
+
+def generate_csrf_token() -> str:
+    """Generate a CSRF token"""
+    token = secrets.token_urlsafe(32)
+    csrf_tokens[token] = datetime.utcnow() + timedelta(hours=1)
+    return token
+
+
+def validate_csrf_token(token: str) -> bool:
+    """Validate CSRF token"""
+    if not token or token not in csrf_tokens:
+        return False
+    
+    # Check if token is expired
+    if csrf_tokens[token] < datetime.utcnow():
+        del csrf_tokens[token]
+        return False
+    
+    return True
+
+
+def check_rate_limit(ip: str, endpoint: str, max_attempts: int = 5, window_minutes: int = 15) -> bool:
+    """
+    Check if IP has exceeded rate limit for failed login attempts
+    Returns True if allowed, False if blocked
+    """
+    key = f"{ip}:{endpoint}"
+    now = datetime.utcnow()
+    
+    if key not in failed_login_attempts:
+        failed_login_attempts[key] = {
+            'count': 0,
+            'first_attempt': now,
+            'locked_until': None
+        }
+    
+    attempt_data = failed_login_attempts[key]
+    
+    # Check if currently locked
+    if attempt_data['locked_until'] and attempt_data['locked_until'] > now:
+        return False
+    
+    # Reset if window has passed
+    if now - attempt_data['first_attempt'] > timedelta(minutes=window_minutes):
+        failed_login_attempts[key] = {
+            'count': 0,
+            'first_attempt': now,
+            'locked_until': None
+        }
+        return True
+    
+    # Check if exceeded max attempts
+    if attempt_data['count'] >= max_attempts:
+        # Lock for 15 minutes
+        attempt_data['locked_until'] = now + timedelta(minutes=window_minutes)
+        return False
+    
+    return True
+
+
+def record_failed_attempt(ip: str, endpoint: str):
+    """Record a failed login attempt"""
+    key = f"{ip}:{endpoint}"
+    now = datetime.utcnow()
+    
+    if key not in failed_login_attempts:
+        failed_login_attempts[key] = {
+            'count': 1,
+            'first_attempt': now,
+            'locked_until': None
+        }
+    else:
+        failed_login_attempts[key]['count'] += 1
+
+
+def reset_failed_attempts(ip: str, endpoint: str):
+    """Reset failed attempts after successful login"""
+    key = f"{ip}:{endpoint}"
+    if key in failed_login_attempts:
+        del failed_login_attempts[key]
+
+
+def mask_sensitive_data(data: str, mask_char: str = "*", visible_chars: int = 4) -> str:
+    """
+    Mask sensitive data showing only last N characters
+    Shows fixed-length mask (12 chars) for consistent display
+    """
+    if not data or len(data) <= visible_chars:
+        return data
+    
+    # Use fixed mask length for consistent display (prevents length-based attacks)
+    fixed_mask_length = 12
+    return mask_char * fixed_mask_length + data[-visible_chars:]
+
+
+def mask_email(email: str) -> str:
+    """Mask email address preserving domain"""
+    if not email or '@' not in email:
+        return email
+    
+    local, domain = email.split('@', 1)
+    if len(local) <= 2:
+        return f"{local}@{domain}"
+    
+    masked_local = local[0] + '*' * (len(local) - 2) + local[-1]
+    return f"{masked_local}@{domain}"
+
+
+def mask_phone(phone: str) -> str:
+    """Mask phone number showing only last 4 digits"""
+    if not phone:
+        return phone
+    
+    # Remove non-numeric characters
+    digits_only = re.sub(r'\D', '', phone)
+    if len(digits_only) <= 4:
+        return phone
+    
+    return '*' * (len(digits_only) - 4) + digits_only[-4:]

repo.py

@@ -0,0 +1,2316 @@
+"""
+Production-Ready Repository Layer for Real Estate Tokenization Platform
+Implements the complete database schema with MongoDB
+"""
+from datetime import datetime
+from typing import Optional, List, Dict, Any
+import logging
+from pymongo.collection import Collection
+from pymongo import ReturnDocument, ASCENDING, DESCENDING
+from bson import ObjectId
+from db import get_db, get_next_sequence
+from config import settings
+from utils.logger import setup_logger
+
+logger = setup_logger(__name__)
+
+
+def _now():
+    """Get current UTC timestamp"""
+    return datetime.utcnow()
+
+
+def _clean_object(data):
+    """Clean MongoDB object by converting ObjectId to string"""
+    if isinstance(data, dict):
+        cleaned = {}
+        for key, value in data.items():
+            if key == "_id":
+                cleaned["id"] = str(value) if isinstance(value, ObjectId) else value
+            else:
+                cleaned[key] = _clean_object(value)
+        return cleaned
+    if isinstance(data, list):
+        return [_clean_object(item) for item in data]
+    if isinstance(data, ObjectId):
+        return str(data)
+    return data
+
+
+def _to_object_id(id_str: str) -> ObjectId:
+    """Convert string ID to ObjectId"""
+    try:
+        return ObjectId(id_str)
+    except:
+        raise ValueError(f"Invalid ObjectId: {id_str}")
+
+
+def _coerce_object_id(id_value):
+    """Return ObjectId when possible, otherwise fall back to original value."""
+    if id_value is None or isinstance(id_value, ObjectId):
+        return id_value
+    try:
+        return ObjectId(id_value)
+    except Exception:
+        logger.warning("Invalid ObjectId %r; storing plain value", id_value)
+        return id_value
+
+
+# ============================================================================
+# USER OPERATIONS
+# ============================================================================
+
+def users_col(db) -> Collection:
+    return db.users
+
+
+def create_user(db, name: str, email: str, password_hash: str, country_code: str, phone: str, role: str = "user") -> Dict[str, Any]:
+    """Create a new user"""
+    logger.info(f"Creating user: {email} with role: {role}")
+    
+    now = _now()
+    doc = {
+        "name": name,
+        "email": email,
+        "password_hash": password_hash,
+        "role": role,
+        "country_code": country_code,
+        "phone": phone,
+        "wallet_id": None,
+        "is_active": True,
+        "deleted": False,
+        "created_at": now,
+        "updated_at": now,
+    }
+    
+    result = users_col(db).insert_one(doc)
+    doc["_id"] = result.inserted_id
+    
+    logger.info(f"User created successfully with ID: {result.inserted_id}")
+    return _clean_object(doc)
+
+
+def get_user_by_email(db, email: str) -> Optional[Dict[str, Any]]:
+    """Get user by email"""
+    doc = users_col(db).find_one({"email": email, "deleted": False})
+    return _clean_object(doc) if doc else None
+
+
+def get_user_by_id(db, user_id: str) -> Optional[Dict[str, Any]]:
+    """Get user by ID"""
+    doc = users_col(db).find_one({"_id": _to_object_id(user_id), "deleted": False})
+    return _clean_object(doc) if doc else None
+
+
+def get_user_by_role(db, role: str) -> Optional[Dict[str, Any]]:
+    """Get a user by role (e.g., 'admin', 'super_admin')"""
+    doc = users_col(db).find_one({"role": role, "deleted": False, "is_active": True})
+    return _clean_object(doc) if doc else None
+
+
+def update_user(db, user_id: str, fields: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """Update user fields"""
+    print(f"[REPO] Updating user {user_id} with fields: {list(fields.keys())}")
+    
+    fields["updated_at"] = _now()
+    doc = users_col(db).find_one_and_update(
+        {"_id": _to_object_id(user_id)},
+        {"$set": fields},
+        return_document=ReturnDocument.AFTER
+    )
+    
+    if doc:
+        print(f"[REPO] User updated successfully")
+    return _clean_object(doc) if doc else None
+
+
+def list_all_users(db, skip: int = 0, limit: int = 100, fetch_live_xrp: bool = True) -> List[Dict[str, Any]]:
+    """List all users with pagination and wallet information
+    
+    Excludes admin users - only returns regular users with role='user'
+    
+    Args:
+        db: Database connection
+        skip: Number of records to skip
+        limit: Maximum number of records to return
+        fetch_live_xrp: If True, fetch live XRP balance from blockchain (slower but accurate)
+    """
+    
+    # Filter to only show regular users, exclude admins
+    # user_docs = list(users_col(db).find({"deleted": False}).skip(skip).limit(limit).sort("created_at", DESCENDING))
+    user_docs = list(users_col(db).find({"deleted": False, "role": "user"}).skip(skip).limit(limit).sort("created_at", DESCENDING))
+
+    users_with_wallets = []
+    for user_doc in user_docs:
+        user = _clean_object(user_doc)
+
+        # Get wallet information for balances
+        wallet_doc = wallets_col(db).find_one({"user_id": _to_object_id(user["id"])})
+        if wallet_doc:
+            # Always use wallet.balance as the source of truth for AED balance
+            user["aed_balance"] = wallet_doc.get("balance", 0.0)
+            user["xrp_address"] = wallet_doc.get("xrp_address")
+            
+            # Use cached XRP balance instead of live fetching (much faster!)
+            if wallet_doc.get("xrp_address"):
+                # Try to get cached balance from Redis first
+                cached_balance = None
+                try:
+                    from utils.cache import get_cached_xrp_balance
+                    cached_balance = get_cached_xrp_balance(wallet_doc.get("xrp_address"))
+                except ImportError:
+                    pass
+                
+                if cached_balance is not None:
+                    # Use cached balance (fast)
+                    user["xrp_balance"] = cached_balance
+                elif wallet_doc.get("xrp_balance_cached"):
+                    # Use database cached balance (fallback)
+                    user["xrp_balance"] = wallet_doc.get("xrp_balance_cached", 0.0)
+                elif fetch_live_xrp:
+                    # Only fetch live if explicitly requested and no cache available
+                    try:
+                        from services.xrp_service import XRPLService
+                        from utils.cache import cache_xrp_balance
+                        xrpl_service = XRPLService()
+                        live_xrp_balance = xrpl_service.get_xrp_balance(wallet_doc.get("xrp_address"))
+                        user["xrp_balance"] = live_xrp_balance
+                        # Cache the result for next time
+                        cache_xrp_balance(wallet_doc.get("xrp_address"), live_xrp_balance, ttl=300)
+                        # Also update database cache
+                        wallets_col(db).update_one(
+                            {"_id": wallet_doc["_id"]},
+                            {"$set": {"xrp_balance_cached": live_xrp_balance, "balance_updated_at": _now()}}
+                        )
+                    except Exception as e:
+                        logger.warning(f"Failed to fetch live XRP balance for {wallet_doc.get('xrp_address')}: {e}")
+                        user["xrp_balance"] = 0.0
+                else:
+                    user["xrp_balance"] = 0.0
+            else:
+                user["xrp_balance"] = 0.0
+        else:
+            # No wallet exists yet
+            user["aed_balance"] = 0.0
+            user["xrp_address"] = None
+            user["xrp_balance"] = 0.0
+
+        users_with_wallets.append(user)
+
+    return users_with_wallets
+
+# ============================================================================
+# ADMIN USER HELPERS
+# ============================================================================
+
+def get_primary_admin(db, session=None) -> Optional[Dict[str, Any]]:
+    """Return first user with role == 'admin'."""
+    base_query = {"role": "admin", "deleted": False}
+    if session:
+        doc = users_col(db).find_one(base_query, session=session)
+    else:
+        doc = users_col(db).find_one(base_query)
+    return _clean_object(doc) if doc else None
+
+
+# ============================================================================
+# WALLET OPERATIONS
+# ============================================================================
+
+def wallets_col(db) -> Collection:
+    return db.wallets
+
+
+def create_wallet(db, user_id: str, balance: float = 0.0, currency: str = "AED", xrp_address: str = None, xrp_seed: str = None) -> Dict[str, Any]:
+    """Create a wallet for a user"""
+    print(f"[REPO] Creating wallet for user {user_id}, balance: {balance} {currency}")
+    
+    now = _now()
+    doc = {
+        "user_id": _to_object_id(user_id),
+        "balance": balance,
+        "currency": currency,
+        "xrp_address": xrp_address,
+        "xrp_seed": xrp_seed,  # Encrypted in production!
+        "is_active": True,
+        "created_at": now,
+        "updated_at": now,
+    }
+    
+    result = wallets_col(db).insert_one(doc)
+    doc["_id"] = result.inserted_id
+    
+    # Update user with wallet reference
+    users_col(db).update_one(
+        {"_id": _to_object_id(user_id)},
+        {"$set": {"wallet_id": result.inserted_id, "updated_at": now}}
+    )
+    
+    print(f"[REPO] Wallet created successfully with ID: {result.inserted_id}")
+    return _clean_object(doc)
+
+
+def get_wallet_by_user(db, user_id: str) -> Optional[Dict[str, Any]]:
+    """Get wallet by user ID"""
+    doc = wallets_col(db).find_one({"user_id": _to_object_id(user_id)})
+    return _clean_object(doc) if doc else None
+
+
+def update_wallet_balance(db, wallet_id: str, amount: float, operation: str = "add", session=None) -> Optional[Dict[str, Any]]:
+    """Update wallet balance (add or subtract)"""
+    print(f"[REPO] {operation.capitalize()}ing {amount} to wallet {wallet_id}")
+    
+    increment = amount if operation == "add" else -amount
+    
+    doc = wallets_col(db).find_one_and_update(
+        {"_id": _to_object_id(wallet_id)},
+        {
+            "$inc": {"balance": increment},
+            "$set": {"updated_at": _now()}
+        },
+        return_document=ReturnDocument.AFTER,
+        session=session
+    )
+    
+    if doc:
+        print(f"[REPO] Wallet balance updated. New balance: {doc.get('balance')}")
+    return _clean_object(doc) if doc else None
+
+
+def update_wallet_xrp(db, wallet_id: str, xrp_address: str, xrp_seed: str) -> Optional[Dict[str, Any]]:
+    """Update wallet with XRP address and seed"""
+    print(f"[REPO] Adding XRP wallet to wallet {wallet_id}: {xrp_address}")
+    
+    doc = wallets_col(db).find_one_and_update(
+        {"_id": _to_object_id(wallet_id)},
+        {
+            "$set": {
+                "xrp_address": xrp_address,
+                "xrp_seed": xrp_seed,  # Should be encrypted in production
+                "updated_at": _now()
+            }
+        },
+        return_document=ReturnDocument.AFTER
+    )
+    
+    if doc:
+        print(f"[REPO] XRP wallet added successfully")
+    return _clean_object(doc) if doc else None
+
+
+# ============================================================================
+# PROPERTY OPERATIONS
+# ============================================================================
+
+def properties_col(db) -> Collection:
+    return db.properties
+
+
+def create_property(db, property_data: Dict[str, Any], created_by: str) -> Dict[str, Any]:
+    """Create a new property"""
+    print(f"[REPO] Creating property: {property_data.get('title')}")
+    
+    now = _now()
+    doc = {
+        **property_data,
+        "available_tokens": property_data.get("total_tokens", 0),
+        "created_by": _coerce_object_id(created_by),
+        "is_active": True,
+        "deleted": False,
+        "created_at": now,
+        "updated_at": now,
+    }
+    
+    result = properties_col(db).insert_one(doc)
+    doc["_id"] = result.inserted_id
+    
+    print(f"[REPO] Property created successfully with ID: {result.inserted_id}")
+    return _clean_object(doc)
+
+
+def get_property_by_id(db, property_id: str) -> Optional[Dict[str, Any]]:
+    """Get property by ID"""
+    doc = properties_col(db).find_one({"_id": _to_object_id(property_id), "deleted": False})
+    return _clean_object(doc) if doc else None
+
+
+def get_property_by_id_optimized(db, property_id: str) -> Optional[Dict[str, Any]]:
+    """
+    Get property by ID with all related data using aggregation (optimized)
+    Returns property with specifications, amenities, images, and documents in a single query
+    """
+    pipeline = [
+        {"$match": {"_id": _to_object_id(property_id), "deleted": False}},
+
+        # Join creator information
+        {"$lookup": {
+            "from": "users",
+            "localField": "created_by",
+            "foreignField": "_id",
+            "as": "creator"
+        }},
+        {"$unwind": {
+            "path": "$creator",
+            "preserveNullAndEmptyArrays": True
+        }},
+        
+        # Join with property_specifications
+        {"$lookup": {
+            "from": "property_specifications",
+            "localField": "_id",
+            "foreignField": "property_id",
+            "as": "specifications"
+        }},
+        {"$unwind": {
+            "path": "$specifications",
+            "preserveNullAndEmptyArrays": True
+        }},
+        
+        # Join with amenities
+        {"$lookup": {
+            "from": "amenities",
+            "localField": "_id",
+            "foreignField": "property_id",
+            "as": "amenities",
+            "pipeline": [
+                {"$match": {"is_active": True}}
+            ]
+        }},
+        
+        # Join with property_images
+        {"$lookup": {
+            "from": "property_images",
+            "localField": "_id",
+            "foreignField": "property_id",
+            "as": "images",
+            "pipeline": [
+                {"$match": {"is_active": True}}
+            ]
+        }},
+        
+        # Join with documents
+        {"$lookup": {
+            "from": "documents",
+            "localField": "_id",
+            "foreignField": "property_id",
+            "as": "documents"
+        }}
+    ]
+    
+    docs = list(properties_col(db).aggregate(pipeline))
+    
+    if docs:
+        return _clean_object(docs[0])
+    return None
+
+
+def list_properties(db, is_active: Optional[bool] = None, skip: int = 0, limit: int = 100) -> List[Dict[str, Any]]:
+    """List properties with optional filtering"""
+    query = {"deleted": False}
+    if is_active is not None:
+        query["is_active"] = is_active
+    
+    docs = list(properties_col(db).find(query).skip(skip).limit(limit).sort("created_at", DESCENDING))
+    return [_clean_object(doc) for doc in docs]
+
+
+def list_properties_optimized(db, is_active: Optional[bool] = None, skip: int = 0, limit: int = 100) -> List[Dict[str, Any]]:
+    """
+    List properties with related data using MongoDB aggregation (optimized - no N+1 queries)
+    Returns properties with specifications, amenities, images, and documents in a single query
+    """
+    # Build match query
+    match_query = {"deleted": False}
+    if is_active is not None:
+        match_query["is_active"] = is_active
+    
+    # Aggregation pipeline
+    pipeline = [
+        {"$match": match_query},
+        {"$sort": {"created_at": DESCENDING}},
+        {"$skip": skip},
+        {"$limit": limit},
+
+        # Join creator information
+        {"$lookup": {
+            "from": "users",
+            "localField": "created_by",
+            "foreignField": "_id",
+            "as": "creator"
+        }},
+        {"$unwind": {
+            "path": "$creator",
+            "preserveNullAndEmptyArrays": True
+        }},
+        
+        # Join with property_specifications (1-to-1)
+        {"$lookup": {
+            "from": "property_specifications",
+            "localField": "_id",
+            "foreignField": "property_id",
+            "as": "specifications"
+        }},
+        {"$unwind": {
+            "path": "$specifications",
+            "preserveNullAndEmptyArrays": True
+        }},
+        
+        # Join with amenities (1-to-many)
+        {"$lookup": {
+            "from": "amenities",
+            "localField": "_id",
+            "foreignField": "property_id",
+            "as": "amenities",
+            "pipeline": [
+                {"$match": {"is_active": True}}
+            ]
+        }},
+        
+        # Join with property_images (1-to-many)
+        {"$lookup": {
+            "from": "property_images",
+            "localField": "_id",
+            "foreignField": "property_id",
+            "as": "images",
+            "pipeline": [
+                {"$match": {"is_active": True}}
+            ]
+        }},
+        
+        # Join with documents (1-to-many)
+        {"$lookup": {
+            "from": "documents",
+            "localField": "_id",
+            "foreignField": "property_id",
+            "as": "documents"
+        }}
+    ]
+    
+    # Execute aggregation
+    docs = list(properties_col(db).aggregate(pipeline))
+    
+    # Clean and return
+    return [_clean_object(doc) for doc in docs]
+
+
+def update_property(db, property_id: str, fields: Dict[str, Any], session=None) -> Optional[Dict[str, Any]]:
+    """Update property fields"""
+    print(f"[REPO] Updating property {property_id} with fields: {list(fields.keys())}")
+    
+    fields["updated_at"] = _now()
+    doc = properties_col(db).find_one_and_update(
+        {"_id": _to_object_id(property_id)},
+        {"$set": fields},
+        return_document=ReturnDocument.AFTER,
+        session=session
+    )
+    
+    if doc:
+        print(f"[REPO] Property updated successfully")
+    return _clean_object(doc) if doc else None
+
+
+def delete_property(db, property_id: str) -> bool:
+    """Soft delete a property"""
+    print(f"[REPO] Soft deleting property {property_id}")
+    
+    result = properties_col(db).update_one(
+        {"_id": _to_object_id(property_id)},
+        {"$set": {"deleted": True, "is_active": False, "updated_at": _now()}}
+    )
+    
+    success = result.matched_count > 0
+    if success:
+        print(f"[REPO] Property soft deleted successfully")
+    else:
+        print(f"[REPO] Property not found for deletion")
+    
+    return success
+
+
+def decrement_available_tokens(db, property_id: str, amount: int, session=None) -> bool:
+    """Decrement available tokens atomically"""
+    print(f"[REPO] Decrementing {amount} tokens from property {property_id}")
+    
+    result = properties_col(db).update_one(
+        {
+            "_id": _to_object_id(property_id),
+            "available_tokens": {"$gte": amount}
+        },
+        {
+            "$inc": {"available_tokens": -amount},
+            "$set": {"updated_at": _now()}
+        },
+        session=session
+    )
+    
+    success = result.matched_count > 0
+    if success:
+        print(f"[REPO] Successfully decremented tokens")
+    else:
+        print(f"[REPO] ERROR: Failed to decrement tokens - insufficient available")
+    
+    return success
+
+
+# ============================================================================
+# PROPERTY SPECIFICATIONS
+# ============================================================================
+
+def property_specifications_col(db) -> Collection:
+    return db.property_specifications
+
+
+def create_property_specification(db, property_id: str, spec_data: Dict[str, Any]) -> Dict[str, Any]:
+    """Create property specifications"""
+    print(f"[REPO] Creating specifications for property {property_id}")
+    
+    now = _now()
+    doc = {
+        **spec_data,
+        "property_id": _to_object_id(property_id),
+        "created_at": now,
+        "updated_at": now,
+    }
+    
+    result = property_specifications_col(db).insert_one(doc)
+    doc["_id"] = result.inserted_id
+    
+    return _clean_object(doc)
+
+
+def get_property_specification(db, property_id: str) -> Optional[Dict[str, Any]]:
+    """Get specifications for a property"""
+    doc = property_specifications_col(db).find_one({"property_id": _to_object_id(property_id)})
+    return _clean_object(doc) if doc else None
+
+
+# ============================================================================
+# AMENITIES
+# ============================================================================
+
+def amenities_col(db) -> Collection:
+    return db.amenities
+
+
+def create_amenities(db, property_id: str, amenity_names: List[str]) -> List[Dict[str, Any]]:
+    """Create multiple amenities for a property"""
+    print(f"[REPO] Creating {len(amenity_names)} amenities for property {property_id}")
+    
+    now = _now()
+    docs = []
+    for name in amenity_names:
+        doc = {
+            "property_id": _to_object_id(property_id),
+            "name": name,
+            "is_active": True,
+            "created_at": now,
+            "updated_at": now,
+        }
+        docs.append(doc)
+    
+    if docs:
+        result = amenities_col(db).insert_many(docs)
+        for i, inserted_id in enumerate(result.inserted_ids):
+            docs[i]["_id"] = inserted_id
+    
+    return [_clean_object(doc) for doc in docs]
+
+
+def get_property_amenities(db, property_id: str) -> List[Dict[str, Any]]:
+    """Get all amenities for a property"""
+    docs = list(amenities_col(db).find({"property_id": _to_object_id(property_id), "is_active": True}))
+    return [_clean_object(doc) for doc in docs]
+
+
+# ============================================================================
+# PROPERTY IMAGES
+# ============================================================================
+
+def property_images_col(db) -> Collection:
+    return db.property_images
+
+
+def create_property_images(db, property_id: str, images_data: List[Dict[str, Any]], uploaded_by: str) -> List[Dict[str, Any]]:
+    """Create multiple images for a property"""
+    print(f"[REPO] Creating {len(images_data)} images for property {property_id}")
+    
+    now = _now()
+    docs = []
+    for img_data in images_data:
+        doc = {
+            **img_data,
+            "property_id": _to_object_id(property_id),
+            "uploaded_by": _coerce_object_id(uploaded_by),
+            "is_active": True,
+            "created_at": now,
+            "updated_at": now,
+        }
+        docs.append(doc)
+    
+    if docs:
+        result = property_images_col(db).insert_many(docs)
+        for i, inserted_id in enumerate(result.inserted_ids):
+            docs[i]["_id"] = inserted_id
+    
+    return [_clean_object(doc) for doc in docs]
+
+
+def get_property_images(db, property_id: str) -> List[Dict[str, Any]]:
+    """Get all images for a property"""
+    docs = list(property_images_col(db).find({"property_id": _to_object_id(property_id), "is_active": True}))
+    return [_clean_object(doc) for doc in docs]
+
+
+# ============================================================================
+# INVESTMENTS
+# ============================================================================
+
+def investments_col(db) -> Collection:
+    return db.investments
+
+
+def create_investment(db, user_id: str, property_id: str, tokens_purchased: int, amount: float, status: str = "confirmed", profit_share: float = 0.0, session=None) -> Dict[str, Any]:
+    """Create a new investment record"""
+    print(f"[REPO] Creating investment: user={user_id}, property={property_id}, tokens={tokens_purchased}, amount={amount}")
+    
+    now = _now()
+    doc = {
+        "user_id": _to_object_id(user_id),
+        "property_id": _to_object_id(property_id),
+        "tokens_purchased": tokens_purchased,
+        "amount": amount,
+        "status": status,
+        "profit_share": profit_share,
+        "created_at": now,
+        "updated_at": now,
+    }
+    
+    result = investments_col(db).insert_one(doc, session=session)
+    doc["_id"] = result.inserted_id
+    
+    print(f"[REPO] Investment created with ID: {result.inserted_id}")
+    return _clean_object(doc)
+
+
+def get_user_investments(db, user_id: str) -> List[Dict[str, Any]]:
+    """Get all investments for a user"""
+    docs = list(investments_col(db).find({"user_id": _to_object_id(user_id)}).sort("created_at", DESCENDING))
+    return [_clean_object(doc) for doc in docs]
+
+
+def get_investment_by_user_and_property(db, user_id: str, property_id: str) -> Optional[Dict[str, Any]]:
+    """Get investment by user and property"""
+    doc = investments_col(db).find_one({
+        "user_id": _to_object_id(user_id),
+        "property_id": _to_object_id(property_id)
+    })
+    return _clean_object(doc) if doc else None
+
+
+def update_investment(db, investment_id: str, fields: Dict[str, Any], session=None) -> Optional[Dict[str, Any]]:
+    """Update investment"""
+    fields["updated_at"] = _now()
+    doc = investments_col(db).find_one_and_update(
+        {"_id": _to_object_id(investment_id)},
+        {"$set": fields},
+        return_document=ReturnDocument.AFTER,
+        session=session
+    )
+    return _clean_object(doc) if doc else None
+
+
+def reduce_investment(db, user_id: str, property_id: str, tokens_to_reduce: int, session=None) -> Optional[Dict[str, Any]]:
+    """Reduce investment tokens when user sells back tokens"""
+    print(f"[REPO] Reducing investment: user={user_id}, property={property_id}, tokens={tokens_to_reduce}")
+    
+    investment = get_investment_by_user_and_property(db, user_id, property_id)
+    if not investment:
+        print(f"[REPO] No investment found")
+        return None
+    
+    current_tokens = investment.get('tokens_purchased', 0)
+    if tokens_to_reduce > current_tokens:
+        print(f"[REPO] Cannot reduce {tokens_to_reduce} tokens, user only has {current_tokens}")
+        return None
+    
+    new_token_count = current_tokens - tokens_to_reduce
+    
+    if new_token_count == 0:
+        # Delete investment if no tokens left
+        print(f"[REPO] Removing investment (all tokens sold)")
+        investments_col(db).delete_one({"_id": _to_object_id(investment['id'])}, session=session)
+        return {**investment, 'tokens_purchased': 0}
+    else:
+        # Update investment with reduced tokens
+        print(f"[REPO] Updating investment tokens: {current_tokens} -> {new_token_count}")
+        updated = update_investment(db, investment['id'], {'tokens_purchased': new_token_count}, session=session)
+        return updated
+
+
+def upsert_investment(db, user_id: str, property_id: str, tokens_purchased: int, amount: float, session=None) -> Dict[str, Any]:
+    """Update existing investment or create new one"""
+    print(f"[REPO] Upserting investment for user {user_id}, property {property_id}")
+    
+    now = _now()
+    doc = investments_col(db).find_one_and_update(
+        {
+            "user_id": _to_object_id(user_id),
+            "property_id": _to_object_id(property_id)
+        },
+        {
+            "$inc": {
+                "tokens_purchased": tokens_purchased,
+                "amount": amount
+            },
+            "$set": {
+                "status": "confirmed",
+                "updated_at": now
+            },
+            "$setOnInsert": {
+                "profit_share": 0.0,
+                "created_at": now
+            }
+        },
+        upsert=True,
+        return_document=ReturnDocument.AFTER,
+        session=session
+    )
+    
+    return _clean_object(doc)
+
+
+def get_user_portfolio_optimized(db, user_id: str) -> List[Dict[str, Any]]:
+    """
+    Get user's complete portfolio with all related data in a single aggregation query
+    Eliminates N+1 query problem by using MongoDB aggregation pipeline
+    Returns investments with property, specifications, amenities, images, and tokens in one query
+    """
+    pipeline = [
+        # Match investments for this user
+        {"$match": {"user_id": _to_object_id(user_id)}},
+        {"$sort": {"created_at": DESCENDING}},
+        
+        # Join with properties collection
+        {
+            "$lookup": {
+                "from": "properties",
+                "localField": "property_id",
+                "foreignField": "_id",
+                "as": "property"
+            }
+        },
+        {"$unwind": {"path": "$property", "preserveNullAndEmptyArrays": False}},
+        
+        # Filter out deleted properties
+        {"$match": {"property.deleted": False}},
+        
+        # Join with property_specifications
+        {
+            "$lookup": {
+                "from": "property_specifications",
+                "localField": "property_id",
+                "foreignField": "property_id",
+                "as": "specifications"
+            }
+        },
+        {"$unwind": {"path": "$specifications", "preserveNullAndEmptyArrays": True}},
+        
+        # Join with amenities
+        {
+            "$lookup": {
+                "from": "amenities",
+                "let": {"prop_id": "$property_id"},
+                "pipeline": [
+                    {"$match": {
+                        "$expr": {"$eq": ["$property_id", "$$prop_id"]},
+                        "is_active": True
+                    }}
+                ],
+                "as": "amenities"
+            }
+        },
+        
+        # Join with property_images
+        {
+            "$lookup": {
+                "from": "property_images",
+                "let": {"prop_id": "$property_id"},
+                "pipeline": [
+                    {"$match": {
+                        "$expr": {"$eq": ["$property_id", "$$prop_id"]},
+                        "is_active": True
+                    }}
+                ],
+                "as": "images"
+            }
+        },
+        
+        # Join with property_tokens
+        {
+            "$lookup": {
+                "from": "property_tokens",
+                "localField": "property_id",
+                "foreignField": "property_id",
+                "as": "tokens"
+            }
+        },
+        {"$unwind": {"path": "$tokens", "preserveNullAndEmptyArrays": True}},
+        
+        # Project final structure
+        {
+            "$project": {
+                "_id": 1,
+                "user_id": 1,
+                "property_id": 1,
+                "tokens_purchased": 1,
+                "amount": 1,
+                "status": 1,
+                "created_at": 1,
+                "updated_at": 1,
+                "property": 1,
+                "specifications": 1,
+                "amenities": 1,
+                "images": 1,
+                "tokens": 1
+            }
+        }
+    ]
+    
+    docs = list(investments_col(db).aggregate(pipeline))
+    return [_clean_object(doc) for doc in docs]
+
+
+# ============================================================================
+# TRANSACTIONS
+# ============================================================================
+
+def transactions_col(db) -> Collection:
+    return db.transactions
+
+
+def create_transaction(db, user_id: str, wallet_id: Optional[str], tx_type: str, amount: float, 
+                       property_id: Optional[str] = None, status: str = "pending", 
+                       metadata: Optional[Dict[str, Any]] = None, session=None) -> Dict[str, Any]:
+    """Create a transaction record"""
+    print(f"[REPO] Creating transaction: type={tx_type}, amount={amount}, status={status}")
+    
+    now = _now()
+    doc = {
+        "user_id": _to_object_id(user_id),
+        "wallet_id": _to_object_id(wallet_id) if wallet_id else None,
+        "type": tx_type,
+        "amount": amount,
+        "property_id": _to_object_id(property_id) if property_id else None,
+        "status": status,
+        "metadata": metadata or {},
+        "created_at": now,
+        "updated_at": now,
+    }
+    
+    result = transactions_col(db).insert_one(doc, session=session)
+    doc["_id"] = result.inserted_id
+    
+    print(f"[REPO] Transaction created with ID: {result.inserted_id}")
+    return _clean_object(doc)
+
+
+def insert_transaction(db, transaction_data: Dict[str, Any], session=None) -> Dict[str, Any]:
+    """Compatibility layer for legacy code paths expecting integer fils fields.
+
+    Supports fields:
+      - total_amount_aed (int fils)
+      - amount (float) (legacy investment amount)
+      - direction (credit/debit informational)
+      - notes/payment_method/payment_reference
+    """
+    # Map legacy naming: if total_amount_aed present, convert fils to float amount for storage uniformity
+    amount = transaction_data.get("amount")
+    total_amount_fils = transaction_data.get("total_amount_aed")
+    metadata = transaction_data.get("metadata", {}) or {}
+
+    if total_amount_fils is not None and amount is None:
+        try:
+            amount = float(total_amount_fils) / 100.0
+            metadata["total_amount_fils"] = int(total_amount_fils)
+        except Exception:
+            amount = 0.0
+
+    # Embed ancillary fields into metadata to avoid schema drift
+    for k in ("notes", "payment_method", "payment_reference", "price_per_token", "xrp_cost", "blockchain_tx_hash",
+              "direction", "counterparty_user_id", "counterparty_username", "counterparty_email", "property_name"):
+        if k in transaction_data and transaction_data[k] is not None:
+            metadata[k] = transaction_data[k]
+
+    return create_transaction(
+        db,
+        user_id=transaction_data.get("user_id"),
+        wallet_id=transaction_data.get("wallet_id"),
+        tx_type=transaction_data.get("type"),
+        amount=amount or 0.0,
+        property_id=transaction_data.get("property_id"),
+        status=transaction_data.get("status", "pending"),
+        metadata=metadata,
+        session=session,
+    )
+
+
+def get_user_transactions(db, user_id: str, skip: int = 0, limit: int = 100) -> List[Dict[str, Any]]:
+    """Get all transactions for a user"""
+    docs = list(transactions_col(db).find({"user_id": _to_object_id(user_id)})
+                .skip(skip).limit(limit).sort("created_at", DESCENDING))
+    return [_clean_object(doc) for doc in docs]
+
+
+def update_transaction_status(db, transaction_id: str, status: str, session=None) -> Optional[Dict[str, Any]]:
+    """Update transaction status"""
+    print(f"[REPO] Updating transaction {transaction_id} status to {status}")
+    
+    doc = transactions_col(db).find_one_and_update(
+        {"_id": _to_object_id(transaction_id)},
+        {"$set": {"status": status, "updated_at": _now()}},
+        return_document=ReturnDocument.AFTER,
+        session=session
+    )
+    
+    return _clean_object(doc) if doc else None
+
+
+# ============================================================================
+# PORTFOLIOS
+# ============================================================================
+
+def portfolios_col(db) -> Collection:
+    return db.portfolios
+
+
+def create_or_update_portfolio(db, user_id: str, session=None) -> Dict[str, Any]:
+    """Create or update user portfolio based on investments"""
+    print(f"[REPO] Calculating portfolio for user {user_id}")
+    
+    # Get all user investments
+    investments = get_user_investments(db, user_id)
+    
+    total_invested = sum(inv.get("amount", 0) for inv in investments)
+    total_current_value = 0
+    
+    # Calculate current value based on current token prices
+    for inv in investments:
+        property_obj = get_property_by_id(db, inv["property_id"])
+        if property_obj:
+            current_value = inv.get("tokens_purchased", 0) * property_obj.get("token_price", 0)
+            total_current_value += current_value
+    
+    total_profit = total_current_value - total_invested
+    
+    now = _now()
+    doc = portfolios_col(db).find_one_and_update(
+        {"user_id": _to_object_id(user_id)},
+        {
+            "$set": {
+                "total_invested": total_invested,
+                "total_current_value": total_current_value,
+                "total_profit": total_profit,
+                "updated_at": now
+            },
+            "$setOnInsert": {
+                "created_at": now
+            }
+        },
+        upsert=True,
+        return_document=ReturnDocument.AFTER,
+        session=session
+    )
+    
+    print(f"[REPO] Portfolio updated: invested={total_invested}, current={total_current_value}, profit={total_profit}")
+    return _clean_object(doc)
+
+
+def get_user_portfolio(db, user_id: str) -> Optional[Dict[str, Any]]:
+    """Get user portfolio"""
+    doc = portfolios_col(db).find_one({"user_id": _to_object_id(user_id)})
+    return _clean_object(doc) if doc else None
+
+
+# ============================================================================
+# DOCUMENTS
+# ============================================================================
+
+def documents_col(db) -> Collection:
+    return db.documents
+
+
+def create_document(db, property_id: str, file_type: str, file_url: str, uploaded_by: str) -> Dict[str, Any]:
+    """Create a document record"""
+    print(f"[REPO] Creating document for property {property_id}, type: {file_type}")
+    
+    now = _now()
+    doc = {
+        "property_id": _to_object_id(property_id),
+        "file_type": file_type,
+        "file_url": file_url,
+        "uploaded_by": _coerce_object_id(uploaded_by),
+        "created_at": now,
+        "updated_at": now,
+    }
+    
+    result = documents_col(db).insert_one(doc)
+    doc["_id"] = result.inserted_id
+    
+    return _clean_object(doc)
+
+
+def create_property_documents(db, property_id: str, documents_data: List[Dict[str, str]], uploaded_by: str) -> List[Dict[str, Any]]:
+    """Create multiple documents for a property"""
+    print(f"[REPO] Creating {len(documents_data)} documents for property {property_id}")
+    
+    now = _now()
+    docs = []
+    for doc_data in documents_data:
+        doc = {
+            "property_id": _to_object_id(property_id),
+            "file_type": doc_data.get("file_type", "pdf"),
+            "file_url": doc_data.get("file_url", ""),
+            "uploaded_by": _coerce_object_id(uploaded_by),
+            "created_at": now,
+            "updated_at": now,
+        }
+        docs.append(doc)
+    
+    if docs:
+        result = documents_col(db).insert_many(docs)
+        for i, inserted_id in enumerate(result.inserted_ids):
+            docs[i]["_id"] = inserted_id
+    
+    return [_clean_object(doc) for doc in docs]
+
+
+def get_property_documents(db, property_id: str) -> List[Dict[str, Any]]:
+    """Get all documents for a property"""
+    docs = list(documents_col(db).find({"property_id": _to_object_id(property_id)}))
+    return [_clean_object(doc) for doc in docs]
+
+
+# ============================================================================
+# TRANSACTIONS (MISSING FUNCTIONS)
+# ============================================================================
+
+def list_user_transactions(db, user_id: str, skip: int = 0, limit: int = 100) -> List[Dict[str, Any]]:
+    docs = list(transactions_col(db).find({"user_id": _to_object_id(user_id)}).skip(skip).limit(limit).sort("created_at", DESCENDING))
+    return [_clean_object(d) for d in docs]
+
+
+def list_aed_wallet_transactions(db, user_id: str, limit: int = 50) -> List[Dict[str, Any]]:
+    """List AED wallet add/deduct style transactions stored via insert_transaction wrapper."""
+    # Filter by metadata presence of total_amount_fils OR type in wallet_add/wallet_deduct/investment
+    docs = list(transactions_col(db).find({
+        "user_id": _to_object_id(user_id),
+        "type": {"$in": ["wallet_add", "wallet_deduct", "investment"]}
+    }).sort("created_at", DESCENDING).limit(limit))
+    return [_clean_object(d) for d in docs]
+
+
+def record_admin_wallet_event(
+    db,
+    delta_fils: int,
+    event_type: str,
+    notes: str,
+    *,
+    counterparty_user: Optional[Dict[str, Any]] = None,
+    property_obj: Optional[Dict[str, Any]] = None,
+    payment_method: Optional[str] = None,
+    payment_reference: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    session=None,
+):
+    """Adjust property creator's (admin) AED balance and mirror a transaction record.
+
+    If property_obj is provided, credits the property creator's wallet.
+    Otherwise, credits the primary admin's wallet.
+    Stores admin AED balance in admin's wallet.balance (float AED).
+    Direction inferred from delta.
+    """
+    try:
+        delta = int(delta_fils or 0)
+    except Exception:
+        delta = 0
+
+    # Determine which admin to credit
+    admin_doc = None
+    
+    # If property is provided, credit the property creator
+    if property_obj and property_obj.get('created_by'):
+        admin_doc = get_user_by_id(db, property_obj['created_by'])
+        if admin_doc:
+            logger.info(f"record_admin_wallet_event: crediting property creator {admin_doc.get('email')}")
+    
+    # Fallback to primary admin if no property or creator not found
+    if not admin_doc:
+        admin_doc = get_primary_admin(db, session=session)
+        if admin_doc:
+            logger.info(f"record_admin_wallet_event: crediting primary admin {admin_doc.get('email')}")
+    
+    if not admin_doc:
+        logger.warning("record_admin_wallet_event: no admin user found")
+        return None
+
+    direction = "credit" if delta >= 0 else "debit"
+    amount_abs = abs(delta)
+
+    # Get admin's wallet
+    admin_wallet = None
+    admin_wallet_id = None
+    
+    if delta != 0:
+        # Update the admin's wallet balance instead of user document
+        admin_wallet = wallets_col(db).find_one({"user_id": _to_object_id(admin_doc["id"])})
+        if admin_wallet:
+            admin_wallet_id = str(admin_wallet["_id"])
+            # Convert fils to AED and update wallet balance
+            delta_aed = float(delta) / 100.0
+            wallets_col(db).update_one(
+                {"_id": admin_wallet["_id"]}, 
+                {"$inc": {"balance": delta_aed}},
+                session=session
+            )
+        else:
+            logger.warning(f"record_admin_wallet_event: admin {admin_doc['id']} has no wallet")
+
+    # Build metadata with all transaction details
+    tx_metadata: Dict[str, Any] = {
+        "direction": direction,
+        "notes": notes,
+    }
+    
+    if property_obj:
+        tx_metadata["property_name"] = property_obj.get("title")
+    if counterparty_user:
+        tx_metadata["counterparty_user_id"] = counterparty_user.get("id")
+        if counterparty_user.get("name"):
+            tx_metadata["counterparty_username"] = counterparty_user.get("name")
+        if counterparty_user.get("email"):
+            tx_metadata["counterparty_email"] = counterparty_user.get("email")
+    if payment_method:
+        tx_metadata["payment_method"] = payment_method
+    if payment_reference:
+        tx_metadata["payment_reference"] = payment_reference
+    if metadata:
+        tx_metadata.update(metadata)  # Merge additional metadata
+    
+    # Convert fils to AED for the amount field
+    amount_aed = float(amount_abs) / 100.0
+    
+    tx_data: Dict[str, Any] = {
+        "user_id": admin_doc["id"],
+        "wallet_id": admin_wallet_id,  # Include wallet_id
+        "type": event_type,
+        "amount": amount_aed,  # Include amount in AED
+        "status": "completed",
+        "metadata": tx_metadata,
+    }
+    
+    if property_obj:
+        # property_obj id may be str
+        tx_data["property_id"] = property_obj.get("id")
+
+    return insert_transaction(db, tx_data, session=session)
+
+
+def upsert_token(db, property_id: str, token_data: Dict[str, Any]) -> Dict[str, Any]:
+    """Create or update token record for a property"""
+    print(f"[REPO] Upserting token record for property {property_id}")
+    
+    now = _now()
+    
+    # Use tokens collection
+    tokens_col = db.tokens
+    
+    doc = tokens_col.find_one_and_update(
+        {"property_id": property_id},
+        {
+            "$set": {
+                **token_data,
+                "property_id": property_id,
+                "updated_at": now
+            },
+            "$setOnInsert": {
+                "created_at": now
+            }
+        },
+        upsert=True,
+        return_document=ReturnDocument.AFTER
+    )
+    
+    return _clean_object(doc)
+
+
+def get_property_token(db, property_id: str) -> Optional[Dict[str, Any]]:
+    """Get token information for a property"""
+    tokens_col = db.tokens
+    doc = tokens_col.find_one({"property_id": property_id})
+    return _clean_object(doc) if doc else None
+
+
+# ============================================================================
+# STATISTICS
+# ============================================================================
+
+def get_admin_stats(db) -> Dict[str, Any]:
+    """Get platform statistics for admin dashboard"""
+    print("[REPO] Calculating admin statistics...")
+    
+    stats = {
+        "total_users": users_col(db).count_documents({"deleted": False}),
+        "total_properties": properties_col(db).count_documents({"deleted": False}),
+        "total_investments": investments_col(db).count_documents({}),
+        "active_users": users_col(db).count_documents({"is_active": True, "deleted": False}),
+        "total_tokens_sold": 0,
+        "total_volume": 0.0,
+        "total_revenue": 0.0,
+    }
+    
+    # Calculate total tokens sold and volume
+    pipeline = [
+        {"$group": {
+            "_id": None,
+            "total_tokens": {"$sum": "$tokens_purchased"},
+            "total_amount": {"$sum": "$amount"}
+        }}
+    ]
+    
+    result = list(investments_col(db).aggregate(pipeline))
+    if result:
+        stats["total_tokens_sold"] = result[0].get("total_tokens", 0)
+        stats["total_volume"] = result[0].get("total_amount", 0.0)
+        stats["total_revenue"] = stats["total_volume"] * 0.02  # 2% platform fee
+    
+    print(f"[REPO] Stats calculated: {stats}")
+    return stats
+
+
+def get_admin_specific_stats(db, admin_user_id: str) -> Dict[str, Any]:
+    """Get statistics for a specific admin's properties only"""
+    print(f"[REPO] Calculating admin-specific statistics for admin: {admin_user_id}")
+    
+    admin_oid = _coerce_object_id(admin_user_id)
+    
+    # Get properties created by this admin
+    admin_properties = list(properties_col(db).find({"created_by": admin_oid, "deleted": False}))
+    admin_property_ids = [prop["_id"] for prop in admin_properties]
+    
+    print(f"[REPO] Found {len(admin_property_ids)} properties created by admin")
+    
+    # Get investments for this admin's properties only
+    admin_investments = list(investments_col(db).find({"property_id": {"$in": admin_property_ids}}))
+    
+    # Get unique buyers who invested in this admin's properties
+    unique_buyers = len(set([inv.get("user_id") for inv in admin_investments if inv.get("user_id")]))
+    
+    # Calculate totals
+    total_tokens_sold = sum(inv.get("tokens_purchased", 0) for inv in admin_investments)
+    total_volume = sum(inv.get("amount", 0) for inv in admin_investments)
+    total_revenue = total_volume * 0.02  # 2% platform fee
+    
+    stats = {
+        "total_users": users_col(db).count_documents({"deleted": False}),  # Platform-wide
+        "total_properties": len(admin_property_ids),  # Admin's properties only
+        "total_investments": len(admin_investments),  # Investments in admin's properties
+        "active_users": unique_buyers,  # Buyers who invested in admin's properties
+        "total_tokens_sold": total_tokens_sold,
+        "total_volume": total_volume,
+        "total_revenue": total_revenue,
+    }
+    
+    print(f"[REPO] Admin-specific stats calculated: {stats}")
+    return stats
+
+
+def get_properties_by_creator(db, creator_id: str) -> List[Dict[str, Any]]:
+    """Get all properties created by a specific admin"""
+    creator_oid = _coerce_object_id(creator_id)
+    properties = list(properties_col(db).find({"created_by": creator_oid, "deleted": False}))
+    return [_clean_object(prop) for prop in properties]
+
+
+# ============================================================================
+# RENT DISTRIBUTION OPERATIONS
+# ============================================================================
+
+def rent_distributions_col(db) -> Collection:
+    return db.rent_distributions
+
+
+def rent_payments_col(db) -> Collection:
+    return db.rent_payments
+
+
+def get_investors_by_property(db, property_id: str) -> List[Dict[str, Any]]:
+    """Get all investors (users with investments) for a specific property"""
+    print(f"[REPO] Getting investors for property: {property_id}")
+    
+    property_oid = _to_object_id(property_id)
+    
+    # Find all unique users who have invested in this property
+    pipeline = [
+        {"$match": {"property_id": property_oid}},
+        {"$group": {
+            "_id": "$user_id",
+            "total_tokens": {"$sum": "$tokens_purchased"},
+            "total_invested": {"$sum": "$investment_amount"}
+        }},
+        {"$lookup": {
+            "from": "users",
+            "localField": "_id",
+            "foreignField": "_id",
+            "as": "user_info"
+        }},
+        {"$unwind": "$user_info"},
+        {"$project": {
+            "user_id": "$_id",
+            "tokens_purchased": "$total_tokens",
+            "total_invested": "$total_invested",
+            "wallet_address": "$user_info.wallet_address",
+            "email": "$user_info.email",
+            "name": "$user_info.name"
+        }}
+    ]
+    
+    investors = list(investments_col(db).aggregate(pipeline))
+    
+    # Clean the results
+    result = []
+    for inv in investors:
+        result.append({
+            "user_id": str(inv["user_id"]),
+            "tokens_purchased": inv.get("tokens_purchased", 0),  # Changed from tokens_owned
+            "total_invested": inv.get("total_invested", 0),
+            "wallet_address": inv.get("wallet_address"),
+            "email": inv.get("email"),
+            "name": inv.get("name")
+        })
+    
+    print(f"[REPO] Found {len(result)} investors for property {property_id}")
+    return result
+
+
+def create_rent_distribution(db, property_id: str, total_rent_amount: float, 
+                            rent_period_start: str, rent_period_end: str,
+                            total_tokens: int, rent_per_token: float,
+                            distribution_date: datetime, notes: Optional[str] = None,
+                            session=None) -> Dict[str, Any]:
+    """Create a rent distribution record"""
+    print(f"[REPO] Creating rent distribution for property: {property_id}, amount: {total_rent_amount}")
+    
+    now = _now()
+    doc = {
+        "property_id": _to_object_id(property_id),
+        "total_rent_amount": total_rent_amount,
+        "total_tokens": total_tokens,
+        "rent_per_token": rent_per_token,
+        "rent_period_start": rent_period_start,
+        "rent_period_end": rent_period_end,
+        "distribution_date": distribution_date,
+        "total_investors": 0,
+        "payments_completed": 0,
+        "status": "pending",
+        "notes": notes,
+        "created_at": now,
+        "updated_at": now,
+    }
+    
+    result = rent_distributions_col(db).insert_one(doc, session=session)
+    doc["_id"] = result.inserted_id
+    
+    print(f"[REPO] Rent distribution created with ID: {result.inserted_id}")
+    return _clean_object(doc)
+
+
+def update_rent_distribution_status(db, distribution_id: str, status: str, 
+                                    total_investors: int, payments_completed: int,
+                                    session=None) -> Dict[str, Any]:
+    """Update rent distribution status and counts"""
+    print(f"[REPO] Updating rent distribution {distribution_id}: status={status}, payments={payments_completed}/{total_investors}")
+    
+    updated = rent_distributions_col(db).find_one_and_update(
+        {"_id": _to_object_id(distribution_id)},
+        {
+            "$set": {
+                "status": status,
+                "total_investors": total_investors,
+                "payments_completed": payments_completed,
+                "updated_at": _now(),
+            }
+        },
+        return_document=ReturnDocument.AFTER,
+        session=session
+    )
+    
+    return _clean_object(updated) if updated else None
+
+
+def create_rent_payment(db, distribution_id: str, user_id: str, property_id: str,
+                       tokens_owned: int, rent_amount: float, rent_period_start: str,
+                       rent_period_end: str, payment_status: str = "pending",
+                       wallet_credited: bool = False, transaction_id: Optional[str] = None,
+                       session=None) -> Dict[str, Any]:
+    """Create a rent payment record for a user"""
+    print(f"[REPO] Creating rent payment for user: {user_id}, amount: {rent_amount}")
+    
+    now = _now()
+    doc = {
+        "distribution_id": _to_object_id(distribution_id),
+        "user_id": _to_object_id(user_id),
+        "property_id": _to_object_id(property_id),
+        "tokens_owned": tokens_owned,
+        "rent_amount": rent_amount,
+        "rent_period_start": rent_period_start,
+        "rent_period_end": rent_period_end,
+        "payment_status": payment_status,
+        "wallet_credited": wallet_credited,
+        "transaction_id": _to_object_id(transaction_id) if transaction_id else None,
+        "payment_date": now if payment_status == "completed" else None,
+        "created_at": now,
+    }
+    
+    result = rent_payments_col(db).insert_one(doc, session=session)
+    doc["_id"] = result.inserted_id
+    
+    print(f"[REPO] Rent payment created with ID: {result.inserted_id}")
+    return _clean_object(doc)
+
+
+def get_user_rent_payments(db, user_id: str, property_id: Optional[str] = None) -> List[Dict[str, Any]]:
+    """Get all rent payments for a user, optionally filtered by property"""
+    print(f"[REPO] Getting rent payments for user: {user_id}")
+    
+    query = {"user_id": _to_object_id(user_id)}
+    if property_id:
+        query["property_id"] = _to_object_id(property_id)
+    
+    payments = list(rent_payments_col(db).find(query).sort("payment_date", DESCENDING))
+    return [_clean_object(payment) for payment in payments]
+
+
+def get_rent_distribution_by_id(db, distribution_id: str) -> Optional[Dict[str, Any]]:
+    """Get a rent distribution by ID"""
+    doc = rent_distributions_col(db).find_one({"_id": _to_object_id(distribution_id)})
+    return _clean_object(doc) if doc else None
+
+
+def get_user_rent_summary(db, user_id: str, property_id: str) -> Dict[str, Any]:
+    """Get rent summary for a user's investment in a property"""
+    print(f"[REPO] Getting rent summary for user: {user_id}, property: {property_id}")
+    
+    # Get all rent payments for this user and property
+    payments = get_user_rent_payments(db, user_id, property_id)
+    
+    if not payments:
+        return {
+            "property_id": property_id,
+            "total_rent_received": 0.0,
+            "total_rent_payments": 0,
+            "last_rent_amount": None,
+            "last_rent_date": None,
+            "average_monthly_rent": None,
+        }
+    
+    # Calculate aggregates
+    total_rent = sum(p.get("rent_amount", 0.0) for p in payments if p.get("payment_status") == "completed")
+    completed_payments = [p for p in payments if p.get("payment_status") == "completed"]
+    
+    last_payment = completed_payments[0] if completed_payments else None
+    
+    return {
+        "property_id": property_id,
+        "total_rent_received": total_rent,
+        "total_rent_payments": len(completed_payments),
+        "last_rent_amount": last_payment.get("rent_amount") if last_payment else None,
+        "last_rent_date": last_payment.get("payment_date") if last_payment else None,
+        "average_monthly_rent": total_rent / len(completed_payments) if completed_payments else None,
+    }
+
+
+# =====================================================================
+# SESSION MANAGEMENT
+# =====================================================================
+
+def sessions_col(db):
+    """Get sessions collection"""
+    return db.sessions
+
+
+def create_session(
+    db, 
+    session_id: str, 
+    user_id: str, 
+    device_fingerprint: str, 
+    token: str,
+    expires_at: datetime
+) -> Dict[str, Any]:
+    """
+    Create a new authentication session
+    
+    Args:
+        db: Database connection
+        session_id: Unique session identifier
+        user_id: User's ID
+        device_fingerprint: Device fingerprint hash
+        token: JWT token
+        expires_at: Session expiration timestamp
+    
+    Returns:
+        Created session document
+    """
+    print(f"[REPO] Creating session for user: {user_id}")
+    
+    session_doc = {
+        "session_id": session_id,
+        "user_id": _to_object_id(user_id),
+        "device_fingerprint": device_fingerprint,
+        "token": token,
+        "created_at": _now(),
+        "last_activity": _now(),
+        "expires_at": expires_at,
+        "is_active": True
+    }
+    
+    sessions_col(db).insert_one(session_doc)
+    return _clean_object(session_doc)
+
+
+def get_session_by_id(db, session_id: str) -> Optional[Dict[str, Any]]:
+    """Get session by session_id"""
+    doc = sessions_col(db).find_one({"session_id": session_id, "is_active": True})
+    return _clean_object(doc) if doc else None
+
+
+def get_session_by_token(db, token: str) -> Optional[Dict[str, Any]]:
+    """Get session by JWT token"""
+    doc = sessions_col(db).find_one({"token": token, "is_active": True})
+    return _clean_object(doc) if doc else None
+
+
+def validate_session(
+    db, 
+    session_id: str, 
+    device_fingerprint: str
+) -> bool:
+    """
+    Validate that a session exists and matches the device fingerprint
+    
+    Args:
+        db: Database connection
+        session_id: Session identifier
+        device_fingerprint: Current device fingerprint
+    
+    Returns:
+        True if session is valid, False otherwise
+    """
+    session = get_session_by_id(db, session_id)
+    
+    if not session:
+        print(f"[REPO] Session not found: {session_id}")
+        return False
+    
+    # Check if expired
+    if session.get("expires_at") and session["expires_at"] < _now():
+        print(f"[REPO] Session expired: {session_id}")
+        invalidate_session(db, session_id)
+        return False
+    
+    # Check device fingerprint match
+    if session.get("device_fingerprint") != device_fingerprint:
+        print(f"[REPO] Device fingerprint mismatch for session: {session_id}")
+        return False
+    
+    # Update last activity
+    sessions_col(db).update_one(
+        {"session_id": session_id},
+        {"$set": {"last_activity": _now()}}
+    )
+    
+    return True
+
+
+def invalidate_session(db, session_id: str) -> bool:
+    """Invalidate a session (logout)"""
+    print(f"[REPO] Invalidating session: {session_id}")
+    result = sessions_col(db).update_one(
+        {"session_id": session_id},
+        {"$set": {"is_active": False, "invalidated_at": _now()}}
+    )
+    return result.modified_count > 0
+
+
+def invalidate_user_sessions(db, user_id: str) -> int:
+    """Invalidate all sessions for a user (logout from all devices)"""
+    print(f"[REPO] Invalidating all sessions for user: {user_id}")
+    result = sessions_col(db).update_many(
+        {"user_id": _to_object_id(user_id), "is_active": True},
+        {"$set": {"is_active": False, "invalidated_at": _now()}}
+    )
+    return result.modified_count
+
+
+def get_user_active_sessions(db, user_id: str) -> List[Dict[str, Any]]:
+    """Get all active sessions for a user"""
+    sessions = list(sessions_col(db).find({
+        "user_id": _to_object_id(user_id),
+        "is_active": True
+    }).sort("last_activity", DESCENDING))
+    return [_clean_object(s) for s in sessions]
+
+
+def cleanup_expired_sessions(db) -> int:
+    """Clean up expired sessions (can be run periodically)"""
+    print("[REPO] Cleaning up expired sessions")
+    result = sessions_col(db).update_many(
+        {
+            "expires_at": {"$lt": _now()},
+            "is_active": True
+        },
+        {"$set": {"is_active": False, "invalidated_at": _now()}}
+    )
+    return result.modified_count
+
+
+# ============================================================================
+# SECONDARY MARKET TRANSACTIONS OPERATIONS
+# ============================================================================
+
+def secondary_market_col(db) -> Collection:
+    """Get secondary_market_transactions collection"""
+    return db["secondary_market_transactions"]
+
+
+def create_market_transaction(
+    db,
+    transaction_id: str,
+    transaction_type: str,
+    property_id: str,
+    property_title: str,
+    token_currency: str,
+    seller_id: str,
+    seller_email: str,
+    seller_xrp_address: str,
+    buyer_id: str,
+    buyer_email: str,
+    buyer_xrp_address: str,
+    tokens_amount: int,
+    price_per_token: float,
+    total_amount: float,
+    blockchain_tx_hash: Optional[str] = None,
+    notes: Optional[str] = None,
+    session=None
+) -> Dict[str, Any]:
+    """
+    Create a new secondary market transaction record
+    
+    Args:
+        db: Database instance
+        transaction_id: Unique transaction identifier
+        transaction_type: Type of market transaction (sell_to_admin, etc.)
+        property_id: Property ID
+        property_title: Property title
+        token_currency: Token currency code
+        seller_id: Seller user ID
+        seller_email: Seller email
+        seller_xrp_address: Seller XRP address
+        buyer_id: Buyer user ID (admin for sell_to_admin)
+        buyer_email: Buyer email
+        buyer_xrp_address: Buyer XRP address
+        tokens_amount: Number of tokens traded
+        price_per_token: Price per token
+        total_amount: Total transaction amount
+        blockchain_tx_hash: Blockchain transaction hash
+        notes: Additional notes
+        session: MongoDB session for transactions
+    
+    Returns:
+        Created market transaction document
+    """
+    logger.info(f"[REPO] Creating market transaction: {transaction_id}")
+    
+    market_tx = {
+        "transaction_id": transaction_id,
+        "transaction_type": transaction_type,
+        "status": "completed" if blockchain_tx_hash else "pending",
+        
+        "property_id": _coerce_object_id(property_id),
+        "property_title": property_title,
+        "token_currency": token_currency,
+        
+        "seller_id": _coerce_object_id(seller_id),
+        "seller_email": seller_email,
+        "seller_xrp_address": seller_xrp_address,
+        
+        "buyer_id": _coerce_object_id(buyer_id),
+        "buyer_email": buyer_email,
+        "buyer_xrp_address": buyer_xrp_address,
+        
+        "tokens_amount": tokens_amount,
+        "price_per_token": price_per_token,
+        "total_amount": total_amount,
+        "currency": "AED",
+        
+        "blockchain_tx_hash": blockchain_tx_hash,
+        "blockchain_confirmed": bool(blockchain_tx_hash),
+        "blockchain_confirmed_at": _now() if blockchain_tx_hash else None,
+        
+        "db_investment_updated": False,
+        "db_wallet_updated": False,
+        "db_property_updated": False,
+        "db_transaction_recorded": False,
+        
+        "initiated_at": _now(),
+        "completed_at": _now() if blockchain_tx_hash else None,
+        
+        "notes": notes,
+        "error_message": None
+    }
+    
+    result = secondary_market_col(db).insert_one(market_tx, session=session)
+    market_tx["_id"] = result.inserted_id
+    
+    logger.info(f"[REPO] Market transaction created: {transaction_id}")
+    return _clean_object(market_tx)
+
+
+def update_market_transaction_status(
+    db,
+    transaction_id: str,
+    status: str,
+    blockchain_tx_hash: Optional[str] = None,
+    error_message: Optional[str] = None,
+    db_updates: Optional[Dict[str, bool]] = None,
+    session=None
+) -> Optional[Dict[str, Any]]:
+    """
+    Update market transaction status and details
+    
+    Args:
+        db: Database instance
+        transaction_id: Transaction ID to update
+        status: New status (pending, completed, failed, etc.)
+        blockchain_tx_hash: Blockchain transaction hash
+        error_message: Error message if failed
+        db_updates: Dictionary of database update flags (investment_updated, wallet_updated, etc.)
+        session: MongoDB session for transactions
+    
+    Returns:
+        Updated market transaction document or None
+    """
+    logger.info(f"[REPO] Updating market transaction {transaction_id} to status: {status}")
+    
+    update_fields = {
+        "status": status
+    }
+    
+    if blockchain_tx_hash:
+        update_fields["blockchain_tx_hash"] = blockchain_tx_hash
+        update_fields["blockchain_confirmed"] = True
+        update_fields["blockchain_confirmed_at"] = _now()
+    
+    if error_message:
+        update_fields["error_message"] = error_message
+    
+    if status == "completed":
+        update_fields["completed_at"] = _now()
+    
+    if db_updates:
+        if "investment_updated" in db_updates:
+            update_fields["db_investment_updated"] = db_updates["investment_updated"]
+        if "wallet_updated" in db_updates:
+            update_fields["db_wallet_updated"] = db_updates["wallet_updated"]
+        if "property_updated" in db_updates:
+            update_fields["db_property_updated"] = db_updates["property_updated"]
+        if "transaction_recorded" in db_updates:
+            update_fields["db_transaction_recorded"] = db_updates["transaction_recorded"]
+    
+    result = secondary_market_col(db).find_one_and_update(
+        {"transaction_id": transaction_id},
+        {"$set": update_fields},
+        return_document=ReturnDocument.AFTER,
+        session=session
+    )
+    
+    if result:
+        logger.info(f"[REPO] Market transaction {transaction_id} updated successfully")
+        return _clean_object(result)
+    
+    logger.warning(f"[REPO] Market transaction {transaction_id} not found")
+    return None
+
+
+def get_user_market_history(
+    db,
+    user_id: str,
+    transaction_type: Optional[str] = None,
+    status: Optional[str] = None,
+    limit: int = 100
+) -> List[Dict[str, Any]]:
+    """
+    Get user's secondary market transaction history
+    
+    Args:
+        db: Database instance
+        user_id: User ID
+        transaction_type: Filter by transaction type (optional)
+        status: Filter by status (optional)
+        limit: Maximum number of records to return
+    
+    Returns:
+        List of market transactions
+    """
+    logger.info(f"[REPO] Fetching market history for user: {user_id}")
+    
+    query = {
+        "$or": [
+            {"seller_id": _coerce_object_id(user_id)},
+            {"buyer_id": _coerce_object_id(user_id)}
+        ]
+    }
+    
+    if transaction_type:
+        query["transaction_type"] = transaction_type
+    
+    if status:
+        query["status"] = status
+    
+    transactions = list(
+        secondary_market_col(db)
+        .find(query)
+        .sort("initiated_at", DESCENDING)
+        .limit(limit)
+    )
+    
+    logger.info(f"[REPO] Found {len(transactions)} market transactions for user {user_id}")
+    return [_clean_object(tx) for tx in transactions]
+
+
+def get_property_market_history(
+    db,
+    property_id: str,
+    status: Optional[str] = None,
+    limit: int = 100
+) -> List[Dict[str, Any]]:
+    """
+    Get property's secondary market transaction history
+    
+    Args:
+        db: Database instance
+        property_id: Property ID
+        status: Filter by status (optional)
+        limit: Maximum number of records to return
+    
+    Returns:
+        List of market transactions for the property
+    """
+    logger.info(f"[REPO] Fetching market history for property: {property_id}")
+    
+    query = {"property_id": _coerce_object_id(property_id)}
+    
+    if status:
+        query["status"] = status
+    
+    transactions = list(
+        secondary_market_col(db)
+        .find(query)
+        .sort("initiated_at", DESCENDING)
+        .limit(limit)
+    )
+    
+    logger.info(f"[REPO] Found {len(transactions)} market transactions for property {property_id}")
+    return [_clean_object(tx) for tx in transactions]
+
+
+def get_market_transaction(db, transaction_id: str) -> Optional[Dict[str, Any]]:
+    """
+    Get a specific market transaction by ID
+    
+    Args:
+        db: Database instance
+        transaction_id: Transaction ID
+    
+    Returns:
+        Market transaction document or None
+    """
+    transaction = secondary_market_col(db).find_one({"transaction_id": transaction_id})
+    
+    if transaction:
+        return _clean_object(transaction)
+    
+    return None
+
+
+# ============================================================================
+# CARDS OPERATIONS (Unified for both investor and admin)
+# ============================================================================
+
+def cards_col(db) -> Collection:
+    """Get cards collection (shared for investor and admin)"""
+    return db["cards"]
+
+
+def _detect_card_type(card_number: str) -> str:
+    """Detect card type from card number"""
+    try:
+        if card_number.startswith('4'):
+            return 'visa'
+        elif card_number.startswith(('51', '52', '53', '54', '55')) or (int(card_number[:6]) >= 222100 and int(card_number[:6]) <= 272099):
+            return 'mastercard'
+        elif card_number.startswith(('34', '37')):
+            return 'amex'
+        elif card_number.startswith('6011') or card_number.startswith('65'):
+            return 'discover'
+    except:
+        pass
+    return 'unknown'
+
+
+def create_card(
+    db,
+    user_id: str,
+    user_role: str,  # "investor" or "admin"
+    card_number: str,
+    expiry_month: int,
+    expiry_year: int,
+    cardholder_name: str,
+    bank_name: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Create a new card for user/admin (stores only last 4 digits for security)
+    
+    Args:
+        db: Database instance
+        user_id: User's ID
+        user_role: "investor" or "admin"
+        card_number: Full card number (will only store last 4)
+        expiry_month: Expiry month (1-12)
+        expiry_year: Expiry year (YYYY)
+        cardholder_name: Name on card
+        bank_name: Issuing bank name (optional)
+    
+    Returns:
+        Created card document (secure - no full card number)
+    """
+    logger.info(f"[REPO] Creating card for {user_role} user: {user_id}")
+    
+    # Detect card type from full number
+    card_type = _detect_card_type(card_number)
+    
+    # Store only last 4 digits
+    last_four = card_number[-4:]
+    
+    # Check if card already exists for this user+role
+    existing = cards_col(db).find_one({
+        "user_id": _to_object_id(user_id),
+        "user_role": user_role,
+        "last_four": last_four,
+        "expiry_month": expiry_month,
+        "expiry_year": expiry_year,
+        "is_active": True
+    })
+    
+    if existing:
+        logger.warning(f"[REPO] Card with last four {last_four} already exists for {user_role} {user_id}")
+        raise ValueError("Card already exists")
+    
+    # Check if this should be default (first card for this user+role)
+    existing_count = cards_col(db).count_documents({
+        "user_id": _to_object_id(user_id),
+        "user_role": user_role,
+        "is_active": True
+    })
+    is_default = existing_count == 0
+    
+    now = _now()
+    card_doc = {
+        "user_id": _to_object_id(user_id),
+        "user_role": user_role,
+        "card_type": card_type,
+        "last_four": last_four,
+        "cardholder_name": cardholder_name,
+        "bank_name": bank_name if bank_name else None,
+        "expiry_month": expiry_month,
+        "expiry_year": expiry_year,
+        "is_default": is_default,
+        "is_active": True,
+        "created_at": now,
+        "updated_at": now
+    }
+    
+    result = cards_col(db).insert_one(card_doc)
+    card_doc["_id"] = result.inserted_id
+    
+    logger.info(f"[REPO] Card created with ID: {result.inserted_id}")
+    return _clean_object(card_doc)
+
+
+def get_cards(db, user_id: str, user_role: str) -> List[Dict[str, Any]]:
+    """Get all active cards for a user/admin"""
+    logger.info(f"[REPO] Getting cards for {user_role} user: {user_id}")
+    
+    cards = list(cards_col(db).find({
+        "user_id": _to_object_id(user_id),
+        "user_role": user_role,
+        "is_active": True
+    }).sort("created_at", DESCENDING))
+    
+    return [_clean_object(card) for card in cards]
+
+
+def delete_card(db, user_id: str, user_role: str, card_id: str) -> bool:
+    """Soft delete a user's/admin's card"""
+    logger.info(f"[REPO] Deleting card {card_id} for {user_role} user {user_id}")
+    
+    result = cards_col(db).update_one(
+        {
+            "_id": _to_object_id(card_id),
+            "user_id": _to_object_id(user_id),
+            "user_role": user_role
+        },
+        {"$set": {"is_active": False, "updated_at": _now()}}
+    )
+    
+    if result.modified_count > 0:
+        # If deleted card was default, set another card as default
+        deleted_card = cards_col(db).find_one({"_id": _to_object_id(card_id)})
+        if deleted_card and deleted_card.get("is_default"):
+            next_card = cards_col(db).find_one({
+                "user_id": _to_object_id(user_id),
+                "user_role": user_role,
+                "is_active": True
+            })
+            if next_card:
+                cards_col(db).update_one(
+                    {"_id": next_card["_id"]},
+                    {"$set": {"is_default": True}}
+                )
+    
+    return result.modified_count > 0
+
+
+def set_default_card(db, user_id: str, user_role: str, card_id: str) -> bool:
+    """Set a card as the default payment method"""
+    logger.info(f"[REPO] Setting card {card_id} as default for {user_role} user {user_id}")
+    
+    # Unset current default for this user+role
+    cards_col(db).update_many(
+        {"user_id": _to_object_id(user_id), "user_role": user_role, "is_default": True},
+        {"$set": {"is_default": False}}
+    )
+    
+    # Set new default
+    result = cards_col(db).update_one(
+        {
+            "_id": _to_object_id(card_id),
+            "user_id": _to_object_id(user_id),
+            "user_role": user_role,
+            "is_active": True
+        },
+        {"$set": {"is_default": True}}
+    )
+    
+    return result.modified_count > 0
+
+
+# Legacy aliases for backward compatibility
+def create_user_card(db, user_id, card_number, expiry_month, expiry_year, cardholder_name, bank_name=None):
+    return create_card(db, user_id, "investor", card_number, expiry_month, expiry_year, cardholder_name, bank_name)
+
+def get_user_cards(db, user_id):
+    return get_cards(db, user_id, "investor")
+
+def delete_user_card(db, user_id, card_id):
+    return delete_card(db, user_id, "investor", card_id)
+
+
+# ============================================================================
+# BANKS OPERATIONS (Unified for both investor and admin)
+# ============================================================================
+
+def banks_col(db) -> Collection:
+    """Get banks collection (shared for investor and admin)"""
+    return db["banks"]
+
+
+def create_bank(
+    db,
+    user_id: str,
+    user_role: str,  # "investor" or "admin"
+    bank_name: str,
+    account_holder_name: str,
+    account_number: str,
+    account_type: str = "savings",
+    iban: Optional[str] = None,
+    swift_code: Optional[str] = None,
+    currency: str = "AED"
+) -> Dict[str, Any]:
+    """
+    Create a new bank account for user/admin (stores only last 4 digits of account number)
+    
+    Args:
+        db: Database instance
+        user_id: User's ID
+        user_role: "investor" or "admin"
+        bank_name: Bank name
+        account_holder_name: Account holder name
+        account_number: Full account number (will store last 4 digits securely)
+        account_type: Account type (savings, current, business)
+        iban: IBAN (optional)
+        swift_code: SWIFT code (optional)
+        currency: Currency code (default AED)
+    
+    Returns:
+        Created bank document (secure - masked account number)
+    """
+    logger.info(f"[REPO] Creating bank account for {user_role} user: {user_id}")
+    
+    # Store last 4 digits for display
+    account_number_last_four = account_number[-4:]
+    iban_last_four = iban[-4:] if iban else None
+    
+    # Check if bank already exists for this user+role
+    existing = banks_col(db).find_one({
+        "user_id": _to_object_id(user_id),
+        "user_role": user_role,
+        "account_number_last_four": account_number_last_four,
+        "bank_name": bank_name,
+        "is_active": True
+    })
+    
+    if existing:
+        logger.warning(f"[REPO] Bank account already exists for {user_role} user {user_id}")
+        raise ValueError("Bank account already exists")
+    
+    # Check if this should be default (first bank for this user+role)
+    existing_count = banks_col(db).count_documents({
+        "user_id": _to_object_id(user_id),
+        "user_role": user_role,
+        "is_active": True
+    })
+    is_default = existing_count == 0
+    
+    now = _now()
+    bank_doc = {
+        "user_id": _to_object_id(user_id),
+        "user_role": user_role,
+        "bank_name": bank_name,
+        "account_holder_name": account_holder_name,
+        "account_number_last_four": account_number_last_four,
+        "account_number_encrypted": account_number,  # In production, encrypt this
+        "iban_last_four": iban_last_four if iban_last_four else None,
+        "iban_encrypted": iban if iban else None,  # In production, encrypt this
+        "swift_code": swift_code if swift_code else None,
+        "account_type": account_type,
+        "currency": currency,
+        "is_default": is_default,
+        "is_verified": False,  # Can be verified via microdeposits
+        "is_active": True,
+        "created_at": now,
+        "updated_at": now
+    }
+    
+    result = banks_col(db).insert_one(bank_doc)
+    bank_doc["_id"] = result.inserted_id
+    
+    # Remove encrypted fields from return value
+    bank_doc.pop("account_number_encrypted", None)
+    bank_doc.pop("iban_encrypted", None)
+    
+    # Remove None values for cleaner output
+    bank_doc = {k: v for k, v in bank_doc.items() if v is not None}
+    
+    logger.info(f"[REPO] Bank account created with ID: {result.inserted_id}")
+    return _clean_object(bank_doc)
+
+
+def get_banks(db, user_id: str, user_role: str) -> List[Dict[str, Any]]:
+    """Get all active bank accounts for a user/admin"""
+    logger.info(f"[REPO] Getting bank accounts for {user_role} user: {user_id}")
+    
+    banks = list(banks_col(db).find({
+        "user_id": _to_object_id(user_id),
+        "user_role": user_role,
+        "is_active": True
+    }).sort("created_at", DESCENDING))
+    
+    # Remove encrypted fields and None values from output
+    result = []
+    for bank in banks:
+        bank_clean = _clean_object(bank)
+        bank_clean.pop("account_number_encrypted", None)
+        bank_clean.pop("iban_encrypted", None)
+        # Remove None values
+        bank_clean = {k: v for k, v in bank_clean.items() if v is not None}
+        result.append(bank_clean)
+    
+    return result
+
+
+def delete_bank(db, user_id: str, user_role: str, bank_id: str) -> bool:
+    """Soft delete a user's/admin's bank account"""
+    logger.info(f"[REPO] Deleting bank {bank_id} for {user_role} user {user_id}")
+    
+    result = banks_col(db).update_one(
+        {
+            "_id": _to_object_id(bank_id),
+            "user_id": _to_object_id(user_id),
+            "user_role": user_role
+        },
+        {"$set": {"is_active": False, "updated_at": _now()}}
+    )
+    
+    if result.modified_count > 0:
+        # If deleted bank was default, set another bank as default
+        deleted_bank = banks_col(db).find_one({"_id": _to_object_id(bank_id)})
+        if deleted_bank and deleted_bank.get("is_default"):
+            next_bank = banks_col(db).find_one({
+                "user_id": _to_object_id(user_id),
+                "user_role": user_role,
+                "is_active": True
+            })
+            if next_bank:
+                banks_col(db).update_one(
+                    {"_id": next_bank["_id"]},
+                    {"$set": {"is_default": True}}
+                )
+    
+    return result.modified_count > 0
+
+
+def set_default_bank(db, user_id: str, user_role: str, bank_id: str) -> bool:
+    """Set a bank account as the default for withdrawals"""
+    logger.info(f"[REPO] Setting bank {bank_id} as default for {user_role} user {user_id}")
+    
+    # Unset current default for this user+role
+    banks_col(db).update_many(
+        {"user_id": _to_object_id(user_id), "user_role": user_role, "is_default": True},
+        {"$set": {"is_default": False}}
+    )
+    
+    # Set new default
+    result = banks_col(db).update_one(
+        {
+            "_id": _to_object_id(bank_id),
+            "user_id": _to_object_id(user_id),
+            "user_role": user_role,
+            "is_active": True
+        },
+        {"$set": {"is_default": True}}
+    )
+    
+    return result.modified_count > 0
+
+
+# Legacy aliases for backward compatibility
+def create_user_bank(db, user_id, bank_name, account_holder_name, account_number, account_type="savings", iban=None, swift_code=None, currency="AED"):
+    return create_bank(db, user_id, "investor", bank_name, account_holder_name, account_number, account_type, iban, swift_code, currency)
+
+def get_user_banks(db, user_id):
+    return get_banks(db, user_id, "investor")
+
+def delete_user_bank(db, user_id, bank_id):
+    return delete_bank(db, user_id, "investor", bank_id)
+

repo_otp.py

@@ -0,0 +1,185 @@
+"""
+OTP Repository Layer
+Handles OTP storage and verification in MongoDB
+"""
+from datetime import datetime
+from typing import Optional, Dict, Any
+from pymongo.collection import Collection
+from bson import ObjectId
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def _now():
+    """Get current UTC timestamp"""
+    return datetime.utcnow()
+
+
+def _clean_object(data):
+    """Clean MongoDB object by converting ObjectId to string"""
+    if isinstance(data, dict):
+        cleaned = {}
+        for key, value in data.items():
+            if key == "_id":
+                cleaned["id"] = str(value) if isinstance(value, ObjectId) else value
+            else:
+                cleaned[key] = value
+        return cleaned
+    return data
+
+
+def otps_col(db) -> Collection:
+    """Get OTPs collection"""
+    return db.otps
+
+
+def create_otp(db, email: str, otp: str, purpose: str, expires_at: datetime) -> Dict[str, Any]:
+    """
+    Create or update OTP record for an email
+    
+    Args:
+        db: Database connection
+        email: User email
+        otp: 6-digit OTP code
+        purpose: 'login' or 'registration'
+        expires_at: Expiry datetime
+    
+    Returns:
+        OTP document
+    """
+    logger.info(f"[OTP_REPO] Creating OTP for {email}, purpose: {purpose}")
+    
+    now = _now()
+    
+    # Delete any existing OTPs for this email and purpose
+    otps_col(db).delete_many({"email": email, "purpose": purpose})
+    
+    doc = {
+        "email": email,
+        "otp": otp,
+        "purpose": purpose,
+        "expires_at": expires_at,
+        "verified": False,
+        "attempts": 0,
+        "created_at": now,
+        "updated_at": now,
+    }
+    
+    result = otps_col(db).insert_one(doc)
+    doc["_id"] = result.inserted_id
+    
+    logger.info(f"[OTP_REPO] [SUCCESS] OTP created with ID: {result.inserted_id}")
+    return _clean_object(doc)
+
+
+def get_otp(db, email: str, purpose: str) -> Optional[Dict[str, Any]]:
+    """
+    Get active OTP for email and purpose
+    
+    Args:
+        db: Database connection
+        email: User email
+        purpose: 'login' or 'registration'
+    
+    Returns:
+        OTP document if found and not expired, None otherwise
+    """
+    doc = otps_col(db).find_one({
+        "email": email,
+        "purpose": purpose,
+        "verified": False,
+        "expires_at": {"$gt": _now()}
+    })
+    
+    return _clean_object(doc) if doc else None
+
+
+def verify_otp(db, email: str, otp: str, purpose: str) -> tuple[bool, str]:
+    """
+    Verify OTP code
+    
+    Args:
+        db: Database connection
+        email: User email
+        otp: OTP code to verify
+        purpose: 'login' or 'registration'
+    
+    Returns:
+        tuple: (success: bool, message: str)
+    """
+    logger.info(f"[OTP_REPO] Verifying OTP for {email}, purpose: {purpose}")
+    
+    # Get OTP record
+    otp_doc = get_otp(db, email, purpose)
+    
+    if not otp_doc:
+        logger.warning(f"[OTP_REPO] [ERROR] No valid OTP found for {email}")
+        return False, "OTP expired or not found. Please request a new one."
+    
+    # Check if max attempts exceeded (5 attempts)
+    if otp_doc.get("attempts", 0) >= 5:
+        logger.warning(f"[OTP_REPO] [ERROR] Max attempts exceeded for {email}")
+        # Delete the OTP
+        otps_col(db).delete_one({"_id": ObjectId(otp_doc["id"])})
+        return False, "Maximum verification attempts exceeded. Please request a new OTP."
+    
+    # Increment attempts
+    otps_col(db).update_one(
+        {"_id": ObjectId(otp_doc["id"])},
+        {
+            "$inc": {"attempts": 1},
+            "$set": {"updated_at": _now()}
+        }
+    )
+    
+    # Verify OTP
+    if otp_doc["otp"] != otp:
+        remaining = 5 - (otp_doc.get("attempts", 0) + 1)
+        logger.warning(f"[OTP_REPO] [ERROR] Invalid OTP for {email}. {remaining} attempts remaining")
+        return False, f"Invalid OTP code. {remaining} attempts remaining."
+    
+    # Mark as verified
+    otps_col(db).update_one(
+        {"_id": ObjectId(otp_doc["id"])},
+        {
+            "$set": {
+                "verified": True,
+                "verified_at": _now(),
+                "updated_at": _now()
+            }
+        }
+    )
+    
+    logger.info(f"[OTP_REPO] [SUCCESS] OTP verified successfully for {email}")
+    return True, "OTP verified successfully"
+
+
+def delete_otp(db, email: str, purpose: str) -> bool:
+    """
+    Delete OTP record
+    
+    Args:
+        db: Database connection
+        email: User email
+        purpose: 'login' or 'registration'
+    
+    Returns:
+        bool: True if deleted, False otherwise
+    """
+    result = otps_col(db).delete_many({"email": email, "purpose": purpose})
+    logger.info(f"[OTP_REPO] Deleted {result.deleted_count} OTP(s) for {email}")
+    return result.deleted_count > 0
+
+
+def cleanup_expired_otps(db) -> int:
+    """
+    Clean up expired OTPs (run periodically)
+    
+    Returns:
+        int: Number of deleted OTPs
+    """
+    result = otps_col(db).delete_many({"expires_at": {"$lt": _now()}})
+    if result.deleted_count > 0:
+        logger.info(f"[OTP_REPO] Cleaned up {result.deleted_count} expired OTP(s)")
+    return result.deleted_count

requirements.txt

@@ -0,0 +1,73 @@
+# =============================================================================
+# AtriumChain Platform - Backend Python Requirements
+# Real Estate Tokenization Platform using XRP Ledger
+# =============================================================================
+# 
+# Installation:
+#   cd backend
+#   python -m venv .venv
+#   source .venv/bin/activate  (Linux/Mac) or .venv\Scripts\activate (Windows)
+#   pip install -r requirements.txt
+#
+# Python Version: 3.10+
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Core Web Framework & Server
+# -----------------------------------------------------------------------------
+fastapi==0.112.2
+uvicorn[standard]==0.30.6
+python-multipart==0.0.9
+
+# -----------------------------------------------------------------------------
+# Database (MongoDB)
+# -----------------------------------------------------------------------------
+pymongo==4.8.0
+dnspython==2.6.1
+
+# -----------------------------------------------------------------------------
+# Data Validation & Settings
+# -----------------------------------------------------------------------------
+pydantic==2.9.2
+pydantic-settings==2.4.0
+email-validator==2.1.0
+
+# -----------------------------------------------------------------------------
+# Authentication & Security
+# -----------------------------------------------------------------------------
+python-jose[cryptography]==3.3.0
+passlib[bcrypt]==1.7.4
+bcrypt==4.1.1
+cryptography==43.0.1
+bleach==6.1.0
+
+# -----------------------------------------------------------------------------
+# XRP Ledger Blockchain Integration
+# -----------------------------------------------------------------------------
+xrpl-py==3.0.0
+
+# -----------------------------------------------------------------------------
+# HTTP Requests (for IPFS, external APIs)
+# -----------------------------------------------------------------------------
+requests>=2.31.0
+
+# -----------------------------------------------------------------------------
+# Rate Limiting & Performance
+# -----------------------------------------------------------------------------
+slowapi==0.1.9
+psutil>=5.9.8
+
+# -----------------------------------------------------------------------------
+# Environment Configuration
+# -----------------------------------------------------------------------------
+python-dotenv==1.0.0
+
+# -----------------------------------------------------------------------------
+# Optional: Redis (for caching - uncomment if using)
+# -----------------------------------------------------------------------------
+# redis==5.0.1
+
+# -----------------------------------------------------------------------------
+# Optional: IPFS Client (uncomment if using local IPFS node)
+# -----------------------------------------------------------------------------
+# ipfshttpclient>=0.8.0a2

routes/admin.py

@@ -0,0 +1,60 @@
+"""
+Production Admin Routes - Main Router
+Admin-only endpoints for platform management with security enhancements
+
+This file serves as the main router that imports and includes all admin sub-routers:
+- admin_properties: Property CRUD operations
+- admin_users: User management endpoints  
+- admin_analytics: Stats, analytics, investments, transactions
+- admin_wallet: Wallet info, connect, cards, banks, deposit/withdraw
+- admin_tokenization: Property tokenization status
+- admin_kyc: KYC document management and blockchain integration
+- admin_rent: Rent distribution to token holders
+"""
+from fastapi import APIRouter
+
+router = APIRouter()
+
+# ============================================================================
+# INCLUDE SUB-ROUTERS FOR MODULAR ORGANIZATION
+# ============================================================================
+
+# Properties: create_property, update_property
+from routes.admin_properties import router as properties_router
+router.include_router(properties_router, tags=["Admin - Properties"])
+
+# Users: list/create/update/delete users, user transactions, user wallet
+from routes.admin_users import router as users_router
+router.include_router(users_router, tags=["Admin - Users"])
+
+# Analytics & Stats: admin stats, analytics, investments listing, transactions
+from routes.admin_analytics import router as analytics_router
+router.include_router(analytics_router, tags=["Admin - Analytics"])
+
+# Wallet: wallet info, connect wallet, cards, banks, deposit/withdraw
+from routes.admin_wallet import router as wallet_router
+router.include_router(wallet_router, tags=["Admin - Wallet"])
+
+# Tokenization: property tokenization status
+from routes.admin_tokenization import router as tokenization_router
+router.include_router(tokenization_router, tags=["Admin - Tokenization"])
+
+# KYC: pending KYC, approve/reject, blockchain records
+from routes.admin_kyc import router as kyc_router
+router.include_router(kyc_router, tags=["Admin - KYC"])
+
+# Rent Distribution: distribute rent, rent history
+from routes.admin_rent import router as rent_router
+router.include_router(rent_router, tags=["Admin - Rent Distribution"])
+
+# ============================================================================
+# All admin endpoints are now organized in the following sub-modules:
+# 
+# routes/admin_properties.py - Property CRUD (create, update)
+# routes/admin_users.py - User management (list, create, update, delete, transactions, wallet)
+# routes/admin_analytics.py - Stats, analytics, investments, transactions
+# routes/admin_wallet.py - Wallet info, connect, cards, banks, deposit/withdraw
+# routes/admin_tokenization.py - Property tokenization status
+# routes/admin_kyc.py - KYC management (pending, approve, reject, blockchain records)
+# routes/admin_rent.py - Rent distribution (distribute, history)
+# ============================================================================

routes/admin_analytics.py

@@ -0,0 +1,191 @@
+"""
+Admin Analytics and Stats Routes
+Endpoints for platform statistics, analytics, investments listing, and transactions
+"""
+from fastapi import APIRouter, Depends, HTTPException, status
+from typing import List, Dict, Any
+from bson import ObjectId
+
+import schemas
+import repo
+from db import get_mongo
+from routes.auth import get_current_admin
+
+router = APIRouter()
+
+
+# ============================================================================
+# ADMIN STATS & ANALYTICS
+# ============================================================================
+
+@router.get("/admin/stats", response_model=schemas.AdminStatsOut)
+def get_admin_stats(db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Get platform statistics (Admin only). Returns comprehensive metrics for the admin dashboard."""
+    print(f"\n[ADMIN] Fetching platform stats - Requested by: {admin_user['email']}")
+    
+    stats = repo.get_admin_stats(db)
+    
+    print(f"[ADMIN] [SUCCESS] Stats retrieved: Users={stats['total_users']}, Properties={stats['total_properties']}")
+    return schemas.AdminStatsOut(**stats)
+
+
+@router.get("/admin/analytics")
+def get_admin_analytics(db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Get comprehensive admin analytics (Admin only). Returns data ONLY for properties created by the current admin."""
+    print(f"\n[ADMIN] Fetching analytics - Requested by: {admin_user['email']}")
+    
+    stats = repo.get_admin_specific_stats(db, admin_user['id'])
+    admin_properties = repo.get_properties_by_creator(db, admin_user['id'])
+    property_performance = []
+    
+    for prop in admin_properties:
+        try:
+            prop_oid = ObjectId(prop["id"])
+        except:
+            prop_oid = prop["id"]
+        
+        investments = list(db.investments.find({"property_id": prop_oid}))
+        tokens_sold = sum(inv.get("tokens_purchased", 0) for inv in investments)
+        revenue = sum(inv.get("amount", 0) for inv in investments)
+        
+        property_performance.append({
+            "property_id": prop["id"],
+            "property_name": prop.get("title", prop.get("name", "Unknown")),
+            "tokens_sold": tokens_sold,
+            "revenue": revenue,
+            "transaction_count": len(investments)
+        })
+    
+    analytics = {
+        "total_users": stats["total_users"],
+        "total_properties": stats["total_properties"],
+        "total_investments": stats["total_investments"],
+        "total_volume": stats["total_volume"],
+        "total_revenue": stats["total_revenue"],
+        "active_users": stats["active_users"],
+        "total_tokens_sold": stats["total_tokens_sold"],
+        "property_performance": property_performance,
+        "user_stats": {"total_users": stats["total_users"], "active_buyers": stats["active_users"], "conversion_rate": (stats["active_users"] / stats["total_users"] * 100) if stats["total_users"] > 0 else 0},
+        "property_stats": {"total_properties": stats["total_properties"], "tokens_sold": stats["total_tokens_sold"]},
+        "sales_stats": {"total_revenue_aed": stats["total_volume"], "total_tokens_sold": stats["total_tokens_sold"]}
+    }
+    
+    return analytics
+
+
+# ============================================================================
+# INVESTMENTS LISTING
+# ============================================================================
+
+@router.get("/admin/investments", response_model=List[schemas.InvestmentOut])
+def list_all_investments(property_id: str = None, skip: int = 0, limit: int = 100, db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """List all investments for properties created by this admin (Admin only). Optionally filter by property_id."""
+    print(f"\n[ADMIN] Listing investments - Requested by: {admin_user['email']}")
+    
+    admin_properties = repo.get_properties_by_creator(db, admin_user['id'])
+    admin_property_ids = [ObjectId(prop["id"]) for prop in admin_properties]
+    
+    query_filter = {"property_id": {"$in": admin_property_ids}}
+    
+    if property_id:
+        prop_oid = ObjectId(property_id)
+        if prop_oid not in admin_property_ids:
+            return []
+        query_filter['property_id'] = prop_oid
+    
+    investments = list(db.investments.find(query_filter).skip(skip).limit(limit).sort("created_at", -1))
+    
+    enriched_investments = []
+    for inv in investments:
+        cleaned_inv = repo._clean_object(inv)
+        user_id = inv.get("user_id")
+        prop_id = inv.get("property_id")
+        
+        admin_tx = db.transactions.find_one({"type": "admin_wallet_credit_purchase", "property_id": prop_id, "metadata.counterparty_user_id": str(user_id)})
+        
+        if admin_tx and admin_tx.get("metadata"):
+            meta = admin_tx["metadata"]
+            cleaned_inv["user_name"] = meta.get("counterparty_username", "Unknown")
+            cleaned_inv["user_email"] = meta.get("counterparty_email", "")
+        else:
+            user = db.users.find_one({"_id": user_id})
+            cleaned_inv["user_name"] = user.get("name", "Unknown") if user else "Unknown"
+            cleaned_inv["user_email"] = user.get("email", "") if user else ""
+        
+        enriched_investments.append(cleaned_inv)
+    
+    return [schemas.InvestmentOut(**inv) for inv in enriched_investments]
+
+
+@router.get("/admin/all-investments")
+def get_all_investments(skip: int = 0, limit: int = 100, admin_user=Depends(get_current_admin)):
+    """Get all investments with user and property details (Admin only)."""
+    from db import get_db
+    db = get_db()
+    
+    investments = list(db.investments.find().skip(skip).limit(limit).sort("created_at", -1))
+    enriched = []
+    
+    for inv in investments:
+        cleaned = repo._clean_object(inv)
+        user = db.users.find_one({"_id": inv.get("user_id")})
+        prop = db.properties.find_one({"_id": inv.get("property_id")})
+        
+        cleaned["user_name"] = user.get("name") if user else "Unknown"
+        cleaned["user_email"] = user.get("email") if user else ""
+        cleaned["property_name"] = prop.get("title") if prop else "Unknown"
+        
+        enriched.append(cleaned)
+    
+    return enriched
+
+
+# ============================================================================
+# TRANSACTIONS LISTING
+# ============================================================================
+
+@router.get("/admin/transactions", response_model=List[schemas.TransactionOut])
+def list_all_transactions(skip: int = 0, limit: int = 100, db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """List all transactions for properties created by this admin (Admin only)."""
+    print(f"\n[ADMIN] Listing transactions - Requested by: {admin_user['email']}")
+    
+    admin_properties = repo.get_properties_by_creator(db, admin_user['id'])
+    admin_property_ids = [ObjectId(prop["id"]) for prop in admin_properties]
+    
+    query_filter = {
+        "$or": [
+            {"property_id": {"$in": admin_property_ids}},
+            {"user_id": repo._to_object_id(admin_user['id']), "type": {"$regex": "^admin_wallet_"}}
+        ]
+    }
+    
+    transactions = list(db.transactions.find(query_filter).skip(skip).limit(limit).sort("created_at", -1))
+    cleaned_transactions = [repo._clean_object(tx) for tx in transactions]
+    
+    return [schemas.TransactionOut(**tx) for tx in cleaned_transactions]
+
+
+@router.post("/admin/wallet/{user_id}/adjust", response_model=schemas.WalletOut)
+def adjust_user_wallet(user_id: str, amount: float, operation: str, db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Adjust user wallet balance (Admin only). Used for refunds, bonuses, or corrections."""
+    print(f"\n[ADMIN] Adjusting wallet for user {user_id}, {operation} {amount} AED")
+    
+    if operation not in ["add", "subtract"]:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Operation must be 'add' or 'subtract'")
+    
+    if amount <= 0:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Amount must be positive")
+    
+    user = repo.get_user_by_id(db, user_id)
+    if not user:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+    
+    wallet = repo.get_wallet_by_user(db, user_id)
+    if not wallet:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Wallet not found")
+    
+    updated_wallet = repo.update_wallet_balance(db, wallet['id'], amount, operation=operation)
+    
+    repo.create_transaction(db, user_id=user_id, wallet_id=wallet['id'], tx_type="deposit" if operation == "add" else "withdrawal", amount=amount, status="completed", metadata={"admin_adjustment": True, "admin_user_id": admin_user['id'], "admin_email": admin_user['email'], "reason": "Admin wallet adjustment"})
+    
+    return schemas.WalletOut(**updated_wallet)

routes/admin_kyc.py

@@ -0,0 +1,276 @@
+"""
+Admin KYC Management Routes
+Endpoints for KYC document review, approval, rejection, and blockchain records
+"""
+from fastapi import APIRouter, Depends, HTTPException, status, Body
+from typing import List, Dict, Any
+from datetime import datetime
+from bson import ObjectId
+import base64
+
+import schemas
+import repo
+from db import get_mongo
+from routes.auth import get_current_admin
+from config import settings
+from utils.crypto_utils import decrypt_secret
+
+router = APIRouter()
+
+
+# ============================================================================
+# KYC MANAGEMENT ENDPOINTS
+# ============================================================================
+
+@router.get("/admin/kyc/count")
+def get_pending_kyc_count(db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Return count of pending KYC submissions"""
+    pending_count = db.kyc_documents.count_documents({"status": "pending"})
+    return {"count": int(pending_count)}
+
+
+@router.get("/admin/kyc/pending")
+def get_pending_kyc(db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Get all pending KYC documents for review"""
+    print(f"\n[ADMIN-KYC] Fetching pending KYC documents - Requested by: {admin_user['email']}")
+    
+    kyc_docs = list(db.kyc_documents.find({"status": "pending"}).sort("uploaded_at", -1))
+    
+    result = []
+    for doc in kyc_docs:
+        user = repo.get_user_by_id(db, str(doc["user_id"]))
+        result.append({
+            "id": str(doc["_id"]),
+            "document_id": str(doc["_id"]),
+            "user_id": str(doc["user_id"]),
+            "user_name": user.get("name") if user else "Unknown",
+            "user_email": user.get("email") if user else "Unknown",
+            "full_name": doc.get("full_name"),
+            "date_of_birth": doc.get("date_of_birth"),
+            "gender": doc.get("gender"),
+            "address": doc.get("address"),
+            "document_url": doc.get("document_url"),
+            "file_size": doc.get("file_size"),
+            "content_type": doc.get("content_type"),
+            "status": doc.get("status"),
+            "uploaded_at": doc.get("uploaded_at")
+        })
+    
+    print(f"[ADMIN-KYC] Found {len(result)} pending KYC documents\n")
+    return {"total": len(result), "pending_kyc": result}
+
+
+@router.post("/admin/kyc/{document_id}/approve")
+async def approve_kyc(document_id: str, db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """
+    Approve KYC document and write to blockchain (IPFS + XRP Ledger)
+    
+    This triggers the hybrid decentralized storage:
+    1. Upload KYC document to IPFS
+    2. Write user data + IPFS hash to XRP Ledger memo
+    3. Store blockchain proof in database
+    """
+    print(f"\n[ADMIN-KYC] APPROVING KYC DOCUMENT: {document_id}")
+    
+    from services.ipfs_service import ipfs_service
+    from services.xrp_service import xrpl_service
+    
+    kyc_doc = db.kyc_documents.find_one({"_id": repo._to_object_id(document_id)})
+    
+    if not kyc_doc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="KYC document not found")
+    
+    if kyc_doc.get('status') == 'approved':
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="KYC already approved")
+    
+    user_id = str(kyc_doc.get('user_id'))
+    user = repo.get_user_by_id(db, user_id)
+    
+    if not user:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+    
+    # STEP 1: UPLOAD TO IPFS
+    document_url = kyc_doc.get('document_url')
+    if not document_url or not document_url.startswith('data:'):
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Invalid document data")
+    
+    parts = document_url.split(',', 1)
+    if len(parts) != 2:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Invalid document data URL format")
+    
+    base64_data = parts[1]
+    content_type = kyc_doc.get('content_type', 'application/octet-stream')
+    file_bytes = base64.b64decode(base64_data)
+    file_ext = 'pdf' if 'pdf' in content_type else 'jpg'
+    filename = f"kyc_{user_id}_{document_id}.{file_ext}"
+    
+    try:
+        ipfs_result = ipfs_service.upload_file(file_bytes, filename, content_type)
+    except Exception as ipfs_error:
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"IPFS upload exception: {str(ipfs_error)}")
+    
+    if not ipfs_result.get('success'):
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"IPFS upload failed: {ipfs_result.get('error')}")
+    
+    ipfs_cid = ipfs_result.get('cid')
+    ipfs_url = ipfs_result.get('url')
+    ipfs_hash = ipfs_result.get('hash')
+    
+    # STEP 2: WRITE TO BLOCKCHAIN
+    now = datetime.utcnow().isoformat()
+    kyc_blockchain_data = {
+        'user_id': user_id,
+        'name': kyc_doc.get('full_name') or user.get('name'),
+        'email': user.get('email'),
+        'phone': user.get('phone') or 'N/A',
+        'address': kyc_doc.get('address') or 'N/A',
+        'ipfs_hash': ipfs_cid,
+        'approved_by': admin_user.get('email'),
+        'approved_at': now
+    }
+    
+    admin_wallet = repo.get_wallet_by_user(db, admin_user['id'])
+    if not admin_wallet or not admin_wallet.get('xrp_seed'):
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Admin XRP wallet not connected")
+    
+    try:
+        if settings.encryption_enabled():
+            admin_xrp_seed = decrypt_secret(admin_wallet.get('xrp_seed'), settings.ENCRYPTION_KEY)
+        else:
+            admin_xrp_seed = base64.b64decode(admin_wallet.get('xrp_seed')).decode()
+    except Exception:
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to decrypt admin wallet seed")
+    
+    try:
+        blockchain_result = await xrpl_service.write_kyc_to_blockchain(kyc_blockchain_data, issuer_seed=admin_xrp_seed)
+    except Exception as blockchain_error:
+        blockchain_result = {'success': False, 'error': str(blockchain_error)}
+    
+    blockchain_tx_hash = blockchain_result.get('tx_hash')
+    blockchain_explorer_url = blockchain_result.get('explorer_url')
+    
+    # STEP 3: UPDATE DATABASE
+    db.kyc_documents.update_one(
+        {"_id": repo._to_object_id(document_id)},
+        {"$set": {
+            "status": "approved",
+            "reviewed_at": datetime.utcnow(),
+            "reviewed_by": admin_user.get('id'),
+            "ipfs_cid": ipfs_cid,
+            "ipfs_url": ipfs_url,
+            "ipfs_hash": ipfs_hash,
+            "blockchain_tx_hash": blockchain_tx_hash,
+            "blockchain_explorer_url": blockchain_explorer_url,
+            "blockchain_success": blockchain_result.get('success', False)
+        }}
+    )
+    
+    repo.update_user(db, user_id, {
+        "kyc_status": "approved",
+        "kyc_approved_at": datetime.utcnow(),
+        "kyc_approved_by": admin_user.get('id'),
+        "kyc_ipfs_cid": ipfs_cid,
+        "kyc_blockchain_tx": blockchain_tx_hash
+    })
+    
+    return {
+        "success": True,
+        "message": f"KYC approved for {user.get('name')}",
+        "user": {"id": user_id, "name": user.get('name'), "email": user.get('email')},
+        "ipfs": {"cid": ipfs_cid, "url": ipfs_url, "hash": ipfs_hash, "gateway_url": f"https://cloudflare-ipfs.com/ipfs/{ipfs_cid}"},
+        "blockchain": {"tx_hash": blockchain_tx_hash, "explorer_url": blockchain_explorer_url, "success": blockchain_result.get('success', False)},
+        "approved_at": now,
+        "approved_by": admin_user.get('email')
+    }
+
+
+@router.post("/admin/kyc/{document_id}/reject")
+def reject_kyc(document_id: str, reason: str = Body(None, embed=True), db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Reject a KYC document and mark it with rejection reason"""
+    print(f"\n[ADMIN-KYC] Rejecting KYC document {document_id}")
+    
+    kyc_doc = db.kyc_documents.find_one({"_id": ObjectId(document_id)})
+    if not kyc_doc:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="KYC document not found")
+    
+    db.kyc_documents.update_one(
+        {"_id": ObjectId(document_id)},
+        {"$set": {
+            "status": "rejected",
+            "rejection_reason": reason or "KYC document did not meet verification requirements",
+            "reviewed_at": datetime.utcnow(),
+            "reviewed_by": admin_user['id']
+        }}
+    )
+    
+    repo.update_user(db, str(kyc_doc["user_id"]), {"kyc_status": "rejected", "kyc_document_id": str(document_id)})
+    
+    return {"success": True, "message": "KYC document rejected successfully", "reason": reason or "KYC document did not meet verification requirements"}
+
+
+@router.get("/admin/users/{user_id}/kyc")
+def get_user_kyc_document(user_id: str, db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Fetch the latest KYC document for a user (if any)."""
+    user = repo.get_user_by_id(db, user_id)
+    doc = None
+    
+    if user and user.get("kyc_document_id"):
+        try:
+            doc = db.kyc_documents.find_one({"_id": ObjectId(user["kyc_document_id"])})
+        except Exception:
+            doc = None
+    
+    if not doc:
+        try:
+            cursor = db.kyc_documents.find({"user_id": repo._to_object_id(user_id)}).sort("uploaded_at", -1).limit(1)
+            doc = next(cursor, None)
+        except Exception:
+            doc = None
+    
+    if not doc:
+        return {"kyc_document": None}
+    
+    return {
+        "kyc_document": {
+            "id": str(doc.get("_id")),
+            "user_id": str(doc.get("user_id")),
+            "full_name": doc.get("full_name"),
+            "date_of_birth": doc.get("date_of_birth"),
+            "gender": doc.get("gender"),
+            "address": doc.get("address"),
+            "document_url": doc.get("document_url") or doc.get("file_data"),
+            "file_size": doc.get("file_size"),
+            "content_type": doc.get("content_type"),
+            "status": doc.get("status", "pending"),
+            "uploaded_at": doc.get("uploaded_at"),
+            "reviewed_at": doc.get("reviewed_at"),
+            "reviewed_by": doc.get("reviewed_by"),
+            "rejection_reason": doc.get("rejection_reason"),
+        }
+    }
+
+
+@router.get("/admin/kyc/blockchain-records")
+def get_blockchain_kyc_records(db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Get all KYC records that have been written to blockchain. Shows IPFS links and blockchain explorer links."""
+    print(f"\n[ADMIN-KYC] Fetching blockchain KYC records...\n")
+    
+    kyc_docs = list(db.kyc_documents.find({
+        "status": "approved",
+        "blockchain_tx_hash": {"$exists": True, "$ne": None}
+    }).sort("reviewed_at", -1))
+    
+    result = []
+    for doc in kyc_docs:
+        user = repo.get_user_by_id(db, str(doc.get('user_id')))
+        result.append({
+            "user_id": str(doc.get('user_id')),
+            "user_name": user.get('name') if user else 'Unknown',
+            "user_email": user.get('email') if user else 'Unknown',
+            "full_name": doc.get('full_name'),
+            "approved_at": doc.get('reviewed_at'),
+            "ipfs": {"cid": doc.get('ipfs_cid'), "url": doc.get('ipfs_url'), "gateway_url": f"https://cloudflare-ipfs.com/ipfs/{doc.get('ipfs_cid')}" if doc.get('ipfs_cid') else None, "hash": doc.get('ipfs_hash')},
+            "blockchain": {"tx_hash": doc.get('blockchain_tx_hash'), "explorer_url": doc.get('blockchain_explorer_url'), "success": doc.get('blockchain_success', False)}
+        })
+    
+    return {"total": len(result), "blockchain_records": result}

routes/admin_properties.py

@@ -0,0 +1,336 @@
+"""
+Admin Property Routes
+CRUD endpoints for property management
+"""
+from fastapi import APIRouter, Depends, HTTPException, status
+from typing import List, Dict, Any
+
+import schemas
+import repo
+from db import get_mongo
+from routes.auth import get_current_admin
+from services.xrp_service import XRPLService
+from config import settings
+from middleware.security import sanitize_input
+
+router = APIRouter()
+
+
+# ============================================================================
+# PROPERTY MANAGEMENT ENDPOINTS
+# ============================================================================
+
+@router.post("/admin/properties", response_model=schemas.PropertyOut, status_code=status.HTTP_201_CREATED)
+def create_property(
+    property_data: schemas.PropertyCreate,
+    db=Depends(get_mongo),
+    admin_user=Depends(get_current_admin)
+):
+    """
+    Create a new property (Admin only)
+    Automatically creates related specifications, amenities, images, and documents
+    Requires admin to have connected XRP wallet (used as issuer)
+    """
+    print(f"\n[ADMIN] Creating property: {property_data.title}")
+    print(f"[ADMIN] Created by: {admin_user['email']}")
+    print(f"[ADMIN] Property data received: {property_data.dict()}")
+    
+    # ========================================================================
+    # SECURITY: Sanitize all text inputs to prevent XSS
+    # ========================================================================
+    property_data.title = sanitize_input(property_data.title)
+    property_data.description = sanitize_input(property_data.description)
+    property_data.location = sanitize_input(property_data.location)
+    
+    # ========================================================================
+    # VALIDATION: Admin must have connected XRP wallet
+    # ========================================================================
+    admin_wallet = repo.get_wallet_by_user(db, admin_user['id'])
+    if not admin_wallet or not admin_wallet.get('xrp_address'):
+        print(f"[ADMIN] [ERROR] Admin wallet not connected")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Admin XRP wallet not connected. Please connect your wallet before creating properties."
+        )
+    
+    admin_xrp_address = admin_wallet.get('xrp_address')
+    admin_xrp_seed = admin_wallet.get('xrp_seed')  # Encrypted seed
+    print(f"[ADMIN] [SUCCESS] Admin wallet connected: {admin_xrp_address}")
+    
+    # Prepare property data
+    prop_dict = property_data.dict(exclude={'specifications', 'amenities', 'images', 'documents'}, exclude_none=True)
+    
+    # IOU model: pre-generate currency code and attach
+    if settings.XRPL_TOKEN_MODEL.upper() == "IOU":
+        try:
+            code = XRPLService().generate_currency_code(getattr(property_data, 'total_tokens', 0) and  prop_dict.get('total_tokens', 0) and repo.get_next_sequence if False else property_data.total_tokens and property_data.total_tokens)  # placeholder; will regenerate with property id below
+        except Exception:
+            code = None
+        if code:
+            prop_dict['currency_code_pending'] = code  # temporary marker
+
+    # Create main property
+    property_obj = repo.create_property(db, prop_dict, admin_user['id'])
+    print(f"[ADMIN] [SUCCESS] Property created: {property_obj['id']}")
+    
+    # Create specifications - ALWAYS create with defaults if not provided
+    spec = None
+    if property_data.specifications:
+        spec_data = property_data.specifications.dict()
+        spec = repo.create_property_specification(db, property_obj['id'], spec_data)
+        print(f"[ADMIN] [SUCCESS] Specifications added from request")
+    else:
+        # Create default specifications
+        default_spec = {
+            "balcony": 0,
+            "kitchen": 1,
+            "bedroom": 1,
+            "bathroom": 1,
+            "area": 1000.0  # Default 1000 sqft
+        }
+        spec = repo.create_property_specification(db, property_obj['id'], default_spec)
+        print(f"[ADMIN] [SUCCESS] Default specifications created")
+    
+    # Create amenities if provided
+    amenities = []
+    if property_data.amenities and len(property_data.amenities) > 0:
+        amenities = repo.create_amenities(db, property_obj['id'], property_data.amenities)
+        print(f"[ADMIN] [SUCCESS] Amenities added: {len(amenities)}")
+    else:
+        print(f"[ADMIN] ⚠ No amenities provided")
+    
+    # Create images if provided
+    images = []
+    if property_data.images and len(property_data.images) > 0:
+        images_data = [img.dict() for img in property_data.images]
+        images = repo.create_property_images(db, property_obj['id'], images_data, admin_user['id'])
+        print(f"[ADMIN] [SUCCESS] Images added: {len(images)}")
+    else:
+        print(f"[ADMIN] ⚠ No images provided")
+    
+    # Create documents if provided
+    documents = []
+    if property_data.documents and len(property_data.documents) > 0:
+        documents = repo.create_property_documents(db, property_obj['id'], property_data.documents, admin_user['id'])
+        print(f"[ADMIN] [SUCCESS] Documents added: {len(documents)}")
+    else:
+        print(f"[ADMIN] ⚠ No documents provided")
+    
+    # ========================================================================
+    # STEP 5: TOKENIZATION ON XRP LEDGER (IOU MODEL - FUNGIBLE TOKENS)
+    # ========================================================================
+    print(f"\n[ADMIN] 🔗 Tokenization on XRP Ledger (model={settings.XRPL_TOKEN_MODEL})...")
+    
+    tokenization_success = False
+    currency_code = None
+    issuer_address = None
+    
+    try:
+        if settings.XRPL_TOKEN_MODEL.upper() == "IOU":
+            # Generate currency code for this property
+            currency_code = XRPLService().generate_currency_code(property_obj['id'])
+            
+            # Use ADMIN's connected wallet as issuer (not master wallet)
+            print(f"[ADMIN] Using admin's connected wallet as issuer...")
+            issuer_address = admin_xrp_address
+            
+            print(f"[ADMIN] ✅ Using Admin Wallet as Issuer!")
+            print(f"[ADMIN]   Address: {issuer_address}")
+            print(f"[ADMIN]   Currency Code: {currency_code}")
+            print(f"[ADMIN]   Total Token Supply: {property_obj['total_tokens']:,}")
+            
+            # Check if wallet is funded
+            xrpl_service = XRPLService()
+            xrp_balance = xrpl_service.get_xrp_balance(issuer_address)
+            wallet_funded = xrp_balance > 10  # Need at least 10 XRP
+            
+            if wallet_funded:
+                print(f"[ADMIN] ✅ Wallet is funded! Balance: {xrp_balance:.2f} XRP")
+            else:
+                print(f"[ADMIN] [WARNING]  Wallet balance low: {xrp_balance:.2f} XRP")
+                print(f"[ADMIN]   Fund at: https://faucet.altnet.rippletest.net/")
+            
+            # Create token metadata in database with admin wallet info
+            token_result = repo.upsert_token(db, property_obj['id'], {
+                "token_type": "IOU",
+                "currency_code": currency_code,
+                "blockchain": "XRP Ledger",
+                "issuer_address": issuer_address,
+                "wallet_funded": wallet_funded,
+                "wallet_balance": xrp_balance,
+                "blockchain_status": "ready" if wallet_funded else "pending_funding",
+                "total_supply": property_obj['total_tokens'],
+                "network": settings.XRPL_NETWORK,
+                "wallet_type": "admin_wallet",
+                "encrypted_issuer_seed": admin_xrp_seed  # Store encrypted seed for token issuance
+            })
+            
+            print(f"[ADMIN] ℹ️ Note: IOU tokens are issued on-demand during purchase (no pre-minting required)")
+            tokenization_success = True
+        
+        # IOU-only model - NFTs are not used for fractional ownership
+        # All tokens are fungible IOUs issued on-demand during purchase
+        
+    except Exception as token_error:
+        print(f"[ADMIN] ⚠ Tokenization error: {token_error}")
+        # Don't fail property creation if tokenization fails
+        import traceback
+        traceback.print_exc()
+    
+    print(f"[ADMIN] ✅ Property creation complete (Tokenization={'yes' if tokenization_success else 'no'})")
+    print(f"[ADMIN] Summary: Property={property_obj['id']}, Specs=1, Amenities={len(amenities)}, Images={len(images)}, Documents={len(documents)}, Tokens={'[SUCCESS] Configured' if tokenization_success else '⚠ Pending'}")
+    
+    # Ensure all required PropertyOut fields have default values
+    if 'property_type' not in property_obj or not property_obj.get('property_type'):
+        property_obj['property_type'] = 'Residential'  # Default type
+    if 'funded_date' not in property_obj:
+        property_obj['funded_date'] = None
+    
+    return schemas.PropertyOut(
+        **property_obj,
+        specifications=schemas.PropertySpecificationOut(**spec) if spec else None,
+        amenities=[schemas.AmenityOut(**a) for a in amenities] if amenities else None,
+        images=[schemas.PropertyImageOut(**img) for img in images] if images else None,
+        documents=[schemas.DocumentOut(**d) for d in documents] if documents else None
+    )
+
+
+@router.put("/admin/properties/{property_id}", response_model=schemas.PropertyOut)
+def update_property(
+    property_id: str,
+    property_data: schemas.PropertyCreate,
+    db=Depends(get_mongo),
+    admin_user=Depends(get_current_admin)
+):
+    """
+    Update an existing property (Admin only)
+    Updates property and all related data (specifications, amenities, images, documents)
+    """
+    from bson import ObjectId
+    
+    print(f"\n[ADMIN] ====== PROPERTY UPDATE REQUEST ======")
+    print(f"[ADMIN] Property ID: {property_id}")
+    print(f"[ADMIN] Updated by: {admin_user['email']}")
+    print(f"[ADMIN] Request data fields: {list(property_data.dict(exclude_none=True).keys())}")
+    
+    # ========================================================================
+    # SECURITY: Sanitize all text inputs to prevent XSS
+    # ========================================================================
+    property_data.title = sanitize_input(property_data.title)
+    property_data.description = sanitize_input(property_data.description)
+    property_data.location = sanitize_input(property_data.location)
+    
+    try:
+        # Convert property_id to ObjectId for database queries
+        property_oid = ObjectId(property_id)
+        print(f"[ADMIN] [SUCCESS] Converted to ObjectId: {property_oid}")
+        
+        # Check if property exists
+        existing_property = repo.get_property_by_id(db, property_id)
+        if not existing_property:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=f"Property {property_id} not found"
+            )
+        
+        # ========================================================================
+        # OWNERSHIP VALIDATION: Admin can only edit their own properties
+        # ========================================================================
+        property_creator_id = str(existing_property.get('created_by', ''))
+        current_admin_id = str(admin_user['id'])
+        
+        if property_creator_id != current_admin_id:
+            print(f"[ADMIN] [ERROR] Ownership validation failed")
+            print(f"[ADMIN]   Property creator: {property_creator_id}")
+            print(f"[ADMIN]   Current admin: {current_admin_id}")
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="You can only edit properties that you created. This property belongs to another admin."
+            )
+        
+        print(f"[ADMIN] [SUCCESS] Ownership validated: Admin owns this property")
+        
+        # Prepare property data (exclude nested objects)
+        prop_dict = property_data.dict(exclude={'specifications', 'amenities', 'images', 'documents'}, exclude_none=True)
+        
+        # Update main property
+        updated_property = repo.update_property(db, property_id, prop_dict)
+        print(f"[ADMIN] [SUCCESS] Property updated: {property_id}")
+        
+        # Update specifications - delete old, create new
+        spec = None
+        if property_data.specifications:
+            spec_data = property_data.specifications.dict()
+            # Delete existing specifications (using ObjectId)
+            delete_result = db.property_specifications.delete_many({"property_id": property_oid})
+            print(f"[ADMIN] Deleted {delete_result.deleted_count} old specifications")
+            # Create new specifications
+            spec = repo.create_property_specification(db, property_id, spec_data)
+            print(f"[ADMIN] [SUCCESS] Specifications updated")
+        else:
+            # Keep existing spec if not provided
+            spec = db.property_specifications.find_one({"property_id": property_oid})
+        
+        # Update amenities - delete old, create new
+        delete_result = db.amenities.delete_many({"property_id": property_oid})
+        print(f"[ADMIN] Deleted {delete_result.deleted_count} old amenities")
+        amenities = []
+        if property_data.amenities and len(property_data.amenities) > 0:
+            amenities = repo.create_amenities(db, property_id, property_data.amenities)
+            print(f"[ADMIN] [SUCCESS] Amenities updated: {len(amenities)}")
+        
+        # Update images - delete old, create new
+        delete_result = db.property_images.delete_many({"property_id": property_oid})
+        print(f"[ADMIN] Deleted {delete_result.deleted_count} old images")
+        images = []
+        if property_data.images and len(property_data.images) > 0:
+            images_data = [img.dict() for img in property_data.images]
+            images = repo.create_property_images(db, property_id, images_data, admin_user['id'])
+            print(f"[ADMIN] [SUCCESS] Images updated: {len(images)}")
+        
+        # Update documents - delete old, create new
+        delete_result = db.documents.delete_many({"property_id": property_oid})
+        print(f"[ADMIN] Deleted {delete_result.deleted_count} old documents")
+        documents = []
+        if property_data.documents and len(property_data.documents) > 0:
+            documents = repo.create_property_documents(db, property_id, property_data.documents, admin_user['id'])
+            print(f"[ADMIN] [SUCCESS] Documents updated: {len(documents)}")
+        
+        print(f"[ADMIN] ✅ Property update complete")
+        
+        # Get fresh data using repo functions (they clean ObjectId to string)
+        updated_property = repo.get_property_by_id(db, property_id)
+        if not updated_property:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail="Failed to retrieve updated property"
+            )
+        
+        # Use repo functions to get cleaned data
+        spec = repo.get_property_specification(db, property_id)
+        amenities = repo.get_property_amenities(db, property_id)
+        images = repo.get_property_images(db, property_id)
+        documents = repo.get_property_documents(db, property_id)
+        
+        # Ensure funded_date field
+        if 'funded_date' not in updated_property:
+            updated_property['funded_date'] = None
+        
+        return schemas.PropertyOut(
+            **updated_property,
+            specifications=schemas.PropertySpecificationOut(**spec) if spec else None,
+            amenities=[schemas.AmenityOut(**a) for a in amenities] if amenities else None,
+            images=[schemas.PropertyImageOut(**img) for img in images] if images else None,
+            documents=[schemas.DocumentOut(**d) for d in documents] if documents else None
+        )
+    
+    except HTTPException:
+        raise
+    except Exception as e:
+        print(f"[ADMIN] [ERROR] Error updating property: {str(e)}")
+        import traceback
+        traceback.print_exc()
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to update property: {str(e)}"
+        )

routes/admin_rent.py

@@ -0,0 +1,195 @@
+"""
+Admin Rent Distribution Routes
+Endpoints for managing rent distributions to token holders
+"""
+from fastapi import APIRouter, Depends, HTTPException, status
+from typing import Dict, Any
+
+import schemas
+import repo
+from db import get_mongo
+from routes.auth import get_current_admin
+from middleware.security import sanitize_input
+
+router = APIRouter()
+
+
+# ============================================================================
+# RENT DISTRIBUTION ENDPOINTS
+# ============================================================================
+
+@router.post("/admin/distribute-rent")
+def distribute_rent(
+    rent_data: schemas.RentDistributionCreate,
+    db=Depends(get_mongo),
+    admin_user=Depends(get_current_admin)
+):
+    """
+    Distribute rent to all token holders of a property (Admin only)
+    
+    This endpoint:
+    1. Validates the property exists
+    2. Calculates rent per token
+    3. Credits rent to each investor's wallet proportionally
+    4. Creates transaction records for each payment
+    5. Creates rent payment records for tracking
+    
+    Returns detailed distribution results including:
+    - Total investors who received rent
+    - Number of successful/failed payments
+    - Individual payment details
+    """
+    print(f"\n[ADMIN] Rent distribution request by: {admin_user['email']}")
+    print(f"[ADMIN] Property ID: {rent_data.property_id}")
+    print(f"[ADMIN] Total Rent Amount: {rent_data.total_rent_amount} AED")
+    print(f"[ADMIN] Period: {rent_data.rent_period_start} to {rent_data.rent_period_end}")
+    
+    # ========================================================================
+    # SECURITY: Sanitize inputs
+    # ========================================================================
+    if rent_data.notes:
+        rent_data.notes = sanitize_input(rent_data.notes)
+    
+    # ========================================================================
+    # VALIDATION: Check property exists and admin has access
+    # ========================================================================
+    property_data = repo.get_property_by_id(db, rent_data.property_id)
+    if not property_data:
+        print(f"[ADMIN] [ERROR] Property not found: {rent_data.property_id}")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Property not found: {rent_data.property_id}"
+        )
+    
+    print(f"[ADMIN] ✅ Property found: {property_data.get('title')}")
+    
+    # ========================================================================
+    # BUSINESS LOGIC: Distribute rent using service
+    # ========================================================================
+    try:
+        from services.rent_distribution_service import RentDistributionService
+        
+        rent_service = RentDistributionService(db)
+        result = rent_service.distribute_rent(
+            property_id=rent_data.property_id,
+            total_rent_amount=rent_data.total_rent_amount,
+            rent_period_start=rent_data.rent_period_start,
+            rent_period_end=rent_data.rent_period_end,
+            distribution_date=rent_data.distribution_date,
+            notes=rent_data.notes
+        )
+        
+        print(f"[ADMIN] ✅ Rent distribution completed")
+        print(f"[ADMIN] Distribution ID: {result['distribution_id']}")
+        print(f"[ADMIN] Payments: {result['payments_completed']} succeeded, {result['payments_failed']} failed")
+        
+        return {
+            "success": True,
+            "message": "Rent distributed successfully",
+            **result
+        }
+        
+    except ValueError as e:
+        print(f"[ADMIN] [ERROR] Validation error: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+    except Exception as e:
+        print(f"[ADMIN] [ERROR] Error during rent distribution: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to distribute rent: {str(e)}"
+        )
+
+
+@router.get("/admin/rent-distributions/{distribution_id}", response_model=schemas.RentDistributionOut)
+def get_rent_distribution(
+    distribution_id: str,
+    db=Depends(get_mongo),
+    admin_user=Depends(get_current_admin)
+):
+    """
+    Get details of a specific rent distribution (Admin only)
+    """
+    print(f"\n[ADMIN] Getting rent distribution: {distribution_id}")
+    
+    from services.rent_distribution_service import RentDistributionService
+    
+    rent_service = RentDistributionService(db)
+    distribution = rent_service.get_distribution_details(distribution_id)
+    
+    if not distribution:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Rent distribution not found: {distribution_id}"
+        )
+    
+    return distribution
+
+
+@router.get("/admin/properties/{property_id}/rent-history")
+def get_property_rent_history(
+    property_id: str,
+    db=Depends(get_mongo),
+    admin_user=Depends(get_current_admin)
+):
+    """
+    Get all rent distributions for a property with detailed payment information (Admin only)
+    
+    Returns:
+    - All distribution records for the property
+    - For each distribution: list of investors who received payments with names, IDs, tokens, and amounts
+    """
+    print(f"\n[ADMIN] Getting rent history for property: {property_id}")
+    
+    # Validate property exists
+    property_data = repo.get_property_by_id(db, property_id)
+    if not property_data:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Property not found: {property_id}"
+        )
+    
+    # Get all distributions for this property
+    distributions = list(db.rent_distributions.find({
+        "property_id": repo._to_object_id(property_id)
+    }).sort("distribution_date", -1))
+    
+    result = []
+    for dist in distributions:
+        dist_obj = repo._clean_object(dist)
+        
+        # Get all payments for this distribution with user details
+        payments = list(db.rent_payments.find({
+            "distribution_id": dist["_id"]
+        }))
+        
+        investor_details = []
+        for payment in payments:
+            user_id = str(payment.get("user_id"))
+            user = repo.get_user_by_id(db, user_id)
+            
+            investor_details.append({
+                "user_id": user_id,
+                "user_name": user.get("name") if user else "Unknown User",
+                "user_email": user.get("email") if user else "",
+                "tokens_owned": payment.get("tokens_owned", 0),
+                "rent_amount": payment.get("rent_amount", 0),
+                "payment_status": payment.get("payment_status", "unknown"),
+                "payment_date": payment.get("payment_date")
+            })
+        
+        dist_obj["investor_payments"] = investor_details
+        dist_obj["total_investors_paid"] = len([p for p in investor_details if p["payment_status"] == "completed"])
+        
+        result.append(dist_obj)
+    
+    print(f"[ADMIN] Found {len(result)} rent distributions")
+    
+    return {
+        "property_id": property_id,
+        "property_title": property_data.get("title"),
+        "total_distributions": len(result),
+        "distributions": result
+    }

routes/admin_tokenization.py

@@ -0,0 +1,70 @@
+"""
+Admin Tokenization Routes
+Endpoints for property token status and blockchain tokenization details
+"""
+from fastapi import APIRouter, Depends, HTTPException, status
+
+import repo
+from db import get_mongo
+from routes.auth import get_current_admin
+from config import settings
+
+router = APIRouter()
+
+
+# ============================================================================
+# TOKENIZATION STATUS ENDPOINTS
+# ============================================================================
+
+@router.get("/admin/properties/{property_id}/tokenization")
+def get_property_tokenization_status(property_id: str, db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Get IOU tokenization status for a property (Admin only). Shows token issuance status, distribution, and blockchain details."""
+    print(f"\n[ADMIN] Getting tokenization status for property: {property_id}")
+    
+    property_obj = repo.get_property_by_id(db, property_id)
+    if not property_obj:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Property not found")
+    
+    token_record = repo.get_property_token(db, property_id)
+    
+    result = {
+        "property_id": property_id,
+        "property_title": property_obj.get("title"),
+        "tokenization_status": "configured" if token_record else "not_configured",
+        "tokenization_details": token_record,
+        "blockchain_network": "XRP Ledger Testnet",
+        "total_tokens_planned": property_obj.get("total_tokens"),
+        "available_for_purchase": property_obj.get("available_tokens"),
+        "token_type": "IOU"
+    }
+    
+    print(f"[ADMIN] [SUCCESS] Tokenization status: {result['tokenization_status']}")
+    return result
+
+
+@router.get("/admin/tokenization/all")
+def get_all_properties_tokenization(db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Get tokenization status for ALL properties (Admin only). Returns a map of property_id -> tokenization details."""
+    print(f"\n[ADMIN] Getting tokenization status for all properties")
+    
+    tokens_col = db['tokens']
+    all_tokens = list(tokens_col.find({}))
+    
+    tokenization_map = {}
+    
+    for token_rec in all_tokens:
+        prop_id = str(token_rec.get('property_id'))
+        tokenization_map[prop_id] = {
+            "issuer_address": token_rec.get('issuer_address'),
+            "currency_code": token_rec.get('currency_code'),
+            "total_supply": token_rec.get('total_supply'),
+            "token_type": token_rec.get('token_type', 'IOU'),
+            "blockchain": token_rec.get('blockchain', 'XRP Ledger'),
+            "network": token_rec.get('network', settings.XRPL_NETWORK),
+            "wallet_funded": token_rec.get('wallet_funded', False),
+            "blockchain_status": token_rec.get('blockchain_status', 'ready'),
+            "status": "issued" if token_rec.get('wallet_funded') else "pending_funding"
+        }
+    
+    print(f"[ADMIN] [SUCCESS] Found tokenization records for {len(tokenization_map)} properties")
+    return tokenization_map

routes/admin_users.py

@@ -0,0 +1,290 @@
+"""
+Admin User Management Routes
+Endpoints for user CRUD operations and user-specific data
+"""
+from fastapi import APIRouter, Depends, HTTPException, status
+from typing import List, Dict, Any
+
+import schemas
+import repo
+from db import get_mongo
+from routes.auth import get_current_admin
+from middleware.security import sanitize_input
+
+router = APIRouter()
+
+
+# ============================================================================
+# USER MANAGEMENT ENDPOINTS
+# ============================================================================
+
+@router.get("/admin/users")
+def list_all_users(
+    skip: int = 0,
+    limit: int = 100,
+    include_wallet: bool = True,
+    db=Depends(get_mongo),
+    admin_user=Depends(get_current_admin)
+):
+    """
+    List all users with wallet information (Admin only)
+    """
+    print(f"\n[ADMIN] Listing users - Requested by: {admin_user['email']}")
+    
+    users = repo.list_all_users(db, skip=skip, limit=limit)
+    
+    # Enrich users with wallet information if requested
+    if include_wallet:
+        from bson import ObjectId
+        enriched_users = []
+        for user in users:
+            user_dict = dict(user)
+            
+            # Get wallet for this user
+            try:
+                user_id_obj = ObjectId(user['id']) if isinstance(user['id'], str) else user['id']
+                wallet = db.wallets.find_one({"user_id": user_id_obj})
+                
+                if wallet:
+                    user_dict['aed_balance'] = wallet.get('balance', 0.0)
+                    user_dict['xrp_address'] = wallet.get('xrp_address')
+                    user_dict['xrp_balance'] = 0.0  # Placeholder, updated on detail view
+                else:
+                    user_dict['aed_balance'] = 0.0
+                    user_dict['xrp_balance'] = 0.0
+                    user_dict['xrp_address'] = None
+                    
+            except Exception as e:
+                print(f"[ADMIN] [WARNING]  Error fetching wallet for user {user.get('id')}: {e}")
+                user_dict['aed_balance'] = 0.0
+                user_dict['xrp_balance'] = 0.0
+                user_dict['xrp_address'] = None
+            
+            # Get profile image for this user
+            try:
+                from routes.profile import profile_images_col
+                profile_image = profile_images_col(db).find_one({"user_id": user_id_obj})
+                if profile_image:
+                    user_dict['profile_image'] = {
+                        "image_url": profile_image.get("image_data"),
+                        "file_size": profile_image.get("file_size"),
+                        "uploaded_at": profile_image.get("uploaded_at")
+                    }
+                else:
+                    user_dict['profile_image'] = None
+            except Exception as e:
+                print(f"[ADMIN] [WARNING]  Error fetching profile image for user {user.get('id')}: {e}")
+                user_dict['profile_image'] = None
+            
+            enriched_users.append(user_dict)
+        
+        print(f"[ADMIN] [SUCCESS] Found {len(enriched_users)} users with wallet info\n")
+        return enriched_users
+    
+    print(f"[ADMIN] [SUCCESS] Found {len(users)} users\n")
+    return users
+
+
+@router.patch("/admin/users/{user_id}", response_model=schemas.UserOut)
+def update_user(
+    user_id: str,
+    user_update: schemas.UserUpdate,
+    db=Depends(get_mongo),
+    admin_user=Depends(get_current_admin)
+):
+    """
+    Update user details (Admin only)
+    """
+    print(f"\n[ADMIN] Updating user {user_id} - Requested by: {admin_user['email']}")
+    
+    existing = repo.get_user_by_id(db, user_id)
+    if not existing:
+        print(f"[ADMIN] [ERROR] User not found: {user_id}\n")
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+    
+    update_data = user_update.dict(exclude_none=True)
+    
+    if not update_data:
+        print(f"[ADMIN] ⚠ No fields to update\n")
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="No fields to update")
+    
+    updated_user = repo.update_user(db, user_id, update_data)
+    
+    if not updated_user:
+        print(f"[ADMIN] [ERROR] Failed to update user\n")
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to update user")
+    
+    print(f"[ADMIN] [SUCCESS] User updated: {list(update_data.keys())}\n")
+    return schemas.UserOut(**updated_user)
+
+
+@router.post("/admin/users", response_model=schemas.UserOut, status_code=status.HTTP_201_CREATED)
+def create_user(
+    user_data: schemas.UserCreate,
+    db=Depends(get_mongo),
+    admin_user=Depends(get_current_admin)
+):
+    """
+    Create a new user (Admin only)
+    """
+    import re
+    print(f"\n[ADMIN] Creating user - Requested by: {admin_user['email']}")
+    
+    user_data.name = sanitize_input(user_data.name).strip()
+    user_data.email = sanitize_input(user_data.email).lower().strip()
+    user_data.phone = sanitize_input(user_data.phone).strip()
+    
+    if not re.match(r"^[a-zA-Z\s\-']+$", user_data.name):
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Name can only contain letters, spaces, hyphens, and apostrophes")
+    
+    if not re.match(r"^[0-9]{10}$", user_data.phone):
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Phone number must be exactly 10 digits")
+    
+    if not user_data.email or '@' not in user_data.email:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Invalid email format")
+    
+    existing = repo.get_user_by_email(db, user_data.email)
+    if existing:
+        print(f"[ADMIN] [ERROR] User already exists: {user_data.email}\n")
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="User with this email already exists")
+    
+    from passlib.context import CryptContext
+    pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+    password_hash = pwd_context.hash(user_data.password)
+    
+    new_user = repo.create_user(
+        db, name=user_data.name, email=user_data.email, password_hash=password_hash,
+        phone=user_data.phone, role=user_data.role or "user"
+    )
+    
+    repo.create_wallet(db, new_user['id'], balance=0.0, currency="AED")
+    
+    print(f"[ADMIN] [SUCCESS] User created: {new_user['email']}\n")
+    return schemas.UserOut(**new_user)
+
+
+@router.delete("/admin/users/{user_id}")
+def delete_user(
+    user_id: str,
+    db=Depends(get_mongo),
+    admin_user=Depends(get_current_admin)
+):
+    """
+    Delete a user and ALL related data (Admin only)
+    Performs HARD DELETE - removes user and all associated data from database
+    """
+    from bson import ObjectId
+    print(f"\n[ADMIN] Deleting user {user_id} and ALL related data - Requested by: {admin_user['email']}")
+
+    existing = repo.get_user_by_id(db, user_id)
+    if not existing:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+
+    if existing['id'] == admin_user['id']:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Cannot delete your own account")
+
+    try:
+        user_oid = ObjectId(user_id)
+        
+        wallet_delete = db.wallets.delete_many({"user_id": user_oid})
+        transaction_delete = db.transactions.delete_many({"user_id": user_oid})
+        certificate_delete = db.certificates.delete_many({"user_id": user_oid})
+        investment_delete = db.investments.delete_many({"user_id": user_oid})
+        portfolio_delete = db.portfolios.delete_many({"user_id": user_oid})
+        document_delete = db.documents.delete_many({"user_id": user_oid})
+        kyc_delete = db.kyc_documents.delete_many({"user_id": user_oid})
+        profile_image_delete = db.profile_images.delete_many({"user_id": user_oid})
+        user_delete = db.users.delete_one({"_id": user_oid})
+
+        total_deleted = (wallet_delete.deleted_count + transaction_delete.deleted_count +
+                        certificate_delete.deleted_count + investment_delete.deleted_count +
+                        portfolio_delete.deleted_count + document_delete.deleted_count +
+                        kyc_delete.deleted_count + profile_image_delete.deleted_count +
+                        user_delete.deleted_count)
+
+        print(f"[ADMIN] [SUCCESS] Successfully deleted user {user_id} and {total_deleted - 1} related records\n")
+
+        return {
+            "message": f"User and all related data deleted successfully",
+            "user_id": user_id,
+            "records_deleted": {
+                "user": user_delete.deleted_count,
+                "wallets": wallet_delete.deleted_count,
+                "transactions": transaction_delete.deleted_count,
+                "total": total_deleted
+            }
+        }
+
+    except Exception as e:
+        print(f"[ADMIN] [ERROR] Error during user deletion: {str(e)}\n")
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"Failed to delete user: {str(e)}")
+
+
+@router.get("/admin/users/{user_id}/transactions", response_model=List[schemas.TransactionOut])
+def get_user_transactions(
+    user_id: str,
+    skip: int = 0,
+    limit: int = 50,
+    db=Depends(get_mongo),
+    admin_user=Depends(get_current_admin)
+):
+    """
+    Get transactions for a specific user (Admin only)
+    """
+    from bson import ObjectId
+    print(f"\n[ADMIN] Getting transactions for user {user_id}")
+
+    user = repo.get_user_by_id(db, user_id)
+    if not user:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+
+    try:
+        user_oid = ObjectId(user_id)
+    except:
+        user_oid = user_id
+    
+    transactions = list(db.transactions.find({"user_id": user_oid}).skip(skip).limit(limit).sort("created_at", -1))
+    cleaned_transactions = [repo._clean_object(tx) for tx in transactions]
+
+    print(f"[ADMIN] [SUCCESS] Found {len(cleaned_transactions)} transactions for user {user_id}\n")
+    return [schemas.TransactionOut(**tx) for tx in cleaned_transactions]
+
+
+@router.get("/admin/users/{user_id}/wallet")
+def get_user_wallet(
+    user_id: str,
+    db=Depends(get_mongo),
+    admin_user=Depends(get_current_admin)
+):
+    """
+    Get wallet information for a specific user (Admin only)
+    """
+    print(f"\n[ADMIN] Getting wallet info for user {user_id}")
+
+    user = repo.get_user_by_id(db, user_id)
+    if not user:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+
+    wallet = repo.get_wallet_by_user(db, user_id)
+    
+    if not wallet:
+        return {"user_id": user_id, "balance": 0.0, "aed_balance": 0.0, "xrp_balance": 0.0, "xrp_address": None, "currency": "AED", "is_active": True}
+
+    xrp_balance = 0.0
+    if wallet.get("xrp_address"):
+        try:
+            from services.xrp_service import XRPLService
+            xrpl_service = XRPLService()
+            xrp_balance = xrpl_service.get_xrp_balance(wallet["xrp_address"])
+        except Exception as e:
+            print(f"[ADMIN] [WARNING]  Could not fetch XRP balance: {e}")
+
+    return {
+        "user_id": user_id,
+        "balance": wallet.get("balance", 0.0),
+        "aed_balance": wallet.get("balance", 0.0),
+        "xrp_balance": xrp_balance,
+        "xrp_address": wallet.get("xrp_address"),
+        "currency": wallet.get("currency", "AED"),
+        "is_active": wallet.get("is_active", True)
+    }

routes/admin_wallet.py

@@ -0,0 +1,277 @@
+"""
+Admin Wallet Routes
+Endpoints for wallet management, payment methods (cards/banks), and deposits/withdrawals
+"""
+from fastapi import APIRouter, Depends, HTTPException, status, Body
+from typing import List, Dict, Any
+from datetime import datetime
+import re
+import base64
+
+import schemas
+import repo
+from db import get_mongo
+from routes.auth import get_current_admin
+from services.xrp_service import XRPLService
+from config import settings
+from utils.crypto_utils import encrypt_secret
+
+router = APIRouter()
+
+
+# ============================================================================
+# ADMIN WALLET INFO & CONNECTION
+# ============================================================================
+
+@router.get("/admin/wallet-info")
+def get_admin_wallet_info(db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Return admin AED/XRP wallet summary and recent transactions.
+    Only shows data for properties created by this admin.
+    """
+    from bson import ObjectId
+    admin_doc = db.users.find_one({"_id": repo._to_object_id(admin_user['id'])}) or admin_user
+    wallet_record = db.wallets.find_one({"user_id": repo._to_object_id(admin_user['id'])})
+    
+    aed_balance_aed = wallet_record.get("balance", 0.0) if wallet_record else 0.0
+    wallet_address = wallet_record.get("xrp_address") if wallet_record else None
+    xrp_balance = 0.0
+    if wallet_record and wallet_record.get("xrp_address"):
+        try:
+            xrp_balance = XRPLService().get_xrp_balance(wallet_record.get("xrp_address"))
+        except Exception:
+            xrp_balance = 0.0
+
+    admin_wallet_info = {
+        "wallet_address": wallet_address,
+        "aed_balance": aed_balance_aed,
+        "xrp_balance": xrp_balance,
+        "wallet_connected": bool(wallet_address),
+    }
+
+    admin_properties = repo.get_properties_by_creator(db, admin_user['id'])
+    admin_property_ids = [ObjectId(prop["id"]) for prop in admin_properties]
+    
+    filt = {
+        "user_id": repo._to_object_id(admin_user['id']), 
+        "type": {"$regex": "^admin_wallet_"},
+        "$or": [
+            {"property_id": {"$in": admin_property_ids}},
+            {"property_id": {"$exists": False}}
+        ]
+    }
+    cursor = db.transactions.find(filt).sort("created_at", -1).limit(50)
+
+    transactions: List[Dict[str, Any]] = []
+    total_credits = 0
+    total_debits = 0
+    total_purchase_earnings = 0
+
+    for tx in cursor:
+        meta = tx.get("metadata") or {}
+        amount_aed = tx.get("amount", 0.0)
+        tx_type_val = tx.get("type") or ""
+        direction = meta.get("direction") or ("credit" if tx_type_val.startswith("admin_wallet_credit") else ("debit" if tx_type_val.startswith("admin_wallet_debit") else None))
+        if direction == "credit":
+            total_credits += amount_aed
+        elif direction == "debit":
+            total_debits += amount_aed
+        if tx.get("type") == "admin_wallet_credit_purchase":
+            total_purchase_earnings += amount_aed
+        signed_amount = amount_aed
+        if direction == "debit":
+            signed_amount = -signed_amount
+        created_at = tx.get("created_at")
+        created_at_str = created_at.isoformat() if isinstance(created_at, datetime) else str(created_at) if created_at else None
+        transactions.append({
+            "id": tx.get("id"),
+            "type": tx.get("type"),
+            "direction": direction,
+            "amount_aed": signed_amount,
+            "status": tx.get("status"),
+            "created_at": created_at_str,
+            "payment_method": meta.get("payment_method"),
+            "payment_reference": meta.get("payment_reference"),
+            "notes": meta.get("notes"),
+            "property": {"id": str(tx.get("property_id")) if tx.get("property_id") else None, "name": meta.get("property_name")} if tx.get("property_id") else None,
+            "counterparty": {"user_id": meta.get("counterparty_user_id"), "username": meta.get("counterparty_username"), "email": meta.get("counterparty_email")} if meta.get("counterparty_user_id") else None,
+        })
+
+    unique_buyers = len(set([str(inv.get("user_id")) for inv in db.investments.find({"property_id": {"$in": admin_property_ids}, "status": "completed"}, {"user_id": 1}) if inv.get("user_id")]))
+
+    flow_summary = {"total_credits_aed": total_credits, "total_debits_aed": total_debits, "net_flow_aed": (total_credits - total_debits)}
+
+    return {
+        "wallet_info": admin_wallet_info,
+        "total_earnings_aed": total_purchase_earnings if total_purchase_earnings else 0.0,
+        "total_buyers": unique_buyers,
+        "flow_summary": flow_summary,
+        "transactions": transactions,
+        "recent_transactions": transactions[:10],
+    }
+
+
+@router.post("/admin/wallet/connect")
+def connect_admin_wallet(
+    wallet_data: schemas.WalletImport,
+    db=Depends(get_mongo),
+    admin_user=Depends(get_current_admin)
+):
+    """Connect XRP wallet for admin user. This wallet will be used as the issuer for all property tokens."""
+    print(f"\n[ADMIN] Connect XRP wallet request for admin: {admin_user['email']}")
+    
+    wallet = repo.get_wallet_by_user(db, admin_user['id'])
+    if not wallet:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Admin wallet not found")
+    
+    addr_pattern = re.compile(r"^r[1-9A-HJ-NP-Za-km-z]{25,34}$")
+    seed_pattern = re.compile(r"^s[1-9A-HJ-NP-Za-km-z]{15,34}$")
+    if not addr_pattern.match(wallet_data.xrp_address):
+        raise HTTPException(status_code=400, detail="Invalid XRP address format")
+    if not seed_pattern.match(wallet_data.xrp_seed):
+        raise HTTPException(status_code=400, detail="Invalid XRP seed format")
+
+    try:
+        xrp_service = XRPLService()
+        xrp_balance = xrp_service.get_xrp_balance(wallet_data.xrp_address)
+        print(f"[ADMIN] [SUCCESS] XRP wallet validated. Balance: {xrp_balance} XRP")
+    except Exception as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=f"Invalid XRP wallet or network error: {str(e)}")
+
+    if settings.encryption_enabled():
+        encoded_seed = encrypt_secret(wallet_data.xrp_seed, settings.ENCRYPTION_KEY)
+    else:
+        encoded_seed = base64.b64encode(wallet_data.xrp_seed.encode()).decode()
+
+    updated_wallet = repo.update_wallet_xrp(db, wallet['id'], wallet_data.xrp_address, encoded_seed)
+    
+    if not updated_wallet:
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Failed to connect wallet")
+    
+    return {"success": True, "message": "Admin wallet connected successfully", "wallet_address": wallet_data.xrp_address, "xrp_balance": xrp_balance}
+
+
+@router.get("/admin/properties/{property_id}/buyers")
+def get_property_buyers(property_id: str, db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Aggregate buyer stats for a property based on investment transactions."""
+    property_obj = repo.get_property_by_id(db, property_id)
+    if not property_obj:
+        raise HTTPException(status_code=404, detail="Property not found")
+
+    txs = list(db.transactions.find({"property_id": repo._to_object_id(property_id), "type": "investment", "status": "completed"}).sort("created_at", -1))
+    buyers: Dict[str, Any] = {}
+    for tx in txs:
+        uid = str(tx.get("user_id"))
+        if uid not in buyers:
+            user_doc = db.users.find_one({"_id": tx.get("user_id")})
+            buyers[uid] = {"user_id": uid, "username": user_doc.get("name") if user_doc else None, "email": user_doc.get("email") if user_doc else None, "total_tokens": 0, "total_spent": 0, "transactions": []}
+        meta = tx.get("metadata") or {}
+        tokens = meta.get("tokens_purchased") or 0
+        amount_float = tx.get("amount") or 0.0
+        buyers[uid]["total_tokens"] += tokens
+        buyers[uid]["total_spent"] += amount_float
+        created_at = tx.get("created_at")
+        buyers[uid]["transactions"].append({"id": tx.get("id"), "tokens": tokens, "spent": amount_float, "date": created_at.isoformat() if isinstance(created_at, datetime) else str(created_at)})
+
+    buyer_list = list(buyers.values())
+    buyer_list.sort(key=lambda b: b["total_spent"], reverse=True)
+    return {"property_id": property_id, "property_name": property_obj.get("title"), "total_buyers": len(buyer_list), "total_tokens_sold": sum(b["total_tokens"] for b in buyer_list), "total_revenue": sum(b["total_spent"] for b in buyer_list), "buyers": buyer_list}
+
+
+# ============================================================================
+# ADMIN PAYMENT METHODS (CARDS & BANKS)
+# ============================================================================
+
+@router.get("/admin/wallet/cards")
+def get_admin_cards(db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Get all saved cards for admin"""
+    return repo.get_cards(db, admin_user['id'], "admin")
+
+
+@router.post("/admin/wallet/cards", response_model=schemas.CardOut)
+def add_admin_card(card_data: schemas.CardCreate, db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Add a new card for admin"""
+    try:
+        card = repo.create_card(db=db, user_id=admin_user['id'], user_role="admin", card_number=card_data.card_number, expiry_month=card_data.expiry_month, expiry_year=card_data.expiry_year, cardholder_name=card_data.cardholder_name, bank_name=card_data.bank_name)
+        return schemas.CardOut(id=card['id'], user_role="admin", card_type=card.get('card_type', 'unknown'), last_four=card['last_four'], cardholder_name=card['cardholder_name'], bank_name=card.get('bank_name'), expiry_month=card['expiry_month'], expiry_year=card['expiry_year'], is_default=card.get('is_default', False), created_at=card['created_at'])
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.delete("/admin/wallet/cards/{card_id}")
+def delete_admin_card(card_id: str, db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Delete an admin's card"""
+    success = repo.delete_card(db, admin_user['id'], "admin", card_id)
+    if not success:
+        raise HTTPException(status_code=404, detail="Card not found or already deleted")
+    return {"success": True, "message": "Card deleted successfully"}
+
+
+@router.get("/admin/wallet/banks")
+def get_admin_banks(db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Get all saved bank accounts for admin"""
+    return repo.get_banks(db, admin_user['id'], "admin")
+
+
+@router.post("/admin/wallet/banks", response_model=schemas.BankOut)
+def add_admin_bank(bank_data: schemas.BankCreate, db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Add a new bank account for admin"""
+    try:
+        bank = repo.create_bank(db=db, user_id=admin_user['id'], user_role="admin", bank_name=bank_data.bank_name, account_holder_name=bank_data.account_holder_name, account_number=bank_data.account_number, account_type=bank_data.account_type.value if hasattr(bank_data.account_type, 'value') else bank_data.account_type, iban=bank_data.iban, swift_code=bank_data.swift_code, currency=bank_data.currency)
+        return schemas.BankOut(id=bank['id'], user_role="admin", bank_name=bank['bank_name'], account_holder_name=bank['account_holder_name'], account_number_last_four=bank['account_number_last_four'], iban_last_four=bank.get('iban_last_four'), swift_code=bank.get('swift_code'), account_type=bank.get('account_type', 'savings'), currency=bank.get('currency', 'AED'), is_default=bank.get('is_default', False), is_verified=bank.get('is_verified', False), created_at=bank['created_at'])
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.delete("/admin/wallet/banks/{bank_id}")
+def delete_admin_bank(bank_id: str, db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Delete an admin's bank account"""
+    success = repo.delete_bank(db, admin_user['id'], "admin", bank_id)
+    if not success:
+        raise HTTPException(status_code=404, detail="Bank account not found or already deleted")
+    return {"success": True, "message": "Bank account deleted successfully"}
+
+
+# ============================================================================
+# ADMIN DEPOSIT & WITHDRAW
+# ============================================================================
+
+@router.post("/admin/wallet/deposit")
+def admin_deposit(amount: float = Body(..., embed=True), payment_method: str = Body("CARD", embed=True), db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Deposit funds to admin wallet (simulated). Payment methods: CARD, BANK_TRANSFER"""
+    if amount <= 0:
+        raise HTTPException(status_code=400, detail="Amount must be greater than 0")
+    if amount > 1000000:
+        raise HTTPException(status_code=400, detail="Maximum deposit is AED 1,000,000")
+    
+    wallet = repo.get_wallet_by_user(db, admin_user['id'])
+    if not wallet:
+        raise HTTPException(status_code=404, detail="Admin wallet not found")
+    
+    new_balance = wallet.get('balance', 0) + amount
+    repo.update_wallet_balance(db, wallet['id'], new_balance)
+    
+    repo.create_transaction(db=db, user_id=admin_user['id'], tx_type="admin_wallet_credit_deposit", amount=amount, status="completed", metadata={"payment_method": payment_method, "direction": "credit", "notes": f"Admin deposit via {payment_method}"})
+    
+    return {"success": True, "message": f"Successfully deposited AED {amount}", "new_balance": new_balance}
+
+
+@router.post("/admin/wallet/withdraw")
+def admin_withdraw(amount: float = Body(..., embed=True), bank_id: str = Body(None, embed=True), db=Depends(get_mongo), admin_user=Depends(get_current_admin)):
+    """Withdraw funds from admin wallet (simulated). Optional bank_id to specify which bank to withdraw to"""
+    if amount <= 0:
+        raise HTTPException(status_code=400, detail="Amount must be greater than 0")
+    
+    wallet = repo.get_wallet_by_user(db, admin_user['id'])
+    if not wallet:
+        raise HTTPException(status_code=404, detail="Admin wallet not found")
+    
+    current_balance = wallet.get('balance', 0)
+    if amount > current_balance:
+        raise HTTPException(status_code=400, detail="Insufficient balance")
+    
+    new_balance = current_balance - amount
+    repo.update_wallet_balance(db, wallet['id'], new_balance)
+    
+    repo.create_transaction(db=db, user_id=admin_user['id'], tx_type="admin_wallet_debit_withdraw", amount=amount, status="completed", metadata={"bank_id": bank_id, "direction": "debit", "notes": "Admin withdrawal"})
+    
+    return {"success": True, "message": f"Successfully withdrew AED {amount}", "new_balance": new_balance}

routes/auth.py

@@ -0,0 +1,497 @@
+"""
+Production Auth Routes
+Handles user authentication and registration with security enhancements
+Includes device fingerprinting and session management
+"""
+from fastapi import APIRouter, Depends, HTTPException, status, Request, Header
+from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
+from passlib.context import CryptContext
+from datetime import datetime, timedelta
+from jose import JWTError, jwt
+from typing import Optional
+import re
+import logging
+
+import schemas
+from db import get_mongo
+import repo
+from config import settings
+from middleware.security import (
+    limiter, 
+    check_rate_limit, 
+    record_failed_attempt, 
+    reset_failed_attempts,
+    sanitize_input,
+    validate_redirect_url,
+    mask_email
+)
+from utils.security_logger import log_login_attempt, log_registration, log_account_lockout
+from utils.fingerprint import generate_device_fingerprint, generate_session_id
+
+router = APIRouter()
+logger = logging.getLogger(__name__)
+
+# Password hashing
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+# OAuth2 scheme
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")
+
+
+def hash_password(password: str) -> str:
+    """Hash a password"""
+    return pwd_context.hash(password)
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """Verify a password against its hash"""
+    return pwd_context.verify(plain_password, hashed_password)
+
+
+def create_access_token(data: dict, expires_delta: Optional[timedelta] = None) -> str:
+    """Create JWT access token with session_id"""
+    to_encode = data.copy()
+    
+    if expires_delta:
+        expire = datetime.utcnow() + expires_delta
+    else:
+        expire = datetime.utcnow() + timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+    
+    to_encode.update({"exp": expire})
+    encoded_jwt = jwt.encode(to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
+    
+    return encoded_jwt
+
+
+def get_current_user(
+    request: Request,
+    token: str = Depends(oauth2_scheme), 
+    db=Depends(get_mongo),
+    x_device_fingerprint: Optional[str] = Header(None)
+) -> dict:
+    """Get current authenticated user with session validation"""
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    
+    try:
+        payload = jwt.decode(token, settings.SECRET_KEY, algorithms=[settings.ALGORITHM])
+        user_id: str = payload.get("sub")
+        session_id: str = payload.get("session_id")
+        
+        if user_id is None:
+            raise credentials_exception
+        
+        # Validate session if session_id exists in token
+        if session_id:
+            device_fingerprint = generate_device_fingerprint(request, x_device_fingerprint)
+            
+            if not repo.validate_session(db, session_id, device_fingerprint):
+                logger.warning(f"Session validation failed for user: {user_id}")
+                raise HTTPException(
+                    status_code=status.HTTP_401_UNAUTHORIZED,
+                    detail="Session invalid or device mismatch. Please login again.",
+                    headers={"WWW-Authenticate": "Bearer"},
+                )
+            
+    except JWTError:
+        raise credentials_exception
+    
+    user = repo.get_user_by_id(db, user_id)
+    
+    if user is None:
+        raise credentials_exception
+    
+    if not user.get("is_active"):
+        raise HTTPException(status_code=400, detail="Inactive user")
+    
+    return user
+
+
+def get_current_admin(current_user: dict = Depends(get_current_user)) -> dict:
+    """Get current user and verify admin role"""
+    if current_user.get("role") != "admin":
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Not authorized. Admin access required."
+        )
+    return current_user
+
+
+@router.post("/register", response_model=schemas.TokenOut, status_code=status.HTTP_201_CREATED)
+@limiter.limit("3/minute")
+def register(
+    request: Request, 
+    user_data: schemas.UserCreate, 
+    db=Depends(get_mongo),
+    x_device_fingerprint: Optional[str] = Header(None)
+):
+    """
+    Register a new user with OTP verification and create session
+    Creates user account, wallet, and device-bound session automatically
+    Rate limited to 3 attempts per minute per IP
+    
+    NOTE: User must verify OTP via /otp/verify-otp before calling this endpoint
+    """
+    logger.info(f"Registration request for: {mask_email(user_data.email)}")
+    
+    # Sanitize inputs
+    user_data.name = sanitize_input(user_data.name).strip()
+    user_data.email = sanitize_input(user_data.email).lower().strip()
+    user_data.country_code = sanitize_input(user_data.country_code).strip()
+    user_data.phone = sanitize_input(user_data.phone).strip()
+    
+    # Additional validation
+    if not re.match(r"^[a-zA-Z\s\-']+$", user_data.name):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Name can only contain letters, spaces, hyphens, and apostrophes"
+        )
+    
+    if not re.match(r"^\+[0-9]{1,4}$", user_data.country_code):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid country code format. Must start with + and contain 1-4 digits"
+        )
+    
+    if not re.match(r"^[0-9]{6,15}$", user_data.phone):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Phone number must be 6-15 digits"
+        )
+    
+    if not user_data.email or '@' not in user_data.email:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid email format"
+        )
+    
+    # Check if user already exists
+    existing_user = repo.get_user_by_email(db, user_data.email)
+    if existing_user:
+        logger.warning(f"Registration failed - user already exists: {mask_email(user_data.email)}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Email already registered"
+        )
+    
+    # Verify OTP was validated (check if verified OTP exists)
+    import repo_otp
+    otp_doc = db.otps.find_one({
+        "email": user_data.email.lower(),
+        "purpose": "registration",
+        "verified": True
+    })
+    
+    if not otp_doc:
+        logger.warning(f"Registration failed - OTP not verified for: {mask_email(user_data.email)}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Please verify your email with OTP first"
+        )
+    
+    # Create user
+    hashed_pwd = hash_password(user_data.password)
+    user = repo.create_user(
+        db,
+        name=user_data.name,
+        email=user_data.email,
+        password_hash=hashed_pwd,
+        country_code=user_data.country_code,
+        phone=user_data.phone,
+        role=user_data.role.value if user_data.role else "user"
+    )
+    
+    logger.info(f"User created: {mask_email(user['email'])}")
+    
+    # Create AED wallet for the user (XRP can be added/imported later via wallet endpoints)
+    wallet = repo.create_wallet(db, user['id'], balance=0.0, currency="AED")
+    logger.info("User wallet created")
+    
+    logger.debug(f"Wallet created for user: {wallet['id']}")
+    
+    # Delete the verified OTP
+    repo_otp.delete_otp(db, user_data.email.lower(), "registration")
+    
+    # Generate device fingerprint
+    device_fingerprint = generate_device_fingerprint(request, x_device_fingerprint)
+    
+    # Create access token with session_id placeholder (will be updated)
+    token_expiry = timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+    expires_at = datetime.utcnow() + token_expiry
+    
+    # Create JWT token
+    access_token = create_access_token(data={"sub": user['id'], "role": user['role']})
+    
+    # Generate session ID
+    session_id = generate_session_id(user['id'], access_token, device_fingerprint)
+    
+    # Create token with session_id
+    access_token = create_access_token(
+        data={"sub": user['id'], "role": user['role'], "session_id": session_id}
+    )
+    
+    # Create session in database
+    repo.create_session(
+        db=db,
+        session_id=session_id,
+        user_id=user['id'],
+        device_fingerprint=device_fingerprint,
+        token=access_token,
+        expires_at=expires_at
+    )
+    
+    logger.info(f"Registration successful for: {mask_email(user_data.email)}")
+    
+    # Log successful registration
+    client_ip = request.client.host if request.client else "unknown"
+    log_registration(user_data.email, client_ip, success=True)
+    
+    return schemas.TokenOut(
+        access_token=access_token,
+        token_type="bearer",
+        user_role=schemas.UserRole(user['role']),
+        user=schemas.UserOut(**user)
+    )
+
+
+@router.post("/login", response_model=schemas.TokenOut)
+@limiter.limit("5/minute")
+def login(
+    request: Request, 
+    form_data: OAuth2PasswordRequestForm = Depends(), 
+    db=Depends(get_mongo),
+    x_device_fingerprint: Optional[str] = Header(None)
+):
+    """
+    User login endpoint with OTP verification and session management
+    Returns JWT token with device-bound session
+    Rate limited to 5 attempts per minute per IP
+    Implements account lockout after 5 failed attempts
+    
+    NOTE: User must verify OTP via /otp/verify-otp before calling this endpoint
+    """
+    logger.info(f"Login attempt for: {mask_email(form_data.username)}")
+    
+    # Get client IP
+    client_ip = request.client.host if request.client else "unknown"
+    
+    # Check rate limit for failed attempts
+    if not check_rate_limit(client_ip, "login", max_attempts=5, window_minutes=15):
+        logger.warning(f"Account locked due to too many failed attempts: {mask_email(form_data.username)}")
+        log_account_lockout(form_data.username, client_ip, duration_minutes=15)
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail="Account temporarily locked due to too many failed login attempts. Please try again in 15 minutes.",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    
+    # Get user by email (username field contains email)
+    user = repo.get_user_by_email(db, form_data.username)
+    
+    if not user:
+        logger.warning(f"Login failed - user not found: {mask_email(form_data.username)}")
+        record_failed_attempt(client_ip, "login")
+        log_login_attempt(form_data.username, client_ip, success=False, reason="User not found")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Incorrect email or password",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    
+    # Verify password
+    if not verify_password(form_data.password, user['password_hash']):
+        logger.warning(f"Login failed - invalid password for: {mask_email(form_data.username)}")
+        record_failed_attempt(client_ip, "login")
+        log_login_attempt(form_data.username, client_ip, success=False, reason="Invalid password")
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Incorrect email or password",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    
+    # Check if user is active
+    if not user.get('is_active'):
+        logger.warning(f"Login failed - inactive user: {mask_email(form_data.username)}")
+        log_login_attempt(form_data.username, client_ip, success=False, reason="Inactive account")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Account is inactive"
+        )
+    
+    # Verify OTP was validated (check if verified OTP exists)
+    import repo_otp
+    otp_doc = db.otps.find_one({
+        "email": form_data.username.lower(),
+        "purpose": "login",
+        "verified": True
+    })
+    
+    if not otp_doc:
+        logger.warning(f"Login failed - OTP not verified for: {mask_email(form_data.username)}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Please verify your email with OTP first"
+        )
+    
+    # Delete the verified OTP
+    repo_otp.delete_otp(db, form_data.username.lower(), "login")
+    
+    # Reset failed attempts on successful login
+    reset_failed_attempts(client_ip, "login")
+    
+    # Generate device fingerprint
+    device_fingerprint = generate_device_fingerprint(request, x_device_fingerprint)
+    
+    # Create token expiry
+    token_expiry = timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+    expires_at = datetime.utcnow() + token_expiry
+    
+    # Create JWT token
+    access_token = create_access_token(data={"sub": user['id'], "role": user['role']})
+    
+    # Generate session ID
+    session_id = generate_session_id(user['id'], access_token, device_fingerprint)
+    
+    # Create token with session_id
+    access_token = create_access_token(
+        data={"sub": user['id'], "role": user['role'], "session_id": session_id}
+    )
+    
+    # Create session in database
+    repo.create_session(
+        db=db,
+        session_id=session_id,
+        user_id=user['id'],
+        device_fingerprint=device_fingerprint,
+        token=access_token,
+        expires_at=expires_at
+    )
+    
+    logger.info(f"Login successful for: {mask_email(form_data.username)} (Role: {user['role']})")
+    
+    # Log successful login
+    log_login_attempt(form_data.username, client_ip, success=True)
+    
+    return schemas.TokenOut(
+        access_token=access_token,
+        token_type="bearer",
+        user_role=schemas.UserRole(user['role']),
+        user=schemas.UserOut(**user)
+    )
+
+
+@router.get("/me", response_model=schemas.UserOut)
+def get_current_user_info(current_user: dict = Depends(get_current_user)):
+    """
+    Get current user information
+    This endpoint validates the session and device fingerprint automatically
+    """
+    return schemas.UserOut(**current_user)
+
+
+@router.post("/logout")
+def logout(
+    request: Request,
+    token: str = Depends(oauth2_scheme),
+    db=Depends(get_mongo)
+):
+    """
+    Logout user and invalidate current session
+    """
+    try:
+        payload = jwt.decode(token, settings.SECRET_KEY, algorithms=[settings.ALGORITHM])
+        session_id = payload.get("session_id")
+        user_id = payload.get("sub")
+        
+        if session_id:
+            repo.invalidate_session(db, session_id)
+            logger.info(f"User logged out: {user_id}")
+            return {"message": "Logged out successfully"}
+        else:
+            # Old token without session_id
+            return {"message": "Logged out successfully (legacy token)"}
+            
+    except JWTError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid token"
+        )
+
+
+@router.post("/logout-all")
+def logout_all_devices(
+    current_user: dict = Depends(get_current_user),
+    db=Depends(get_mongo)
+):
+    """
+    Logout user from all devices by invalidating all sessions
+    """
+    count = repo.invalidate_user_sessions(db, current_user['id'])
+    logger.info(f"Invalidated {count} sessions for user: {current_user['id']}")
+    return {"message": f"Logged out from {count} device(s) successfully"}
+
+
+@router.get("/sessions")
+def get_active_sessions(
+    current_user: dict = Depends(get_current_user),
+    db=Depends(get_mongo)
+):
+    """
+    Get all active sessions for the current user
+    """
+    sessions = repo.get_user_active_sessions(db, current_user['id'])
+    
+    # Clean sensitive data
+    cleaned_sessions = []
+    for session in sessions:
+        cleaned_sessions.append({
+            "session_id": session.get("session_id"),
+            "created_at": session.get("created_at"),
+            "last_activity": session.get("last_activity"),
+            "expires_at": session.get("expires_at")
+        })
+    
+    return {"sessions": cleaned_sessions, "total": len(cleaned_sessions)}
+
+
+@router.post("/refresh", response_model=schemas.TokenOut)
+@limiter.limit("10/hour")
+def refresh_token(
+    request: Request, 
+    token: str = Depends(oauth2_scheme),
+    current_user: dict = Depends(get_current_user)
+):
+    """
+    Refresh access token (maintains same session)
+    Rate limited to 10 refreshes per hour to prevent token abuse
+    """
+    logger.debug(f"Token refresh for user: {mask_email(current_user['email'])}")
+    
+    # Extract existing session_id from current token to maintain session continuity
+    session_id = None
+    try:
+        payload = jwt.decode(token, settings.SECRET_KEY, algorithms=[settings.ALGORITHM])
+        session_id = payload.get("session_id")
+    except JWTError:
+        pass  # If decoding fails, create token without session_id
+    
+    # Create new access token with same session_id
+    token_data = {"sub": current_user['id'], "role": current_user['role']}
+    if session_id:
+        token_data["session_id"] = session_id
+    
+    access_token = create_access_token(data=token_data)
+    
+    return schemas.TokenOut(
+        access_token=access_token,
+        token_type="bearer",
+        user_role=schemas.UserRole(current_user['role']),
+        user=schemas.UserOut(**current_user)
+    )
+
+# Note: duplicate definitions previously present here were removed to prevent
+# accidental overrides. The synchronous get_current_user/get_current_admin above
+# are the canonical accessors used by route dependencies.

routes/market.py

@@ -0,0 +1,1293 @@
+"""
+Production Market Routes
+Handles token purchases and marketplace operations with IOU token transfers
+Implements atomic transactions with blockchain verification
+"""
+from fastapi import APIRouter, Depends, HTTPException, status, Request
+from pymongo.errors import OperationFailure
+from typing import Optional, Dict, Any
+
+import schemas
+from db import get_mongo, get_client
+import repo
+from repo import record_admin_wallet_event
+from routes.auth import get_current_user
+from services.xrp_service import XRPLService
+from config import settings
+from utils.crypto_utils import decrypt_secret
+from middleware.security import limiter
+import re
+import time
+
+# Simple in-memory rate limiter (per-process). Not production-grade but prevents abuse bursts.
+_PURCHASE_WINDOW_SECONDS = 30
+_PURCHASE_MAX_REQUESTS = 5  # max purchases per user per window
+_purchase_events: dict[str, list[float]] = {}
+
+router = APIRouter()
+
+
+@router.post("/market/buy", response_model=schemas.PurchaseResponse)
+@limiter.limit("20/hour")  # Prevent purchase abuse - 20 purchases per hour
+def buy_tokens(
+    request: Request,
+    buy_request: schemas.BuyRequest,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """
+    Purchase property tokens
+    PRODUCTION-READY: Handles database transactions, wallet deductions, and investment tracking
+    
+    This endpoint:
+    1. Validates user wallet balance
+    2. Checks token availability
+    3. Creates investment record
+    4. Deducts from wallet
+    5. Updates property available tokens
+    6. Records all transactions
+    7. Updates user portfolio
+    
+    All operations are atomic when MongoDB transactions are supported
+    """
+    print("\n" + "="*80)
+    print(f"PROCESSING TOKEN PURCHASE")
+    print("="*80)
+    print(f"User: {current_user['name']} ({current_user['email']})")
+    print(f"Property ID: {buy_request.property_id}")
+    print(f"Tokens to buy: {buy_request.amount_tokens}")
+    print(f"Payment method: {buy_request.payment_method}")
+    
+    # ========================================================================
+    # KYC CHECK - User must have approved KYC to purchase
+    # ========================================================================
+    print("\n[KYC CHECK] Verifying user KYC status...")
+    user_kyc_status = current_user.get('kyc_status', 'pending')
+    
+    if user_kyc_status != 'approved':
+        print(f"[KYC CHECK] [ERROR] KYC not approved. Status: {user_kyc_status}")
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="KYC verification required. Please complete your KYC verification before purchasing tokens."
+        )
+    
+    print(f"[KYC CHECK] [SUCCESS] KYC approved. User can proceed with purchase.")
+    
+    # ========================================================================
+    # RATE LIMIT CHECK (lightweight, per user)
+    # ========================================================================
+    now = time.time()
+    evts = _purchase_events.get(current_user['id'], [])
+    # prune old
+    evts = [t for t in evts if now - t <= _PURCHASE_WINDOW_SECONDS]
+    if len(evts) >= _PURCHASE_MAX_REQUESTS:
+        raise HTTPException(status_code=429, detail="Too many purchase attempts, please slow down")
+    evts.append(now)
+    _purchase_events[current_user['id']] = evts
+
+    # ========================================================================
+    # STEP 1: Validate Property
+    # ========================================================================
+    print("\n[STEP 1] Validating property...")
+    property_obj = repo.get_property_by_id(db, buy_request.property_id)
+    
+    if not property_obj:
+        print(f"[ERROR] ERROR: Property not found: {buy_request.property_id}\n")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Property not found"
+        )
+    
+    if not property_obj.get('is_active'):
+        print(f"[ERROR] ERROR: Property is not active\n")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Property is not available for purchase"
+        )
+    
+    print(f"[SUCCESS] Property validated: {property_obj['title']}")
+    print(f"  Available tokens: {property_obj['available_tokens']}")
+    print(f"  Token price: {property_obj['token_price']} AED")
+    
+    # ========================================================================
+    # STEP 2: Check Token Availability
+    # ========================================================================
+    print("\n[STEP 2] Checking token availability...")
+    
+    if buy_request.amount_tokens > property_obj['available_tokens']:
+        print(f"[ERROR] ERROR: Not enough tokens available")
+        print(f"  Requested: {buy_request.amount_tokens}")
+        print(f"  Available: {property_obj['available_tokens']}\n")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Only {property_obj['available_tokens']} tokens available"
+        )
+    
+    print(f"[SUCCESS] Tokens available: {buy_request.amount_tokens} tokens OK")
+    
+    # ========================================================================
+    # STEP 3: Calculate Total Cost
+    # ========================================================================
+    print("\n[STEP 3] Calculating purchase cost...")
+    
+    total_cost = buy_request.amount_tokens * property_obj['token_price']
+    
+    # Check minimum investment
+    if total_cost < property_obj.get('min_investment', 2000.0):
+        print(f"[ERROR] ERROR: Investment below minimum")
+        print(f"  Total cost: {total_cost} AED")
+        print(f"  Minimum required: {property_obj.get('min_investment', 2000.0)} AED\n")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Minimum investment is {property_obj.get('min_investment', 2000.0)} AED"
+        )
+    
+    print(f"[SUCCESS] Purchase cost calculated:")
+    print(f"  Tokens: {buy_request.amount_tokens}")
+    print(f"  Price per token: {property_obj['token_price']} AED")
+    print(f"  Total cost: {total_cost} AED")
+    
+    # ========================================================================
+    # STEP 4: Validate Wallet Balance
+    # ========================================================================
+    print("\n[STEP 4] Validating wallet balance...")
+    
+    wallet = repo.get_wallet_by_user(db, current_user['id'])
+    
+    if not wallet:
+        print(f"[ERROR] ERROR: Wallet not found for user\n")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Wallet not found. Please contact support."
+        )
+    
+    if wallet['balance'] < total_cost:
+        print(f"[ERROR] ERROR: Insufficient wallet balance")
+        print(f"  Current balance: {wallet['balance']} AED")
+        print(f"  Required: {total_cost} AED")
+        print(f"  Shortfall: {total_cost - wallet['balance']} AED\n")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Insufficient balance. You need {total_cost} AED but have {wallet['balance']} AED"
+        )
+    
+    print(f"[SUCCESS] Wallet balance sufficient:")
+    print(f"  Current balance: {wallet['balance']} AED")
+    print(f"  After purchase: {wallet['balance'] - total_cost} AED")
+    
+    # ========================================================================
+    # STEP 5: Calculate Ownership Percentage
+    # ========================================================================
+    print("\n[STEP 5] Calculating ownership details...")
+    
+    ownership_percentage = (buy_request.amount_tokens / property_obj['total_tokens']) * 100
+    
+    # Check if user already has investment in this property
+    existing_investment = repo.get_investment_by_user_and_property(
+        db, current_user['id'], buy_request.property_id
+    )
+    
+    total_tokens_after = buy_request.amount_tokens
+    if existing_investment:
+        total_tokens_after += existing_investment.get('tokens_purchased', 0)
+    
+    total_ownership = (total_tokens_after / property_obj['total_tokens']) * 100
+    
+    print(f"[SUCCESS] Ownership calculated:")
+    print(f"  New tokens: {buy_request.amount_tokens}")
+    print(f"  New ownership: {ownership_percentage:.4f}%")
+    if existing_investment:
+        print(f"  Previous tokens: {existing_investment.get('tokens_purchased', 0)}")
+        print(f"  Total tokens: {total_tokens_after}")
+        print(f"  Total ownership: {total_ownership:.4f}%")
+    
+    # ========================================================================
+    # STEP 6: Execute Purchase (Atomic Transaction)
+    # ========================================================================
+    print("\n[STEP 6] Executing purchase transaction...")
+    
+    client = get_client()
+    investment_id = None
+    transaction_id = None
+    blockchain_tx_hash = None
+    
+    # ========================================================================
+    # CRITICAL: BLOCKCHAIN-FIRST APPROACH
+    # Execute blockchain transaction BEFORE database updates
+    # This ensures we never take user's money without giving them tokens
+    # ========================================================================
+    
+    # Respect feature flag for on-ledger purchases
+    if not settings.XRPL_LEDGER_PURCHASE_ENABLED:
+        print("[BLOCKCHAIN] [ERROR] On-ledger purchases are disabled by configuration (XRPL_LEDGER_PURCHASE_ENABLED=False)")
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="On-ledger purchases are temporarily disabled. Please try again later."
+        )
+
+    print("\n[BLOCKCHAIN] Executing on-ledger token purchase...")
+    print(f"  Token Model: {settings.XRPL_TOKEN_MODEL}")
+    
+    # Get property token information
+    property_token = repo.get_property_token(db, buy_request.property_id)
+    
+    if not property_token or not property_token.get('currency_code'):
+        print(f"[ERROR] ERROR: Property not tokenized on blockchain")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="This property has not been tokenized on the blockchain yet. Please contact support."
+        )
+    
+    currency_code = property_token['currency_code']
+    issuer_address = property_token.get('issuer_address')
+    
+    if not issuer_address:
+        print(f"[ERROR] ERROR: No issuer address for property tokens")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Property token issuer not configured. Please contact support."
+        )
+    
+    # Get user's XRP wallet
+    user_xrp_address = wallet.get('xrp_address')
+    encrypted_user_seed = wallet.get('xrp_seed')
+    
+    if not user_xrp_address or not encrypted_user_seed:
+        print(f"[ERROR] ERROR: User does not have XRP wallet")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="You need an XRP wallet to purchase tokens. Please create one in your wallet settings."
+        )
+    
+    # Decrypt the user's XRP seed
+    print(f"[DEBUG] Encrypted seed starts with: {encrypted_user_seed[:20] if encrypted_user_seed else 'None'}...")
+    user_xrp_seed = decrypt_secret(encrypted_user_seed, settings.ENCRYPTION_KEY)
+    print(f"[DEBUG] Decrypted seed starts with: {user_xrp_seed[:5] if user_xrp_seed else 'None'}...")
+    
+    if not user_xrp_seed:
+        print(f"[ERROR] ERROR: Failed to decrypt user's XRP wallet seed")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Wallet decryption failed. Please contact support."
+        )
+    
+    # Calculate XRP cost for the purchase
+    from services.xrp_service import xrpl_service
+    from services.property_wallet_manager import property_wallet_manager
+    xrp_cost = xrpl_service.calculate_xrp_cost(buy_request.amount_tokens, property_obj['token_price'])
+    
+    # Get property's dedicated issuer seed (encrypted)
+    encrypted_issuer_seed = property_token.get('encrypted_issuer_seed')
+    issuer_seed = None
+    
+    if encrypted_issuer_seed:
+        try:
+            issuer_seed = property_wallet_manager._decrypt_seed(encrypted_issuer_seed)
+            print(f"[BLOCKCHAIN] Using property's dedicated wallet")
+        except Exception as e:
+            print(f"[BLOCKCHAIN] Warning: Could not decrypt property wallet seed: {e}")
+            print(f"[BLOCKCHAIN] Will attempt to use master wallet if available")
+    
+    print(f"\n[BLOCKCHAIN] Purchase Details:")
+    print(f"  Currency Code: {currency_code}")
+    print(f"  Issuer: {issuer_address}")
+    print(f"  Buyer: {user_xrp_address}")
+    print(f"  Token Amount: {buy_request.amount_tokens}")
+    print(f"  XRP Cost: {xrp_cost} XRP")
+    print(f"  AED Equivalent: {total_cost} AED")
+    print(f"  Wallet Type: {'Dedicated Property Wallet' if issuer_seed else 'Master Wallet'}")
+    
+    # Execute blockchain purchase (this will handle trustline setup and token transfer)
+    try:
+        blockchain_result = xrpl_service.purchase_tokens_with_xrp(
+            buyer_seed=user_xrp_seed,
+            currency=currency_code,
+            issuer=issuer_address,
+            token_amount=buy_request.amount_tokens,
+            xrp_cost=xrp_cost,
+            issuer_seed=issuer_seed  # Pass property's dedicated seed
+        )
+        
+        if not blockchain_result.get('success'):
+            error_msg = blockchain_result.get('error', 'Unknown blockchain error')
+            print(f"[ERROR] BLOCKCHAIN TRANSACTION FAILED: {error_msg}")
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Blockchain transaction failed: {error_msg}"
+            )
+        
+        blockchain_tx_hash = blockchain_result.get('token_tx_hash') or blockchain_result.get('payment_tx_hash')
+        print(f"✅ BLOCKCHAIN TRANSACTION SUCCESS!")
+        print(f"  Transaction Hash: {blockchain_tx_hash}")
+        print(f"  Payment TX: {blockchain_result.get('payment_tx_hash')}")
+        print(f"  Token TX: {blockchain_result.get('token_tx_hash')}")
+        
+    except HTTPException:
+        raise
+    except Exception as blockchain_error:
+        print(f"[ERROR] BLOCKCHAIN ERROR: {blockchain_error}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Blockchain transaction failed: {str(blockchain_error)}"
+        )
+    
+    # ========================================================================
+    # Now update database - blockchain transaction succeeded
+    # ========================================================================
+    
+    try:
+        # Try to use MongoDB transactions for atomicity
+        with client.start_session() as session:
+            with session.start_transaction():
+                print("  → Starting database transaction...")
+                
+                # 6.1: Deduct from wallet
+                print(f"  → Deducting {total_cost} AED from wallet...")
+                updated_wallet = repo.update_wallet_balance(
+                    db, wallet['id'], total_cost, operation="subtract", session=session
+                )
+                
+                if not updated_wallet:
+                    raise Exception("Failed to deduct from wallet")
+                
+                # 6.2: Decrement available tokens
+                print(f"  → Decrementing {buy_request.amount_tokens} tokens from property...")
+                success = repo.decrement_available_tokens(
+                    db, buy_request.property_id, buy_request.amount_tokens, session=session
+                )
+                
+                if not success:
+                    raise Exception("Failed to decrement available tokens")
+                
+                # 6.3: Create or update investment
+                print(f"  → Creating/updating investment record...")
+                investment = repo.upsert_investment(
+                    db,
+                    user_id=current_user['id'],
+                    property_id=buy_request.property_id,
+                    tokens_purchased=buy_request.amount_tokens,
+                    amount=total_cost,
+                    session=session
+                )
+                investment_id = investment['id']
+                
+                # 6.4: Create purchase transaction
+                print(f"  → Recording purchase transaction...")
+                transaction = repo.create_transaction(
+                    db,
+                    user_id=current_user['id'],
+                    wallet_id=wallet['id'],
+                    tx_type="investment",
+                    amount=total_cost,
+                    property_id=buy_request.property_id,
+                    status="completed",
+                    metadata={
+                        "tokens_purchased": buy_request.amount_tokens,
+                        "token_price": property_obj['token_price'],
+                        "property_name": property_obj['title'],
+                        "ownership_percentage": ownership_percentage,
+                        "payment_method": buy_request.payment_method,
+                        "blockchain_tx_hash": blockchain_tx_hash,
+                        "currency_code": currency_code,
+                        "issuer_address": issuer_address,
+                        "xrp_cost": xrp_cost
+                    },
+                    session=session
+                )
+                transaction_id = transaction['id']
+
+                # Mirror admin wallet credit event (platform receives funds) in fils
+                try:
+                    record_admin_wallet_event(
+                        db,
+                        delta_fils=int(total_cost * 100),
+                        event_type="admin_wallet_credit_purchase",
+                        notes=f"Received AED {total_cost:.2f} from {current_user.get('name')} for {buy_request.amount_tokens} tokens of {property_obj.get('title')}",
+                        counterparty_user=current_user,
+                        property_obj=property_obj,
+                        payment_method=buy_request.payment_method,
+                        payment_reference=f"INVEST_{buy_request.property_id}_{buy_request.amount_tokens}",
+                        metadata={
+                            "amount": buy_request.amount_tokens,
+                            "price_per_token": property_obj['token_price'],
+                            "blockchain_tx_hash": blockchain_tx_hash,
+                        },
+                        session=session,
+                    )
+                except Exception as admin_evt_err:
+                    print(f"[MARKET] ⚠ Failed to record admin wallet event: {admin_evt_err}")
+                
+                # 6.5: Update portfolio
+                print(f"  → Updating user portfolio...")
+                repo.create_or_update_portfolio(db, current_user['id'], session=session)
+                
+                print("  [SUCCESS] Database transaction committed successfully!")
+                
+    except OperationFailure as e:
+        # Fallback for standalone MongoDB (no transaction support)
+        if "Transaction numbers" in str(e) or "replica set" in str(e):
+            print("  ⚠ Transactions not supported, executing sequentially...")
+            
+            # Execute without session (less safe but works)
+            updated_wallet = repo.update_wallet_balance(
+                db, wallet['id'], total_cost, operation="subtract"
+            )
+            
+            if not updated_wallet:
+                raise HTTPException(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail="Failed to deduct from wallet"
+                )
+            
+            success = repo.decrement_available_tokens(
+                db, buy_request.property_id, buy_request.amount_tokens
+            )
+            
+            if not success:
+                # Rollback wallet deduction
+                repo.update_wallet_balance(db, wallet['id'], total_cost, operation="add")
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="Failed to reserve tokens"
+                )
+            
+            investment = repo.upsert_investment(
+                db,
+                user_id=current_user['id'],
+                property_id=buy_request.property_id,
+                tokens_purchased=buy_request.amount_tokens,
+                amount=total_cost
+            )
+            investment_id = investment['id']
+            
+            transaction = repo.create_transaction(
+                db,
+                user_id=current_user['id'],
+                wallet_id=wallet['id'],
+                tx_type="investment",
+                amount=total_cost,
+                property_id=buy_request.property_id,
+                status="completed",
+                metadata={
+                    "tokens_purchased": buy_request.amount_tokens,
+                    "token_price": property_obj['token_price'],
+                    "property_name": property_obj['title'],
+                    "ownership_percentage": ownership_percentage,
+                    "payment_method": buy_request.payment_method,
+                    "blockchain_tx_hash": blockchain_tx_hash,
+                    "currency_code": currency_code,
+                    "issuer_address": issuer_address,
+                    "xrp_cost": xrp_cost
+                }
+            )
+            transaction_id = transaction['id']
+
+            # Admin wallet credit outside transaction fallback
+            try:
+                record_admin_wallet_event(
+                    db,
+                    delta_fils=int(total_cost * 100),
+                    event_type="admin_wallet_credit_purchase",
+                    notes=f"Received AED {total_cost:.2f} from {current_user.get('name')} for {buy_request.amount_tokens} tokens of {property_obj.get('title')}",
+                    counterparty_user=current_user,
+                    property_obj=property_obj,
+                    payment_method=buy_request.payment_method,
+                    payment_reference=f"INVEST_{buy_request.property_id}_{buy_request.amount_tokens}",
+                    metadata={
+                        "amount": buy_request.amount_tokens,
+                        "price_per_token": property_obj['token_price'],
+                        "blockchain_tx_hash": blockchain_tx_hash,
+                    },
+                )
+            except Exception as admin_evt_err:
+                print(f"[MARKET] ⚠ Failed to record admin wallet event (fallback): {admin_evt_err}")
+            
+            repo.create_or_update_portfolio(db, current_user['id'])
+            
+            print("  [SUCCESS] Sequential execution completed!")
+        else:
+            raise
+    
+    # ========================================================================
+    # STEP 7: Return Success Response
+    # ========================================================================
+    # Get updated investment to calculate total tokens
+    updated_investment = repo.get_investment_by_user_and_property(
+        db, current_user['id'], buy_request.property_id
+    )
+    user_total_tokens = updated_investment.get('tokens_purchased', buy_request.amount_tokens) if updated_investment else buy_request.amount_tokens
+    
+    # Get updated property data
+    updated_property = repo.get_property_by_id(db, buy_request.property_id)
+    tokens_remaining = updated_property.get('available_tokens', 0) if updated_property else 0
+    
+    # Get updated wallet balance
+    updated_wallet_data = repo.get_wallet_by_user(db, current_user['id'])
+    remaining_balance = updated_wallet_data.get('balance', 0) if updated_wallet_data else 0
+    
+    print("\n[STEP 7] Purchase completed successfully!")
+    print("="*80)
+    print("PURCHASE SUMMARY")
+    print("="*80)
+    print(f"Transaction ID: {transaction_id}")
+    print(f"Investment ID: {investment_id}")
+    print(f"Tokens purchased: {buy_request.amount_tokens}")
+    print(f"Total cost: {total_cost} AED")
+    print(f"Ownership: {ownership_percentage:.4f}%")
+    print(f"Your total tokens: {user_total_tokens}")
+    print(f"Tokens remaining: {tokens_remaining}")
+    print(f"Remaining wallet balance: {remaining_balance} AED")
+    print(f"Blockchain TX Hash: {blockchain_tx_hash}")
+    print("="*80 + "\n")
+    
+    return schemas.PurchaseResponse(
+            success=True,
+            message=f"Successfully purchased {buy_request.amount_tokens} tokens on the blockchain!",
+            transaction_id=transaction_id,
+            investment_id=investment_id,
+            tokens_purchased=buy_request.amount_tokens,
+            total_cost_aed=total_cost,
+            aed_wallet_balance=remaining_balance,
+            your_total_tokens=user_total_tokens,
+            tokens_remaining=tokens_remaining,
+            blockchain_tx_hash=blockchain_tx_hash or "",
+            ownership_percentage=ownership_percentage,
+            property_details={
+                "id": property_obj['id'],
+                "title": property_obj['title'],
+                "location": property_obj['location'],
+                "total_tokens": property_obj['total_tokens'],
+                "available_tokens": tokens_remaining,
+                "token_price": property_obj['token_price']
+            }
+        )
+
+
+@router.get("/market/properties/available")
+@limiter.limit("30/minute")  # Prevent API abuse
+def get_available_properties(
+    request: Request,
+    db=Depends(get_mongo),
+    current_user: dict = Depends(get_current_user)
+):
+    """
+    Get all properties with available tokens for purchase
+    Rate Limited: 30 requests per minute to prevent abuse
+    Requires authentication
+    """
+    print("\n[MARKET] Fetching available properties...")
+    
+    # Get all active properties
+    all_properties = repo.list_properties(db, is_active=True, limit=500)
+    
+    # Filter only those with available tokens
+    available = [p for p in all_properties if p.get('available_tokens', 0) > 0]
+    
+    print(f"[MARKET] [SUCCESS] Found {len(available)} properties with available tokens\n")
+    
+    return {
+        "total_available": len(available),
+        "properties": available
+    }
+
+
+@router.post("/market/calculate-cost")
+@limiter.limit("60/minute")  # Allow frequent calculations but prevent abuse
+def calculate_purchase_cost(
+    request: Request,
+    cost_request: dict,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """
+    Calculate the real-time XRP cost for purchasing tokens
+    Used by frontend to show accurate blockchain transaction costs
+    Rate Limited: 60 requests per minute per user
+    """
+    property_id = cost_request.get('property_id')
+    amount_tokens = cost_request.get('amount_tokens', 0)
+    
+    if not property_id or amount_tokens <= 0:
+        raise HTTPException(status_code=400, detail="Invalid property_id or amount_tokens")
+    
+    # Get property details
+    property_obj = repo.get_property_by_id(db, property_id)
+    if not property_obj:
+        raise HTTPException(status_code=404, detail="Property not found")
+    
+    if property_obj.get('available_tokens', 0) < amount_tokens:
+        raise HTTPException(status_code=400, detail="Not enough tokens available")
+    
+    # Calculate costs using live rates
+    from services.xrp_service import xrpl_service
+    xrp_cost = xrpl_service.calculate_xrp_cost(amount_tokens, property_obj['token_price'])
+    aed_cost = amount_tokens * property_obj['token_price']
+    
+    return {
+        "property_id": property_id,
+        "amount_tokens": amount_tokens,
+        "token_price_aed": property_obj['token_price'],
+        "total_cost_aed": aed_cost,
+        "xrp_cost": xrp_cost,
+        "ownership_percentage": (amount_tokens / property_obj['total_tokens']) * 100
+    }
+
+
+@router.post("/market/place-offer", response_model=Dict[str, Any])
+@limiter.limit("10/hour")  # Limit sell-back requests to prevent abuse
+def place_sell_offer(
+    request: Request,
+    sell_request: schemas.PlaceOfferRequest,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """
+    Sell tokens back to admin/issuer
+    User sells their tokens back to the platform for refund
+    Rate Limited: 10 sell requests per hour
+    
+    This endpoint:
+    1. Validates user has enough tokens
+    2. Verifies blockchain balance
+    3. Transfers tokens back to issuer on blockchain
+    4. Refunds user's AED wallet
+    5. Updates investment records
+    6. Updates property available tokens
+    7. Records transaction in transactions table
+    8. Records transaction in secondary_market_transactions table (NEW!)
+    9. Records admin wallet events
+    
+    All operations are atomic with comprehensive history tracking
+    """
+    print(f"\n[SELL OFFER] User {current_user['email']} selling tokens back")
+    print(f"  Property ID: {sell_request.property_id}")
+    print(f"  Amount: {sell_request.amount_tokens} tokens")
+    
+    # ========================================================================
+    # STEP 1: Validate Property
+    # ========================================================================
+    property_obj = repo.get_property_by_id(db, sell_request.property_id)
+    if not property_obj:
+        raise HTTPException(status_code=404, detail="Property not found")
+    
+    # ========================================================================
+    # STEP 2: Validate User Investment
+    # ========================================================================
+    investment = repo.get_investment_by_user_and_property(db, current_user['id'], sell_request.property_id)
+    if not investment:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="You don't own any tokens for this property"
+        )
+    
+    user_tokens = investment.get('tokens_purchased', 0)
+    if sell_request.amount_tokens > user_tokens:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Cannot sell {sell_request.amount_tokens} tokens. You only own {user_tokens} tokens."
+        )
+    
+    # ========================================================================
+    # STEP 3: Get Wallet Information
+    # ========================================================================
+    wallet = repo.get_wallet_by_user(db, current_user['id'])
+    if not wallet:
+        raise HTTPException(status_code=400, detail="Wallet not found")
+    
+    user_xrp_address = wallet.get('xrp_address')
+    encrypted_user_seed = wallet.get('xrp_seed')
+    
+    if not user_xrp_address or not encrypted_user_seed:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="XRP wallet required to sell tokens"
+        )
+    
+    # Decrypt user's wallet seed
+    user_xrp_seed = decrypt_secret(encrypted_user_seed, settings.ENCRYPTION_KEY)
+    if not user_xrp_seed:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to decrypt wallet"
+        )
+    
+    # ========================================================================
+    # STEP 4: Get Property Token Information
+    # ========================================================================
+    property_token = repo.get_property_token(db, sell_request.property_id)
+    if not property_token or not property_token.get('currency_code'):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Property not tokenized on blockchain"
+        )
+    
+    currency_code = property_token['currency_code']
+    issuer_address = property_token.get('issuer_address')
+    encrypted_issuer_seed = property_token.get('encrypted_issuer_seed')
+    
+    if not issuer_address:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Property issuer not configured"
+        )
+    
+    # Get admin user info
+    admin_user = repo.get_user_by_role(db, 'admin')
+    if not admin_user:
+        raise HTTPException(status_code=500, detail="Admin user not found")
+    
+    # Decrypt issuer seed if available
+    issuer_seed = None
+    if encrypted_issuer_seed:
+        try:
+            from services.property_wallet_manager import property_wallet_manager
+            issuer_seed = property_wallet_manager._decrypt_seed(encrypted_issuer_seed)
+        except Exception as e:
+            print(f"[SELL] Warning: Could not decrypt issuer seed: {e}")
+    
+    # ========================================================================
+    # STEP 4.5: VERIFY BLOCKCHAIN BALANCE (CRITICAL!)
+    # ========================================================================
+    print(f"\n[BLOCKCHAIN VERIFICATION] Checking user's on-chain token balance...")
+    
+    from services.xrp_service import xrpl_service
+    
+    try:
+        blockchain_balance = xrpl_service.get_user_token_balance(
+            user_xrp_address,
+            currency_code,
+            issuer_address
+        )
+        blockchain_balance = float(blockchain_balance or 0)
+        
+        print(f"  User XRP Address: {user_xrp_address}")
+        print(f"  Currency: {currency_code}")
+        print(f"  Issuer: {issuer_address}")
+        print(f"  Blockchain Balance: {blockchain_balance} tokens")
+        print(f"  Database Balance: {user_tokens} tokens")
+        print(f"  Trying to Sell: {sell_request.amount_tokens} tokens")
+        
+        if blockchain_balance < sell_request.amount_tokens:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Insufficient blockchain balance. You have {blockchain_balance} tokens on blockchain but trying to sell {sell_request.amount_tokens}. Database shows {user_tokens} tokens. Please use the sync endpoint to fix this issue."
+            )
+        
+        print(f"[BLOCKCHAIN VERIFICATION] ✅ User has sufficient tokens on blockchain")
+    
+    except HTTPException:
+        raise
+    except Exception as e:
+        print(f"[BLOCKCHAIN VERIFICATION] ❌ Error checking balance: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to verify blockchain balance: {str(e)}"
+        )
+    
+    # ========================================================================
+    # STEP 5: Calculate Refund Amount
+    # ========================================================================
+    token_price = property_obj['token_price']
+    refund_amount = sell_request.amount_tokens * token_price
+    
+    print(f"\n[SELL] Refund Calculation:")
+    print(f"  Token Price: {token_price} AED")
+    print(f"  Tokens Selling: {sell_request.amount_tokens}")
+    print(f"  Refund Amount: {refund_amount} AED")
+    
+    # ========================================================================
+    # STEP 6: Execute Blockchain Transfer (Transfer tokens back to issuer)
+    # ========================================================================
+    print(f"\n[BLOCKCHAIN] Transferring tokens back to issuer...")
+    print(f"  Seller: {user_xrp_address}")
+    print(f"  Issuer: {issuer_address}")
+    print(f"  Currency: {currency_code}")
+    print(f"  Amount: {sell_request.amount_tokens}")
+    
+    from services.xrp_service import xrpl_service
+    
+    blockchain_result = xrpl_service.transfer_tokens_to_issuer(
+        seller_seed=user_xrp_seed,
+        currency=currency_code,
+        issuer=issuer_address,
+        token_amount=sell_request.amount_tokens,
+        issuer_seed=issuer_seed
+    )
+    
+    if not blockchain_result.get('success'):
+        error_msg = blockchain_result.get('error', 'Blockchain transfer failed')
+        print(f"[BLOCKCHAIN] ❌ Transfer failed: {error_msg}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to transfer tokens on blockchain: {error_msg}"
+        )
+    
+    blockchain_tx_hash = blockchain_result.get('tx_hash')
+    print(f"[BLOCKCHAIN] ✅ Tokens transferred. TX: {blockchain_tx_hash}")
+    
+    # ========================================================================
+    # STEP 7: Execute Database Updates (Atomic Transaction with History)
+    # ========================================================================
+    print(f"\n[DATABASE] Executing sell transaction with full history tracking...")
+    
+    import uuid
+    from datetime import datetime
+    
+    market_transaction_id = f"MKT-{uuid.uuid4().hex[:12].upper()}"
+    
+    client = get_client()
+    sell_transaction_id = None
+    
+    try:
+        with client.start_session() as session:
+            with session.start_transaction():
+                # 7.1: Create market transaction record (NEW!)
+                market_tx = repo.create_market_transaction(
+                    db,
+                    transaction_id=market_transaction_id,
+                    transaction_type="sell_to_admin",
+                    property_id=sell_request.property_id,
+                    property_title=property_obj.get('title', 'Unknown'),
+                    token_currency=currency_code,
+                    seller_id=current_user['id'],
+                    seller_email=current_user['email'],
+                    seller_xrp_address=user_xrp_address,
+                    buyer_id=admin_user['id'],
+                    buyer_email=admin_user['email'],
+                    buyer_xrp_address=issuer_address,
+                    tokens_amount=sell_request.amount_tokens,
+                    price_per_token=token_price,
+                    total_amount=refund_amount,
+                    blockchain_tx_hash=blockchain_tx_hash,
+                    notes=f"User {current_user['email']} sold {sell_request.amount_tokens} tokens back to admin",
+                    session=session
+                )
+                print(f"[DATABASE] ✅ Market transaction created: {market_transaction_id}")
+                
+                # 7.2: Reduce user's investment
+                updated_investment = repo.reduce_investment(
+                    db, 
+                    current_user['id'], 
+                    sell_request.property_id, 
+                    sell_request.amount_tokens,
+                    session=session
+                )
+                
+                if not updated_investment:
+                    raise HTTPException(
+                        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                        detail="Failed to update investment"
+                    )
+                print(f"[DATABASE] ✅ Investment reduced")
+                
+                # 7.3: Refund user's AED wallet
+                updated_wallet = repo.update_wallet_balance(
+                    db,
+                    wallet['id'],
+                    refund_amount,
+                    session=session
+                )
+                
+                if not updated_wallet:
+                    raise HTTPException(
+                        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                        detail="Failed to refund wallet"
+                    )
+                print(f"[DATABASE] ✅ Wallet refunded: {refund_amount} AED")
+                
+                # 7.4: Increase property available tokens
+                new_available = property_obj.get('available_tokens', 0) + sell_request.amount_tokens
+                repo.update_property(
+                    db,
+                    sell_request.property_id,
+                    {'available_tokens': new_available},
+                    session=session
+                )
+                print(f"[DATABASE] ✅ Property updated: {new_available} tokens available")
+                
+                # 7.5: Record sell transaction
+                sell_transaction = repo.create_transaction(
+                    db,
+                    user_id=current_user['id'],
+                    wallet_id=wallet['id'],
+                    tx_type='token_buyback',
+                    amount=refund_amount,
+                    property_id=sell_request.property_id,
+                    status='completed',
+                    metadata={
+                        'tokens_sold': sell_request.amount_tokens,
+                        'token_price': token_price,
+                        'blockchain_tx_hash': blockchain_tx_hash,
+                        'issuer_address': issuer_address,
+                        'seller_address': user_xrp_address,
+                        'market_transaction_id': market_transaction_id
+                    },
+                    session=session
+                )
+                sell_transaction_id = sell_transaction['id']
+                print(f"[DATABASE] ✅ Sell transaction recorded: {sell_transaction_id}")
+                
+                # 7.6: Record admin wallet credit event
+                record_admin_wallet_event(
+                    db,
+                    delta_fils=int(refund_amount),  # Convert AED to fils (admin wallet uses AED but function expects delta_fils)
+                    event_type='token_buyback',
+                    notes=f"User {current_user['email']} sold {sell_request.amount_tokens} tokens back to admin",
+                    property_obj=property_obj,
+                    metadata={
+                        'tokens_bought_back': sell_request.amount_tokens,
+                        'refund_amount': refund_amount,
+                        'blockchain_tx_hash': blockchain_tx_hash,
+                        'transaction_id': sell_transaction_id,
+                        'market_transaction_id': market_transaction_id,
+                        'user_id': current_user['id'],
+                        'property_id': sell_request.property_id
+                    },
+                    session=session
+                )
+                print(f"[DATABASE] ✅ Admin wallet event recorded")
+                
+                # 7.7: Update market transaction with database update flags
+                repo.update_market_transaction_status(
+                    db,
+                    market_transaction_id,
+                    status="completed",
+                    db_updates={
+                        "investment_updated": True,
+                        "wallet_updated": True,
+                        "property_updated": True,
+                        "transaction_recorded": True
+                    },
+                    session=session
+                )
+                print(f"[DATABASE] ✅ Market transaction status updated to completed")
+                print(f"[DATABASE] ✅ Market transaction status updated to completed")
+                
+                print(f"[DATABASE] ✅ All updates committed successfully")
+    
+    except Exception as e:
+        print(f"[DATABASE] ❌ Transaction failed: {str(e)}")
+        
+        # Try to mark market transaction as failed
+        try:
+            repo.update_market_transaction_status(
+                db,
+                market_transaction_id,
+                status="failed",
+                error_message=str(e)
+            )
+        except:
+            pass
+        
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Database transaction failed: {str(e)}"
+        )
+    
+    # ========================================================================
+    # STEP 8: Return Success Response
+    # ========================================================================
+    remaining_tokens = user_tokens - sell_request.amount_tokens
+    new_wallet_balance = updated_wallet['balance']
+    
+    print(f"\n[SELL OFFER] ✅ Sale completed successfully!")
+    print(f"  Market Transaction ID: {market_transaction_id}")
+    print(f"  Wallet Transaction ID: {sell_transaction_id}")
+    print(f"  Tokens Sold: {sell_request.amount_tokens}")
+    print(f"  Refund: {refund_amount} AED")
+    print(f"  Remaining Tokens: {remaining_tokens}")
+    print(f"  New Wallet Balance: {new_wallet_balance} AED")
+    
+    return {
+        'success': True,
+        'message': f'Successfully sold {sell_request.amount_tokens} tokens!',
+        'market_transaction_id': market_transaction_id,
+        'transaction_id': sell_transaction_id,
+        'tokens_sold': sell_request.amount_tokens,
+        'refund_amount': refund_amount,
+        'token_price': token_price,
+        'remaining_tokens': remaining_tokens,
+        'wallet_balance': new_wallet_balance,
+        'blockchain_tx_hash': blockchain_tx_hash,
+        'property_available_tokens': new_available
+    }
+
+
+@router.post("/market/sync-balance", response_model=schemas.SyncBalanceResponse)
+@limiter.limit("5/hour")  # Limit sync requests
+def sync_balance_with_blockchain(
+    request: Request,
+    sync_request: schemas.SyncBalanceRequest,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """
+    Sync database token balance with blockchain balance
+    This fixes sync issues where database and blockchain balances don't match
+    Rate Limited: 5 sync requests per hour
+    
+    This endpoint:
+    1. Fetches actual blockchain balance
+    2. Compares with database balance
+    3. Updates database to match blockchain (source of truth)
+    4. Records sync transaction for audit trail
+    """
+    print(f"\n[SYNC BALANCE] User {current_user['email']} syncing balance")
+    print(f"  Property ID: {sync_request.property_id}")
+    
+    # ========================================================================
+    # STEP 1: Validate Property
+    # ========================================================================
+    property_obj = repo.get_property_by_id(db, sync_request.property_id)
+    if not property_obj:
+        raise HTTPException(status_code=404, detail="Property not found")
+    
+    # ========================================================================
+    # STEP 2: Get User Investment
+    # ========================================================================
+    investment = repo.get_investment_by_user_and_property(db, current_user['id'], sync_request.property_id)
+    if not investment:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="You don't have any investment in this property"
+        )
+    
+    db_balance_before = investment.get('tokens_purchased', 0)
+    
+    # ========================================================================
+    # STEP 3: Get Wallet and Token Information
+    # ========================================================================
+    wallet = repo.get_wallet_by_user(db, current_user['id'])
+    if not wallet or not wallet.get('xrp_address'):
+        raise HTTPException(status_code=400, detail="XRP wallet not found")
+    
+    property_token = repo.get_property_token(db, sync_request.property_id)
+    if not property_token or not property_token.get('currency_code'):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Property not tokenized on blockchain"
+        )
+    
+    user_xrp_address = wallet['xrp_address']
+    currency_code = property_token['currency_code']
+    issuer_address = property_token['issuer_address']
+    
+    # ========================================================================
+    # STEP 4: Fetch Blockchain Balance (Source of Truth)
+    # ========================================================================
+    print(f"\n[SYNC] Fetching blockchain balance...")
+    print(f"  User XRP Address: {user_xrp_address}")
+    print(f"  Currency: {currency_code}")
+    print(f"  Issuer: {issuer_address}")
+    print(f"  Database Balance: {db_balance_before} tokens")
+    
+    from services.xrp_service import xrpl_service
+    
+    try:
+        blockchain_balance = xrpl_service.get_user_token_balance(
+            user_xrp_address,
+            currency_code,
+            issuer_address
+        )
+        blockchain_balance = float(blockchain_balance or 0)
+        blockchain_balance_int = int(blockchain_balance)
+        
+        print(f"  Blockchain Balance: {blockchain_balance} tokens")
+    
+    except Exception as e:
+        print(f"[SYNC] ❌ Error fetching blockchain balance: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to fetch blockchain balance: {str(e)}"
+        )
+    
+    # ========================================================================
+    # STEP 5: Compare and Sync
+    # ========================================================================
+    if db_balance_before == blockchain_balance_int and not sync_request.force_sync:
+        print(f"[SYNC] ℹ️ Balances already match, no sync needed")
+        return {
+            "success": True,
+            "property_id": sync_request.property_id,
+            "property_title": property_obj.get('title', 'Unknown'),
+            "user_id": current_user['id'],
+            "db_balance_before": db_balance_before,
+            "blockchain_balance": blockchain_balance,
+            "db_balance_after": db_balance_before,
+            "tokens_adjusted": 0,
+            "was_out_of_sync": False,
+            "sync_action": "no_change",
+            "message": "Balances already match. No sync needed."
+        }
+    
+    tokens_adjusted = blockchain_balance_int - db_balance_before
+    sync_action = "increased" if tokens_adjusted > 0 else ("decreased" if tokens_adjusted < 0 else "no_change")
+    
+    print(f"\n[SYNC] Syncing database to match blockchain...")
+    print(f"  Adjustment: {tokens_adjusted:+d} tokens")
+    print(f"  Action: {sync_action}")
+    
+    # ========================================================================
+    # STEP 6: Update Database
+    # ========================================================================
+    client = get_client()
+    
+    try:
+        with client.start_session() as session:
+            with session.start_transaction():
+                # Update investment
+                repo.update_investment(
+                    db,
+                    investment['id'],
+                    {'tokens_purchased': blockchain_balance_int},
+                    session=session
+                )
+                
+                # Record sync transaction
+                repo.create_transaction(
+                    db,
+                    user_id=current_user['id'],
+                    wallet_id=wallet['id'],
+                    tx_type='wallet_add' if tokens_adjusted > 0 else 'wallet_deduct',
+                    amount=0,  # No monetary transaction
+                    property_id=sync_request.property_id,
+                    status='completed',
+                    metadata={
+                        'sync_operation': True,
+                        'db_balance_before': db_balance_before,
+                        'blockchain_balance': blockchain_balance,
+                        'tokens_adjusted': tokens_adjusted,
+                        'sync_action': sync_action,
+                        'forced_sync': sync_request.force_sync
+                    },
+                    session=session
+                )
+                
+                print(f"[SYNC] ✅ Database updated successfully")
+    
+    except Exception as e:
+        print(f"[SYNC] ❌ Database update failed: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Failed to sync database: {str(e)}"
+        )
+    
+    # ========================================================================
+    # STEP 7: Return Success Response
+    # ========================================================================
+    print(f"\n[SYNC] ✅ Balance sync completed!")
+    print(f"  Before: {db_balance_before} tokens")
+    print(f"  After: {blockchain_balance_int} tokens")
+    print(f"  Adjusted: {tokens_adjusted:+d} tokens")
+    
+    return {
+        "success": True,
+        "property_id": sync_request.property_id,
+        "property_title": property_obj.get('title', 'Unknown'),
+        "user_id": current_user['id'],
+        "db_balance_before": db_balance_before,
+        "blockchain_balance": blockchain_balance,
+        "db_balance_after": blockchain_balance_int,
+        "tokens_adjusted": tokens_adjusted,
+        "was_out_of_sync": True,
+        "sync_action": sync_action,
+        "message": f"Balance synced successfully. Adjusted {tokens_adjusted:+d} tokens to match blockchain."
+    }
+
+
+@router.get("/market/history", response_model=schemas.MarketHistoryResponse)
+@limiter.limit("30/hour")
+def get_market_history(
+    request: Request,
+    transaction_type: Optional[str] = None,
+    status: Optional[str] = None,
+    limit: int = 100,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """
+    Get user's secondary market transaction history
+    Shows all sell/buy transactions in the secondary market
+    Rate Limited: 30 requests per hour
+    """
+    print(f"\n[MARKET HISTORY] Fetching history for user {current_user['email']}")
+    
+    transactions = repo.get_user_market_history(
+        db,
+        current_user['id'],
+        transaction_type=transaction_type,
+        status=status,
+        limit=limit
+    )
+    
+    # Calculate stats
+    total_transactions = len(transactions)
+    total_sold = sum(
+        tx['tokens_amount'] 
+        for tx in transactions 
+        if tx.get('transaction_type') == 'sell_to_admin' and tx.get('status') == 'completed'
+    )
+    total_earned = sum(
+        tx['total_amount'] 
+        for tx in transactions 
+        if tx.get('transaction_type') == 'sell_to_admin' and tx.get('status') == 'completed'
+    )
+    
+    print(f"[MARKET HISTORY] Found {total_transactions} transactions")
+    print(f"  Total Sold: {total_sold} tokens")
+    print(f"  Total Earned: {total_earned} AED")
+    
+    return {
+        "total_transactions": total_transactions,
+        "total_sold": total_sold,
+        "total_earned": total_earned,
+        "transactions": transactions
+    }
+
+
+@router.get("/market/property-history/{property_id}", response_model=schemas.MarketHistoryResponse)
+@limiter.limit("30/hour")
+def get_property_market_history(
+    request: Request,
+    property_id: str,
+    status: Optional[str] = None,
+    limit: int = 100,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """
+    Get property's secondary market transaction history
+    Shows all trading activity for a specific property
+    Rate Limited: 30 requests per hour
+    """
+    print(f"\n[PROPERTY MARKET HISTORY] Fetching history for property {property_id}")
+    
+    # Verify property exists
+    property_obj = repo.get_property_by_id(db, property_id)
+    if not property_obj:
+        raise HTTPException(status_code=404, detail="Property not found")
+    
+    transactions = repo.get_property_market_history(
+        db,
+        property_id,
+        status=status,
+        limit=limit
+    )
+    
+    # Calculate stats
+    total_transactions = len(transactions)
+    total_sold = sum(tx['tokens_amount'] for tx in transactions if tx.get('status') == 'completed')
+    total_volume = sum(tx['total_amount'] for tx in transactions if tx.get('status') == 'completed')
+    
+    print(f"[PROPERTY MARKET HISTORY] Found {total_transactions} transactions")
+    print(f"  Total Tokens Traded: {total_sold}")
+    print(f"  Total Volume: {total_volume} AED")
+    
+    return {
+        "total_transactions": total_transactions,
+        "total_sold": total_sold,
+        "total_earned": total_volume,
+        "transactions": transactions
+    }
+
+

routes/otp.py

@@ -0,0 +1,203 @@
+"""
+OTP Routes for Email Verification
+Handles OTP generation, sending, and verification
+"""
+from fastapi import APIRouter, Depends, HTTPException, status, Request
+from pydantic import BaseModel, EmailStr
+from typing import Optional
+import logging
+
+from db import get_mongo
+import repo
+import repo_otp
+from utils.email_service import generate_otp, send_otp_email, get_otp_expiry
+from middleware.security import limiter, sanitize_input
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+# ============================================================================
+# REQUEST/RESPONSE MODELS
+# ============================================================================
+
+class SendOTPRequest(BaseModel):
+    email: EmailStr
+    purpose: str  # 'login' or 'registration'
+
+
+class VerifyOTPRequest(BaseModel):
+    email: EmailStr
+    otp: str
+    purpose: str  # 'login' or 'registration'
+
+
+class OTPResponse(BaseModel):
+    success: bool
+    message: str
+    expires_in_minutes: Optional[int] = None
+
+
+# ============================================================================
+# OTP ENDPOINTS
+# ============================================================================
+
+@router.post("/send-otp", response_model=OTPResponse)
+@limiter.limit("3/minute")
+async def send_otp(request: Request, data: SendOTPRequest, db=Depends(get_mongo)):
+    """
+    Send OTP to user's email
+    
+    Rate limited to 3 requests per minute per IP
+    
+    Purpose:
+    - 'registration': Send OTP during registration
+    - 'login': Send OTP during login
+    """
+    logger.info(f"\n[OTP] Send OTP request for: {data.email}, purpose: {data.purpose}")
+    
+    # Sanitize input
+    email = sanitize_input(data.email.lower())
+    purpose = sanitize_input(data.purpose.lower())
+    
+    # Validate purpose
+    if purpose not in ['login', 'registration']:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid purpose. Must be 'login' or 'registration'"
+        )
+    
+    # For registration: Check if user already exists
+    if purpose == 'registration':
+        existing_user = repo.get_user_by_email(db, email)
+        if existing_user:
+            logger.warning(f"[OTP] [ERROR] User already exists: {email}")
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Email already registered. Please login instead."
+            )
+    
+    # For login: Check if user exists
+    if purpose == 'login':
+        user = repo.get_user_by_email(db, email)
+        if not user:
+            logger.warning(f"[OTP] [ERROR] User not found: {email}")
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Email not registered. Please sign up first."
+            )
+        
+        # Check if user is active
+        if not user.get('is_active'):
+            logger.warning(f"[OTP] [ERROR] Inactive user: {email}")
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Account is inactive. Please contact support."
+            )
+    
+    # Generate OTP
+    otp = generate_otp()
+    expires_at = get_otp_expiry()
+    
+    logger.info(f"[OTP] Generated OTP for {email}, purpose: {purpose} (expires at {expires_at})")
+    
+    # Print OTP to console for testing/debugging
+    print("\n" + "="*80)
+    print(f"[LOCK] OTP CODE FOR: {email}")
+    print(f"   Purpose: {purpose}")
+    print(f"   OTP: {otp}")
+    print(f"   Expires: {expires_at}")
+    print("="*80 + "\n")
+    
+    # Log OTP to file for agent access
+    logger.info(f"[AGENT_ACCESS] OTP CODE: {otp}")
+    
+    # Save OTP to database
+    repo_otp.create_otp(db, email, otp, purpose, expires_at)
+    
+    # Send OTP via email
+    email_sent = send_otp_email(email, otp, purpose)
+    
+    if not email_sent:
+        logger.error(f"[OTP] [ERROR] Failed to send email to {email}")
+        logger.error(f"[OTP] [WARNING] Gmail App Password not configured!")
+        logger.error(f"[OTP] Run: python backend/setup_gmail.py to configure")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to send OTP email. Gmail App Password not configured. Please contact administrator."
+        )
+    
+    logger.info(f"[OTP] [SUCCESS] OTP sent successfully to {email}\n")
+    
+    return OTPResponse(
+        success=True,
+        message=f"OTP sent to {email}. Please check your inbox.",
+        expires_in_minutes=10
+    )
+
+
+@router.post("/verify-otp", response_model=OTPResponse)
+@limiter.limit("10/minute")
+async def verify_otp(request: Request, data: VerifyOTPRequest, db=Depends(get_mongo)):
+    """
+    Verify OTP code
+    
+    Rate limited to 10 requests per minute per IP
+    
+    Returns success if OTP is valid and not expired
+    """
+    logger.info(f"\n[OTP] Verify OTP request for: {data.email}, purpose: {data.purpose}")
+    
+    # Sanitize input
+    email = sanitize_input(data.email.lower())
+    otp = sanitize_input(data.otp.strip())
+    purpose = sanitize_input(data.purpose.lower())
+    
+    # Validate purpose
+    if purpose not in ['login', 'registration']:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid purpose. Must be 'login' or 'registration'"
+        )
+    
+    # Validate OTP format (6 digits)
+    if not otp.isdigit() or len(otp) != 6:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid OTP format. Must be 6 digits."
+        )
+    
+    # Verify OTP
+    success, message = repo_otp.verify_otp(db, email, otp, purpose)
+    
+    if not success:
+        logger.warning(f"[OTP] [ERROR] Verification failed for {email}: {message}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=message
+        )
+    
+    logger.info(f"[OTP] [SUCCESS] OTP verified successfully for {email}\n")
+    
+    return OTPResponse(
+        success=True,
+        message=message
+    )
+
+
+@router.post("/resend-otp", response_model=OTPResponse)
+@limiter.limit("2/minute")
+async def resend_otp(request: Request, data: SendOTPRequest, db=Depends(get_mongo)):
+    """
+    Resend OTP to user's email
+    
+    Rate limited to 2 requests per minute per IP (stricter than send-otp)
+    """
+    logger.info(f"\n[OTP] Resend OTP request for: {data.email}, purpose: {data.purpose}")
+    
+    # Delete existing OTP
+    repo_otp.delete_otp(db, data.email.lower(), data.purpose.lower())
+    
+    # Use the same logic as send_otp
+    return await send_otp(request, data, db)

routes/portfolio.py

@@ -0,0 +1,243 @@
+"""
+Production Portfolio Routes
+Handles user investment portfolio and analytics with real-time blockchain verification
+"""
+from fastapi import APIRouter, Depends, HTTPException, status
+
+import schemas
+from db import get_mongo
+import repo
+from routes.auth import get_current_user
+from services.xrp_service import XRPLService
+from config import settings
+from utils.cache import cache, get_cached_token_balance, cache_token_balance
+
+router = APIRouter()
+xrpl_service = XRPLService()
+
+
+@router.get("/portfolio", response_model=schemas.PortfolioResponse)
+def get_portfolio(
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """
+    Get user's complete investment portfolio
+    Includes all properties, tokens owned, and financial analytics
+    OPTIMIZED: Uses aggregation pipeline to fetch all data in single query
+    """
+    print(f"\n[PORTFOLIO] Fetching portfolio for user: {current_user['email']}")
+    
+    # Get or create portfolio
+    portfolio = repo.create_or_update_portfolio(db, current_user['id'])
+    
+    # Get all user investments with related data in ONE aggregation query
+    portfolio_data = repo.get_user_portfolio_optimized(db, current_user['id'])
+    
+    print(f"[PORTFOLIO] Found {len(portfolio_data)} investments")
+    
+    # Build portfolio items from aggregated data
+    portfolio_items = []
+    
+    for data in portfolio_data:
+        # Extract data from aggregation result
+        investment = {
+            'id': data.get('id'),
+            'tokens_purchased': data.get('tokens_purchased', 0),
+            'amount': data.get('amount', 0),
+            'status': data.get('status'),
+            'created_at': data.get('created_at'),
+            'property_id': data.get('property_id')
+        }
+        property_obj = data.get('property', {})
+        spec = data.get('specifications')
+        amenities = data.get('amenities', [])
+        images = data.get('images', [])
+        token_rec = data.get('tokens')
+        
+        if not property_obj:
+            print(f"[PORTFOLIO] ⚠ Property not found in aggregation result")
+            continue
+        
+        
+        # Calculate current value and profit/loss
+        tokens_owned = investment.get('tokens_purchased', 0)
+        investment_amount = investment.get('amount', 0)
+        current_token_price = property_obj.get('token_price', 0)
+        current_value = tokens_owned * current_token_price
+        profit_loss = current_value - investment_amount
+        ownership_percentage = (tokens_owned / property_obj.get('total_tokens', 1)) * 100
+        
+        # Ensure all required PropertyOut fields have default values
+        if 'property_type' not in property_obj or not property_obj.get('property_type'):
+            property_obj['property_type'] = 'Residential'  # Default type
+        if 'funded_date' not in property_obj:
+            property_obj['funded_date'] = None
+        
+        # Build property output
+        property_out = schemas.PropertyOut(
+            **property_obj,
+            specifications=schemas.PropertySpecificationOut(**spec) if spec else None,
+            amenities=[schemas.AmenityOut(**a) for a in amenities] if amenities else None,
+            images=[schemas.PropertyImageOut(**img) for img in images] if images else None
+        )
+        
+        # Get blockchain verification for IOU tokens
+        blockchain_balance = 0.0
+        blockchain_verified = False
+
+        try:
+            # Get user's wallet to check blockchain balance (cached query)
+            user_wallet = repo.get_wallet_by_user(db, current_user['id'])
+
+            if user_wallet and token_rec:
+                xrp_address = user_wallet.get('xrp_address')
+                currency_code = token_rec.get('currency_code') or settings.IOU_TOKEN_CURRENCY
+                issuer_address = token_rec.get('issuer_address')
+
+                if xrp_address and currency_code and issuer_address:
+                    # Try cached token balance first (5min TTL)
+                    blockchain_balance = get_cached_token_balance(xrp_address, currency_code, issuer_address)
+                    
+                    if blockchain_balance is None:
+                        # Cache miss - fetch from blockchain
+                        balance_val = xrpl_service.get_user_token_balance(
+                            xrp_address,
+                            currency_code,
+                            issuer_address,
+                        )
+                        blockchain_balance = float(balance_val or 0.0)
+                        # Cache for 5 minutes
+                        cache_token_balance(xrp_address, currency_code, issuer_address, blockchain_balance, ttl=300)
+                        print(f"[PORTFOLIO] [SUCCESS] Blockchain verified (live): {blockchain_balance} {currency_code}")
+                    else:
+                        print(f"[PORTFOLIO] [SUCCESS] Blockchain verified (cached): {blockchain_balance} {currency_code}")
+                    
+                    blockchain_verified = True
+        except Exception as e:
+            print(f"[PORTFOLIO] ⚠ Blockchain verification error: {e}")
+        
+        # Compare database vs blockchain balance
+        balance_mismatch = blockchain_verified and abs(tokens_owned - blockchain_balance) > 0.001
+        
+        # Convert purchase_date to string if it's a datetime object
+        purchase_date = investment.get('created_at')
+        if purchase_date and hasattr(purchase_date, 'isoformat'):
+            purchase_date = purchase_date.isoformat()
+        
+        # Get rent summary for this property
+        rent_summary = None
+        try:
+            rent_data = repo.get_user_rent_summary(db, current_user['id'], property_obj['id'])
+            if rent_data and rent_data.get('total_rent_received', 0) > 0:
+                # Calculate annual rental yield if possible
+                annual_yield = None
+                if investment_amount > 0 and rent_data.get('total_rent_received'):
+                    # Estimate annual yield based on total rent received and payment count
+                    num_payments = rent_data.get('total_rent_payments', 1)
+                    if num_payments > 0:
+                        avg_monthly = rent_data['total_rent_received'] / num_payments
+                        annual_rent = avg_monthly * 12
+                        annual_yield = (annual_rent / investment_amount) * 100
+                
+                rent_summary = {
+                    "property_id": property_obj['id'],
+                    "property_title": property_obj.get('title', ''),
+                    "total_tokens_owned": tokens_owned,
+                    "total_rent_received": rent_data.get('total_rent_received', 0.0),
+                    "total_rent_payments": rent_data.get('total_rent_payments', 0),
+                    "last_rent_amount": rent_data.get('last_rent_amount'),
+                    "last_rent_date": rent_data.get('last_rent_date').isoformat() if rent_data.get('last_rent_date') and hasattr(rent_data.get('last_rent_date'), 'isoformat') else None,
+                    "average_monthly_rent": rent_data.get('average_monthly_rent'),
+                    "annual_rental_yield": annual_yield
+                }
+                print(f"[PORTFOLIO]   → Rent received: {rent_data.get('total_rent_received', 0):.2f} AED ({rent_data.get('total_rent_payments', 0)} payments)")
+        except Exception as e:
+            print(f"[PORTFOLIO] ⚠ Error fetching rent data: {e}")
+        
+        # Build portfolio item with blockchain verification
+        item = schemas.PortfolioItemOut(
+            property=property_out,
+            tokens_owned=tokens_owned,
+            token_balance=tokens_owned,  # Frontend compatibility
+            blockchain_balance=blockchain_balance,  # Real blockchain balance
+            investment_amount=investment_amount,
+            current_value=current_value,
+            profit_loss=profit_loss,
+            ownership_percentage=ownership_percentage,
+            purchase_date=purchase_date,
+            purchase_price_per_token=investment_amount / tokens_owned if tokens_owned > 0 else 0,
+            failed_transactions_count=0,
+            rent_data=rent_summary,  # Add rent data
+            # Add blockchain verification metadata
+            blockchain_verified=blockchain_verified,
+            balance_mismatch=balance_mismatch
+        )
+        
+        portfolio_items.append(item)
+        
+        print(f"[PORTFOLIO]   - {property_obj['title']}: {tokens_owned} tokens, "
+              f"Blockchain: {blockchain_balance} ({'[SUCCESS]' if blockchain_verified else '✗'}), "
+              f"Value: {current_value:.2f} AED, P/L: {profit_loss:.2f} AED"
+              f"{' [MISMATCH]' if balance_mismatch else ''}")
+    
+    print(f"[PORTFOLIO] [SUCCESS] Portfolio summary:")
+    print(f"[PORTFOLIO]   Total invested: {portfolio['total_invested']:.2f} AED")
+    print(f"[PORTFOLIO]   Current value: {portfolio['total_current_value']:.2f} AED")
+    print(f"[PORTFOLIO]   Total profit: {portfolio['total_profit']:.2f} AED\n")
+    
+    return schemas.PortfolioResponse(
+        portfolio=schemas.PortfolioOut(**portfolio),
+        items=portfolio_items,
+        total_properties=len(portfolio_items)
+    )
+
+
+@router.get("/portfolio/summary")
+def get_portfolio_summary(
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """Get quick portfolio summary without full details"""
+    print(f"\n[PORTFOLIO] Fetching summary for user: {current_user['email']}")
+    
+    portfolio = repo.create_or_update_portfolio(db, current_user['id'])
+    investments = repo.get_user_investments(db, current_user['id'])
+    
+    # Count confirmed investments only
+    confirmed_count = sum(1 for inv in investments if inv.get('status') == 'confirmed')
+    
+    summary = {
+        "total_invested": portfolio.get('total_invested', 0),
+        "total_current_value": portfolio.get('total_current_value', 0),
+        "total_profit": portfolio.get('total_profit', 0),
+        "profit_percentage": (portfolio.get('total_profit', 0) / portfolio.get('total_invested', 1)) * 100 if portfolio.get('total_invested', 0) > 0 else 0,
+        "total_properties": confirmed_count,
+        "total_investments": len(investments)
+    }
+    
+    print(f"[PORTFOLIO] [SUCCESS] Summary: {confirmed_count} properties, "
+          f"{summary['total_invested']:.2f} AED invested\n")
+    
+    return summary
+
+
+@router.get("/portfolio/rent-payments/{property_id}")
+def get_property_rent_payments(
+    property_id: str,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """
+    Get all rent payments for a specific property for the current user
+    """
+    try:
+        # Get rent payments for this user and property
+        rent_payments = repo.get_user_rent_payments(db, current_user['id'], property_id)
+        return rent_payments
+    except Exception as e:
+        print(f"[PORTFOLIO] Error fetching rent payments: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to fetch rent payment history"
+        )

routes/profile.py

@@ -0,0 +1,772 @@
+"""
+Profile Management Routes
+Handles user profile operations including image upload, personal details CRUD, and KYC documents
+Security: All endpoints require authentication, sensitive data is masked
+"""
+from fastapi import APIRouter, Depends, HTTPException, status, UploadFile, File, Form, Request
+from typing import Optional, List
+import base64
+from datetime import datetime
+import logging
+
+import schemas
+from db import get_mongo
+import repo
+from routes.auth import get_current_user
+from middleware.security import (
+    sanitize_input, mask_email, mask_phone, mask_sensitive_data,
+    validate_name, validate_phone, validate_date, validate_gender, validate_address,
+    limiter
+)
+
+router = APIRouter()
+logger = logging.getLogger(__name__)
+
+
+
+# ============================================================================
+# PROFILE IMAGE OPERATIONS
+# ============================================================================
+
+def profile_images_col(db):
+    """Get profile images collection"""
+    return db.profile_images
+
+
+@router.post("/upload-image", status_code=status.HTTP_200_OK)
+@limiter.limit("10/minute")
+async def upload_profile_image(
+    request: Request,
+    file: UploadFile = File(...),
+    current_user: dict = Depends(get_current_user),
+    db=Depends(get_mongo)
+):
+    """
+    Upload profile image (max 10KB)
+    Stores image as base64 in separate collection
+    """
+    logger.info(f"Profile image upload request from user: {mask_email(current_user['email'])}")
+    
+    # Read file content
+    content = await file.read()
+    file_size = len(content)
+    
+    # Validate file size (10KB = 10240 bytes)
+    if file_size > 10240:
+        logger.warning(f"Profile image too large: {file_size} bytes")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"File size ({file_size} bytes) exceeds 10KB limit"
+        )
+    
+    # Validate file type
+    if not file.content_type or not file.content_type.startswith('image/'):
+        logger.warning(f"Invalid profile image type: {file.content_type}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Only image files are allowed"
+        )
+    
+    # Convert to base64
+    base64_image = base64.b64encode(content).decode('utf-8')
+    image_data_url = f"data:{file.content_type};base64,{base64_image}"
+    
+    # Store in profile_images collection
+    now = datetime.utcnow()
+    profile_image_doc = {
+        "user_id": repo._to_object_id(current_user['id']),
+        "image_data": image_data_url,
+        "content_type": file.content_type,
+        "file_size": file_size,
+        "uploaded_at": now,
+        "updated_at": now
+    }
+    
+    # Upsert (update if exists, insert if not)
+    profile_images_col(db).update_one(
+        {"user_id": repo._to_object_id(current_user['id'])},
+        {"$set": profile_image_doc},
+        upsert=True
+    )
+    
+    logger.info(f"Profile image uploaded successfully: {file_size} bytes")
+    
+    return {
+        "success": True,
+        "message": "Profile image uploaded successfully",
+        "image_url": image_data_url,
+        "file_size": file_size
+    }
+
+
+@router.get("/image")
+def get_profile_image(
+    current_user: dict = Depends(get_current_user),
+    db=Depends(get_mongo)
+):
+    """Get user's profile image"""
+    profile_image = profile_images_col(db).find_one(
+        {"user_id": repo._to_object_id(current_user['id'])}
+    )
+    
+    if not profile_image:
+        return {"image_url": None}
+    
+    return {
+        "image_url": profile_image.get("image_data"),
+        "file_size": profile_image.get("file_size"),
+        "uploaded_at": profile_image.get("uploaded_at")
+    }
+
+
+@router.get("/image/user/{user_id}")
+@limiter.limit("30/minute")
+def get_user_profile_image(
+    request: Request,
+    user_id: str,
+    db=Depends(get_mongo),
+    current_user: dict = Depends(get_current_user)
+):
+    """
+    Get any user's profile image by user ID
+    Requires authentication - users can only view profile images if logged in
+    Rate limited to 30 requests per minute per IP to prevent abuse
+    """
+    try:
+        profile_image = profile_images_col(db).find_one(
+            {"user_id": repo._to_object_id(user_id)}
+        )
+        
+        if not profile_image:
+            return {"image_url": None}
+        
+        return {
+            "image_url": profile_image.get("image_data"),
+            "file_size": profile_image.get("file_size"),
+            "uploaded_at": profile_image.get("uploaded_at")
+        }
+    except Exception as e:
+        logger.error(f"Error fetching user profile image: {e}")
+        return {"image_url": None}
+
+
+@router.delete("/image")
+@limiter.limit("5/minute")
+def delete_profile_image(
+    request: Request,
+    current_user: dict = Depends(get_current_user),
+    db=Depends(get_mongo)
+):
+    """Delete user's profile image"""
+    logger.info(f"Deleting profile image for user: {mask_email(current_user['email'])}")
+    
+    result = profile_images_col(db).delete_one(
+        {"user_id": repo._to_object_id(current_user['id'])}
+    )
+    
+    if result.deleted_count == 0:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="No profile image found"
+        )
+    
+    logger.info("Profile image deleted successfully")
+    
+    return {"success": True, "message": "Profile image deleted successfully"}
+
+
+# ============================================================================
+# PROFILE DETAILS OPERATIONS
+# ============================================================================
+
+@router.get("/details", response_model=schemas.UserOut)
+def get_profile_details(
+    current_user: dict = Depends(get_current_user),
+    db=Depends(get_mongo),
+    mask_data: bool = True,
+    show_full_data: bool = False
+):
+    """
+    Get complete user profile details
+    Returns masked sensitive data by default
+    Set show_full_data=True only for specific authorized operations
+    """
+    # Get fresh user data
+    user = repo.get_user_by_id(db, current_user['id'])
+    
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found"
+        )
+    
+    # Get wallet information
+    wallet = repo.get_wallet_by_user(db, user['id'])
+    if wallet:
+        user['aed_balance'] = wallet.get('balance', 0.0)
+        user['xrp_address'] = wallet.get('xrp_address')
+        user['xrp_balance'] = wallet.get('xrp_balance', 0.0)
+    
+    # Apply masking unless explicitly requested not to
+    if mask_data and not show_full_data:
+        # Mask email
+        if user.get('email'):
+            user['email_masked'] = mask_email(user['email'])
+            
+        # Mask phone
+        if user.get('phone'):
+            user['phone_masked'] = mask_phone(user['phone'])
+            user['phone'] = user['phone_masked']  # Replace original with masked
+            
+        # Mask wallet address
+        if user.get('xrp_address'):
+            user['xrp_address_masked'] = mask_sensitive_data(user['xrp_address'], visible_chars=8)
+            user['xrp_address'] = user['xrp_address_masked']  # Replace with masked
+            
+        # Mask date of birth (show only year)
+        if user.get('date_of_birth'):
+            dob = str(user['date_of_birth'])
+            if len(dob) >= 4:
+                user['date_of_birth'] = f"****-**-** ({dob[:4]})"
+                
+        # Mask address (show only city/state)
+        if user.get('address'):
+            address_parts = user['address'].split(',')
+            if len(address_parts) > 1:
+                user['address'] = f"****, {address_parts[-1].strip()}"
+            else:
+                user['address'] = "****"
+    
+    return schemas.UserOut(**user)
+
+
+@router.put("/details", response_model=schemas.UserOut)
+@limiter.limit("10/minute")
+def update_profile_details(
+    request: Request,
+    profile_data: schemas.UserUpdate,
+    current_user: dict = Depends(get_current_user),
+    db=Depends(get_mongo)
+):
+    """Update user profile details with comprehensive input validation"""
+    logger.info(f"Updating profile for user: {mask_email(current_user['email'])}")
+    
+    # Prepare update fields with validation
+    update_fields = {}
+    
+    # Validate name (required)
+    if profile_data.name is not None:
+        is_valid, result = validate_name(profile_data.name)
+        if not is_valid:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=result
+            )
+        update_fields['name'] = result
+    
+    # Validate phone
+    if profile_data.phone is not None:
+        is_valid, result = validate_phone(profile_data.phone)
+        if not is_valid:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=result
+            )
+        update_fields['phone'] = result if result else None
+    
+    # Validate date of birth (optional)
+    if profile_data.date_of_birth is not None:
+        is_valid, result = validate_date(str(profile_data.date_of_birth))
+        if not is_valid:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=result
+            )
+        update_fields['date_of_birth'] = result
+    
+    # Validate gender (optional)
+    if profile_data.gender is not None:
+        is_valid, result = validate_gender(profile_data.gender)
+        if not is_valid:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=result
+            )
+        update_fields['gender'] = result
+    
+    # Validate address (optional)
+    if profile_data.address is not None:
+        is_valid, result = validate_address(profile_data.address)
+        if not is_valid:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=result
+            )
+        update_fields['address'] = result if result else None
+    
+    # Add country, state, city fields (optional, no special validation needed)
+    if profile_data.country is not None:
+        update_fields['country'] = sanitize_input(profile_data.country) if profile_data.country else None
+    
+    if profile_data.state is not None:
+        update_fields['state'] = sanitize_input(profile_data.state) if profile_data.state else None
+    
+    if profile_data.city is not None:
+        update_fields['city'] = sanitize_input(profile_data.city) if profile_data.city else None
+    
+    # Add employment fields (optional)
+    if profile_data.employment_status is not None:
+        update_fields['employment_status'] = sanitize_input(profile_data.employment_status) if profile_data.employment_status else None
+    
+    if profile_data.employment_details is not None:
+        update_fields['employment_details'] = sanitize_input(profile_data.employment_details) if profile_data.employment_details else None
+    
+    if not update_fields:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="No valid fields to update"
+        )
+    
+    logger.debug(f"Validated update fields: {list(update_fields.keys())}")
+    
+    # Update user
+    updated_user = repo.update_user(db, current_user['id'], update_fields)
+    
+    if not updated_user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found"
+        )
+    
+    # Get wallet information
+    wallet = repo.get_wallet_by_user(db, updated_user['id'])
+    if wallet:
+        updated_user['aed_balance'] = wallet.get('balance', 0.0)
+        updated_user['xrp_address'] = wallet.get('xrp_address')
+        updated_user['xrp_balance'] = wallet.get('xrp_balance', 0.0)
+    
+    logger.info("Profile updated successfully")
+    
+    return schemas.UserOut(**updated_user)
+
+
+# ============================================================================
+# PROFILE STATISTICS
+# ============================================================================
+
+@router.get("/stats")
+def get_profile_stats(
+    current_user: dict = Depends(get_current_user),
+    db=Depends(get_mongo)
+):
+    """Get user profile statistics"""
+    user_id = current_user['id']
+    
+    # Get investments
+    investments = repo.get_user_investments(db, user_id)
+    
+    # Get transactions
+    transactions = repo.get_user_transactions(db, user_id, limit=1000)
+    
+    # Calculate stats
+    total_invested = sum(inv.get('amount', 0) for inv in investments)
+    total_properties = len(set(inv.get('property_id') for inv in investments))
+    total_tokens = sum(inv.get('tokens_purchased', 0) for inv in investments)
+    
+    # Calculate current value
+    total_current_value = 0
+    for inv in investments:
+        property_obj = repo.get_property_by_id(db, inv['property_id'])
+        if property_obj:
+            current_value = inv.get('tokens_purchased', 0) * property_obj.get('token_price', 0)
+            total_current_value += current_value
+    
+    total_profit = total_current_value - total_invested
+    profit_percentage = (total_profit / total_invested * 100) if total_invested > 0 else 0
+    
+    # Get wallet
+    wallet = repo.get_wallet_by_user(db, user_id)
+    wallet_balance = wallet.get('balance', 0.0) if wallet else 0.0
+    
+    # Transaction counts
+    completed_transactions = len([t for t in transactions if t.get('status') == 'completed'])
+    pending_transactions = len([t for t in transactions if t.get('status') == 'pending'])
+    
+    return {
+        "total_invested": total_invested,
+        "total_current_value": total_current_value,
+        "total_profit": total_profit,
+        "profit_percentage": round(profit_percentage, 2),
+        "total_properties": total_properties,
+        "total_tokens": total_tokens,
+        "wallet_balance": wallet_balance,
+        "total_transactions": len(transactions),
+        "completed_transactions": completed_transactions,
+        "pending_transactions": pending_transactions,
+        "member_since": current_user.get('created_at')
+    }
+
+
+# ============================================================================
+# KYC DOCUMENT OPERATIONS
+# ============================================================================
+
+def kyc_documents_col(db):
+    """Get KYC documents collection"""
+    return db.kyc_documents
+
+
+@router.post("/kyc/upload", status_code=status.HTTP_200_OK)
+@limiter.limit("5/minute")
+async def upload_kyc_document(
+    request: Request,
+    file: UploadFile = File(...),
+    document_type: str = "identity",
+    current_user: dict = Depends(get_current_user),
+    db=Depends(get_mongo)
+):
+    """
+    Upload KYC document (max 500KB)
+    Document types: identity, address_proof, pan_card, aadhar_card, passport
+    """
+    logger.info(f"KYC document upload request from user: {mask_email(current_user['email'])}")
+    
+    # Read file content
+    content = await file.read()
+    file_size = len(content)
+    
+    # Validate file size (500KB = 512000 bytes)
+    if file_size > 512000:
+        logger.warning(f"KYC document too large: {file_size} bytes")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"File size ({file_size} bytes) exceeds 500KB limit"
+        )
+    
+    # Validate file type (images and PDFs)
+    allowed_types = ['image/', 'application/pdf']
+    if not file.content_type or not any(file.content_type.startswith(t) for t in allowed_types):
+        logger.warning(f"Invalid KYC document type: {file.content_type}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Only image and PDF files are allowed"
+        )
+    
+    # Convert to base64
+    base64_file = base64.b64encode(content).decode('utf-8')
+    file_data_url = f"data:{file.content_type};base64,{base64_file}"
+    
+    # Store in kyc_documents collection
+    now = datetime.utcnow()
+    kyc_doc = {
+        "user_id": repo._to_object_id(current_user['id']),
+        "document_type": document_type,
+        "file_name": file.filename,
+        "file_data": file_data_url,
+        "content_type": file.content_type,
+        "file_size": file_size,
+        "status": "draft",  # draft until /kyc/submit is called
+        "uploaded_at": now,
+        "updated_at": now
+    }
+    
+    result = kyc_documents_col(db).insert_one(kyc_doc)
+    kyc_doc["_id"] = result.inserted_id
+    
+    logger.info(f"KYC document uploaded successfully: {file_size} bytes")
+    
+    return {
+        "success": True,
+        "message": "KYC document uploaded successfully",
+        "document_id": str(result.inserted_id),
+        "document_type": document_type,
+        "file_name": file.filename,
+        "file_size": file_size,
+        "status": "draft"
+    }
+
+
+@router.get("/kyc/documents")
+def get_kyc_documents(
+    current_user: dict = Depends(get_current_user),
+    db=Depends(get_mongo)
+):
+    """Get all KYC documents for user"""
+    docs = list(kyc_documents_col(db).find(
+        {"user_id": repo._to_object_id(current_user['id'])}
+    ).sort("uploaded_at", -1))
+    
+    result = []
+    for doc in docs:
+        result.append({
+            "id": str(doc["_id"]),
+            "document_type": doc.get("document_type"),
+            "file_name": doc.get("file_name"),
+            "file_size": doc.get("file_size"),
+            "status": doc.get("status", "draft"),
+            "uploaded_at": doc.get("uploaded_at"),
+            "file_data": doc.get("file_data")  # Include for preview
+        })
+    
+    return result
+
+
+@router.delete("/kyc/documents/{document_id}")
+@limiter.limit("5/minute")
+def delete_kyc_document(
+    request: Request,
+    document_id: str,
+    current_user: dict = Depends(get_current_user),
+    db=Depends(get_mongo)
+):
+    """Delete a KYC document"""
+    logger.info(f"Deleting KYC document {document_id}")
+    
+    result = kyc_documents_col(db).delete_one({
+        "_id": repo._to_object_id(document_id),
+        "user_id": repo._to_object_id(current_user['id'])
+    })
+    
+    if result.deleted_count == 0:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Document not found"
+        )
+    
+    logger.info("KYC document deleted successfully")
+    
+    return {"success": True, "message": "Document deleted successfully"}
+
+
+@router.get("/completion-status")
+def get_profile_completion_status(
+    current_user: dict = Depends(get_current_user),
+    db=Depends(get_mongo)
+):
+    """Get profile completion status"""
+    user = repo.get_user_by_id(db, current_user['id'])
+    
+    # Check profile image
+    profile_image = profile_images_col(db).find_one(
+        {"user_id": repo._to_object_id(current_user['id'])}
+    )
+    
+    # Check KYC documents
+    kyc_docs = list(kyc_documents_col(db).find(
+        {"user_id": repo._to_object_id(current_user['id'])}
+    ))
+    
+    # Calculate completion
+    completion_items = {
+        "personal_info": bool(user.get('name') and user.get('email') and user.get('phone')),
+        "profile_image": bool(profile_image),
+        "kyc_documents": len(kyc_docs) > 0,
+        "wallet_setup": bool(user.get('wallet_id')),
+        "email_verified": True  # Assuming email is verified on registration
+    }
+    
+    completed = sum(1 for v in completion_items.values() if v)
+    total = len(completion_items)
+    percentage = (completed / total) * 100
+    
+    return {
+        "completion_percentage": round(percentage, 1),
+        "completed_items": completed,
+        "total_items": total,
+        "items": completion_items,
+        "kyc_documents_count": len(kyc_docs)
+    }
+
+
+# ============================================================================
+# NEW KYC ROUTES
+# ============================================================================
+
+@router.post("/kyc/submit", status_code=status.HTTP_200_OK)
+@limiter.limit("3/hour")
+async def submit_kyc(
+    request: Request,
+    full_name: str = Form(...),
+    date_of_birth: str = Form(...),
+    gender: str = Form(...),
+    address: str = Form(...),
+    country: str = Form(None),
+    state: str = Form(None),
+    city: str = Form(None),
+    file: UploadFile = File(None),
+    current_user: dict = Depends(get_current_user),
+    db=Depends(get_mongo)
+):
+    """
+    Submit KYC using either a newly attached file (multipart) or the latest uploaded draft.
+    - Max file size: 500KB
+    - Accepted types: images and PDF
+    """
+    logger.info(f"KYC submission from user: {mask_email(current_user['email'])}")
+    
+    # Validate required fields
+    if not full_name or not full_name.strip():
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Full name is required"
+        )
+    if not date_of_birth or not date_of_birth.strip():
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Date of birth is required"
+        )
+    if not gender or not gender.strip():
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Gender is required"
+        )
+    if not address or not address.strip():
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Address is required"
+        )
+
+    now = datetime.utcnow()
+    user_oid = repo._to_object_id(current_user['id'])
+
+    document_url = None
+    content_type = None
+    file_size = None
+    kyc_doc_id = None
+
+    if file is not None:
+        # Read and validate attached file
+        content = await file.read()
+        file_size = len(content)
+        if file_size > 512000:
+            print(f"[KYC] [ERROR] File too large: {file_size} bytes")
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"File size ({file_size} bytes) exceeds 500KB limit"
+            )
+        allowed_types_prefix = ['image/', 'application/pdf']
+        if not file.content_type or not any(file.content_type.startswith(t) for t in allowed_types_prefix):
+            print(f"[KYC] [ERROR] Invalid file type: {file.content_type}")
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Only image and PDF files are allowed"
+            )
+        # Convert to data URL
+        base64_file = base64.b64encode(content).decode('utf-8')
+        document_url = f"data:{file.content_type};base64,{base64_file}"
+        content_type = file.content_type
+
+        # Remove previous drafts to keep only the submitted one
+        kyc_documents_col(db).delete_many({"user_id": user_oid})
+
+        # Insert new pending document with location details
+        kyc_doc = {
+            "user_id": user_oid,
+            "full_name": full_name,
+            "date_of_birth": date_of_birth,
+            "gender": gender,
+            "address": address,
+            "country": country,
+            "state": state,
+            "city": city,
+            "document_url": document_url,
+            "file_size": file_size,
+            "content_type": content_type,
+            "status": "pending",
+            "uploaded_at": now,
+            "reviewed_at": None,
+            "reviewed_by": None,
+            "rejection_reason": None
+        }
+        result = kyc_documents_col(db).insert_one(kyc_doc)
+        kyc_doc_id = result.inserted_id
+    else:
+        # No file attached: try to use latest draft
+        latest = kyc_documents_col(db).find({"user_id": user_oid}).sort("uploaded_at", -1).limit(1)
+        latest_doc = next(latest, None)
+        if not latest_doc or latest_doc.get("status") not in ("draft", "pending"):
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="No draft document found to submit. Please upload your KYC document first."
+            )
+        # Normalize fields
+        document_url = latest_doc.get("document_url") or latest_doc.get("file_data")
+        content_type = latest_doc.get("content_type")
+        file_size = latest_doc.get("file_size")
+        if not document_url:
+            raise HTTPException(status_code=400, detail="Draft document is missing file data. Please re-upload.")
+        # Update existing doc to pending and attach personal details
+        kyc_documents_col(db).update_one(
+            {"_id": latest_doc["_id"]},
+            {"$set": {
+                "full_name": full_name,
+                "date_of_birth": date_of_birth,
+                "gender": gender,
+                "address": address,
+                "country": country,
+                "state": state,
+                "city": city,
+                "document_url": document_url,
+                "status": "pending",
+                "updated_at": now
+            }}
+        )
+        kyc_doc_id = latest_doc["_id"]
+
+    # Update user KYC status and pointer, and also update location fields in user document
+    repo.update_user(db, current_user['id'], {
+        "kyc_status": "pending",
+        "kyc_document_id": str(kyc_doc_id),
+        "gender": gender,
+        "country": country,
+        "state": state,
+        "city": city
+    })
+
+    logger.info(f"KYC submitted successfully")
+
+    return {
+        "success": True,
+        "message": "KYC submitted. Awaiting admin approval.",
+        "document_id": str(kyc_doc_id),
+        "status": "pending"
+    }
+
+
+@router.get("/kyc/status")
+def get_kyc_status(
+    current_user: dict = Depends(get_current_user),
+    db=Depends(get_mongo)
+):
+    """Get user's KYC status"""
+    user = repo.get_user_by_id(db, current_user['id'])
+    # Determine status more accurately: only treat as pending/approved/rejected when a submitted doc exists
+    kyc_status = user.get('kyc_status')
+    if not kyc_status:
+        # If user has a submitted doc id, default to pending, else not started
+        kyc_status = 'pending' if user.get('kyc_document_id') else 'not_started'
+    
+    # Get KYC document if exists
+    kyc_doc = None
+    if user.get('kyc_document_id'):
+        doc = kyc_documents_col(db).find_one({"_id": repo._to_object_id(user['kyc_document_id'])})
+        if doc:
+            kyc_doc = {
+                "id": str(doc["_id"]),
+                "full_name": doc.get("full_name"),
+                "date_of_birth": doc.get("date_of_birth"),
+                "address": doc.get("address"),
+                "country": doc.get("country"),
+                "state": doc.get("state"),
+                "city": doc.get("city"),
+                "status": doc.get("status", "pending"),
+                "uploaded_at": doc.get("uploaded_at"),
+                "reviewed_at": doc.get("reviewed_at"),
+                "rejection_reason": doc.get("rejection_reason")
+            }
+    
+    return {
+        "kyc_status": kyc_status,
+        "kyc_document": kyc_doc,
+        "can_purchase": kyc_status == "approved"
+    }

routes/properties.py

@@ -0,0 +1,851 @@
+"""
+Production Property Routes
+Handles property listing, details, and creation with security enhancements
+"""
+from fastapi import APIRouter, Depends, HTTPException, status, Query, Request
+from typing import List, Optional
+from datetime import datetime
+from bson import ObjectId
+
+import schemas
+from db import get_mongo
+import repo
+from routes.auth import get_current_user, get_current_admin
+from middleware.security import validate_object_id, sanitize_input, limiter
+from utils.cache import cache
+
+router = APIRouter()
+
+
+def map_old_to_new_schema(prop: dict) -> dict:
+    """
+    Map OLD schema fields to NEW schema fields for backward compatibility
+    OLD: name, tokens, price_per_token, value_in_aed, city, type
+    NEW: title, total_tokens, token_price, original_price, location, property_type
+    """
+    mapped = prop.copy()
+    
+    # Map field names
+    if 'name' in mapped and 'title' not in mapped:
+        mapped['title'] = mapped['name']
+    
+    if 'tokens' in mapped and 'total_tokens' not in mapped:
+        mapped['total_tokens'] = mapped['tokens']
+    
+    if 'price_per_token' in mapped and 'token_price' not in mapped:
+        mapped['token_price'] = mapped['price_per_token']
+    
+    if 'value_in_inr' in mapped and 'original_price' not in mapped:
+        mapped['original_price'] = mapped['value_in_inr']
+    
+    # Map property_type from old 'type' field
+    if 'type' in mapped and 'property_type' not in mapped:
+        mapped['property_type'] = mapped['type']
+    
+    # Ensure property_type has a default value
+    if 'property_type' not in mapped:
+        mapped['property_type'] = 'Residential'
+    
+    # Map location from city + type if not present
+    if 'location' not in mapped and ('city' in mapped or 'type' in mapped):
+        city = mapped.get('city', '')
+        prop_type = mapped.get('type', '')
+        mapped['location'] = f"{city}, {prop_type}" if city and prop_type else (city or prop_type)
+    
+    # Ensure funded_date exists
+    if 'funded_date' not in mapped:
+        mapped['funded_date'] = None
+    
+    return mapped
+
+
+@router.get("/public/properties", response_model=List[schemas.PropertyOut])
+@limiter.limit("30/minute")
+def list_properties_public(
+    request: Request,
+    is_active: Optional[bool] = Query(None, description="Filter by active status"),
+    skip: int = Query(0, ge=0, description="Number of records to skip"),
+    limit: int = Query(50, ge=1, le=100, description="Max number of records to return"),
+    db=Depends(get_mongo)
+):
+    """
+    PUBLIC: List properties WITHOUT authentication
+    Rate limited to 30 requests per minute per IP
+    Returns limited property data (no documents, no sensitive info)
+    """
+    print(f"\n[PROPERTIES] PUBLIC listing properties (is_active={is_active}, skip={skip}, limit={limit})")
+    
+    # Use optimized version that fetches all data in single aggregation query
+    properties = repo.list_properties_optimized(db, is_active=is_active, skip=skip, limit=limit)
+    
+    # Build enriched property objects (limited data for public access)
+    enriched_properties = []
+    for prop in properties:
+        # Map OLD schema to NEW schema for backward compatibility
+        prop = map_old_to_new_schema(prop)
+        
+        # Extract nested data from aggregation result
+        spec = prop.pop('specifications', None)
+        amenities = prop.pop('amenities', [])
+        images = prop.pop('images', [])
+        prop.pop('documents', None)  # EXCLUDE documents from public view
+        
+        # Build enriched property object WITHOUT documents (public limited access)
+        prop_out = schemas.PropertyOut(
+            **prop,
+            specifications=schemas.PropertySpecificationOut(**spec) if spec else None,
+            amenities=[schemas.AmenityOut(**a) for a in amenities] if amenities else None,
+            images=[schemas.PropertyImageOut(**img) for img in images] if images else None,
+            documents=None  # No documents for public view
+        )
+        enriched_properties.append(prop_out)
+    
+    print(f"[PROPERTIES] [SUCCESS] PUBLIC: Returning {len(enriched_properties)} properties (limited data)\n")
+    
+    return enriched_properties
+
+
+@router.get("/public/properties-by-status")
+@limiter.limit("30/minute")
+def list_public_properties_by_status(
+    request: Request,
+    status_filter: str = Query("available", description="Filter: 'available', 'funded', or 'all'"),
+    skip: int = Query(0, ge=0),
+    limit: int = Query(4, ge=1, le=20),
+    db=Depends(get_mongo)
+):
+    """
+    PUBLIC: List properties filtered by funding status.
+    - 'available': Properties with available_tokens > 0
+    - 'funded': Properties from funded_properties collection (available_tokens = 0)
+    - 'all': Both available and funded properties combined
+    
+    Returns counts for both categories to support tab UI.
+    """
+    print(f"\n[PROPERTIES] PUBLIC listing by status: {status_filter} (skip={skip}, limit={limit})")
+    
+    result = {
+        "status_filter": status_filter,
+        "properties": [],
+        "counts": {
+            "available": 0,
+            "funded": 0
+        }
+    }
+    
+    try:
+        # 1. Get Counts (Always)
+        result["counts"]["available"] = db.properties.count_documents({
+            "is_active": True,
+            "available_tokens": {"$gt": 0}
+        })
+        
+        result["counts"]["funded"] = db.funded_properties.count_documents({
+            "is_active": True,
+            "funding_status": "funded"
+        })
+        
+        # 2. Get Properties based on filter
+        properties_list = []
+        
+        if status_filter == "available":
+            # Get available properties
+            # Use optimized repo function but we need to pass is_active=True
+            cursor = db.properties.find({
+                "is_active": True,
+                "available_tokens": {"$gt": 0}
+            }).sort("created_at", -1).skip(skip).limit(limit)
+            
+            for prop in cursor:
+                # Use list_properties_public logic to clean data
+                if '_id' in prop and not isinstance(prop['_id'], str):
+                    prop['id'] = str(prop.pop('_id'))
+                
+                prop = map_old_to_new_schema(prop)
+                
+                # Manual fetch for images/specs if not joined
+                prop_images = repo.get_property_images(db, prop['id'])
+                prop['images'] = [img for img in prop_images]
+                
+                if 'specifications' not in prop:
+                    spec = repo.get_property_specification(db, prop['id'])
+                    prop['specifications'] = spec
+                
+                # Mock amenities if missing
+                if 'amenities' not in prop:
+                     prop['amenities'] = []
+
+                properties_list.append(prop)
+                
+        elif status_filter == "funded":
+            # Get funded properties
+            cursor = db.funded_properties.find({
+                "is_active": True,
+                "funding_status": "funded"
+            }).sort("funded_date", -1).skip(skip).limit(limit)
+            
+            for doc in cursor:
+                doc['id'] = str(doc.pop('_id'))
+                # Funded properties schema is flat
+                if 'main_image_url' in doc:
+                    doc['image'] = doc['main_image_url']
+                    doc['images'] = [{'image_url': doc['main_image_url']}]
+                
+                # Enrich with basic fields if missing for card
+                if 'specifications' not in doc:
+                    # Funded properties usually have flattened specs in them if archived correctly, 
+                    # but if not, we might check if we can fetch them or just provide defaults 
+                    # based on what's available in the doc
+                    doc['specifications'] = {
+                        "bedroom": doc.get("specifications", {}).get("bedroom") or doc.get("bedroom") or 0,
+                        "bathroom": doc.get("specifications", {}).get("bathroom") or doc.get("bathroom") or 0,
+                        "area": doc.get("specifications", {}).get("area") or doc.get("area") or 0,
+                    }
+
+                properties_list.append(doc)
+        
+        result["properties"] = properties_list
+        
+        print(f"[PROPERTIES] [SUCCESS] Returned {len(properties_list)} properties. Counts: {result['counts']}\n")
+        return result
+        
+    except Exception as e:
+        print(f"[PROPERTIES] [ERROR] Error in public status listing: {e}\n")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to retrieve properties"
+        )
+
+
+@router.get("/properties", response_model=List[schemas.PropertyOut])
+@limiter.limit("60/minute")
+def list_properties(
+    request: Request,
+    is_active: Optional[bool] = Query(None, description="Filter by active status"),
+    skip: int = Query(0, ge=0, description="Number of records to skip"),
+    limit: int = Query(100, ge=1, le=500, description="Max number of records to return"),
+    db=Depends(get_mongo),
+    current_user: dict = Depends(get_current_user)  # REQUIRE AUTHENTICATION
+):
+    """
+    List all properties with optional filtering
+    SECURED: Authentication required to view properties
+    Rate limited to 60 requests per minute per user
+    OPTIMIZED: Uses aggregation pipeline to fetch all related data in single query
+    Returns full property data including documents for authenticated users
+    """
+    print(f"\n[PROPERTIES] Listing properties (is_active={is_active}, skip={skip}, limit={limit})")
+    print(f"[PROPERTIES] Requested by: {current_user['email']}")
+    
+    # Use optimized version that fetches all data in single aggregation query
+    properties = repo.list_properties_optimized(db, is_active=is_active, skip=skip, limit=limit)
+    
+    # Build enriched property objects (data already loaded from aggregation)
+    enriched_properties = []
+    for prop in properties:
+        # Map OLD schema to NEW schema for backward compatibility
+        prop = map_old_to_new_schema(prop)
+        
+        # Extract nested data from aggregation result
+        spec = prop.pop('specifications', None)
+        amenities = prop.pop('amenities', [])
+        images = prop.pop('images', [])
+        documents = prop.pop('documents', [])  # Include documents for authenticated users
+        
+        # Build enriched property object WITH documents (authenticated users get full access)
+        prop_out = schemas.PropertyOut(
+            **prop,
+            specifications=schemas.PropertySpecificationOut(**spec) if spec else None,
+            amenities=[schemas.AmenityOut(**a) for a in amenities] if amenities else None,
+            images=[schemas.PropertyImageOut(**img) for img in images] if images else None,
+            documents=[schemas.DocumentOut(**d) for d in documents] if documents else None
+        )
+        enriched_properties.append(prop_out)
+    
+    print(f"[PROPERTIES] [SUCCESS] Returning {len(enriched_properties)} properties (authenticated user - full data)\n")
+    
+    return enriched_properties
+
+
+@router.get("/properties/{property_id}")
+@limiter.limit("120/minute")
+def get_property(
+    request: Request, 
+    property_id: str, 
+    db=Depends(get_mongo),
+    current_user: dict = Depends(get_current_user)  # REQUIRE AUTHENTICATION
+):
+    """
+    Get detailed information about a specific property
+    SECURED: Authentication required to view property details
+    Rate limited to 120 requests per minute per user
+    Validates property ID format before querying
+    Returns property with FULL issuer details (for authenticated users only)
+    Documents are included for authenticated users
+    """
+    print(f"\n[PROPERTIES] Getting property details: {property_id}")
+    print(f"[PROPERTIES] Requested by: {current_user['email']}")
+    
+    # Validate ObjectId format
+    if not validate_object_id(property_id):
+        print(f"[PROPERTIES] [ERROR] Invalid property ID format: {property_id}\n")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid property ID format. Property ID must be a valid 24-character hexadecimal string."
+        )
+    
+    try:
+        # Use optimized version that fetches all data in single aggregation query
+        prop = repo.get_property_by_id_optimized(db, property_id)
+        
+        if not prop:
+            print(f"[PROPERTIES] [ERROR] Property not found: {property_id}\n")
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Property not found. The property you are looking for does not exist or has been removed."
+            )
+        
+        # Extract nested data from aggregation result
+        spec = prop.pop('specifications', None)
+        amenities = prop.pop('amenities', [])
+        images = prop.pop('images', [])
+        documents = prop.pop('documents', [])  # Include documents for authenticated users
+        
+        # Get issuer details (created_by user) - FULL details for authenticated users
+        issuer = None
+        if prop.get('created_by'):
+            try:
+                issuer_user = repo.get_user_by_id(db, prop['created_by'])
+                if issuer_user:
+                    # Get issuer's wallet for XRP address
+                    issuer_wallet = repo.get_wallet_by_user(db, issuer_user['id'])
+                    
+                    # AUTHENTICATED: Show full details
+                    issuer = {
+                        'id': issuer_user['id'],
+                        'name': issuer_user.get('name'),
+                        'email': issuer_user.get('email'),  # Full email
+                        'phone': issuer_user.get('phone'),  # Full phone
+                        'role': issuer_user.get('role'),
+                        'xrp_address': issuer_wallet.get('xrp_address') if issuer_wallet else None
+                    }
+                    print(f"[PROPERTIES]   - Issuer: {issuer['name']} (full details - authenticated)")
+            except Exception as e:
+                print(f"[PROPERTIES]   - Warning: Could not fetch issuer details: {e}")
+        
+        # Map OLD schema to NEW schema for backward compatibility
+        prop = map_old_to_new_schema(prop)
+        
+        print(f"[PROPERTIES] [SUCCESS] Property found: {prop.get('title', 'Unknown')}")
+        print(f"[PROPERTIES]   - Specifications: {'Yes' if spec else 'No'}")
+        print(f"[PROPERTIES]   - Amenities: {len(amenities)}")
+        print(f"[PROPERTIES]   - Images: {len(images)}")
+        print(f"[PROPERTIES]   - Documents: {len(documents)} (included for authenticated user)\n")
+        
+        # Build response WITH documents (authenticated users get full access)
+        property_response = schemas.PropertyOut(
+            **prop,
+            specifications=schemas.PropertySpecificationOut(**spec) if spec else None,
+            amenities=[schemas.AmenityOut(**a) for a in amenities] if amenities else None,
+            images=[schemas.PropertyImageOut(**img) for img in images] if images else None,
+            documents=[schemas.DocumentOut(**d) for d in documents] if documents else None
+        )
+        
+        # Convert to dict and add full issuer details
+        response_dict = property_response.dict()
+        if issuer:
+            response_dict['issuer'] = issuer
+        
+        return response_dict
+    except HTTPException:
+        # Re-raise HTTP exceptions
+        raise
+    except Exception as e:
+        print(f"[PROPERTIES] [ERROR] Error retrieving property: {str(e)}\n")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="An error occurred while retrieving property details. Please try again later."
+        )
+
+
+# NOTE: create_property endpoint is implemented in routes/admin.py with IOU tokenization logic
+
+@router.patch("/admin/properties/{property_id}", response_model=schemas.PropertyOut)
+def update_property(
+    property_id: str,
+    property_update: schemas.PropertyUpdate,
+    db=Depends(get_mongo),
+    admin_user=Depends(get_current_admin)
+):
+    """
+    Update property details (Admin only)
+    """
+    print(f"\n[PROPERTIES] Admin updating property: {property_id}")
+    print(f"[PROPERTIES] Updated by: {admin_user['email']}")
+    
+    # Check if property exists
+    existing = repo.get_property_by_id(db, property_id)
+    if not existing:
+        print(f"[PROPERTIES] [ERROR] Property not found: {property_id}\n")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Property not found"
+        )
+    
+    # Update property
+    update_data = property_update.dict(exclude_none=True)
+    
+    if not update_data:
+        print(f"[PROPERTIES] ⚠ No fields to update\n")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="No fields to update"
+        )
+    
+    updated_property = repo.update_property(db, property_id, update_data)
+    
+    if not updated_property:
+        print(f"[PROPERTIES] [ERROR] Failed to update property\n")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to update property"
+        )
+    
+    print(f"[PROPERTIES] [SUCCESS] Property updated: {list(update_data.keys())}\n")
+    
+    # Get related data
+    spec = repo.get_property_specification(db, property_id)
+    amenities = repo.get_property_amenities(db, property_id)
+    images = repo.get_property_images(db, property_id)
+    
+    return schemas.PropertyOut(
+        **updated_property,
+        specifications=schemas.PropertySpecificationOut(**spec) if spec else None,
+        amenities=[schemas.AmenityOut(**a) for a in amenities] if amenities else None,
+        images=[schemas.PropertyImageOut(**img) for img in images] if images else None
+    )
+
+
+# ============================================================================
+# DOCUMENT MANAGEMENT ENDPOINTS
+# ============================================================================
+
+@router.post("/admin/properties/{property_id}/documents", response_model=schemas.DocumentOut, status_code=status.HTTP_201_CREATED)
+def add_property_document(
+    property_id: str,
+    document_data: schemas.DocumentCreate,
+    db=Depends(get_mongo),
+    admin_user=Depends(get_current_admin)
+):
+    """
+    Add a document to a property (Admin only)
+    Supports: PDF, DOC, DOCX, JPG, PNG
+    """
+    print(f"\n[DOCUMENTS] Adding document to property: {property_id}")
+    print(f"[DOCUMENTS] File type: {document_data.file_type}, Uploaded by: {admin_user['email']}")
+    
+    # Verify property exists
+    property_obj = repo.get_property_by_id(db, property_id)
+    if not property_obj:
+        print(f"[DOCUMENTS] [ERROR] Property not found: {property_id}\n")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Property not found"
+        )
+    
+    # Create document
+    document = repo.create_document(
+        db,
+        property_id,
+        document_data.file_type,
+        document_data.file_url,
+        admin_user['id']
+    )
+    
+    print(f"[DOCUMENTS] [SUCCESS] Document added successfully: {document['id']}\n")
+    
+    return schemas.DocumentOut(**document)
+
+
+@router.get("/properties/{property_id}/documents", response_model=List[schemas.DocumentOut])
+def get_property_documents_list(
+    property_id: str,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)  # SECURITY: Require authentication
+):
+    """
+    Get all documents for a property
+    SECURED: Authentication required to view property documents
+    """
+    print(f"\n[DOCUMENTS] Fetching documents for property: {property_id}")
+    print(f"[DOCUMENTS] Requested by: {current_user['email']}")
+    
+    # Verify property exists
+    property_obj = repo.get_property_by_id(db, property_id)
+    if not property_obj:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Property not found"
+        )
+    
+    documents = repo.get_property_documents(db, property_id)
+    
+    print(f"[DOCUMENTS] [SUCCESS] Found {len(documents)} documents\n")
+    
+    return [schemas.DocumentOut(**d) for d in documents]
+
+
+@router.delete("/admin/properties/{property_id}/documents/{document_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_property_document(
+    property_id: str,
+    document_id: str,
+    db=Depends(get_mongo),
+    admin_user=Depends(get_current_admin)
+):
+    """
+    Delete a property document (Admin only)
+    """
+    print(f"\n[DOCUMENTS] Deleting document: {document_id} from property: {property_id}")
+    print(f"[DOCUMENTS] Deleted by: {admin_user['email']}")
+    
+    from bson import ObjectId
+    
+    # Delete from database
+    result = db.documents.delete_one({"_id": ObjectId(document_id)})
+    
+    if result.deleted_count == 0:
+        print(f"[DOCUMENTS] [ERROR] Document not found: {document_id}\n")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Document not found"
+        )
+    
+    print(f"[DOCUMENTS] [SUCCESS] Document deleted successfully\n")
+    
+    return None
+
+
+# ============================================================================
+# FUNDED PROPERTIES ENDPOINTS
+# ============================================================================
+
+def archive_to_funded_properties(db, property_obj: dict) -> dict:
+    """
+    Helper function to archive a property to the funded_properties collection
+    when it reaches 100% funding (available_tokens = 0).
+    
+    This creates a snapshot of the property at the time of full funding.
+    """
+    print(f"[FUNDED] Archiving property to funded_properties: {property_obj.get('id')}")
+    
+    now = datetime.utcnow()
+    
+    # Calculate funding duration if created_at exists
+    created_at = property_obj.get('created_at')
+    funding_duration_days = None
+    if created_at:
+        if isinstance(created_at, str):
+            created_at = datetime.fromisoformat(created_at.replace('Z', '+00:00'))
+        funding_duration_days = (now - created_at).days
+    
+    # Get main image URL
+    images = property_obj.get('images', [])
+    main_image_url = None
+    if images:
+        for img in images:
+            if isinstance(img, dict) and img.get('is_main'):
+                main_image_url = img.get('image_url')
+                break
+        if not main_image_url and images:
+            first_img = images[0]
+            main_image_url = first_img.get('image_url') if isinstance(first_img, dict) else None
+    
+    # Count unique investors
+    try:
+        investor_count = db.investments.count_documents({
+            "property_id": property_obj.get('id'),
+            "status": "confirmed"
+        })
+        
+        # Calculate average investment
+        pipeline = [
+            {"$match": {"property_id": property_obj.get('id'), "status": "confirmed"}},
+            {"$group": {"_id": None, "avg_amount": {"$avg": "$amount"}}}
+        ]
+        avg_result = list(db.investments.aggregate(pipeline))
+        average_investment = avg_result[0]['avg_amount'] if avg_result else None
+    except Exception as e:
+        print(f"[FUNDED] Warning: Could not calculate investor stats: {e}")
+        investor_count = 0
+        average_investment = None
+    
+    # Build funded property document
+    funded_doc = {
+        "property_id": property_obj.get('id'),
+        "title": property_obj.get('title', property_obj.get('name', 'Unknown')),
+        "description": property_obj.get('description', ''),
+        "location": property_obj.get('location', property_obj.get('city', '')),
+        "property_type": property_obj.get('property_type', property_obj.get('type', 'Residential')),
+        "total_tokens": property_obj.get('total_tokens', property_obj.get('tokens', 0)),
+        "token_price": property_obj.get('token_price', property_obj.get('price_per_token', 0)),
+        "original_price": property_obj.get('original_price', property_obj.get('value_in_inr', 0)),
+        "funding_status": "funded",
+        "funded_date": now,
+        "funding_duration_days": funding_duration_days,
+        "total_investors": investor_count,
+        "average_investment": average_investment,
+        "net_rental_yield": property_obj.get('net_rental_yield'),
+        "annual_roi": property_obj.get('annual_roi'),
+        "gross_rental_yield": property_obj.get('gross_rental_yield'),
+        "main_image_url": main_image_url,
+        "is_active": True,
+        "created_at": now,
+        "updated_at": now
+    }
+    
+    # Upsert to funded_properties (update if exists, insert if not)
+    try:
+        result = db.funded_properties.update_one(
+            {"property_id": property_obj.get('id')},
+            {"$set": funded_doc},
+            upsert=True
+        )
+        
+        if result.upserted_id:
+            funded_doc['id'] = str(result.upserted_id)
+            print(f"[FUNDED] [SUCCESS] Property archived as new funded property")
+        else:
+            # Get existing document ID
+            existing = db.funded_properties.find_one({"property_id": property_obj.get('id')})
+            if existing:
+                funded_doc['id'] = str(existing['_id'])
+            print(f"[FUNDED] [SUCCESS] Funded property record updated")
+        
+        # Also update the funded_date on the original property
+        db.properties.update_one(
+            {"_id": ObjectId(property_obj.get('id'))},
+            {"$set": {"funded_date": now}}
+        )
+        
+        return funded_doc
+        
+    except Exception as e:
+        print(f"[FUNDED] [ERROR] Failed to archive property: {e}")
+        raise
+
+
+@router.get("/funded-properties", response_model=schemas.FundedPropertiesListResponse)
+@limiter.limit("60/minute")
+def list_funded_properties(
+    request: Request,
+    skip: int = Query(0, ge=0, description="Number of records to skip"),
+    limit: int = Query(50, ge=1, le=100, description="Max number of records to return"),
+    db=Depends(get_mongo),
+    current_user: dict = Depends(get_current_user)
+):
+    """
+    List all funded (100% subscribed) properties.
+    SECURED: Authentication required.
+    Returns properties from the funded_properties collection.
+    """
+    print(f"\n[FUNDED] Listing funded properties (skip={skip}, limit={limit})")
+    print(f"[FUNDED] Requested by: {current_user['email']}")
+    
+    try:
+        # Query funded_properties collection
+        cursor = db.funded_properties.find(
+            {"is_active": True, "funding_status": "funded"}
+        ).sort("funded_date", -1).skip(skip).limit(limit)
+        
+        funded_properties = []
+        for doc in cursor:
+            doc['id'] = str(doc.pop('_id'))
+            
+            # If main_image_url is missing, try to fetch from original property
+            if not doc.get('main_image_url') and doc.get('property_id'):
+                try:
+                    # Fetch images from property_images collection using property_id
+                    prop_images = list(db.property_images.find({
+                        "property_id": ObjectId(doc['property_id']),
+                        "is_active": True
+                    }).limit(1))
+                    
+                    if prop_images:
+                        main_img = next((img for img in prop_images if img.get('is_main')), prop_images[0])
+                        doc['main_image_url'] = main_img.get('image_url')
+                except Exception as img_err:
+                    print(f"[FUNDED] Warning: Could not fetch image for property {doc.get('property_id')}: {img_err}")
+            
+            funded_properties.append(schemas.FundedPropertyOut(**doc))
+        
+        # Get total count
+        total_count = db.funded_properties.count_documents(
+            {"is_active": True, "funding_status": "funded"}
+        )
+        
+        # Calculate funding stats
+        stats_pipeline = [
+            {"$match": {"is_active": True, "funding_status": "funded"}},
+            {"$group": {
+                "_id": None,
+                "total_value": {"$sum": "$original_price"},
+                "total_investors": {"$sum": "$total_investors"},
+                "avg_funding_days": {"$avg": "$funding_duration_days"}
+            }}
+        ]
+        stats_result = list(db.funded_properties.aggregate(stats_pipeline))
+        funding_stats = None
+        if stats_result:
+            s = stats_result[0]
+            funding_stats = {
+                "total_funded_value": s.get('total_value', 0),
+                "total_unique_investors": s.get('total_investors', 0),
+                "average_funding_days": round(s.get('avg_funding_days', 0), 1) if s.get('avg_funding_days') else None
+            }
+        
+        print(f"[FUNDED] [SUCCESS] Found {len(funded_properties)} funded properties (total: {total_count})\n")
+        
+        return schemas.FundedPropertiesListResponse(
+            properties=funded_properties,
+            total_count=total_count,
+            funding_stats=funding_stats
+        )
+        
+    except Exception as e:
+        print(f"[FUNDED] [ERROR] Error listing funded properties: {e}\n")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to retrieve funded properties"
+        )
+
+
+@router.get("/funded-properties/{property_id}", response_model=schemas.FundedPropertyOut)
+@limiter.limit("120/minute")
+def get_funded_property(
+    request: Request,
+    property_id: str,
+    db=Depends(get_mongo),
+    current_user: dict = Depends(get_current_user)
+):
+    """
+    Get details of a specific funded property.
+    SECURED: Authentication required.
+    """
+    print(f"\n[FUNDED] Getting funded property: {property_id}")
+    print(f"[FUNDED] Requested by: {current_user['email']}")
+    
+    if not validate_object_id(property_id):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid property ID format"
+        )
+    
+    try:
+        # Try to find by property_id reference first, then by _id
+        doc = db.funded_properties.find_one({"property_id": property_id})
+        
+        if not doc:
+            doc = db.funded_properties.find_one({"_id": ObjectId(property_id)})
+        
+        if not doc:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Funded property not found"
+            )
+        
+        doc['id'] = str(doc.pop('_id'))
+        
+        print(f"[FUNDED] [SUCCESS] Found funded property: {doc.get('title')}\n")
+        
+        return schemas.FundedPropertyOut(**doc)
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        print(f"[FUNDED] [ERROR] Error retrieving funded property: {e}\n")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to retrieve funded property"
+        )
+
+
+@router.get("/properties-by-status")
+@limiter.limit("60/minute")
+def list_properties_by_status(
+    request: Request,
+    status_filter: str = Query("available", description="Filter: 'available', 'funded', or 'all'"),
+    skip: int = Query(0, ge=0),
+    limit: int = Query(50, ge=1, le=100),
+    db=Depends(get_mongo),
+    current_user: dict = Depends(get_current_user)
+):
+    """
+    List properties filtered by funding status.
+    - 'available': Properties with available_tokens > 0
+    - 'funded': Properties from funded_properties collection (available_tokens = 0)
+    - 'all': Both available and funded properties combined
+    
+    SECURED: Authentication required.
+    This endpoint is designed to power the frontend tabs (Available | Funded).
+    """
+    print(f"\n[PROPERTIES] Listing by status: {status_filter} (skip={skip}, limit={limit})")
+    print(f"[PROPERTIES] Requested by: {current_user['email']}")
+    
+    result = {
+        "status_filter": status_filter,
+        "available_properties": [],
+        "funded_properties": [],
+        "available_count": 0,
+        "funded_count": 0
+    }
+    
+    try:
+        if status_filter in ["available", "all"]:
+            # Get available properties (available_tokens > 0)
+            available_cursor = db.properties.find({
+                "is_active": True,
+                "available_tokens": {"$gt": 0}
+            }).sort("created_at", -1)
+            
+            if status_filter == "available":
+                available_cursor = available_cursor.skip(skip).limit(limit)
+            
+            for prop in available_cursor:
+                prop['id'] = str(prop.pop('_id'))
+                prop = map_old_to_new_schema(prop)
+                result["available_properties"].append(prop)
+            
+            result["available_count"] = db.properties.count_documents({
+                "is_active": True,
+                "available_tokens": {"$gt": 0}
+            })
+        
+        if status_filter in ["funded", "all"]:
+            # Get funded properties from funded_properties collection
+            funded_cursor = db.funded_properties.find({
+                "is_active": True,
+                "funding_status": "funded"
+            }).sort("funded_date", -1)
+            
+            if status_filter == "funded":
+                funded_cursor = funded_cursor.skip(skip).limit(limit)
+            
+            for doc in funded_cursor:
+                doc['id'] = str(doc.pop('_id'))
+                result["funded_properties"].append(doc)
+            
+            result["funded_count"] = db.funded_properties.count_documents({
+                "is_active": True,
+                "funding_status": "funded"
+            })
+        
+        print(f"[PROPERTIES] [SUCCESS] Available: {len(result['available_properties'])}, Funded: {len(result['funded_properties'])}\n")
+        
+        return result
+        
+    except Exception as e:
+        print(f"[PROPERTIES] [ERROR] Error listing properties by status: {e}\n")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to retrieve properties"
+        )

routes/secondary_market.py

@@ -0,0 +1,286 @@
+"""
+Secondary Market Routes - Token Trading
+Allows users to buy/sell tokens on XRP DEX
+"""
+from fastapi import APIRouter, Depends, HTTPException, status, Request
+from typing import List, Dict, Any
+from pydantic import BaseModel
+
+import schemas
+from db import get_mongo
+import repo
+from routes.auth import get_current_user
+from services.secondary_market import secondary_market
+from services.price_oracle import price_oracle
+from utils.crypto_utils import decrypt_secret
+from config import settings
+from middleware.security import limiter
+
+router = APIRouter()
+
+
+class SellOfferRequest(BaseModel):
+    property_id: str
+    token_amount: int
+    price_per_token_aed: float  # Price in AED (will convert to XRP)
+
+
+class BuyOfferRequest(BaseModel):
+    property_id: str
+    token_amount: int
+    price_per_token_aed: float
+
+
+class CancelOfferRequest(BaseModel):
+    offer_sequence: int
+
+
+@router.post("/secondary-market/sell")
+@limiter.limit("30/hour")  # Limit sell offers to prevent spam
+def create_sell_offer(
+    request: Request,
+    sell_request: SellOfferRequest,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """
+    Create a sell offer for your tokens
+    List your tokens for sale at your desired price
+    Rate Limited: 30 sell offers per hour
+    """
+    print(f"\n[SECONDARY MARKET] User {current_user['email']} creating sell offer")
+    
+    # Get property token info
+    property_token = repo.get_property_token(db, sell_request.property_id)
+    if not property_token:
+        raise HTTPException(status_code=404, detail="Property token not found")
+    
+    currency_code = property_token['currency_code']
+    issuer_address = property_token['issuer_address']
+    
+    # Get user's wallet
+    wallet = repo.get_wallet_by_user(db, current_user['id'])
+    if not wallet or not wallet.get('xrp_seed'):
+        raise HTTPException(status_code=400, detail="XRP wallet required")
+    
+    # Decrypt wallet seed
+    seller_seed = decrypt_secret(wallet['xrp_seed'], settings.ENCRYPTION_KEY)
+    if not seller_seed:
+        raise HTTPException(status_code=500, detail="Failed to decrypt wallet")
+    
+    # Convert AED price to XRP
+    price_per_token_xrp = price_oracle.get_aed_to_xrp(sell_request.price_per_token_aed)
+    
+    print(f"  Property ID: {sell_request.property_id}")
+    print(f"  Tokens: {sell_request.token_amount}")
+    print(f"  Price: {sell_request.price_per_token_aed} AED = {price_per_token_xrp:.6f} XRP per token")
+    
+    # Create sell offer on DEX
+    result = secondary_market.create_sell_offer(
+        seller_seed=seller_seed,
+        currency_code=currency_code,
+        issuer_address=issuer_address,
+        token_amount=sell_request.token_amount,
+        price_per_token_xrp=price_per_token_xrp
+    )
+    
+    if not result.get('success'):
+        raise HTTPException(status_code=400, detail=result.get('error', 'Failed to create offer'))
+    
+    # Record offer in database
+    repo.create_transaction(
+        db,
+        user_id=current_user['id'],
+        wallet_id=wallet['id'],
+        tx_type="sell",
+        amount=sell_request.price_per_token_aed * sell_request.token_amount,
+        property_id=sell_request.property_id,
+        status="pending",
+        metadata={
+            "offer_type": "sell",
+            "offer_sequence": result['offer_sequence'],
+            "token_amount": sell_request.token_amount,
+            "price_per_token_aed": sell_request.price_per_token_aed,
+            "price_per_token_xrp": price_per_token_xrp,
+            "blockchain_tx_hash": result['tx_hash']
+        }
+    )
+    
+    return {
+        "success": True,
+        "message": "Sell offer created successfully!",
+        "offer_sequence": result['offer_sequence'],
+        "tx_hash": result['tx_hash'],
+        "token_amount": sell_request.token_amount,
+        "price_per_token_aed": sell_request.price_per_token_aed,
+        "price_per_token_xrp": price_per_token_xrp,
+        "total_xrp": result['total_xrp']
+    }
+
+
+@router.post("/secondary-market/buy")
+@limiter.limit("30/hour")  # Limit buy offers to prevent spam
+def create_buy_offer(
+    request: Request,
+    buy_request: BuyOfferRequest,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """
+    Create a buy offer for tokens
+    Place a bid to buy tokens at your desired price
+    Rate Limited: 30 buy offers per hour
+    """
+    print(f"\n[SECONDARY MARKET] User {current_user['email']} creating buy offer")
+    
+    # Get property token info
+    property_token = repo.get_property_token(db, buy_request.property_id)
+    if not property_token:
+        raise HTTPException(status_code=404, detail="Property token not found")
+    
+    currency_code = property_token['currency_code']
+    issuer_address = property_token['issuer_address']
+    
+    # Get user's wallet
+    wallet = repo.get_wallet_by_user(db, current_user['id'])
+    if not wallet or not wallet.get('xrp_seed'):
+        raise HTTPException(status_code=400, detail="XRP wallet required")
+    
+    # Decrypt wallet seed
+    buyer_seed = decrypt_secret(wallet['xrp_seed'], settings.ENCRYPTION_KEY)
+    if not buyer_seed:
+        raise HTTPException(status_code=500, detail="Failed to decrypt wallet")
+    
+    # Convert AED price to XRP
+    price_per_token_xrp = price_oracle.get_aed_to_xrp(buy_request.price_per_token_aed)
+    
+    # Create buy offer on DEX
+    result = secondary_market.create_buy_offer(
+        buyer_seed=buyer_seed,
+        currency_code=currency_code,
+        issuer_address=issuer_address,
+        token_amount=buy_request.token_amount,
+        price_per_token_xrp=price_per_token_xrp
+    )
+    
+    if not result.get('success'):
+        raise HTTPException(status_code=400, detail=result.get('error', 'Failed to create offer'))
+    
+    # Record offer in database
+    repo.create_transaction(
+        db,
+        user_id=current_user['id'],
+        wallet_id=wallet['id'],
+        tx_type="buy",
+        amount=buy_request.price_per_token_aed * buy_request.token_amount,
+        property_id=buy_request.property_id,
+        status="pending",
+        metadata={
+            "offer_type": "buy",
+            "offer_sequence": result['offer_sequence'],
+            "token_amount": buy_request.token_amount,
+            "price_per_token_aed": buy_request.price_per_token_aed,
+            "price_per_token_xrp": price_per_token_xrp,
+            "blockchain_tx_hash": result['tx_hash']
+        }
+    )
+    
+    return {
+        "success": True,
+        "message": "Buy offer created successfully!",
+        "offer_sequence": result['offer_sequence'],
+        "tx_hash": result['tx_hash'],
+        "token_amount": buy_request.token_amount,
+        "price_per_token_aed": buy_request.price_per_token_aed,
+        "price_per_token_xrp": price_per_token_xrp,
+        "total_xrp": result['total_xrp']
+    }
+
+
+@router.post("/secondary-market/cancel")
+@limiter.limit("60/hour")  # Limit cancellations
+def cancel_offer(
+    request: Request,
+    cancel_request: CancelOfferRequest,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """Cancel an existing buy/sell offer - Rate Limited: 60 cancellations per hour"""
+    wallet = repo.get_wallet_by_user(db, current_user['id'])
+    if not wallet or not wallet.get('xrp_seed'):
+        raise HTTPException(status_code=400, detail="XRP wallet required")
+    
+    # Decrypt wallet seed
+    wallet_seed = decrypt_secret(wallet['xrp_seed'], settings.ENCRYPTION_KEY)
+    if not wallet_seed:
+        raise HTTPException(status_code=500, detail="Failed to decrypt wallet")
+    
+    result = secondary_market.cancel_offer(
+        wallet_seed=wallet_seed,
+        offer_sequence=cancel_request.offer_sequence
+    )
+    
+    if not result.get('success'):
+        raise HTTPException(status_code=400, detail=result.get('error', 'Failed to cancel offer'))
+    
+    return {
+        "success": True,
+        "message": "Offer cancelled successfully",
+        "tx_hash": result['tx_hash']
+    }
+
+
+@router.get("/secondary-market/my-offers")
+@limiter.limit("60/minute")  # Limit queries
+def get_my_offers(
+    request: Request,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """Get all your active buy/sell offers"""
+    wallet = repo.get_wallet_by_user(db, current_user['id'])
+    if not wallet or not wallet.get('xrp_address'):
+        return {"offers": []}
+    
+    offers = secondary_market.get_user_offers(wallet['xrp_address'])
+    
+    return {
+        "success": True,
+        "offers": offers,
+        "total_offers": len(offers)
+    }
+
+
+@router.get("/secondary-market/orderbook/{property_id}")
+@limiter.limit("60/minute")  # Limit orderbook queries
+def get_orderbook(
+    request: Request,
+    property_id: str,
+    db=Depends(get_mongo),
+    current_user: dict = Depends(get_current_user)
+):
+    """Get orderbook (buy and sell offers) for a property - Requires authentication - Rate Limited: 60/minute"""
+    property_token = repo.get_property_token(db, property_id)
+    if not property_token:
+        raise HTTPException(status_code=404, detail="Property token not found")
+    
+    orderbook = secondary_market.get_orderbook(
+        currency_code=property_token['currency_code'],
+        issuer_address=property_token['issuer_address']
+    )
+    
+    if not orderbook.get('success'):
+        raise HTTPException(status_code=500, detail="Failed to get orderbook")
+    
+    # Convert XRP prices to AED for display
+    for bid in orderbook['bids']:
+        bid['price_aed'] = price_oracle.get_xrp_to_aed(bid['price'])
+    
+    for ask in orderbook['asks']:
+        ask['price_aed'] = price_oracle.get_xrp_to_aed(ask['price'])
+    
+    return {
+        "success": True,
+        "property_id": property_id,
+        "orderbook": orderbook
+    }

routes/super_admin.py

@@ -0,0 +1,1410 @@
+"""
+Super Admin Routes
+Handles platform-wide administration and management
+Only accessible by users with super_admin role
+"""
+from fastapi import APIRouter, Depends, HTTPException, status, Query
+from typing import List, Optional
+from pydantic import BaseModel
+from datetime import datetime, timedelta
+from pathlib import Path
+from bson import ObjectId
+import json
+import psutil
+import time
+
+import schemas
+from db import get_mongo
+import repo
+from repo import _clean_object
+from routes.auth import get_current_user, hash_password, verify_password
+from middleware.security import sanitize_input
+
+router = APIRouter()
+
+SECURITY_LOG_PATH = Path("logs/security.log")
+APP_START_TIME = time.time()
+
+
+class NotificationDismissPayload(BaseModel):
+    notification_ids: List[str]
+
+
+def _notification_ack_collection(db):
+    return db.super_admin_notification_ack
+
+
+def _get_acknowledged_notification_ids(db, super_admin_id) -> set:
+    coll = _notification_ack_collection(db)
+    cursor = coll.find({
+        "super_admin_id": str(super_admin_id)
+    }, {"notification_id": 1})
+    return {doc.get("notification_id") for doc in cursor if doc.get("notification_id")}
+
+
+def _acknowledge_notifications(db, super_admin_id, notification_ids: List[str]):
+    if not notification_ids:
+        return
+    coll = _notification_ack_collection(db)
+    now = datetime.utcnow()
+    for notif_id in notification_ids:
+        if not notif_id:
+            continue
+        coll.update_one(
+            {"super_admin_id": str(super_admin_id), "notification_id": notif_id},
+            {"$set": {"acknowledged_at": now}},
+            upsert=True
+        )
+
+
+def get_current_super_admin(current_user=Depends(get_current_user)):
+    """Verify user has super_admin role"""
+    if current_user.get("role") != "super_admin":
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Super Admin access required. This action is restricted to platform administrators only."
+        )
+    return current_user
+
+
+def _parse_security_logs(limit: int = 50) -> List[dict]:
+    """Tail the structured security log file and surface recent entries."""
+    if not SECURITY_LOG_PATH.exists():
+        return []
+
+    try:
+        with SECURITY_LOG_PATH.open("r", encoding="utf-8", errors="ignore") as handle:
+            lines = handle.readlines()
+    except Exception as exc:
+        print(f"[SUPER ADMIN] Unable to read security log: {exc}")
+        return []
+
+    entries: List[dict] = []
+    severity_map = {
+        "INFO": "low",
+        "WARNING": "high",
+        "ERROR": "critical",
+        "CRITICAL": "critical"
+    }
+
+    for raw_line in reversed(lines):
+        if len(entries) >= limit:
+            break
+        parts = raw_line.strip().split(" - ", 3)
+        if len(parts) < 4:
+            continue
+        timestamp_str, _logger, level, message = parts
+        payload = {}
+        json_start = message.find("{")
+        action = message.split(":", 1)[0].strip()
+        if json_start != -1:
+            try:
+                payload = json.loads(message[json_start:])
+            except json.JSONDecodeError:
+                payload = {}
+
+        entry = {
+            "id": f"audit-{abs(hash(raw_line))}",
+            "actor": payload.get("email") or payload.get("user_id") or payload.get("ip_address") or "System",
+            "action": action or payload.get("event_type", "Security event"),
+            "severity": severity_map.get(level.strip().upper(), "medium"),
+            "source": payload.get("event_type", "system"),
+            "entity": payload.get("endpoint") or payload.get("data_type") or payload.get("activity_type"),
+            "created_at": timestamp_str,
+            "metadata": payload,
+        }
+        entries.append(entry)
+
+    return list(reversed(entries))
+
+
+def _build_wallet_overview(db):
+    """Aggregate wallet balances by owner role for dashboard metrics."""
+    wallets = list(db.wallets.find({}))
+    if not wallets:
+        return {
+            "summary": {
+                "escrow_balance": {"value": 0.0, "formatted": "0.00 XRP", "updated_at": datetime.utcnow(), "variance": "0% of total"},
+                "reserve_balance": {"value": 0.0, "formatted": "0.00 XRP", "updated_at": datetime.utcnow(), "variance": "0% of total"},
+                "operational_balance": {"value": 0.0, "formatted": "0.00 XRP", "updated_at": datetime.utcnow(), "variance": "0% of total", "pending_payouts": 0},
+            },
+            "wallets": []
+        }
+
+    owner_ids = {wallet.get("user_id") for wallet in wallets if wallet.get("user_id")}
+    owners = {}
+    if owner_ids:
+        owner_docs = db.users.find({"_id": {"$in": list(owner_ids)}})
+        owners = {doc["_id"]: doc for doc in owner_docs}
+
+    type_totals = {"escrow": 0.0, "reserve": 0.0, "operational": 0.0}
+    wallet_payload = []
+
+    for wallet in wallets:
+        owner = owners.get(wallet.get("user_id"))
+        role = (owner or {}).get("role", "user")
+        if role == "admin":
+            wallet_type = "reserve"
+        elif role == "super_admin":
+            wallet_type = "operational"
+        else:
+            wallet_type = "escrow"
+
+        balance = float(wallet.get("balance", 0.0))
+        type_totals[wallet_type] += balance
+        last_synced_at = wallet.get("last_synced_at") or wallet.get("updated_at")
+        status = "healthy" if wallet.get("is_active", True) else "inactive"
+        wallet_payload.append({
+            "id": str(wallet.get("_id")),
+            "label": (owner or {}).get("name") or wallet.get("label") or "Platform Wallet",
+            "type": wallet_type,
+            "address": wallet.get("xrp_address"),
+            "balance": balance,
+            "formatted_balance": f"{balance:.2f} {wallet.get('currency', 'XRP')}",
+            "variance": wallet.get("variance"),
+            "last_synced_at": last_synced_at,
+            "status": status
+        })
+
+    total_balance = sum(type_totals.values()) or 1.0
+    pending_payouts = db.transactions.count_documents({"status": {"$in": ["pending", "processing"]}})
+
+    def build_metric(bucket: str, include_pending: bool = False):
+        value = type_totals[bucket]
+        metric = {
+            "value": value,
+            "formatted": f"{value:.2f} XRP",
+            "updated_at": datetime.utcnow(),
+            "variance": f"{(value / total_balance) * 100:.1f}% of total"
+        }
+        if include_pending:
+            metric["pending_payouts"] = pending_payouts
+        return metric
+
+    summary = {
+        "escrow_balance": build_metric("escrow"),
+        "reserve_balance": build_metric("reserve"),
+        "operational_balance": build_metric("operational", include_pending=True)
+    }
+
+    return {"summary": summary, "wallets": wallet_payload}
+
+
+def _calculate_property_risk(property_doc: dict) -> int:
+    total = property_doc.get("total_tokens") or 0
+    available = property_doc.get("available_tokens") or 0
+    if not total:
+        return 0
+    sold_ratio = max(0.0, min(1.0, (total - available) / total))
+    risk = 35 + sold_ratio * 40
+    if not property_doc.get("is_active", True):
+        risk += 15
+    return int(min(95, round(risk)))
+
+
+def _build_property_audit(property_doc: dict, investments: List[dict]) -> List[dict]:
+    entries: List[dict] = []
+    creator = property_doc.get("creator_name") or property_doc.get("creator", {}).get("name")
+    entries.append({
+        "id": f"audit-{property_doc.get('id')}-created",
+        "actor": creator or "System",
+        "action": "Property created",
+        "severity": "low",
+        "source": "system",
+        "entity": property_doc.get("title"),
+        "created_at": property_doc.get("created_at"),
+        "metadata": {"property_id": property_doc.get("id")}
+    })
+
+    if property_doc.get("updated_at") and property_doc.get("updated_at") != property_doc.get("created_at"):
+        entries.append({
+            "id": f"audit-{property_doc.get('id')}-updated",
+            "actor": creator or "System",
+            "action": "Property updated",
+            "severity": "medium",
+            "source": "admin",
+            "entity": property_doc.get("title"),
+            "created_at": property_doc.get("updated_at"),
+            "metadata": {"is_active": property_doc.get("is_active")}
+        })
+
+    for investment in investments[:5]:
+        entries.append({
+            "id": f"audit-{investment.get('id')}-investment",
+            "actor": investment.get("investor_email") or investment.get("investor_name") or "Investor",
+            "action": "Investment confirmed",
+            "severity": "medium",
+            "source": "api",
+            "entity": property_doc.get("title"),
+            "created_at": investment.get("created_at"),
+            "metadata": {"amount": investment.get("amount"), "tokens": investment.get("tokens")}
+        })
+
+    return entries
+
+
+# ============================================================================
+# DASHBOARD & STATISTICS
+# ============================================================================
+
+@router.get("/super-admin/stats", response_model=schemas.SuperAdminStatsOut)
+def get_platform_stats(
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """
+    Get comprehensive platform statistics
+    Includes users, admins, properties, revenue, KYC status, etc.
+    """
+    print(f"\n[SUPER ADMIN] Fetching platform statistics...")
+    
+    # Get all users grouped by role
+    all_users = list(db.users.find({"deleted": False}))
+    users = [u for u in all_users if u.get("role") == "user"]
+    admins = [u for u in all_users if u.get("role") == "admin"]
+    
+    # Active vs blocked users
+    active_users = len([u for u in users if u.get("is_active", True)])
+    blocked_users = len([u for u in users if not u.get("is_active", True)])
+    
+    # KYC statistics
+    pending_kyc = len([u for u in users if u.get("kyc_status") == "pending"])
+    approved_kyc = len([u for u in users if u.get("kyc_status") == "approved"])
+    rejected_kyc = len([u for u in users if u.get("kyc_status") == "rejected"])
+    
+    # Properties
+    total_properties = db.properties.count_documents({"deleted": False})
+    
+    # Investments & Volume
+    investments = list(db.investments.find({}))
+    total_investments = len(investments)
+    total_volume = sum(inv.get("amount", 0) for inv in investments)
+    total_tokens_sold = sum(inv.get("tokens_purchased", 0) for inv in investments)
+    
+    # Platform revenue (2% of total volume)
+    platform_revenue = total_volume * 0.02
+    
+    # Total transactions
+    total_transactions = db.transactions.count_documents({})
+    
+    # Additional stats for enhanced dashboard
+    active_properties = db.properties.count_documents({"deleted": False, "is_active": True})
+    total_revenue_xrp = platform_revenue  # Alias for frontend compatibility
+    pending_kyc_count = pending_kyc  # Alias for frontend compatibility
+    approved_kyc_count = approved_kyc  # Alias for frontend compatibility
+    
+    stats = {
+        "total_users": len(users),
+        "total_admins": len(admins),
+        "total_properties": total_properties,
+        "active_properties": active_properties,
+        "total_investments": total_investments,
+        "total_volume": total_volume,
+        "platform_revenue": platform_revenue,
+        "total_revenue_xrp": total_revenue_xrp,
+        "active_users": active_users,
+        "blocked_users": blocked_users,
+        "pending_kyc": pending_kyc,
+        "pending_kyc_count": pending_kyc_count,
+        "approved_kyc": approved_kyc,
+        "approved_kyc_count": approved_kyc_count,
+        "rejected_kyc": rejected_kyc,
+        "total_tokens_sold": total_tokens_sold,
+        "total_transactions": total_transactions
+    }
+    
+    print(f"[SUPER ADMIN] [SUCCESS] Stats calculated successfully")
+    return stats
+
+
+# ============================================================================
+# USER MANAGEMENT
+# ============================================================================
+
+@router.get("/super-admin/users")
+def get_all_users(
+    skip: int = Query(0, ge=0),
+    limit: int = Query(100, ge=1, le=500),
+    role: Optional[str] = Query(None),
+    is_active: Optional[bool] = None,
+    kyc_status: Optional[str] = Query(None),
+    search: Optional[str] = None,
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """
+    Get all users with filtering and pagination
+    Can filter by role, active status, KYC status, and search
+    """
+    try:
+        print(f"\n[SUPER ADMIN] Fetching users (skip={skip}, limit={limit})")
+        print(f"[SUPER ADMIN] Super admin user: {super_admin.get('email')}")
+        
+        # Build query
+        query = {"deleted": False}
+        
+        # Exclude super admins from list
+        query["role"] = {"$ne": "super_admin"}
+        
+        if role and role in ["user", "admin"]:
+            query["role"] = role
+        
+        if is_active is not None:
+            query["is_active"] = is_active
+        
+        if kyc_status and kyc_status in ["pending", "approved", "rejected"]:
+            query["kyc_status"] = kyc_status
+        
+        if search:
+            try:
+                search_clean = sanitize_input(search)
+                query["$or"] = [
+                    {"name": {"$regex": search_clean, "$options": "i"}},
+                    {"email": {"$regex": search_clean, "$options": "i"}},
+                    {"phone": {"$regex": search_clean, "$options": "i"}}
+                ]
+            except Exception as search_error:
+                print(f"[SUPER ADMIN] Search sanitization error: {search_error}")
+        
+        print(f"[SUPER ADMIN] Query: {query}")
+        
+        # Get users
+        users = list(db.users.find(query).skip(skip).limit(limit).sort("created_at", -1))
+        print(f"[SUPER ADMIN] Found {len(users)} users in database")
+        
+        # Enrich with investment data
+        result = []
+        for user in users:
+            try:
+                user_id = str(user["_id"])
+                
+                # Get wallet balance
+                wallet = db.wallets.find_one({"user_id": user["_id"]})
+                wallet_balance = wallet.get("balance", 0.0) if wallet else 0.0
+                
+                # Get investment stats
+                user_investments = list(db.investments.find({"user_id": user["_id"]}))
+                total_invested = sum(inv.get("amount", 0) for inv in user_investments)
+                total_tokens = sum(inv.get("tokens_purchased", 0) for inv in user_investments)
+                
+                # Ensure email satisfies EmailStr validation
+                raw_email = user.get("email", "")
+                if isinstance(raw_email, str) and "@" in raw_email and "." in raw_email.split("@")[-1]:
+                    safe_email = raw_email
+                else:
+                    safe_email = f"user{user_id}@invalid.local"
+
+                # Coerce role to valid enum values (user|admin|super_admin)
+                raw_role = str(user.get("role", "user")).strip().lower()
+                if raw_role in ("superadmin", "super-admin", "super_admin"):
+                    raw_role = "super_admin"
+                elif raw_role in ("administrator",):
+                    raw_role = "admin"
+                elif raw_role not in ("user", "admin", "super_admin"):
+                    raw_role = "user"
+
+                # Normalize types for strict response model
+                created_at_val = user.get("created_at")
+                if isinstance(created_at_val, datetime):
+                    created_at_dt = created_at_val
+                else:
+                    created_at_dt = datetime.utcnow()
+                    
+                last_login_val = user.get("last_login")
+                if isinstance(last_login_val, datetime):
+                    last_login_dt = last_login_val
+                else:
+                    last_login_dt = None
+                    
+                phone_val = str(user.get("phone", "0000000000"))
+                if not phone_val or len(phone_val) < 10:
+                    phone_val = "0000000000"
+                    
+                total_invested = float(total_invested or 0.0)
+                total_tokens = int(total_tokens or 0)
+                wallet_balance = float(wallet_balance or 0.0)
+                
+                result.append({
+                    "user_id": user_id,
+                    "full_name": user.get("name", "Unknown"),
+                    "email": safe_email,
+                    "role": raw_role,
+                    "phone": phone_val,
+                    "is_active": bool(user.get("is_active", True)),
+                    "kyc_status": user.get("kyc_status", "pending"),
+                    "created_at": created_at_dt,
+                    "total_invested": total_invested,
+                    "total_tokens": total_tokens,
+                    "wallet_balance": wallet_balance,
+                    "last_login": last_login_dt
+                })
+            except Exception as user_error:
+                print(f"[SUPER ADMIN] Error processing user {user.get('email', 'unknown')}: {str(user_error)}")
+                import traceback
+                traceback.print_exc()
+                continue
+        
+        print(f"[SUPER ADMIN] [SUCCESS] Returning {len(result)} users")
+        return result
+    
+    except Exception as e:
+        print(f"[SUPER ADMIN] ERROR in get_all_users: {str(e)}")
+        import traceback
+        traceback.print_exc()
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error fetching users: {str(e)}"
+        )
+
+
+@router.put("/super-admin/users/{user_id}/block")
+def block_user(
+    user_id: str,
+    block_request: schemas.BlockUserRequest,
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Block a user account"""
+    print(f"\n[SUPER ADMIN] Blocking user: {user_id}")
+    
+    user = repo.get_user_by_id(db, user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    
+    if user.get("role") == "super_admin":
+        raise HTTPException(status_code=403, detail="Cannot block super admin")
+    
+    # Update user status
+    updated = repo.update_user(db, user_id, {
+        "is_active": False,
+        "block_reason": sanitize_input(block_request.reason),
+        "blocked_at": datetime.utcnow(),
+        "blocked_by": super_admin["id"]
+    })
+    
+    print(f"[SUPER ADMIN] [SUCCESS] User blocked: {user['email']}")
+    return {"message": "User blocked successfully", "user": updated}
+
+
+@router.put("/super-admin/users/{user_id}/unblock")
+def unblock_user(
+    user_id: str,
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Unblock a user account"""
+    print(f"\n[SUPER ADMIN] Unblocking user: {user_id}")
+    
+    user = repo.get_user_by_id(db, user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    
+    # Update user status
+    updated = repo.update_user(db, user_id, {
+        "is_active": True,
+        "block_reason": None,
+        "blocked_at": None,
+        "blocked_by": None
+    })
+    
+    print(f"[SUPER ADMIN] [SUCCESS] User unblocked: {user['email']}")
+    return {"message": "User unblocked successfully", "user": updated}
+
+
+@router.delete("/super-admin/users/{user_id}")
+def delete_user(
+    user_id: str,
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Soft delete a user account"""
+    print(f"\n[SUPER ADMIN] Deleting user: {user_id}")
+    
+    user = repo.get_user_by_id(db, user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    
+    if user.get("role") == "super_admin":
+        raise HTTPException(status_code=403, detail="Cannot delete super admin")
+    
+    # Soft delete
+    updated = repo.update_user(db, user_id, {
+        "deleted": True,
+        "is_active": False,
+        "deleted_at": datetime.utcnow(),
+        "deleted_by": super_admin["id"]
+    })
+    
+    print(f"[SUPER ADMIN] [SUCCESS] User deleted: {user['email']}")
+    return {"message": "User deleted successfully"}
+
+
+@router.put("/super-admin/users/{user_id}/role")
+def update_user_role(
+    user_id: str,
+    role_request: schemas.UpdateUserRoleRequest,
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Promote user to admin or demote admin to user"""
+    print(f"\n[SUPER ADMIN] Updating user role: {user_id} -> {role_request.new_role}")
+    
+    user = repo.get_user_by_id(db, user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    
+    if user.get("role") == "super_admin":
+        raise HTTPException(status_code=403, detail="Cannot change super admin role")
+    
+    # Update role
+    updated = repo.update_user(db, user_id, {
+        "role": role_request.new_role.value,
+        "role_updated_at": datetime.utcnow(),
+        "role_updated_by": super_admin["id"]
+    })
+    
+    print(f"[SUPER ADMIN] [SUCCESS] Role updated: {user['email']} -> {role_request.new_role}")
+    return {"message": f"User role updated to {role_request.new_role}", "user": updated}
+
+
+# ============================================================================
+# ADMIN MANAGEMENT
+# ============================================================================
+
+@router.get("/super-admin/admins")
+def get_all_admins(
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Get all admin users with their statistics"""
+    try:
+        print(f"\n[SUPER ADMIN] Fetching all admins...")
+        
+        admins = list(db.users.find({"role": "admin", "deleted": False}))
+        
+        result = []
+        for admin in admins:
+            try:
+                admin_id = str(admin["_id"])
+                
+                # Get admin's properties
+                properties = list(db.properties.find({"created_by": admin["_id"], "deleted": False}))
+                total_properties = len(properties)
+                
+                # Get investments in admin's properties
+                property_ids = [p["_id"] for p in properties]
+                investments = list(db.investments.find({"property_id": {"$in": [str(pid) for pid in property_ids]}}))
+                
+                total_revenue = sum(inv.get("amount", 0) for inv in investments) * 0.02  # 2% commission
+                unique_buyers = len(set(str(inv.get("user_id")) for inv in investments))
+                
+                # Ensure email is valid
+                raw_email = admin.get("email", "")
+                if isinstance(raw_email, str) and "@" in raw_email and "." in raw_email.split("@")[-1]:
+                    safe_email = raw_email
+                else:
+                    safe_email = f"admin{admin_id}@invalid.local"
+                
+                # Ensure phone is valid
+                phone_val = str(admin.get("phone", "0000000000"))
+                if not phone_val or len(phone_val) < 10:
+                    phone_val = "0000000000"
+                
+                # Ensure dates are datetime objects
+                created_at = admin.get("created_at")
+                if not isinstance(created_at, datetime):
+                    created_at = datetime.utcnow()
+                    
+                last_login = admin.get("last_login")
+                if last_login and not isinstance(last_login, datetime):
+                    last_login = None
+                
+                result.append({
+                    "admin_id": admin_id,
+                    "id": admin_id,
+                    "full_name": admin.get("name", "Unknown"),
+                    "name": admin.get("name", "Unknown"),
+                    "email": safe_email,
+                    "phone": phone_val,
+                    "is_active": bool(admin.get("is_active", True)),
+                    "kyc_status": admin.get("kyc_status", "pending"),
+                    "created_at": created_at,
+                    "last_login": last_login,
+                    "properties_count": total_properties,
+                    "total_properties": total_properties,
+                    "total_revenue_xrp": float(total_revenue),
+                    "total_revenue": float(total_revenue),
+                    "total_buyers": unique_buyers
+                })
+            except Exception as admin_error:
+                print(f"[SUPER ADMIN] Error processing admin {admin.get('email', 'unknown')}: {str(admin_error)}")
+                import traceback
+                traceback.print_exc()
+                continue
+        
+        print(f"[SUPER ADMIN] [SUCCESS] Found {len(result)} admins")
+        return result
+    
+    except Exception as e:
+        print(f"[SUPER ADMIN] ERROR in get_all_admins: {str(e)}")
+        import traceback
+        traceback.print_exc()
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Error fetching admins: {str(e)}"
+        )
+
+
+# ============================================================================
+# PROPERTY MANAGEMENT
+# ============================================================================
+
+@router.get("/super-admin/properties")
+def get_all_properties(
+    skip: int = Query(0, ge=0),
+    limit: int = Query(100, ge=1, le=500),
+    is_active: Optional[bool] = None,
+    property_type: Optional[str] = None,
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Get all properties across all admins"""
+    print(f"\n[SUPER ADMIN] Fetching all properties...")
+    
+    query = {"deleted": False}
+    if is_active is not None:
+        query["is_active"] = is_active
+    if property_type:
+        query["property_type"] = property_type
+    
+    properties = repo.list_properties_optimized(db, is_active=is_active, skip=skip, limit=limit)
+
+    for prop in properties:
+        creator = prop.pop("creator", None)
+        if creator:
+            prop["creator_name"] = creator.get("name", "Unknown")
+            prop["creator_email"] = creator.get("email", "Unknown")
+        if prop.get("images") and not prop.get("image"):
+            main_image = next((img.get("image_url") for img in prop["images"] if img.get("is_main")), None)
+            prop["image"] = main_image or prop["images"][0].get("image_url")
+    
+    print(f"[SUPER ADMIN] [SUCCESS] Found {len(properties)} properties")
+    return properties
+
+
+@router.get("/super-admin/properties/{property_id}")
+def get_property_detail(
+    property_id: str,
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Return a single property with investments and audit trail."""
+    try:
+        property_doc = repo.get_property_by_id_optimized(db, property_id)
+    except Exception as exc:
+        print(f"[SUPER ADMIN] Invalid property id {property_id}: {exc}")
+        raise HTTPException(status_code=400, detail="Invalid property id")
+
+    if not property_doc:
+        raise HTTPException(status_code=404, detail="Property not found")
+
+    creator = property_doc.pop("creator", None)
+    if creator:
+        property_doc["creator_name"] = creator.get("name")
+        property_doc["creator_email"] = creator.get("email")
+
+    try:
+        property_oid = ObjectId(property_id)
+    except Exception:
+        raise HTTPException(status_code=400, detail="Invalid property id")
+
+    investments_raw = list(
+        db.investments.find({"property_id": property_oid}).sort("created_at", -1).limit(50)
+    )
+    investor_ids = {inv.get("user_id") for inv in investments_raw if inv.get("user_id")}
+    investor_map = {}
+    if investor_ids:
+        investor_docs = db.users.find({"_id": {"$in": list(investor_ids)}})
+        investor_map = {doc["_id"]: doc for doc in investor_docs}
+
+    investments: List[dict] = []
+    for inv in investments_raw:
+        investor = investor_map.get(inv.get("user_id"))
+        investments.append({
+            "id": str(inv.get("_id")),
+            "investor_name": (investor or {}).get("name", "Unknown"),
+            "investor_email": (investor or {}).get("email"),
+            "tokens": inv.get("tokens_purchased", 0),
+            "amount": inv.get("amount", 0),
+            "status": inv.get("status"),
+            "created_at": inv.get("created_at")
+        })
+
+    property_doc["investments"] = investments
+    property_doc["audit_log"] = _build_property_audit(property_doc, investments)
+    property_doc["minted_tokens"] = max(0, (property_doc.get("total_tokens") or 0) - (property_doc.get("available_tokens") or 0))
+    property_doc["audit_risk_score"] = _calculate_property_risk(property_doc)
+
+    return property_doc
+
+
+@router.put("/super-admin/properties/{property_id}/toggle-active")
+def toggle_property_active(
+    property_id: str,
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Activate or deactivate any property"""
+    print(f"\n[SUPER ADMIN] Toggling property active status: {property_id}")
+    
+    prop = repo.get_property_by_id(db, property_id)
+    if not prop:
+        raise HTTPException(status_code=404, detail="Property not found")
+    
+    new_status = not prop.get("is_active", True)
+    updated = repo.update_property(db, property_id, {"is_active": new_status})
+    
+    print(f"[SUPER ADMIN] [SUCCESS] Property status changed: {new_status}")
+    return {"message": f"Property {'activated' if new_status else 'deactivated'}", "property": updated}
+
+
+# ============================================================================
+# CUSTODIAL WALLETS
+# ============================================================================
+
+@router.get("/super-admin/wallets", response_model=schemas.WalletOverviewOut)
+def get_wallet_overview(
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Surface custodial wallet balances grouped by owner role."""
+    overview = _build_wallet_overview(db)
+    return overview
+
+
+@router.post("/super-admin/wallets/sync")
+def trigger_wallet_sync(
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    now = datetime.utcnow()
+    result = db.wallets.update_many({}, {"$set": {"last_synced_at": now, "updated_at": now}})
+    print(f"[SUPER ADMIN] Wallet sync triggered by {super_admin.get('email')} -> {result.modified_count} entries")
+    return {"message": "Wallet reconciliation triggered", "synced_wallets": result.modified_count}
+
+
+# ============================================================================
+# TRANSACTION MONITORING
+# ============================================================================
+
+@router.get("/super-admin/transactions", response_model=List[schemas.TransactionDetailOut])
+def get_all_transactions(
+    skip: int = Query(0, ge=0),
+    limit: int = Query(100, ge=1, le=500),
+    tx_type: Optional[str] = None,
+    status: Optional[str] = None,
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Get all transactions across the platform"""
+    print(f"\n[SUPER ADMIN] Fetching transactions...")
+    
+    query = {}
+    if tx_type:
+        query["type"] = tx_type
+    if status:
+        query["status"] = status
+    
+    transactions = list(db.transactions.find(query).skip(skip).limit(limit).sort("created_at", -1))
+    
+    result = []
+    for tx in transactions:
+        # Get user info
+        user = db.users.find_one({"_id": tx.get("user_id")})
+        
+        # Get property info if applicable
+        property_name = None
+        if tx.get("property_id"):
+            prop = db.properties.find_one({"_id": tx.get("property_id")})
+            property_name = prop.get("title") if prop else None
+        
+        result.append({
+            "id": str(tx["_id"]),
+            "user_id": str(tx.get("user_id")),
+            "user_name": user.get("name") if user else "Unknown",
+            "user_email": user.get("email") if user else "Unknown",
+            "wallet_id": str(tx.get("wallet_id")) if tx.get("wallet_id") else None,
+            "type": tx.get("type"),
+            "amount": tx.get("amount", 0),
+            "property_id": str(tx.get("property_id")) if tx.get("property_id") else None,
+            "property_name": property_name,
+            "status": tx.get("status"),
+            "metadata": tx.get("metadata", {}),
+            "created_at": tx.get("created_at", datetime.utcnow()),
+            "blockchain_tx_hash": tx.get("metadata", {}).get("blockchain_tx_hash")
+        })
+    
+    print(f"[SUPER ADMIN] [SUCCESS] Found {len(result)} transactions")
+    return result
+
+
+# ============================================================================
+# KYC MANAGEMENT
+# ============================================================================
+
+@router.get("/super-admin/kyc/pending")
+def get_pending_kyc(
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Get all pending KYC documents"""
+    print(f"\n[SUPER ADMIN] Fetching pending KYC documents...")
+    
+    # Find users with pending KYC
+    pending_users = list(db.users.find({
+        "kyc_status": "pending",
+        "deleted": False
+    }))
+    
+    kyc_submissions = []
+    for user in pending_users:
+        kyc_submissions.append({
+            "user_id": str(user["_id"]),
+            "full_name": user.get("name", ""),
+            "email": user.get("email", ""),
+            "role": user.get("role", "user"),
+            "kyc_status": user.get("kyc_status", "pending"),
+            "document_type": user.get("kyc_document_type", "ID Card"),
+            "kyc_document_url": user.get("kyc_document_url", None),
+            "submitted_at": user.get("kyc_submitted_at", user.get("created_at", datetime.utcnow()))
+        })
+    
+    print(f"[SUPER ADMIN] [SUCCESS] Found {len(kyc_submissions)} pending KYC")
+    return {"kyc_submissions": kyc_submissions}
+
+
+@router.put("/super-admin/kyc/{user_id}/approve")
+def approve_kyc(
+    user_id: str,
+    approval: schemas.KYCApprovalRequest,
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Approve or reject user KYC"""
+    print(f"\n[SUPER ADMIN] Reviewing KYC for user: {user_id} -> {approval.status}")
+    
+    user = repo.get_user_by_id(db, user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    
+    update_data = {
+        "kyc_status": approval.status,
+        "kyc_reviewed_at": datetime.utcnow(),
+        "kyc_reviewed_by": super_admin["id"]
+    }
+    
+    if approval.status == "rejected" and approval.rejection_reason:
+        update_data["kyc_rejection_reason"] = sanitize_input(approval.rejection_reason)
+    
+    updated = repo.update_user(db, user_id, update_data)
+    
+    print(f"[SUPER ADMIN] [SUCCESS] KYC {approval.status} for {user['email']}")
+    return {"message": f"KYC {approval.status}", "user": updated}
+
+
+# ============================================================================
+# PLATFORM SETTINGS
+# ============================================================================
+
+@router.get("/super-admin/settings", response_model=schemas.PlatformSettingsOut)
+def get_platform_settings(
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Get current platform settings"""
+    # Settings stored in a special collection
+    settings_doc = db.platform_settings.find_one({"_id": "global"})
+    
+    if not settings_doc:
+        # Default settings
+        return {
+            "min_investment": 2000.0,
+            "platform_fee_percentage": 2.0,
+            "kyc_required": True,
+            "new_registrations_enabled": True,
+            "purchases_enabled": True,
+            "maintenance_mode": False
+        }
+    
+    return settings_doc
+
+
+@router.put("/super-admin/settings")
+def update_platform_settings(
+    settings: schemas.PlatformSettingsUpdate,
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Update platform settings"""
+    print(f"\n[SUPER ADMIN] Updating platform settings...")
+    
+    update_data = {k: v for k, v in settings.dict().items() if v is not None}
+    update_data["updated_at"] = datetime.utcnow()
+    update_data["updated_by"] = super_admin["id"]
+    
+    db.platform_settings.update_one(
+        {"_id": "global"},
+        {"$set": update_data},
+        upsert=True
+    )
+    
+    print(f"[SUPER ADMIN] [SUCCESS] Settings updated")
+    return {"message": "Settings updated successfully", "settings": update_data}
+
+
+@router.get("/super-admin/audit-logs")
+def get_audit_logs(
+    limit: int = Query(50, ge=10, le=200),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Expose parsed security log snippets for the audit center."""
+    return _parse_security_logs(limit)
+
+
+# ============================================================================
+# SUPER ADMIN PROFILE & SECURITY
+# ============================================================================
+
+@router.get("/super-admin/profile", response_model=schemas.SuperAdminProfileOut)
+def get_profile(super_admin=Depends(get_current_super_admin)):
+    """Return current super admin profile details."""
+    return {
+        "full_name": super_admin.get("name", ""),
+        "email": super_admin.get("email"),
+        "two_factor_enabled": bool(super_admin.get("two_factor_enabled"))
+    }
+
+
+@router.put("/super-admin/profile", response_model=schemas.SuperAdminProfileOut)
+def update_profile(
+    payload: schemas.SuperAdminProfileUpdate,
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Allow renaming/email updates for the active super admin."""
+    update_data = {
+        "name": sanitize_input(payload.full_name),
+        "email": payload.email,
+        "updated_at": datetime.utcnow()
+    }
+    updated = repo.update_user(db, super_admin["id"], update_data)
+    return {
+        "full_name": updated.get("name"),
+        "email": updated.get("email"),
+        "two_factor_enabled": bool(updated.get("two_factor_enabled"))
+    }
+
+
+@router.post("/super-admin/profile/password")
+def update_password(
+    payload: schemas.PasswordUpdateRequest,
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Rotate the super admin password after verifying the existing secret."""
+    if not verify_password(payload.current_password, super_admin.get("password_hash")):
+        raise HTTPException(status_code=400, detail="Current password is incorrect")
+
+    hashed = hash_password(payload.new_password)
+    repo.update_user(db, super_admin["id"], {"password_hash": hashed, "password_rotated_at": datetime.utcnow()})
+    return {"message": "Password updated successfully"}
+
+
+@router.post("/super-admin/profile/two-factor")
+def toggle_two_factor(
+    payload: schemas.TwoFactorToggleRequest,
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Enable or disable the 2FA flag for the active super admin."""
+    repo.update_user(db, super_admin["id"], {
+        "two_factor_enabled": bool(payload.enabled),
+        "two_factor_updated_at": datetime.utcnow()
+    })
+    return {"message": "Two-factor preference updated", "enabled": payload.enabled}
+
+
+# ============================================================================
+# NOTIFICATIONS
+# ============================================================================
+
+@router.get("/super-admin/notifications")
+def get_notifications(
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """
+    Get rich, actionable notifications for Super Admin
+    - Surface every new investor registration from the last 24h
+    - Highlight pending KYCs with the actual user name/email
+    - Flag pending withdrawal requests that still need approval
+    """
+    notifications = []
+    now = datetime.utcnow()
+    last_24h = now - timedelta(hours=24)
+
+    def _ts(value, default_ts):
+        if isinstance(value, datetime):
+            return value.isoformat()
+        if isinstance(value, str):
+            return value
+        return default_ts.isoformat()
+
+    # 1. Individual new registrations (last 24h)
+    recent_users = db.users.find({
+        "created_at": {"$gte": last_24h},
+        "role": "user",
+        "deleted": False
+    }).sort("created_at", -1).limit(5)
+
+    for user in recent_users:
+        user_name = user.get("name") or user.get("full_name") or user.get("email") or "New investor"
+        email = user.get("email", "-")
+        source = user.get("registration_source", "Web")
+        notifications.append({
+            "id": f"notif-new-user-{str(user.get('_id'))}",
+            "title": "New Investor Registered",
+            "message": f"{user_name} ({email}) completed onboarding via {source}.",
+            "type": "info",
+            "created_at": _ts(user.get("created_at"), now),
+            "read": False,
+            "action_label": "Open Investors",
+            "action_path": "/super-admin/users"
+        })
+
+    # 2. Pending KYC submissions (mirror admin experience)
+    pending_kyc_docs = db.kyc_documents.find({
+        "status": "pending"
+    }).sort("uploaded_at", -1).limit(5)
+
+    for doc in pending_kyc_docs:
+        related_user = repo.get_user_by_id(db, str(doc.get("user_id"))) if doc.get("user_id") else None
+        user_name = related_user.get("name") if related_user else doc.get("full_name") or "Unknown user"
+        email = related_user.get("email") if related_user else "N/A"
+        doc_type = doc.get("document_type", "Identity document")
+        uploaded_at = doc.get("uploaded_at") or now
+        age_hours = (now - uploaded_at).total_seconds() / 3600 if isinstance(uploaded_at, datetime) else 0
+        severity = "danger" if age_hours >= 48 else "warning"
+
+        notifications.append({
+            "id": f"notif-kyc-{str(doc.get('_id'))}",
+            "title": "Pending KYC Review",
+            "message": f"{user_name} ({email}) submitted {doc_type}. Awaiting verification.",
+            "type": severity,
+            "created_at": _ts(uploaded_at, now),
+            "read": False,
+            "action_label": "Review KYC",
+            "action_path": "/super-admin/kyc"
+        })
+
+    # 3. Pending withdrawal transactions (actionable alert)
+    pending_withdrawals = db.transactions.find({
+        "status": "pending",
+        "type": "withdrawal"
+    }).sort("created_at", -1).limit(5)
+
+    for tx in pending_withdrawals:
+        related_user = repo.get_user_by_id(db, str(tx.get("user_id"))) if tx.get("user_id") else None
+        user_label = related_user.get("email") if related_user else tx.get("user_email", "Investor")
+        amount = tx.get("amount", 0)
+        currency = tx.get("currency", "XRP")
+        wallet = tx.get("target_wallet") or tx.get("address") or "destination wallet"
+        urgency = "danger" if amount and amount >= 5000 else "warning"
+
+        notifications.append({
+            "id": f"notif-withdraw-{str(tx.get('_id'))}",
+            "title": "Withdrawal Approval Needed",
+            "message": f"{user_label} requested {amount} {currency} to {wallet}.",
+            "type": urgency,
+            "created_at": _ts(tx.get("created_at"), now),
+            "read": False,
+            "action_label": "Review Transaction",
+            "action_path": "/super-admin/transactions"
+        })
+
+    # Sort notifications so the most recent surface first
+    notifications.sort(key=lambda item: item.get("created_at", ""), reverse=True)
+
+    acknowledged_ids = _get_acknowledged_notification_ids(db, super_admin.get("_id"))
+    if acknowledged_ids:
+        notifications = [item for item in notifications if item["id"] not in acknowledged_ids]
+
+    return {"notifications": notifications[:15]}
+
+
+@router.post("/super-admin/notifications/dismiss")
+def dismiss_notifications(
+    payload: NotificationDismissPayload,
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Dismiss specific notifications so they no longer show up."""
+    notification_ids = payload.notification_ids or []
+    if not notification_ids:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="No notifications supplied")
+    _acknowledge_notifications(db, super_admin.get("_id"), notification_ids)
+    return {"success": True, "dismissed": len(notification_ids)}
+
+
+@router.post("/super-admin/notifications/read-all")
+def mark_notifications_read(
+    payload: Optional[NotificationDismissPayload] = None,
+    db=Depends(get_mongo),
+    super_admin=Depends(get_current_super_admin)
+):
+    """Mark (and persist) notifications as read for the current super admin."""
+    notification_ids = payload.notification_ids if payload and payload.notification_ids else []
+    if not notification_ids:
+        current_notifications = get_notifications(db=db, super_admin=super_admin)
+        notification_ids = [item["id"] for item in current_notifications.get("notifications", [])]
+    _acknowledge_notifications(db, super_admin.get("_id"), notification_ids)
+    return {"success": True, "message": "All notifications marked as read", "count": len(notification_ids)}
+
+
+# ============================================================================
+# SYSTEM CONTROLS & MONITORING
+# ============================================================================
+
+@router.get("/super-admin/system/status")
+def get_system_status(
+    super_admin=Depends(get_current_super_admin)
+):
+    """
+    Get comprehensive system status including CPU, memory, disk, and service health
+    """
+    try:
+        # Get system metrics
+        cpu_usage = psutil.cpu_percent(interval=0.5)
+        memory = psutil.virtual_memory()
+        disk = psutil.disk_usage('/')
+        
+        # Calculate uptime
+        uptime_seconds = time.time() - APP_START_TIME
+        uptime_days = int(uptime_seconds // 86400)
+        uptime_hours = int((uptime_seconds % 86400) // 3600)
+        uptime_minutes = int((uptime_seconds % 3600) // 60)
+        uptime_str = f"{uptime_days}d {uptime_hours}h {uptime_minutes}m"
+        
+        # Check database connection
+        db = next(get_mongo())
+        try:
+            db.command('ping')
+            db_status = 'connected'
+        except Exception:
+            db_status = 'disconnected'
+        
+        return {
+            "status": "healthy" if cpu_usage < 90 and memory.percent < 90 else "warning",
+            "uptime": uptime_str,
+            "cpu_usage": round(cpu_usage, 1),
+            "memory_usage": round(memory.percent, 1),
+            "disk_usage": round(disk.percent, 1),
+            "database_status": db_status,
+            "xrp_service_status": "operational",
+            "ipfs_service_status": "operational",
+            "last_backup": datetime.utcnow().isoformat()
+        }
+    except Exception as e:
+        print(f"[SUPER ADMIN] Error getting system status: {e}")
+        return {
+            "status": "unknown",
+            "uptime": "0d 0h 0m",
+            "cpu_usage": 0,
+            "memory_usage": 0,
+            "disk_usage": 0,
+            "database_status": "unknown",
+            "xrp_service_status": "unknown",
+            "ipfs_service_status": "unknown",
+            "last_backup": datetime.utcnow().isoformat()
+        }
+
+
+@router.get("/super-admin/system/services")
+def get_system_services(
+    super_admin=Depends(get_current_super_admin)
+):
+    """
+    Get status of all system services
+    """
+    uptime_seconds = time.time() - APP_START_TIME
+    uptime_days = int(uptime_seconds // 86400)
+    uptime_hours = int((uptime_seconds % 86400) // 3600)
+    uptime_str = f"{uptime_days}d {uptime_hours}h"
+    
+    services = [
+        {
+            "id": "api",
+            "name": "API Service",
+            "status": "running",
+            "port": 8000,
+            "uptime": uptime_str
+        },
+        {
+            "id": "database",
+            "name": "MongoDB",
+            "status": "running",
+            "port": 27017,
+            "uptime": uptime_str
+        },
+        {
+            "id": "xrp",
+            "name": "XRP Service",
+            "status": "running",
+            "port": None,
+            "uptime": uptime_str
+        },
+        {
+            "id": "ipfs",
+            "name": "IPFS Service",
+            "status": "running",
+            "port": None,
+            "uptime": uptime_str
+        },
+        {
+            "id": "cache",
+            "name": "Cache Service",
+            "status": "running",
+            "port": None,
+            "uptime": uptime_str
+        }
+    ]
+    
+    return services
+
+
+@router.post("/super-admin/system/services/{service_id}/{action}")
+def control_service(
+    service_id: str,
+    action: str,
+    super_admin=Depends(get_current_super_admin)
+):
+    """
+    Control system services (start, stop, restart)
+    Note: This is a placeholder. Actual implementation requires proper service management.
+    """
+    if action not in ["start", "stop", "restart"]:
+        raise HTTPException(status_code=400, detail="Invalid action")
+    
+    print(f"[SUPER ADMIN] Service control: {service_id} -> {action} by {super_admin.get('email')}")
+    
+    # Log the action
+    return {
+        "success": True,
+        "message": f"Service {service_id} {action} command sent",
+        "service_id": service_id,
+        "action": action
+    }
+
+
+@router.get("/super-admin/system/api-endpoints")
+def get_api_endpoints(
+    super_admin=Depends(get_current_super_admin)
+):
+    """
+    Get all API endpoints with their status and usage statistics
+    """
+    endpoints = [
+        {"category": "Authentication", "path": "/api/v1/auth/login", "method": "POST", "status": "active", "calls_24h": 1234},
+        {"category": "Authentication", "path": "/api/v1/auth/register", "method": "POST", "status": "active", "calls_24h": 456},
+        {"category": "Authentication", "path": "/api/v1/auth/me", "method": "GET", "status": "active", "calls_24h": 2345},
+        {"category": "Properties", "path": "/api/v1/properties", "method": "GET", "status": "active", "calls_24h": 5678},
+        {"category": "Properties", "path": "/api/v1/properties/{id}", "method": "GET", "status": "active", "calls_24h": 2345},
+        {"category": "Properties", "path": "/api/v1/properties/{id}/invest", "method": "POST", "status": "active", "calls_24h": 789},
+        {"category": "Investments", "path": "/api/v1/investments", "method": "GET", "status": "active", "calls_24h": 1234},
+        {"category": "Wallet", "path": "/api/v1/wallet/balance", "method": "GET", "status": "active", "calls_24h": 3456},
+        {"category": "Wallet", "path": "/api/v1/wallet/transactions", "method": "GET", "status": "active", "calls_24h": 1890},
+        {"category": "Admin", "path": "/api/v1/admin/properties", "method": "POST", "status": "active", "calls_24h": 123},
+        {"category": "Admin", "path": "/api/v1/admin/properties/{id}", "method": "PUT", "status": "active", "calls_24h": 98},
+        {"category": "Super Admin", "path": "/api/v1/super-admin/stats", "method": "GET", "status": "active", "calls_24h": 567},
+        {"category": "Super Admin", "path": "/api/v1/super-admin/users", "method": "GET", "status": "active", "calls_24h": 234},
+        {"category": "Super Admin", "path": "/api/v1/super-admin/properties", "method": "GET", "status": "active", "calls_24h": 345},
+    ]
+    
+    return endpoints
+
+
+@router.post("/super-admin/system/api-endpoints/toggle")
+def toggle_api_endpoint(
+    payload: dict,
+    super_admin=Depends(get_current_super_admin)
+):
+    """
+    Enable or disable specific API endpoints
+    Note: This is a placeholder. Actual implementation requires middleware integration.
+    """
+    path = payload.get("path")
+    method = payload.get("method")
+    
+    print(f"[SUPER ADMIN] Endpoint toggle: {method} {path} by {super_admin.get('email')}")
+    
+    return {
+        "success": True,
+        "message": f"Endpoint {method} {path} toggled",
+        "path": path,
+        "method": method
+    }
+
+
+@router.get("/super-admin/system/cache")
+def get_cache_stats(
+    super_admin=Depends(get_current_super_admin)
+):
+    """
+    Get cache statistics
+    """
+    return {
+        "total_keys": 1234,
+        "memory_used": "45.2 MB",
+        "hit_rate": 87.3,
+        "miss_rate": 12.7,
+        "evictions": 23
+    }
+
+
+@router.post("/super-admin/system/cache/clear")
+def clear_cache(
+    super_admin=Depends(get_current_super_admin)
+):
+    """
+    Clear all cache entries
+    """
+    print(f"[SUPER ADMIN] Cache cleared by {super_admin.get('email')}")
+    
+    return {
+        "success": True,
+        "message": "Cache cleared successfully",
+        "keys_cleared": 1234
+    }
+
+
+@router.post("/super-admin/system/backup")
+def create_database_backup(
+    super_admin=Depends(get_current_super_admin)
+):
+    """
+    Create a database backup
+    Note: This is a placeholder. Actual implementation requires backup tools.
+    """
+    timestamp = datetime.utcnow().strftime("%Y%m%d_%H%M%S")
+    filename = f"backup_{timestamp}.gz"
+    
+    print(f"[SUPER ADMIN] Database backup created: {filename} by {super_admin.get('email')}")
+    
+    return {
+        "success": True,
+        "message": "Backup created successfully",
+        "filename": filename,
+        "timestamp": datetime.utcnow().isoformat()
+    }
+
+

routes/wallet.py

@@ -0,0 +1,466 @@
+"""
+Production Wallet Routes
+Handles wallet operations and balance management
+"""
+from fastapi import APIRouter, Depends, HTTPException, status, Body, Request
+from typing import List
+from pydantic import BaseModel
+import logging
+
+import schemas
+from db import get_mongo
+import repo
+from routes.auth import get_current_user
+from services.xrp_service import XRPLService
+from repo import record_admin_wallet_event, list_aed_wallet_transactions
+from middleware.security import limiter, mask_email
+import base64
+import re
+from utils.crypto_utils import encrypt_secret
+from utils.cache import get_cached_xrp_balance, cache_xrp_balance
+
+router = APIRouter()
+logger = logging.getLogger(__name__)
+
+class DepositRequest(BaseModel):
+    amount: float
+    payment_method: str
+
+
+@router.get("/wallet", response_model=schemas.WalletOut)
+def get_wallet(
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """Get current user's wallet information with live XRP balance"""
+    logger.debug(f"Fetching wallet for user: {mask_email(current_user['email'])}")
+    
+    wallet = repo.get_wallet_by_user(db, current_user['id'])
+    
+    if not wallet:
+        logger.warning(f"Wallet not found for user: {current_user['id']}")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Wallet not found"
+        )
+    
+    # Fetch XRP balance with caching (5min TTL)
+    xrp_balance = 0.0
+    if wallet.get('xrp_address'):
+        try:
+            # Try cache first (2ms), fall back to live fetch (500ms) if needed
+            xrp_balance = get_cached_xrp_balance(wallet['xrp_address'])
+            if xrp_balance is None:
+                xrp_service = XRPLService()
+                xrp_balance = xrp_service.get_xrp_balance(wallet['xrp_address'])
+                # Cache for 5 minutes
+                cache_xrp_balance(wallet['xrp_address'], xrp_balance, ttl=300)
+                logger.debug(f"Live XRP balance fetched and cached: {xrp_balance} XRP")
+            else:
+                logger.debug(f"Cached XRP balance: {xrp_balance} XRP")
+        except Exception as e:
+            logger.warning(f"Could not fetch XRP balance: {e}")
+            xrp_balance = 0.0
+    
+    wallet['xrp_balance'] = xrp_balance
+    
+    logger.debug(f"Wallet balance: {wallet['balance']} {wallet['currency']}, XRP: {xrp_balance}")
+    
+    return schemas.WalletOut(**wallet)
+
+
+@router.post("/wallet/import", response_model=schemas.WalletOut)
+@limiter.limit("3/hour")
+def import_xrp_wallet(
+    request: Request,
+    wallet_import: schemas.WalletImport,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """
+    Import XRP wallet for current user
+    Validates the wallet credentials and saves them
+    Rate limited to 3 attempts per hour to prevent brute force attacks
+    """
+    logger.info(f"Import XRP wallet request for user: {mask_email(current_user['email'])}")
+    logger.debug(f"XRP Address: {wallet_import.xrp_address}")
+    
+    # Get user's wallet
+    wallet = repo.get_wallet_by_user(db, current_user['id'])
+    
+    if not wallet:
+        print(f"[WALLET] [ERROR] Wallet not found\n")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Wallet not found"
+        )
+    
+    # Basic format validation before hitting ledger
+    addr_pattern = re.compile(r"^r[1-9A-HJ-NP-Za-km-z]{25,34}$")
+    seed_pattern = re.compile(r"^s[1-9A-HJ-NP-Za-km-z]{15,34}$")
+    if not addr_pattern.match(wallet_import.xrp_address):
+        raise HTTPException(status_code=400, detail="Invalid XRP address format")
+    if not seed_pattern.match(wallet_import.xrp_seed):
+        raise HTTPException(status_code=400, detail="Invalid XRP seed format")
+
+    # Validate XRP wallet by checking if we can get balance (lightweight existence check)
+    try:
+        xrp_service = XRPLService()
+        xrp_balance = xrp_service.get_xrp_balance(wallet_import.xrp_address)
+        logger.info(f"XRP wallet validated. Balance: {xrp_balance} XRP")
+    except Exception as e:
+        logger.error(f"Invalid XRP wallet: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid XRP wallet or network error: {str(e)}"
+        )
+
+    # Encrypt or fallback base64 encode seed before storing
+    # Maintain backward compatibility: if encryption key absent we keep base64 behavior
+    from config import settings as _settings
+    if _settings.encryption_enabled():
+        encoded_seed = encrypt_secret(wallet_import.xrp_seed, _settings.ENCRYPTION_KEY)
+    else:
+        encoded_seed = base64.b64encode(wallet_import.xrp_seed.encode()).decode()
+
+    updated_wallet = repo.update_wallet_xrp(
+        db,
+        wallet['id'],
+        wallet_import.xrp_address,
+        encoded_seed
+    )
+    
+    if not updated_wallet:
+        logger.error("Failed to update wallet")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to import wallet"
+        )
+    
+    updated_wallet['xrp_balance'] = xrp_balance
+    
+    logger.info("XRP wallet imported successfully")
+    
+    return schemas.WalletOut(**updated_wallet)
+
+
+@router.post("/wallet/deposit", response_model=schemas.TransactionOut)
+@limiter.limit("10/hour")
+def deposit_to_wallet(
+    request: Request,
+    deposit: DepositRequest = Body(...),
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """
+    Deposit money to wallet (Simulated for demo)
+    In production, this would integrate with payment gateway
+    Rate limited to 10 deposits per hour to prevent abuse
+    """
+    # Extract deposit details
+    amount = deposit.amount
+    payment_method = deposit.payment_method
+    logger.info(f"Deposit request: {amount} AED for user: {mask_email(current_user['email'])} using {payment_method}")
+    
+    if amount <= 0:
+        logger.warning(f"Invalid deposit amount: {amount}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Deposit amount must be positive"
+        )
+    
+    # Get wallet
+    wallet = repo.get_wallet_by_user(db, current_user['id'])
+    
+    if not wallet:
+        print(f"[WALLET] [ERROR] Wallet not found\n")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Wallet not found"
+        )
+    
+    # Update wallet balance
+    updated_wallet = repo.update_wallet_balance(db, wallet['id'], amount, operation="add")
+    
+    # Create transaction record
+    transaction = repo.create_transaction(
+        db,
+        user_id=current_user['id'],
+        wallet_id=wallet['id'],
+        tx_type="deposit",
+        amount=amount,
+        status="completed",
+        metadata={
+            "payment_method": payment_method,
+            "description": "Wallet deposit"
+        }
+    )
+
+    # Mirror admin wallet credit topup event (store in fils)
+    try:
+        record_admin_wallet_event(
+            db,
+            delta_fils=int(amount * 100),
+            event_type="admin_wallet_credit_topup",
+            notes=f"Received AED {amount:.2f} from {current_user.get('name')} via {payment_method}",
+            counterparty_user=current_user,
+            payment_method=payment_method,
+            payment_reference=f"DEP_{wallet['id']}",
+            metadata={"amount": amount},
+        )
+    except Exception as e:
+        logger.warning(f"Failed to record admin wallet topup event: {e}")
+    
+    logger.info(f"Deposit successful. New balance: {updated_wallet['balance']} AED")
+    
+    return schemas.TransactionOut(**transaction)
+
+
+@router.get("/wallet/transactions", response_model=List[schemas.TransactionOut])
+def get_wallet_transactions(
+    skip: int = 0,
+    limit: int = 50,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """Get wallet transaction history"""
+    logger.debug(f"Fetching transactions for user: {mask_email(current_user['email'])}")
+    
+    transactions = repo.get_user_transactions(db, current_user['id'], skip=skip, limit=limit)
+    
+    logger.debug(f"Found {len(transactions)} transactions")
+    
+    return [schemas.TransactionOut(**tx) for tx in transactions]
+
+
+# AED specific wallet utilities (parallel to reference implementation)
+@router.get("/wallet/aed/balance")
+def get_aed_wallet_balance(db=Depends(get_mongo), current_user=Depends(get_current_user)):
+    # Get balance from wallet collection, not user document
+    wallet = db.wallets.find_one({"user_id": repo._to_object_id(current_user['id'])})
+    balance_aed = wallet.get("balance", 0.0) if wallet else 0.0
+    
+    return {
+        "balance_aed": balance_aed,
+        "balance_fils": int(balance_aed * 100),
+    }
+
+
+@router.get("/wallet/aed/transactions")
+def get_aed_wallet_transactions(db=Depends(get_mongo), current_user=Depends(get_current_user)):
+    txs = list_aed_wallet_transactions(db, user_id=current_user['id'], limit=50)
+    out = []
+    for tx in txs:
+        meta = tx.get("metadata") or {}
+        amount_fils = meta.get("total_amount_fils") or 0
+        out.append({
+            "id": tx.get("id"),
+            "type": tx.get("type"),
+            "amount_aed": amount_fils / 100.0,
+            "payment_method": meta.get("payment_method"),
+            "payment_reference": meta.get("payment_reference"),
+            "status": tx.get("status"),
+            "created_at": tx.get("created_at"),
+            "notes": meta.get("notes"),
+        })
+    return out
+
+
+# ============================================================================
+# USER CARDS ENDPOINTS
+# ============================================================================
+
+@router.get("/wallet/cards", response_model=List[schemas.CardOut])
+def get_user_cards(
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """Get all saved cards for the current user"""
+    logger.debug(f"Fetching cards for user: {mask_email(current_user['email'])}")
+    
+    cards = repo.get_user_cards(db, current_user['id'])
+    
+    logger.debug(f"Found {len(cards)} cards")
+    
+    return [schemas.CardOut(**card) for card in cards]
+
+
+@router.post("/wallet/cards", response_model=schemas.CardOut, status_code=status.HTTP_201_CREATED)
+@limiter.limit("5/hour")
+def add_user_card(
+    request: Request,
+    card_data: schemas.CardCreate,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """Add a new card for the current user"""
+    logger.info(f"Adding card for user: {mask_email(current_user['email'])}")
+    
+    try:
+        card = repo.create_user_card(
+            db,
+            user_id=current_user['id'],
+            card_number=card_data.card_number,
+            expiry_month=card_data.expiry_month,
+            expiry_year=card_data.expiry_year,
+            cardholder_name=card_data.cardholder_name,
+            bank_name=card_data.bank_name
+        )
+        
+        logger.info(f"Card added: ****{card['last_four']}")
+        
+        return schemas.CardOut(**card)
+        
+    except ValueError as e:
+        logger.warning(f"Card add failed: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+
+
+@router.delete("/wallet/cards/{card_id}")
+def delete_user_card(
+    card_id: str,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """Delete a saved card"""
+    logger.info(f"Deleting card {card_id}")
+    
+    success = repo.delete_user_card(db, current_user['id'], card_id)
+    
+    if not success:
+        logger.warning("Card not found or already deleted")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Card not found"
+        )
+    
+    logger.info("Card deleted")
+    
+    return {"success": True, "message": "Card deleted successfully"}
+
+
+@router.put("/wallet/cards/{card_id}/default")
+def set_default_card(
+    card_id: str,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """Set a card as the default payment method"""
+    logger.info(f"Setting card {card_id} as default")
+    
+    success = repo.set_default_card(db, current_user['id'], card_id)
+    
+    if not success:
+        logger.warning("Card not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Card not found"
+        )
+    
+    logger.info("Card set as default")
+    
+    return {"success": True, "message": "Card set as default"}
+
+
+# ============================================================================
+# USER BANKS ENDPOINTS
+# ============================================================================
+
+@router.get("/wallet/banks", response_model=List[schemas.BankOut])
+def get_user_banks(
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """Get all saved bank accounts for the current user"""
+    logger.debug(f"Fetching bank accounts for user: {mask_email(current_user['email'])}")
+    
+    banks = repo.get_user_banks(db, current_user['id'])
+    
+    logger.debug(f"Found {len(banks)} bank accounts")
+    
+    return [schemas.BankOut(**bank) for bank in banks]
+
+
+@router.post("/wallet/banks", response_model=schemas.BankOut, status_code=status.HTTP_201_CREATED)
+@limiter.limit("5/hour")
+def add_user_bank(
+    request: Request,
+    bank_data: schemas.BankCreate,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """Add a new bank account for the current user"""
+    logger.info(f"Adding bank account for user: {mask_email(current_user['email'])}")
+    
+    try:
+        bank = repo.create_user_bank(
+            db,
+            user_id=current_user['id'],
+            bank_name=bank_data.bank_name,
+            account_holder_name=bank_data.account_holder_name,
+            account_number=bank_data.account_number,
+            account_type=bank_data.account_type.value,
+            iban=bank_data.iban,
+            swift_code=bank_data.swift_code,
+            currency=bank_data.currency
+        )
+        
+        logger.info(f"Bank account added: {bank['bank_name']}")
+        
+        return schemas.BankOut(**bank)
+        
+    except ValueError as e:
+        logger.warning(f"Bank add failed: {str(e)}")
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+
+
+@router.delete("/wallet/banks/{bank_id}")
+def delete_user_bank(
+    bank_id: str,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """Delete a saved bank account"""
+    logger.info(f"Deleting bank {bank_id}")
+    
+    success = repo.delete_user_bank(db, current_user['id'], bank_id)
+    
+    if not success:
+        logger.warning("Bank account not found or already deleted")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Bank account not found"
+        )
+    
+    logger.info("Bank account deleted")
+    
+    return {"success": True, "message": "Bank account deleted successfully"}
+
+
+@router.put("/wallet/banks/{bank_id}/default")
+def set_default_bank(
+    bank_id: str,
+    db=Depends(get_mongo),
+    current_user=Depends(get_current_user)
+):
+    """Set a bank account as the default for withdrawals"""
+    logger.info(f"Setting bank {bank_id} as default")
+    
+    success = repo.set_default_bank(db, current_user['id'], bank_id)
+    
+    if not success:
+        logger.warning("Bank account not found")
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Bank account not found"
+        )
+    
+    logger.info("Bank account set as default")
+    
+    return {"success": True, "message": "Bank account set as default"}

schemas.py

@@ -0,0 +1,1536 @@
+"""
+Production-Ready Pydantic Schemas for Real Estate Tokenization Platform
+Based on the new database schema with complete validation
+"""
+from pydantic import BaseModel, EmailStr, Field, validator
+from typing import Optional, List, Dict, Any, Union
+from datetime import datetime
+from enum import Enum
+import re
+
+
+# ============================================================================
+# ENUMS
+# ============================================================================
+
+class UserRole(str, Enum):
+    user = "user"
+    admin = "admin"
+    super_admin = "super_admin"
+
+
+class PropertyType(str, Enum):
+    residential = "Residential"
+    commercial = "Commercial"
+    retail = "Retail"
+    industrial = "Industrial"
+
+
+class TransactionType(str, Enum):
+    deposit = "deposit"
+    withdrawal = "withdrawal"
+    investment = "investment"
+    profit = "profit"
+    buy = "buy"
+    sell = "sell"
+    wallet_deduct = "wallet_deduct"
+    tokenize = "tokenize"
+    wallet_add = "wallet_add"  # Added for AED wallet topups (compat)
+    admin_wallet_credit_purchase = "admin_wallet_credit_purchase"  # Admin mirror events
+    admin_wallet_credit_topup = "admin_wallet_credit_topup"
+    admin_wallet_debit_payout = "admin_wallet_debit_payout"
+    token_buyback = "token_buyback"  # Token sell-back to admin
+
+
+class TransactionStatus(str, Enum):
+    pending = "pending"
+    completed = "completed"
+    failed = "failed"
+    confirmed = "confirmed"
+    cancelled = "cancelled"
+
+
+class InvestmentStatus(str, Enum):
+    pending = "pending"
+    confirmed = "confirmed"
+    cancelled = "cancelled"
+
+
+class FileType(str, Enum):
+    pdf = "pdf"
+    doc = "doc"
+    docx = "docx"
+    jpg = "jpg"
+    png = "png"
+
+
+# ============================================================================
+# USER SCHEMAS
+# ============================================================================
+
+class UserCreate(BaseModel):
+    name: str = Field(..., min_length=2, max_length=100, pattern=r"^[a-zA-Z\s\-']+$")
+    email: EmailStr
+    password: str = Field(..., min_length=8)
+    country_code: str = Field(..., pattern=r"^\+[0-9]{1,4}$")  # Required, e.g., +1, +91, +971
+    phone: str = Field(..., pattern=r"^[0-9]{6,15}$")  # Required, 6-15 digits for international numbers
+    role: Optional[UserRole] = UserRole.user
+    
+    @validator('name')
+    def validate_name_chars(cls, v):
+        """Validate name contains only letters, spaces, hyphens, apostrophes"""
+        if not re.match(r"^[a-zA-Z\s\-']+$", v):
+            raise ValueError('Name can only contain letters, spaces, hyphens, and apostrophes')
+        return v.strip()
+    
+    @validator('country_code')
+    def validate_country_code_format(cls, v):
+        """Validate country code format"""
+        if not re.match(r"^\+[0-9]{1,4}$", v):
+            raise ValueError('Country code must start with + and contain 1-4 digits')
+        return v
+    
+    @validator('phone')
+    def validate_phone_digits(cls, v):
+        """Validate phone is 6-15 digits"""
+        if not re.match(r"^[0-9]{6,15}$", v):
+            raise ValueError('Phone number must be 6-15 digits')
+        return v
+    
+    @validator('email')
+    def validate_email_format(cls, v):
+        """Additional email validation"""
+        if not v or '@' not in v or '.' not in v.split('@')[1]:
+            raise ValueError('Invalid email format')
+        return v.lower().strip()
+
+
+class UserLogin(BaseModel):
+    email: EmailStr
+    password: str
+
+
+class UserOut(BaseModel):
+    id: str
+    name: str
+    email: EmailStr
+    role: UserRole
+    # country_code: str  # Required field
+    # phone: str  # Required field
+    country_code: Optional[str] = "+91"  # Default for backward compatibility with existing users
+    phone: Optional[str] = None  # Optional for backward compatibility
+    date_of_birth: Optional[str] = None
+    gender: Optional[str] = None
+    address: Optional[str] = None
+    country: Optional[str] = None
+    state: Optional[str] = None
+    city: Optional[str] = None
+    employment_status: Optional[str] = None
+    employment_details: Optional[str] = None
+    wallet_id: Optional[str] = None
+    is_active: bool = True
+    kyc_status: Optional[str] = "pending"  # pending, approved, rejected
+    kyc_document_id: Optional[str] = None
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class UserUpdate(BaseModel):
+    name: Optional[str] = Field(None, pattern=r"^[a-zA-Z\s\-']+$")
+    country_code: Optional[str] = Field(None, pattern=r"^\+[0-9]{1,4}$")
+    phone: Optional[str] = Field(None, pattern=r"^[0-9]{6,15}$")
+    date_of_birth: Optional[str] = None
+    gender: Optional[str] = None
+    address: Optional[str] = None
+    country: Optional[str] = None
+    state: Optional[str] = None
+    city: Optional[str] = None
+    employment_status: Optional[str] = None
+    employment_details: Optional[str] = None
+    is_active: Optional[bool] = None
+    kyc_status: Optional[str] = None
+    
+    @validator('name')
+    def validate_name_chars(cls, v):
+        """Validate name contains only letters, spaces, hyphens, apostrophes"""
+        if v is not None and not re.match(r"^[a-zA-Z\s\-']+$", v):
+            raise ValueError('Name can only contain letters, spaces, hyphens, and apostrophes')
+        return v.strip() if v else v
+    
+    @validator('country_code')
+    def validate_country_code_format(cls, v):
+        """Validate country code format"""
+        if v is not None and not re.match(r"^\+[0-9]{1,4}$", v):
+            raise ValueError('Country code must start with + and contain 1-4 digits')
+        return v
+    
+    @validator('phone')
+    def validate_phone_digits(cls, v):
+        """Validate phone is 6-15 digits"""
+        if v is not None and not re.match(r"^[0-9]{6,15}$", v):
+            raise ValueError('Phone number must be 6-15 digits')
+        return v
+
+
+# ============================================================================
+# WALLET SCHEMAS
+# ============================================================================
+
+class WalletCreate(BaseModel):
+    currency: str = "AED"
+    balance: float = 0.0
+
+
+class WalletOut(BaseModel):
+    id: str
+    user_id: str
+    balance: float
+    aed_balance: Optional[float] = None  # Alias for balance (for frontend compatibility)
+    currency: str
+    xrp_address: Optional[str] = None
+    xrp_balance: float = 0.0
+    is_active: bool
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+    
+    @validator('aed_balance', pre=True, always=True)
+    def set_aed_balance(cls, v, values):
+        """Set aed_balance from balance if not provided"""
+        return v if v is not None else values.get('balance', 0.0)
+
+
+class WalletUpdate(BaseModel):
+    balance: Optional[float] = None
+    xrp_address: Optional[str] = None
+    is_active: Optional[bool] = None
+
+
+class WalletImport(BaseModel):
+    xrp_address: str = Field(..., min_length=25, max_length=35, description="XRP Ledger address")
+    xrp_seed: str = Field(..., min_length=25, max_length=35, description="XRP wallet seed/secret")
+
+
+# ============================================================================
+# PROPERTY SCHEMAS
+# ============================================================================
+
+class PropertySpecificationCreate(BaseModel):
+    balcony: int = 0
+    kitchen: int = 1
+    bedroom: int = 1
+    bathroom: int = 1
+    area: float = Field(..., gt=0, description="Area in square meters")
+
+
+class PropertySpecificationOut(BaseModel):
+    id: str
+    property_id: str
+    balcony: int
+    kitchen: int
+    bedroom: int
+    bathroom: int
+    area: float
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class AmenityCreate(BaseModel):
+    name: str = Field(..., min_length=2, max_length=100)
+    is_active: bool = True
+
+
+class AmenityOut(BaseModel):
+    id: str
+    property_id: str
+    name: str
+    is_active: bool
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class PropertyImageCreate(BaseModel):
+    image_url: str
+    caption: Optional[str] = None
+    is_main: bool = False
+
+
+class PropertyImageOut(BaseModel):
+    id: str
+    property_id: str
+    image_url: str
+    caption: Optional[str]
+    is_main: bool
+    uploaded_by: Optional[str]
+    is_active: bool
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class PropertyCreate(BaseModel):
+    title: str = Field(..., min_length=5, max_length=200)
+    description: str = Field(..., min_length=20)
+    location: str = Field(..., min_length=5, max_length=200)
+    property_type: PropertyType = Field(default=PropertyType.residential, description="Type of property")
+    total_tokens: int = Field(..., gt=0)
+    token_price: float = Field(..., gt=0)
+    min_investment: float = Field(default=2000.0, ge=2000.0)
+    original_price: float = Field(..., gt=0)
+    square_feet: Optional[float] = Field(None, gt=0, description="Property area in square feet")
+    price_per_sqft: Optional[float] = Field(None, gt=0, description="Price per square foot")
+    purchase_cost: Optional[float] = None
+    platform_fees: Optional[float] = None
+    dld_fees: Optional[float] = None
+    net_rental_yield: Optional[float] = Field(None, ge=0, le=100)
+    annual_roi: Optional[float] = Field(None, ge=0, le=100)
+    gross_rental_yield: Optional[float] = Field(None, ge=0, le=100)
+    funded_date: Optional[datetime] = None
+    
+    # Related data
+    specifications: Optional[PropertySpecificationCreate] = None
+    amenities: Optional[List[Union[str, Dict[str, str]]]] = None  # Accept both string and dict formats
+    images: Optional[List[PropertyImageCreate]] = None
+    documents: Optional[List[Dict[str, str]]] = None  # Added documents support
+
+    @validator('amenities', pre=True)
+    def normalize_amenities(cls, v):
+        """Convert amenities to list of strings, handling both string and dict formats"""
+        if v is None:
+            return None
+        
+        normalized = []
+        for item in v:
+            if isinstance(item, str):
+                normalized.append(item)
+            elif isinstance(item, dict) and 'name' in item:
+                normalized.append(item['name'])
+            else:
+                # Skip invalid items
+                continue
+        return normalized
+
+    @validator('purchase_cost', always=True)
+    def set_purchase_cost(cls, v, values):
+        if v is None and 'original_price' in values:
+            return values['original_price']
+        return v
+
+    @validator('platform_fees', always=True)
+    def set_platform_fees(cls, v, values):
+        if v is None and 'original_price' in values:
+            # Default 2% AtriumChain platform fees
+            return values['original_price'] * 0.02
+        return v
+
+    @validator('dld_fees', always=True)
+    def set_dld_fees(cls, v, values):
+        if v is None and 'original_price' in values:
+            # Default 2% DLD fees (reduced from 4%)
+            return values['original_price'] * 0.02
+        return v
+
+
+# ============================================================================
+# DOCUMENT SCHEMAS
+# ============================================================================
+
+class DocumentCreate(BaseModel):
+    property_id: str
+    file_type: FileType
+    file_url: str
+    uploaded_by: Optional[str] = None
+
+
+class DocumentOut(BaseModel):
+    id: str
+    property_id: str
+    file_type: FileType
+    file_url: str
+    uploaded_by: Optional[str]
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+# ============================================================================
+# PROPERTY OUTPUT SCHEMA
+# ============================================================================
+
+class PropertyOut(BaseModel):
+    id: str
+    title: str
+    description: str
+    location: str
+    property_type: str
+    total_tokens: int
+    token_price: float
+    min_investment: float
+    available_tokens: int
+    original_price: float
+    square_feet: Optional[float] = None
+    price_per_sqft: Optional[float] = None
+    purchase_cost: float
+    platform_fees: float
+    dld_fees: float
+    net_rental_yield: Optional[float]
+    annual_roi: Optional[float]
+    gross_rental_yield: Optional[float]
+    funded_date: Optional[datetime]
+    created_by: Optional[str]
+    is_active: bool
+    created_at: datetime
+    updated_at: datetime
+    
+    # Embedded/related data
+    specifications: Optional[PropertySpecificationOut] = None
+    amenities: Optional[List[AmenityOut]] = None
+    images: Optional[List[PropertyImageOut]] = None
+    documents: Optional[List[DocumentOut]] = None
+    
+    # Computed fields for backward compatibility
+    image: Optional[str] = None
+    projected_roi: Optional[float] = None
+
+    class Config:
+        from_attributes = True
+        
+    @validator('image', always=True)
+    def compute_main_image(cls, v, values):
+        """Get main image URL from images array for backward compatibility"""
+        if v is not None:
+            return v
+        
+        images = values.get('images')
+        if images and len(images) > 0:
+            # Find the main image
+            for img in images:
+                if hasattr(img, 'is_main') and img.is_main:
+                    return img.image_url
+            # If no main image, return first image
+            return images[0].image_url if hasattr(images[0], 'image_url') else None
+        
+        return None
+    
+    @validator('projected_roi', always=True)
+    def compute_projected_roi(cls, v, values):
+        """Map annual_roi to projected_roi for backward compatibility"""
+        if v is not None:
+            return v
+        return values.get('annual_roi')
+
+
+class PropertyUpdate(BaseModel):
+    title: Optional[str] = None
+    description: Optional[str] = None
+    location: Optional[str] = None
+    token_price: Optional[float] = None
+    min_investment: Optional[float] = None
+    available_tokens: Optional[int] = None
+    net_rental_yield: Optional[float] = None
+    annual_roi: Optional[float] = None
+    gross_rental_yield: Optional[float] = None
+    is_active: Optional[bool] = None
+
+
+# ============================================================================
+# FUNDED PROPERTY SCHEMAS (Fully Funded Properties Archive)
+# ============================================================================
+
+class FundingStatus(str, Enum):
+    """Status of property funding lifecycle"""
+    available = "available"      # Property is open for investment
+    funded = "funded"            # All tokens sold, fully funded
+    exited = "exited"            # Investment cycle complete, returns distributed
+
+
+class FundedPropertyCreate(BaseModel):
+    """
+    Schema for creating a funded property record.
+    This is automatically created when a property reaches 100% funding.
+    """
+    property_id: str = Field(..., description="Reference to original property")
+    
+    # Property snapshot at time of funding
+    title: str = Field(..., min_length=5, max_length=200)
+    description: str = Field(..., min_length=20)
+    location: str = Field(..., min_length=5, max_length=200)
+    property_type: str = Field(..., description="Type of property")
+    
+    # Tokenization details
+    total_tokens: int = Field(..., gt=0, description="Total tokens issued")
+    token_price: float = Field(..., gt=0, description="Price per token at funding")
+    original_price: float = Field(..., gt=0, description="Total property value")
+    
+    # Funding metrics
+    funding_status: FundingStatus = FundingStatus.funded
+    funded_date: datetime = Field(..., description="Date when fully funded")
+    funding_duration_days: Optional[int] = Field(None, ge=0, description="Days taken to fully fund")
+    
+    # Investor statistics
+    total_investors: int = Field(default=0, ge=0, description="Number of unique investors")
+    average_investment: Optional[float] = Field(None, ge=0, description="Average investment amount")
+    
+    # ROI projections
+    net_rental_yield: Optional[float] = Field(None, ge=0, le=100, description="Net rental yield %")
+    annual_roi: Optional[float] = Field(None, ge=0, le=100, description="Projected annual ROI %")
+    gross_rental_yield: Optional[float] = Field(None, ge=0, le=100, description="Gross rental yield %")
+    
+    # Main image for display
+    main_image_url: Optional[str] = None
+    
+    # Metadata
+    is_active: bool = True
+    notes: Optional[str] = Field(None, max_length=1000)
+
+
+class FundedPropertyOut(BaseModel):
+    """
+    Schema for funded property output.
+    Includes all details needed for displaying funded properties in the UI.
+    """
+    id: str
+    property_id: str
+    
+    # Property details
+    title: str
+    description: str
+    location: str
+    property_type: str
+    
+    # Tokenization details
+    total_tokens: int
+    token_price: float
+    original_price: float
+    
+    # Funding status
+    funding_status: FundingStatus
+    funded_date: datetime
+    funding_duration_days: Optional[int] = None
+    
+    # Investor statistics
+    total_investors: int = 0
+    average_investment: Optional[float] = None
+    
+    # ROI details
+    net_rental_yield: Optional[float] = None
+    annual_roi: Optional[float] = None
+    gross_rental_yield: Optional[float] = None
+    
+    # Display image
+    main_image_url: Optional[str] = None
+    
+    # Computed fields for frontend compatibility
+    available_tokens: int = 0  # Always 0 for funded properties
+    funding_progress: float = 100.0  # Always 100% for funded properties
+    
+    # Metadata
+    is_active: bool = True
+    created_at: datetime
+    updated_at: datetime
+    
+    class Config:
+        from_attributes = True
+    
+    @validator('available_tokens', always=True)
+    def set_available_tokens(cls, v):
+        """Funded properties always have 0 available tokens"""
+        return 0
+    
+    @validator('funding_progress', always=True)
+    def set_funding_progress(cls, v):
+        """Funded properties always have 100% progress"""
+        return 100.0
+
+
+class FundedPropertyUpdate(BaseModel):
+    """Schema for updating funded property records (admin only)"""
+    funding_status: Optional[FundingStatus] = None
+    notes: Optional[str] = Field(None, max_length=1000)
+    is_active: Optional[bool] = None
+    # For exited properties
+    exit_date: Optional[datetime] = None
+    total_returns_distributed: Optional[float] = Field(None, ge=0)
+
+
+class FundedPropertiesListResponse(BaseModel):
+    """Response schema for listing funded properties"""
+    properties: List[FundedPropertyOut]
+    total_count: int
+    funding_stats: Optional[Dict[str, Any]] = None
+
+
+# ============================================================================
+# SUPER ADMIN CONSOLE SCHEMAS
+# ============================================================================
+
+class WalletMetricOut(BaseModel):
+    value: float
+    formatted: str
+    updated_at: Optional[datetime]
+    variance: Optional[str] = None
+    pending_payouts: Optional[int] = None
+
+
+class WalletEntryOut(BaseModel):
+    id: str
+    label: str
+    type: str
+    address: Optional[str] = None
+    balance: float
+    formatted_balance: str
+    variance: Optional[str] = None
+    last_synced_at: Optional[datetime] = None
+    status: str
+
+
+class WalletOverviewOut(BaseModel):
+    summary: Dict[str, WalletMetricOut]
+    wallets: List[WalletEntryOut]
+
+
+class SuperAdminProfileOut(BaseModel):
+    full_name: str
+    email: EmailStr
+    two_factor_enabled: bool = False
+
+
+class SuperAdminProfileUpdate(BaseModel):
+    full_name: str = Field(..., min_length=2, max_length=100)
+    email: EmailStr
+
+
+class PasswordUpdateRequest(BaseModel):
+    current_password: str = Field(..., min_length=8)
+    new_password: str = Field(..., min_length=8)
+
+
+class TwoFactorToggleRequest(BaseModel):
+    enabled: bool
+
+
+# ============================================================================
+# INVESTMENT SCHEMAS
+# ============================================================================
+
+class InvestmentCreate(BaseModel):
+    property_id: str
+    tokens_purchased: int = Field(..., gt=0)
+    amount: float = Field(..., gt=0)
+    profit_share: Optional[float] = 0.0
+
+
+class InvestmentOut(BaseModel):
+    id: str
+    user_id: str
+    property_id: str
+    tokens_purchased: int
+    amount: float
+    status: InvestmentStatus
+    profit_share: float
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class InvestmentUpdate(BaseModel):
+    status: Optional[InvestmentStatus] = None
+    profit_share: Optional[float] = None
+
+
+# ============================================================================
+# TRANSACTION SCHEMAS
+# ============================================================================
+
+class TransactionCreate(BaseModel):
+    wallet_id: Optional[str] = None
+    type: TransactionType
+    amount: float = Field(..., gt=0)
+    property_id: Optional[str] = None
+    status: Optional[TransactionStatus] = TransactionStatus.pending
+    metadata: Optional[Dict[str, Any]] = None
+
+
+class TransactionOut(BaseModel):
+    id: str
+    user_id: str
+    wallet_id: Optional[str]
+    type: TransactionType
+    amount: float
+    property_id: Optional[str]
+    status: TransactionStatus
+    metadata: Optional[Dict[str, Any]]
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+# ============================================================================
+# PORTFOLIO SCHEMAS
+# ============================================================================
+
+class PortfolioOut(BaseModel):
+    id: str
+    user_id: str
+    total_invested: float
+    total_current_value: float
+    total_profit: float
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class PortfolioItemOut(BaseModel):
+    property: PropertyOut
+    tokens_owned: int
+    token_balance: int  # For frontend compatibility
+    blockchain_balance: Optional[float] = None  # IOU token balance from blockchain
+    investment_amount: float
+    current_value: float
+    profit_loss: float
+    ownership_percentage: float
+    purchase_date: Optional[str] = None
+    purchase_price_per_token: Optional[float] = None
+    failed_transactions_count: int = 0
+    rent_data: Optional[Dict[str, Any]] = None  # Rent earnings for this property
+
+
+class PortfolioResponse(BaseModel):
+    portfolio: PortfolioOut
+    items: List[PortfolioItemOut]
+    total_properties: int
+
+
+# ============================================================================
+# TOKEN/AUTH SCHEMAS
+# ============================================================================
+
+class TokenOut(BaseModel):
+    access_token: str
+    token_type: str = "bearer"
+    user_role: UserRole
+    user: UserOut
+
+
+# ============================================================================
+# MARKET/PURCHASE SCHEMAS
+# ============================================================================
+
+class BuyRequest(BaseModel):
+    property_id: str
+    amount_tokens: int = Field(..., gt=0)
+    payment_method: str = "WALLET"  # WALLET, CARD, BANK_TRANSFER
+
+
+class OfferRequest(BaseModel):
+    property_id: str
+    amount_tokens: int = Field(..., gt=0)
+    price_per_token: float = Field(..., gt=0)
+
+
+class PlaceOfferRequest(BaseModel):
+    """Request to sell tokens back to admin/issuer"""
+    property_id: str
+    amount_tokens: int = Field(..., gt=0)
+    price_in_xrp: Optional[float] = None  # Optional: for compatibility with frontend
+
+
+class PurchaseResponse(BaseModel):
+    success: bool
+    message: str
+    transaction_id: str
+    investment_id: str
+    tokens_purchased: int
+    total_cost_aed: float
+    aed_wallet_balance: float
+    your_total_tokens: int
+    tokens_remaining: int
+    blockchain_tx_hash: str
+    ownership_percentage: float
+    property_details: Dict[str, Any]
+
+
+# ============================================================================
+# ADMIN SCHEMAS
+# ============================================================================
+
+class AdminStatsOut(BaseModel):
+    total_users: int
+    total_properties: int
+    total_investments: int
+    total_volume: float
+    active_users: int
+    total_tokens_sold: int
+    total_revenue: float
+
+
+class TokenizePropertyRequest(BaseModel):
+    property_id: str
+    blockchain_network: str = "XRP_TESTNET"
+    auto_create_tokens: bool = True
+
+
+# ============================================================================
+# ADMIN WALLET / AED WALLET AUXILIARY SCHEMAS
+# ============================================================================
+
+class AEDWalletAddRequest(BaseModel):
+    amount: float = Field(..., gt=0, description="Amount in AED")
+    payment_method: str = Field(..., description="Payment method e.g. UPI, CARD")
+
+
+class AEDWalletTransactionOut(BaseModel):
+    id: str
+    type: str
+    amount_aed: float
+    payment_method: Optional[str]
+    payment_reference: Optional[str]
+    status: str
+    created_at: Optional[datetime]
+    notes: Optional[str]
+
+
+class AEDWalletBalanceOut(BaseModel):
+    balance_aed: float
+    balance_fils: int
+
+
+class WalletCreateOut(BaseModel):
+    address: str
+    seed: str
+
+
+class WalletImportRequest(BaseModel):
+    address: str
+    seed: str
+
+
+class WalletBalanceOut(BaseModel):
+    address: str
+    xrp_balance: float
+    tokens: List[Dict[str, Any]]
+
+
+class AdminWalletInfoResponse(BaseModel):
+    wallet_info: Dict[str, Any]
+    total_earnings_aed: float
+    total_buyers: int
+    flow_summary: Dict[str, Any]
+    transactions: List[Dict[str, Any]]
+    recent_transactions: List[Dict[str, Any]]
+
+
+# ============================================================================
+# SUPER ADMIN SCHEMAS
+# ============================================================================
+
+class SuperAdminStatsOut(BaseModel):
+    """Comprehensive platform statistics for super admin"""
+    total_users: int
+    total_admins: int
+    total_properties: int
+    total_investments: int
+    total_volume: float
+    platform_revenue: float
+    active_users: int
+    blocked_users: int
+    pending_kyc: int
+    approved_kyc: int
+    rejected_kyc: int
+    total_tokens_sold: int
+    total_transactions: int
+
+
+class UserManagementOut(BaseModel):
+    """User details for super admin management"""
+    user_id: str
+    full_name: str
+    email: EmailStr
+    role: UserRole
+    phone: str
+    is_active: bool
+    kyc_status: Optional[str] = "pending"
+    created_at: datetime
+    total_invested: Optional[float] = 0.0
+    total_tokens: Optional[int] = 0
+    wallet_balance: Optional[float] = 0.0
+    last_login: Optional[datetime] = None
+
+
+class BlockUserRequest(BaseModel):
+    reason: str = Field(..., min_length=10, max_length=500)
+
+
+class UpdateUserRoleRequest(BaseModel):
+    new_role: UserRole
+
+
+class PlatformSettingsOut(BaseModel):
+    """Platform configuration settings"""
+    min_investment: float
+    platform_fee_percentage: float
+    kyc_required: bool
+    new_registrations_enabled: bool
+    purchases_enabled: bool
+    maintenance_mode: bool
+
+
+class PlatformSettingsUpdate(BaseModel):
+    """Update platform settings"""
+    min_investment: Optional[float] = Field(None, ge=0)
+    platform_fee_percentage: Optional[float] = Field(None, ge=0, le=100)
+    kyc_required: Optional[bool] = None
+    new_registrations_enabled: Optional[bool] = None
+    purchases_enabled: Optional[bool] = None
+    maintenance_mode: Optional[bool] = None
+
+
+class TransactionDetailOut(BaseModel):
+    """Detailed transaction info for super admin"""
+    id: str
+    user_id: str
+    user_name: Optional[str] = None
+    user_email: Optional[str] = None
+    wallet_id: Optional[str]
+    type: TransactionType
+    amount: float
+    property_id: Optional[str]
+    property_name: Optional[str] = None
+    status: TransactionStatus
+    metadata: Optional[Dict[str, Any]]
+    created_at: datetime
+    blockchain_tx_hash: Optional[str] = None
+
+
+class KYCDocumentManagementOut(BaseModel):
+    """KYC document for super admin review"""
+    id: str
+    user_id: str
+    user_name: str
+    user_email: str
+    full_name: str
+    date_of_birth: str
+    gender: str
+    address: str
+    document_url: str
+    status: str
+    uploaded_at: datetime
+    reviewed_at: Optional[datetime] = None
+    rejection_reason: Optional[str] = None
+
+
+class KYCApprovalRequest(BaseModel):
+    """Approve/Reject KYC document"""
+    status: str = Field(..., pattern="^(approved|rejected)$")
+    rejection_reason: Optional[str] = Field(None, min_length=10, max_length=500)
+
+
+class AdminManagementOut(BaseModel):
+    """Admin user details for management"""
+    admin_id: str
+    id: str
+    full_name: str
+    name: str
+    email: EmailStr
+    phone: str
+    is_active: bool
+    kyc_status: Optional[str] = "pending"
+    created_at: datetime
+    last_login: Optional[datetime] = None
+    properties_count: int
+    total_properties: int
+    total_revenue_xrp: Optional[float] = 0.0
+    total_revenue: float
+    total_buyers: int
+
+
+# ============================================================================
+# KYC SCHEMAS
+# ============================================================================
+
+class KYCUploadRequest(BaseModel):
+    full_name: str = Field(..., min_length=2, max_length=100)
+    date_of_birth: str = Field(..., description="Date of birth in YYYY-MM-DD format")
+    gender: str = Field(..., description="Gender: Male, Female, Other")
+    address: str = Field(..., min_length=10, max_length=500)
+
+
+class KYCDocumentOut(BaseModel):
+    id: str
+    user_id: str
+    full_name: str
+    date_of_birth: str
+    gender: str
+    address: str
+    document_url: str
+    file_size: int
+    content_type: str
+    status: str  # pending, approved, rejected
+    uploaded_at: datetime
+    reviewed_at: Optional[datetime] = None
+    reviewed_by: Optional[str] = None
+    rejection_reason: Optional[str] = None
+
+    class Config:
+        from_attributes = True
+
+
+class KYCStatusOut(BaseModel):
+    kyc_status: str
+    kyc_document: Optional[KYCDocumentOut] = None
+    can_purchase: bool
+
+
+# ============================================================================
+# RENT DISTRIBUTION SCHEMAS
+# ============================================================================
+
+class RentDistributionCreate(BaseModel):
+    """Schema for creating a new rent distribution event"""
+    property_id: str = Field(..., description="Property generating rent")
+    total_rent_amount: float = Field(..., gt=0, description="Total rent collected in AED")
+    rent_period_start: str = Field(..., description="Rent period start date (YYYY-MM-DD)")
+    rent_period_end: str = Field(..., description="Rent period end date (YYYY-MM-DD)")
+    distribution_date: Optional[datetime] = Field(None, description="When to distribute (default: now)")
+    notes: Optional[str] = Field(None, max_length=500, description="Additional notes")
+    
+    @validator('rent_period_start', 'rent_period_end')
+    def validate_date_format(cls, v):
+        """Validate date is in YYYY-MM-DD format"""
+        try:
+            datetime.strptime(v, '%Y-%m-%d')
+            return v
+        except ValueError:
+            raise ValueError('Date must be in YYYY-MM-DD format')
+    
+    @validator('distribution_date', always=True)
+    def set_distribution_date(cls, v):
+        """Set distribution date to now if not provided"""
+        return v if v is not None else datetime.utcnow()
+
+
+class RentDistributionOut(BaseModel):
+    """Schema for rent distribution response"""
+    id: str
+    property_id: str
+    property_title: Optional[str] = None
+    total_rent_amount: float
+    total_tokens: int
+    rent_per_token: float
+    rent_period_start: str
+    rent_period_end: str
+    distribution_date: datetime
+    total_investors: int
+    payments_completed: int
+    status: str  # pending, processing, completed, failed
+    notes: Optional[str] = None
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class RentPaymentCreate(BaseModel):
+    """Schema for creating individual rent payment (internal use)"""
+    distribution_id: str
+    user_id: str
+    property_id: str
+    tokens_owned: int = Field(..., gt=0)
+    rent_amount: float = Field(..., gt=0)
+    payment_status: str = "pending"
+    wallet_credited: bool = False
+    transaction_id: Optional[str] = None
+
+
+class RentPaymentOut(BaseModel):
+    """Schema for rent payment response"""
+    id: str
+    distribution_id: str
+    user_id: str
+    property_id: str
+    property_title: Optional[str] = None
+    tokens_owned: int
+    rent_amount: float
+    rent_period_start: str
+    rent_period_end: str
+    payment_status: str
+    wallet_credited: bool
+    transaction_id: Optional[str] = None
+    payment_date: datetime
+    created_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class UserRentSummary(BaseModel):
+    """Schema for user's rent summary per property"""
+    property_id: str
+    property_title: str
+    total_tokens_owned: int
+    total_rent_received: float
+    total_rent_payments: int
+    last_rent_amount: Optional[float] = None
+    last_rent_date: Optional[datetime] = None
+    average_monthly_rent: Optional[float] = None
+    annual_rental_yield: Optional[float] = None
+
+    class Config:
+        from_attributes = True
+
+
+# ============================================================================
+# SECONDARY MARKET SCHEMAS
+# ============================================================================
+
+class MarketTransactionType(str, Enum):
+    """Types of secondary market transactions"""
+    sell_to_admin = "sell_to_admin"  # User sells tokens back to admin
+    buy_from_user = "buy_from_user"  # User buys tokens from another user
+    sell_to_user = "sell_to_user"    # User sells tokens to another user
+
+
+class MarketTransactionStatus(str, Enum):
+    """Status of secondary market transactions"""
+    pending = "pending"
+    blockchain_processing = "blockchain_processing"
+    completed = "completed"
+    failed = "failed"
+    cancelled = "cancelled"
+
+
+class SecondaryMarketTransaction(BaseModel):
+    """Schema for secondary market trading history"""
+    transaction_id: str
+    transaction_type: MarketTransactionType
+    status: MarketTransactionStatus
+    
+    # Property details
+    property_id: str
+    property_title: str
+    token_currency: str
+    
+    # Seller details
+    seller_id: str
+    seller_email: str
+    seller_xrp_address: str
+    
+    # Buyer details (admin for sell_to_admin)
+    buyer_id: str
+    buyer_email: str
+    buyer_xrp_address: str
+    
+    # Transaction details
+    tokens_amount: int
+    price_per_token: float
+    total_amount: float
+    currency: str = "AED"
+    
+    # Blockchain details
+    blockchain_tx_hash: Optional[str] = None
+    blockchain_confirmed: bool = False
+    blockchain_confirmed_at: Optional[datetime] = None
+    
+    # Database sync
+    db_investment_updated: bool = False
+    db_wallet_updated: bool = False
+    db_property_updated: bool = False
+    db_transaction_recorded: bool = False
+    
+    # Timestamps
+    initiated_at: datetime
+    completed_at: Optional[datetime] = None
+    
+    # Additional info
+    notes: Optional[str] = None
+    error_message: Optional[str] = None
+
+    class Config:
+        from_attributes = True
+
+
+class PlaceOfferRequest(BaseModel):
+    """Request schema for placing a sell offer"""
+    property_id: str = Field(..., description="Property ID to sell tokens for")
+    amount_tokens: int = Field(..., gt=0, description="Number of tokens to sell (must be positive)")
+    price_in_xrp: Optional[float] = Field(None, gt=0, description="Optional: price per token in XRP")
+
+
+class MarketHistoryResponse(BaseModel):
+    """Response schema for market transaction history"""
+    total_transactions: int
+    total_sold: int
+    total_earned: float
+    transactions: List[SecondaryMarketTransaction]
+
+    class Config:
+        from_attributes = True
+
+
+class SyncBalanceRequest(BaseModel):
+    """Request schema for syncing blockchain balance with database"""
+    property_id: str = Field(..., description="Property ID to sync balance for")
+    force_sync: bool = Field(False, description="Force sync even if balances match")
+
+
+class SyncBalanceResponse(BaseModel):
+    """Response schema for balance sync operation"""
+    success: bool
+    property_id: str
+    property_title: str
+    user_id: str
+    
+    # Before sync
+    db_balance_before: int
+    blockchain_balance: float
+    
+    # After sync
+    db_balance_after: int
+    tokens_adjusted: int
+    
+    # Details
+    was_out_of_sync: bool
+    sync_action: str  # "increased", "decreased", "no_change"
+    message: str
+
+    class Config:
+        from_attributes = True
+
+
+# ============================================================================
+# PAYMENT METHOD SCHEMAS (Cards & Banks)
+# ============================================================================
+
+class CardType(str, Enum):
+    visa = "visa"
+    mastercard = "mastercard"
+    amex = "amex"
+    discover = "discover"
+    unknown = "unknown"
+
+
+class BankAccountType(str, Enum):
+    savings = "savings"
+    current = "current"
+    business = "business"
+
+
+class CardCreate(BaseModel):
+    """Schema for adding a new card"""
+    card_number: str = Field(..., min_length=13, max_length=19, description="Full card number")
+    expiry_month: int = Field(..., ge=1, le=12, description="Expiry month (1-12)")
+    expiry_year: int = Field(..., ge=2024, le=2099, description="Expiry year (YYYY)")
+    cvv: str = Field(..., min_length=3, max_length=4, description="CVV code")
+    cardholder_name: str = Field(..., min_length=2, max_length=100, description="Name on card")
+    bank_name: Optional[str] = Field(None, max_length=100, description="Issuing bank name")
+    
+    @validator('card_number')
+    def validate_card_number(cls, v):
+        """Remove spaces and validate digits only"""
+        cleaned = v.replace(' ', '').replace('-', '')
+        if not cleaned.isdigit():
+            raise ValueError('Card number must contain only digits')
+        if len(cleaned) < 13 or len(cleaned) > 19:
+            raise ValueError('Card number must be 13-19 digits')
+        return cleaned
+    
+    @validator('cvv')
+    def validate_cvv(cls, v):
+        """Validate CVV is digits only"""
+        if not v.isdigit():
+            raise ValueError('CVV must contain only digits')
+        return v
+
+
+class CardOut(BaseModel):
+    """Schema for card output (secure - no full card number)"""
+    id: str
+    user_role: Optional[str] = None
+    card_type: CardType
+    last_four: str
+    cardholder_name: str
+    bank_name: Optional[str] = None
+    expiry_month: int
+    expiry_year: int
+    is_default: bool = False
+    created_at: datetime
+    
+    class Config:
+        from_attributes = True
+        
+    def dict(self, **kwargs):
+        kwargs['exclude_none'] = True
+        return super().dict(**kwargs)
+    
+    def model_dump(self, **kwargs):
+        kwargs['exclude_none'] = True
+        return super().model_dump(**kwargs)
+
+
+# ============================================================================
+# MISSING UPDATE SCHEMAS (Schema Completeness)
+# ============================================================================
+
+class PropertySpecificationUpdate(BaseModel):
+    """Update schema for property specifications"""
+    balcony: Optional[int] = Field(None, ge=0)
+    kitchen: Optional[int] = Field(None, ge=0)
+    bedroom: Optional[int] = Field(None, ge=0)
+    bathroom: Optional[int] = Field(None, ge=0)
+    area: Optional[float] = Field(None, gt=0, description="Area in square meters")
+
+
+class AmenityUpdate(BaseModel):
+    """Update schema for property amenities"""
+    name: Optional[str] = Field(None, min_length=2, max_length=100)
+    is_active: Optional[bool] = None
+
+
+class PropertyImageUpdate(BaseModel):
+    """Update schema for property images"""
+    image_url: Optional[str] = None
+    caption: Optional[str] = None
+    is_main: Optional[bool] = None
+    is_active: Optional[bool] = None
+
+
+class TransactionUpdate(BaseModel):
+    """Update schema for transactions"""
+    status: Optional[TransactionStatus] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+class DocumentUpdate(BaseModel):
+    """Update schema for documents"""
+    file_type: Optional[FileType] = None
+    file_url: Optional[str] = None
+    is_active: Optional[bool] = None
+
+
+class PortfolioCreate(BaseModel):
+    """Create schema for user portfolio"""
+    user_id: str
+    total_invested: float = 0.0
+    total_current_value: float = 0.0
+    total_profit: float = 0.0
+
+
+class PortfolioUpdate(BaseModel):
+    """Update schema for user portfolio"""
+    total_invested: Optional[float] = Field(None, ge=0)
+    total_current_value: Optional[float] = Field(None, ge=0)
+    total_profit: Optional[float] = None
+
+
+# ============================================================================
+# SESSION SCHEMAS (Device-bound Authentication)
+# ============================================================================
+
+class SessionCreate(BaseModel):
+    """Create schema for user session"""
+    user_id: str = Field(..., description="User ID")
+    device_fingerprint: str = Field(..., min_length=10, max_length=256, description="Device fingerprint hash")
+    device_info: Optional[Dict[str, Any]] = Field(None, description="Device metadata (browser, OS, etc.)")
+    ip_address: Optional[str] = Field(None, max_length=45, description="IPv4 or IPv6 address")
+    user_agent: Optional[str] = Field(None, max_length=512, description="User agent string")
+    expires_at: Optional[datetime] = Field(None, description="Session expiration time")
+
+
+class SessionOut(BaseModel):
+    """Output schema for user session"""
+    id: str
+    session_id: str
+    user_id: str
+    device_fingerprint: str
+    device_info: Optional[Dict[str, Any]] = None
+    ip_address: Optional[str] = None
+    user_agent: Optional[str] = None
+    is_active: bool = True
+    last_activity: Optional[datetime] = None
+    expires_at: datetime
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class SessionUpdate(BaseModel):
+    """Update schema for user session"""
+    is_active: Optional[bool] = None
+    last_activity: Optional[datetime] = None
+    expires_at: Optional[datetime] = None
+
+
+# ============================================================================
+# CERTIFICATE SCHEMAS (Ownership Certificates)
+# ============================================================================
+
+class CertificatePropertyDetails(BaseModel):
+    """Property details embedded in certificate"""
+    property_id: str
+    property_title: str
+    property_location: Optional[str] = None
+    token_currency: Optional[str] = None
+
+
+class CertificateCreate(BaseModel):
+    """Create schema for ownership certificate"""
+    user_id: str = Field(..., description="Owner user ID")
+    property_details: CertificatePropertyDetails = Field(..., description="Property information")
+    tokens_owned: int = Field(..., gt=0, description="Number of tokens owned")
+    ownership_percentage: float = Field(..., ge=0, le=100, description="Ownership percentage")
+    investment_amount: float = Field(..., gt=0, description="Total investment amount in AED")
+    purchase_date: datetime = Field(..., description="Date of purchase")
+    blockchain_tx_hash: Optional[str] = Field(None, description="Blockchain transaction hash")
+    issued_date: Optional[datetime] = Field(None, description="Certificate issue date")
+
+
+class CertificateOut(BaseModel):
+    """Output schema for ownership certificate"""
+    id: str
+    certificate_id: str
+    user_id: str
+    user_name: Optional[str] = None
+    user_email: Optional[str] = None
+    property_details: CertificatePropertyDetails
+    tokens_owned: int
+    ownership_percentage: float
+    investment_amount: float
+    purchase_date: datetime
+    blockchain_tx_hash: Optional[str] = None
+    issued_date: datetime
+    is_valid: bool = True
+    revoked_at: Optional[datetime] = None
+    revocation_reason: Optional[str] = None
+    created_at: datetime
+    updated_at: datetime
+
+    class Config:
+        from_attributes = True
+
+
+class CertificateUpdate(BaseModel):
+    """Update schema for ownership certificate"""
+    tokens_owned: Optional[int] = Field(None, gt=0)
+    ownership_percentage: Optional[float] = Field(None, ge=0, le=100)
+    is_valid: Optional[bool] = None
+    revoked_at: Optional[datetime] = None
+    revocation_reason: Optional[str] = Field(None, max_length=500)
+
+
+# ============================================================================
+# RENT DISTRIBUTION UPDATE SCHEMAS
+# ============================================================================
+
+class RentDistributionUpdate(BaseModel):
+    """Update schema for rent distribution"""
+    total_rent_amount: Optional[float] = Field(None, gt=0)
+    status: Optional[str] = Field(None, pattern="^(pending|processing|completed|failed)$")
+    payments_completed: Optional[int] = Field(None, ge=0)
+    notes: Optional[str] = Field(None, max_length=500)
+
+
+class RentPaymentUpdate(BaseModel):
+    """Update schema for rent payment"""
+    payment_status: Optional[str] = Field(None, pattern="^(pending|processing|completed|failed)$")
+    wallet_credited: Optional[bool] = None
+    transaction_id: Optional[str] = None
+
+
+# ============================================================================
+# SECONDARY MARKET UPDATE SCHEMA
+# ============================================================================
+
+class SecondaryMarketUpdate(BaseModel):
+    """Update schema for secondary market transactions"""
+    status: Optional[MarketTransactionStatus] = None
+    blockchain_tx_hash: Optional[str] = None
+    blockchain_confirmed: Optional[bool] = None
+    blockchain_confirmed_at: Optional[datetime] = None
+    db_investment_updated: Optional[bool] = None
+    db_wallet_updated: Optional[bool] = None
+    db_property_updated: Optional[bool] = None
+    db_transaction_recorded: Optional[bool] = None
+    completed_at: Optional[datetime] = None
+    error_message: Optional[str] = Field(None, max_length=1000)
+    notes: Optional[str] = Field(None, max_length=500)
+
+
+class BankCreate(BaseModel):
+    """Schema for adding a new bank account"""
+    bank_name: str = Field(..., min_length=2, max_length=100, description="Bank name")
+    account_holder_name: str = Field(..., min_length=2, max_length=100, description="Account holder name")
+    account_number: str = Field(..., min_length=8, max_length=20, description="Account number")
+    iban: Optional[str] = Field(None, max_length=34, description="IBAN")
+    swift_code: Optional[str] = Field(None, max_length=11, description="SWIFT/BIC code")
+    account_type: BankAccountType = BankAccountType.savings
+    currency: str = Field("AED", max_length=3)
+    
+    @validator('account_number')
+    def validate_account_number(cls, v):
+        """Remove spaces and validate"""
+        cleaned = v.replace(' ', '').replace('-', '')
+        if not cleaned.isalnum():
+            raise ValueError('Account number must be alphanumeric')
+        return cleaned
+    
+    @validator('iban')
+    def validate_iban(cls, v):
+        """Validate IBAN format if provided"""
+        if v is None:
+            return v
+        cleaned = v.replace(' ', '').upper()
+        if len(cleaned) < 15 or len(cleaned) > 34:
+            raise ValueError('IBAN must be 15-34 characters')
+        return cleaned
+
+
+class BankOut(BaseModel):
+    """Schema for bank output (secure - masked account number)"""
+    id: str
+    user_role: Optional[str] = None
+    bank_name: str
+    account_holder_name: str
+    account_number_last_four: str
+    iban_last_four: Optional[str] = None
+    swift_code: Optional[str] = None
+    account_type: BankAccountType
+    currency: str
+    is_default: bool = False
+    is_verified: bool = False
+    created_at: datetime
+    
+    class Config:
+        from_attributes = True
+        
+    def dict(self, **kwargs):
+        kwargs['exclude_none'] = True
+        return super().dict(**kwargs)
+    
+    def model_dump(self, **kwargs):
+        kwargs['exclude_none'] = True
+        return super().model_dump(**kwargs)
+

services/ipfs_service.py

@@ -0,0 +1,306 @@
+"""
+IPFS Service for Decentralized File Storage
+Handles document uploads to IPFS and returns content-addressed hashes
+"""
+import io
+import base64
+import hashlib
+from typing import Optional, Dict, Any
+import requests
+from config import settings
+
+# Import logging
+from utils.logger import log_info, log_error, log_warning
+
+
+class IPFSService:
+    """
+    Service for interacting with IPFS (InterPlanetary File System)
+    Uses Web3.Storage API for free, permanent storage
+    """
+    
+    def __init__(self):
+        """Initialize IPFS service"""
+        # Get configuration from settings
+        self.ipfs_provider = getattr(settings, 'IPFS_PROVIDER', 'local_simulation')
+        
+        # Web3.Storage API
+        self.web3_api_url = "https://api.web3.storage"
+        self.web3_token = getattr(settings, 'WEB3_STORAGE_API_TOKEN', None)
+        
+        # Pinata API
+        self.pinata_api_url = "https://api.pinata.cloud"
+        self.pinata_api_key = getattr(settings, 'PINATA_API_KEY', None)
+        self.pinata_secret_key = getattr(settings, 'PINATA_SECRET_KEY', None)
+        
+        # Determine which provider to use
+        if self.ipfs_provider == "pinata" and self.pinata_api_key and self.pinata_secret_key:
+            log_info("[IPFS] Initialized with Pinata provider")
+        elif self.ipfs_provider == "web3storage" and self.web3_token:
+            log_info("[IPFS] Initialized with Web3.Storage provider")
+        else:
+            log_warning("[IPFS] Using local simulation mode - files won't be uploaded to real IPFS network")
+            log_warning("[IPFS] To use real IPFS: Set IPFS_PROVIDER='pinata' and configure PINATA_API_KEY + PINATA_SECRET_KEY in .env")
+    
+    def upload_file(self, file_content: bytes, filename: str, content_type: str = "application/octet-stream") -> Dict[str, Any]:
+        """
+        Upload file to IPFS and return CID (Content Identifier)
+        
+        Args:
+            file_content: File bytes
+            filename: Original filename
+            content_type: MIME type
+            
+        Returns:
+            {
+                'success': bool,
+                'cid': str,  # IPFS CID (QmXxx...)
+                'url': str,  # Public IPFS gateway URL
+                'size': int,
+                'hash': str  # SHA-256 hash for verification
+            }
+        """
+        try:
+            log_info(f"[IPFS] Uploading file: {filename} ({len(file_content)} bytes)")
+            
+            # Calculate SHA-256 hash for verification
+            file_hash = hashlib.sha256(file_content).hexdigest()
+            
+            result = None
+            
+            # Route to appropriate provider
+            if self.ipfs_provider == "pinata" and self.pinata_api_key:
+                result = self._upload_to_pinata(file_content, filename, content_type)
+                # Fallback to public IPFS if Pinata fails (e.g., API key revoked)
+                if not result.get('success'):
+                    log_warning(f"[IPFS] Pinata failed, falling back to public IPFS/simulation...")
+                    result = self._upload_to_public_ipfs(file_content, filename)
+            elif self.ipfs_provider == "web3storage" and self.web3_token:
+                result = self._upload_to_web3_storage(file_content, filename, content_type)
+                # Fallback to public IPFS if Web3.Storage fails
+                if not result.get('success'):
+                    log_warning(f"[IPFS] Web3.Storage failed, falling back to public IPFS/simulation...")
+                    result = self._upload_to_public_ipfs(file_content, filename)
+            else:
+                # Fallback: Upload to public IPFS node or local simulation
+                result = self._upload_to_public_ipfs(file_content, filename)
+            
+            if result['success']:
+                result['hash'] = file_hash
+                log_info(f"[IPFS] SUCCESS: Upload successful! CID: {result['cid']}")
+            else:
+                log_error(f"[IPFS] ERROR: Upload failed: {result.get('error')}")
+            
+            return result
+            
+        except Exception as e:
+            log_error(f"[IPFS] Upload error: {e}")
+            return {
+                'success': False,
+                'error': str(e)
+            }
+    
+    def _upload_to_web3_storage(self, file_content: bytes, filename: str, content_type: str) -> Dict[str, Any]:
+        """Upload file to Web3.Storage API"""
+        try:
+            # Prepare upload
+            headers = {
+                'Authorization': f'Bearer {self.api_token}',
+                'X-NAME': filename
+            }
+            
+            files = {
+                'file': (filename, io.BytesIO(file_content), content_type)
+            }
+            
+            # Upload to Web3.Storage
+            response = requests.post(
+                f"{self.web3_api_url}/upload",
+                headers=headers,
+                files=files,
+                timeout=30
+            )
+            
+            if response.status_code == 200:
+                data = response.json()
+                cid = data.get('cid')
+                
+                return {
+                    'success': True,
+                    'cid': cid,
+                    'url': f"https://ipfs.io/ipfs/{cid}",
+                    'gateway_url': f"https://w3s.link/ipfs/{cid}",
+                    'size': len(file_content),
+                    'provider': 'web3.storage'
+                }
+            else:
+                return {
+                    'success': False,
+                    'error': f"Web3.Storage API error: {response.status_code} - {response.text}"
+                }
+                
+        except Exception as e:
+            return {
+                'success': False,
+                'error': f"Web3.Storage upload failed: {str(e)}"
+            }
+    
+    def _upload_to_pinata(self, file_content: bytes, filename: str, content_type: str) -> Dict[str, Any]:
+        """Upload file to Pinata (pinata.cloud)"""
+        try:
+            log_info(f"[IPFS] Uploading to Pinata...")
+            
+            # Pinata requires pinFileToIPFS endpoint
+            url = f"{self.pinata_api_url}/pinning/pinFileToIPFS"
+            
+            headers = {
+                'pinata_api_key': self.pinata_api_key,
+                'pinata_secret_api_key': self.pinata_secret_key
+            }
+            
+            files = {
+                'file': (filename, io.BytesIO(file_content), content_type)
+            }
+            
+            response = requests.post(
+                url,
+                headers=headers,
+                files=files,
+                timeout=60
+            )
+            
+            if response.status_code == 200:
+                data = response.json()
+                cid = data.get('IpfsHash')
+                
+                log_info(f"[IPFS] SUCCESS: Pinata upload successful! CID: {cid}")
+                
+                return {
+                    'success': True,
+                    'cid': cid,
+                    'url': f"https://ipfs.io/ipfs/{cid}",
+                    'gateway_url': f"https://gateway.pinata.cloud/ipfs/{cid}",
+                    'size': len(file_content),
+                    'provider': 'pinata',
+                    'pinata_data': data
+                }
+            else:
+                log_error(f"[IPFS] Pinata API error: {response.status_code} - {response.text}")
+                return {
+                    'success': False,
+                    'error': f"Pinata API error: {response.status_code} - {response.text}"
+                }
+                
+        except Exception as e:
+            log_error(f"[IPFS] Pinata upload failed: {str(e)}")
+            return {
+                'success': False,
+                'error': f"Pinata upload failed: {str(e)}"
+            }
+    
+    def _upload_to_public_ipfs(self, file_content: bytes, filename: str) -> Dict[str, Any]:
+        """
+        Fallback: Upload to public IPFS node
+        Note: Public nodes may not persist data permanently
+        """
+        try:
+            # Method 1: Try Web3.Storage (free public IPFS API - no auth required for small files)
+            # Note: Uses nft.storage domain but serves general IPFS content
+            try:
+                log_info(f"[IPFS] Trying Web3.Storage public API...")
+                files = {
+                    'file': (filename, io.BytesIO(file_content))
+                }
+                
+                response = requests.post(
+                    "https://api.nft.storage/upload",
+                    files=files,
+                    timeout=30
+                )
+                
+                if response.status_code == 200 or response.status_code == 201:
+                    data = response.json()
+                    cid = data.get('value', {}).get('cid') or data.get('cid')
+                    
+                    if cid:
+                        log_info(f"[IPFS] SUCCESS: Web3.Storage upload successful! CID: {cid}")
+                        return {
+                            'success': True,
+                            'cid': cid,
+                            'url': f"https://ipfs.io/ipfs/{cid}",
+                            'gateway_url': f"https://nftstorage.link/ipfs/{cid}",
+                            'size': len(file_content),
+                            'provider': 'web3.storage',
+                            'warning': 'Using public gateway - free tier'
+                        }
+            except Exception as e:
+                log_warning(f"[IPFS] Web3.Storage failed: {e}")
+            
+            # Method 2: Use a mock/local storage approach (for development)
+            # Generate a deterministic "fake CID" based on content hash
+            log_warning(f"[IPFS] All public nodes failed. Creating local reference...")
+            content_hash = hashlib.sha256(file_content).hexdigest()
+            fake_cid = f"Qm{content_hash[:44]}"  # Simulate IPFS CID format
+            
+            log_info(f"[IPFS] WARNING: Using local storage simulation. CID: {fake_cid}")
+            log_info(f"[IPFS] WARNING: Note: File is stored locally, not on IPFS network")
+            
+            return {
+                'success': True,
+                'cid': fake_cid,
+                'url': f"https://ipfs.io/ipfs/{fake_cid}",
+                'gateway_url': f"https://cloudflare-ipfs.com/ipfs/{fake_cid}",
+                'size': len(file_content),
+                'provider': 'local_simulation',
+                'warning': 'LOCAL SIMULATION ONLY - Not uploaded to real IPFS. For production, configure Web3.Storage API token.'
+            }
+            
+        except Exception as e:
+            return {
+                'success': False,
+                'error': f"Public IPFS upload failed: {str(e)}"
+            }
+    
+    def get_file_url(self, cid: str, gateway: str = "ipfs.io") -> str:
+        """
+        Get public URL for IPFS file
+        
+        Args:
+            cid: IPFS CID
+            gateway: Gateway domain (default: ipfs.io)
+            
+        Returns:
+            Public URL to access file
+        """
+        return f"https://{gateway}/ipfs/{cid}"
+    
+    def verify_file_hash(self, cid: str, expected_hash: str) -> bool:
+        """
+        Verify that file on IPFS matches expected hash
+        
+        Args:
+            cid: IPFS CID
+            expected_hash: Expected SHA-256 hash
+            
+        Returns:
+            True if hashes match
+        """
+        try:
+            # Download file from IPFS
+            url = self.get_file_url(cid)
+            response = requests.get(url, timeout=30)
+            
+            if response.status_code == 200:
+                # Calculate hash of downloaded file
+                actual_hash = hashlib.sha256(response.content).hexdigest()
+                return actual_hash == expected_hash
+            
+            return False
+            
+        except Exception as e:
+            log_error(f"[IPFS] Hash verification failed: {e}")
+            return False
+
+
+# Global IPFS service instance
+ipfs_service = IPFSService()

services/price_oracle.py

@@ -0,0 +1,118 @@
+"""
+Price Oracle Service for Real-Time XRP/AED Exchange Rates
+Fetches live prices from multiple sources for accuracy
+"""
+
+import requests
+from typing import Optional, Dict
+import time
+from config import settings
+
+class PriceOracle:
+    """Fetches real-time XRP/AED exchange rates"""
+    
+    def __init__(self):
+        self.cache_duration = 60  # Cache price for 60 seconds
+        self.last_fetch_time = 0
+        self.cached_rate = None
+        self.fallback_rate = settings.XRPL_RATE_AED_TO_XRP  # Use config as fallback
+    
+    def get_xrp_aed_rate(self) -> float:
+        """
+        Get current XRP to AED exchange rate
+        Returns: XRP per 1 AED (e.g., 0.000017 means 1 AED = 0.000017 XRP)
+        """
+        # Check cache first
+        current_time = time.time()
+        if self.cached_rate and (current_time - self.last_fetch_time) < self.cache_duration:
+            return self.cached_rate
+        
+        # Try to fetch live rate
+        live_rate = self._fetch_live_rate()
+        
+        if live_rate:
+            self.cached_rate = live_rate
+            self.last_fetch_time = current_time
+            return live_rate
+        
+        # Fallback to config or cached value
+        return self.cached_rate if self.cached_rate else self.fallback_rate
+    
+    def _fetch_live_rate(self) -> Optional[float]:
+        """Fetch live XRP/AED rate from exchange APIs"""
+        
+        # Source 1: CoinGecko API (Free, no API key needed)
+        try:
+            response = requests.get(
+                'https://api.coingecko.com/api/v3/simple/price',
+                params={'ids': 'ripple', 'vs_currencies': 'aed'},
+                timeout=5
+            )
+            if response.status_code == 200:
+                data = response.json()
+                xrp_aed_price = data.get('ripple', {}).get('aed')
+                if xrp_aed_price and xrp_aed_price > 0:
+                    # Convert from "1 XRP = X AED" to "1 AED = X XRP"
+                    xrp_per_aed = 1.0 / xrp_aed_price
+                    print(f"[ORACLE] Live rate: 1 XRP = {xrp_aed_price:.2f} AED | 1 AED = {xrp_per_aed:.8f} XRP")
+                    return xrp_per_aed
+        except Exception as e:
+            print(f"[ORACLE] CoinGecko API failed: {e}")
+        
+        # Source 2: CoinDCX API (Exchange)
+        try:
+            response = requests.get(
+                'https://api.coindcx.com/exchange/ticker',
+                timeout=5
+            )
+            if response.status_code == 200:
+                data = response.json()
+                # Find XRP/AED pair (or convert via USDT if needed)
+                for ticker in data:
+                    if ticker.get('market') == 'XRPAED':
+                        last_price = float(ticker.get('last_price', 0))
+                        if last_price > 0:
+                            xrp_per_aed = 1.0 / last_price
+                            print(f"[ORACLE] CoinDCX rate: 1 XRP = {last_price:.2f} AED | 1 AED = {xrp_per_aed:.8f} XRP")
+                            return xrp_per_aed
+        except Exception as e:
+            print(f"[ORACLE] CoinDCX API failed: {e}")
+        
+        # Source 3: Binance API (as additional fallback)
+        try:
+            # First get XRP/USDT
+            response = requests.get(
+                'https://api.binance.com/api/v3/ticker/price',
+                params={'symbol': 'XRPUSDT'},
+                timeout=5
+            )
+            if response.status_code == 200:
+                xrp_usdt = float(response.json().get('price', 0))
+                
+                # Then get USDT/AED (approximate - 1 USD ≈ 3.67 AED)
+                # Using fixed rate or could fetch from another API
+                usdt_aed = 3.67  # Approximate fixed rate
+                    
+                if xrp_usdt > 0 and usdt_aed > 0:
+                    xrp_aed = xrp_usdt * usdt_aed
+                    xrp_per_aed = 1.0 / xrp_aed
+                    print(f"[ORACLE] Binance rate: 1 XRP = {xrp_aed:.2f} AED | 1 AED = {xrp_per_aed:.8f} XRP")
+                    return xrp_per_aed
+        except Exception as e:
+            print(f"[ORACLE] Binance API failed: {e}")
+        
+        print(f"[ORACLE] [WARNING] All price sources failed, using fallback rate: {self.fallback_rate}")
+        return None
+    
+    def get_aed_to_xrp(self, aed_amount: float) -> float:
+        """Convert AED amount to XRP"""
+        rate = self.get_xrp_aed_rate()
+        return aed_amount * rate
+    
+    def get_xrp_to_aed(self, xrp_amount: float) -> float:
+        """Convert XRP amount to AED"""
+        rate = self.get_xrp_aed_rate()
+        return xrp_amount / rate if rate > 0 else 0
+
+# Global instance
+price_oracle = PriceOracle()

services/property_wallet_manager.py

@@ -0,0 +1,136 @@
+"""
+Property Wallet Manager - Per-Property Issuer Wallets
+Creates and manages individual issuer wallets for each property
+"""
+
+from xrpl.wallet import Wallet
+from xrpl.clients import JsonRpcClient
+from xrpl.models.requests import AccountInfo
+from typing import Dict, Optional
+import base64
+from config import settings
+from cryptography.fernet import Fernet as _FernetLegacy
+from utils.crypto_utils import encrypt_secret, decrypt_secret, is_encrypted
+
+class PropertyWalletManager:
+    """Manages individual issuer wallets for each property"""
+    
+    def __init__(self):
+        self.client = JsonRpcClient(settings.XRPL_RPC_URL)
+        # No local cipher; rely on shared crypto utils for consistent format
+        self.cipher = None
+    
+    def _encrypt_seed(self, seed: str) -> str:
+        """Encrypt wallet seed for storage using shared crypto utils.
+
+        Returns ENC::<token> when ENCRYPTION_KEY is set; otherwise returns legacy base64.
+        """
+        enc_val = encrypt_secret(seed, settings.ENCRYPTION_KEY)
+        if is_encrypted(enc_val):
+            return enc_val
+        # When encryption is not enabled, encrypt_secret returns plaintext.
+        # Preserve previous behavior: store legacy base64-obfuscated seed.
+        return base64.b64encode(enc_val.encode()).decode()
+    
+    def _decrypt_seed(self, encrypted_seed: str) -> str:
+        """Decrypt wallet seed from storage.
+
+        Supports both new ENC:: format and legacy base64/plain values.
+        """
+        # If value is ENC::..., decrypt via shared util
+        if is_encrypted(encrypted_seed):
+            seed = decrypt_secret(encrypted_seed, settings.ENCRYPTION_KEY)
+            if not seed:
+                raise ValueError("Failed to decrypt property wallet seed: invalid token or key")
+            return seed
+        # Otherwise, try legacy base64(FernetToken) using previous derivation; if fails, plaintext/base64
+        try:
+            enc_bytes = base64.b64decode(encrypted_seed.encode())
+            # Attempt legacy cipher path
+            if settings.ENCRYPTION_KEY:
+                try:
+                    if len(settings.ENCRYPTION_KEY) == 44:
+                        key_bytes = settings.ENCRYPTION_KEY.encode()
+                    else:
+                        key_bytes = base64.urlsafe_b64encode(settings.ENCRYPTION_KEY.encode()[:32])
+                    legacy_cipher = _FernetLegacy(key_bytes)
+                    return legacy_cipher.decrypt(enc_bytes).decode()
+                except Exception:
+                    pass
+            # If legacy decrypt fails, last chance: maybe enc_bytes are actually plaintext bytes
+            return enc_bytes.decode()
+        except Exception:
+            return encrypted_seed
+    
+    def create_property_wallet(self, property_id: str, property_name: str) -> Dict:
+        """
+        Create a new wallet specifically for this property
+        
+        Returns:
+            Dict with wallet_address, encrypted_seed, and metadata
+        """
+        # Generate new wallet
+        wallet = Wallet.create()
+        
+        print(f"[WALLET MGR] Created wallet for property: {property_name}")
+        print(f"[WALLET MGR]   Address: {wallet.classic_address}")
+        print(f"[WALLET MGR]   [WARNING]  FUND THIS WALLET: https://faucet.altnet.rippletest.net/")
+        
+        # Encrypt the seed before storage
+        encrypted_seed = self._encrypt_seed(wallet.seed)
+        
+        return {
+            "property_id": property_id,
+            "issuer_address": wallet.classic_address,
+            "encrypted_seed": encrypted_seed,
+            "public_key": wallet.public_key,
+            "wallet_type": "property_issuer",
+            "funded": False,  # Will be updated when wallet is funded
+            "created_for": property_name,
+            "network": settings.XRPL_NETWORK
+        }
+    
+    def get_property_wallet(self, encrypted_seed: str) -> Wallet:
+        """Get Wallet object from encrypted seed"""
+        seed = self._decrypt_seed(encrypted_seed)
+        return Wallet.from_seed(seed)
+    
+    def check_wallet_funded(self, address: str) -> Dict:
+        """Check if wallet is funded and get balance"""
+        try:
+            account_info_request = AccountInfo(account=address)
+            response = self.client.request(account_info_request)
+            
+            if response.is_successful() and 'account_data' in response.result:
+                balance_drops = response.result['account_data'].get('Balance', '0')
+                balance_xrp = float(balance_drops) / 1_000_000
+                
+                return {
+                    "funded": True,
+                    "balance_xrp": balance_xrp,
+                    "balance_drops": balance_drops,
+                    "sequence": response.result['account_data'].get('Sequence', 0)
+                }
+            else:
+                return {"funded": False, "balance_xrp": 0}
+                
+        except Exception as e:
+            print(f"[WALLET MGR] Error checking wallet: {e}")
+            return {"funded": False, "balance_xrp": 0}
+    
+    def use_master_wallet_fallback(self) -> bool:
+        """Check if we should fall back to master wallet"""
+        # If no issuer seed configured, can't use master wallet
+        if not settings.ISSUER_SEED:
+            return False
+        
+        # Check if master wallet is funded
+        try:
+            master_wallet = Wallet.from_seed(settings.ISSUER_SEED)
+            status = self.check_wallet_funded(master_wallet.classic_address)
+            return status.get('funded', False)
+        except:
+            return False
+
+# Global instance
+property_wallet_manager = PropertyWalletManager()

services/rent_distribution_service.py

@@ -0,0 +1,294 @@
+"""
+Rent Distribution Service for Real Estate Tokenization Platform
+Handles automated rent distribution to token holders
+"""
+from typing import Dict, Any, List, Optional
+from datetime import datetime
+import logging
+from pymongo.client_session import ClientSession
+
+import repo
+
+logger = logging.getLogger(__name__)
+
+
+class RentDistributionService:
+    """Service to handle rent distribution to token holders"""
+    
+    def __init__(self, db):
+        self.db = db
+    
+    def distribute_rent(
+        self,
+        property_id: str,
+        total_rent_amount: float,
+        rent_period_start: str,
+        rent_period_end: str,
+        distribution_date: Optional[datetime] = None,
+        notes: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Distribute rent to all token holders of a property
+        
+        Steps:
+        1. Validate property exists
+        2. Get total tokens for the property
+        3. Calculate rent per token
+        4. Create rent distribution record
+        5. Find all investors (token holders)
+        6. For each investor:
+           - Calculate their rent share
+           - Credit their wallet
+           - Create transaction record
+           - Create rent payment record
+        7. Update distribution status
+        
+        Args:
+            property_id: Property ID generating rent
+            total_rent_amount: Total rent collected (AED)
+            rent_period_start: Start date (YYYY-MM-DD)
+            rent_period_end: End date (YYYY-MM-DD)
+            distribution_date: When to distribute (default: now)
+            notes: Additional notes
+            
+        Returns:
+            Dict containing distribution details and results
+        """
+        logger.info(f"Starting rent distribution for property {property_id}, amount: {total_rent_amount} AED")
+        
+        if distribution_date is None:
+            distribution_date = datetime.utcnow()
+        
+        # Step 1: Validate property exists
+        property_data = repo.get_property_by_id(self.db, property_id)
+        if not property_data:
+            raise ValueError(f"Property not found: {property_id}")
+        
+        property_title = property_data.get("title", "Unknown Property")
+        
+        # Step 2: Get total tokens for the property
+        total_tokens = property_data.get("total_tokens", 0)
+        if total_tokens <= 0:
+            raise ValueError(f"Property has no tokens: {property_id}")
+        
+        # Step 3: Calculate rent per token
+        rent_per_token = total_rent_amount / total_tokens
+        logger.info(f"Rent per token: {rent_per_token:.6f} AED ({total_rent_amount} / {total_tokens})")
+        
+        # Step 4: Create rent distribution record
+        distribution = repo.create_rent_distribution(
+            db=self.db,
+            property_id=property_id,
+            total_rent_amount=total_rent_amount,
+            rent_period_start=rent_period_start,
+            rent_period_end=rent_period_end,
+            total_tokens=total_tokens,
+            rent_per_token=rent_per_token,
+            distribution_date=distribution_date,
+            notes=notes
+        )
+        
+        distribution_id = distribution["id"]
+        logger.info(f"Created rent distribution: {distribution_id}")
+        
+        # Step 5: Find all investors for this property
+        investors = repo.get_investors_by_property(self.db, property_id)
+        logger.info(f"Found {len(investors)} investors for property {property_id}")
+        
+        if not investors:
+            # No investors, mark as completed
+            repo.update_rent_distribution_status(
+                db=self.db,
+                distribution_id=distribution_id,
+                status="completed",
+                total_investors=0,
+                payments_completed=0
+            )
+            return {
+                "distribution_id": distribution_id,
+                "property_title": property_title,
+                "total_rent_amount": total_rent_amount,
+                "total_investors": 0,
+                "payments_completed": 0,
+                "payments_failed": 0,
+                "status": "completed",
+                "message": "No investors found for this property"
+            }
+        
+        # Update status to processing
+        repo.update_rent_distribution_status(
+            db=self.db,
+            distribution_id=distribution_id,
+            status="processing",
+            total_investors=len(investors),
+            payments_completed=0
+        )
+        
+        # Step 6: Process each investor WITH TRANSACTION
+        # Using MongoDB transaction for atomicity - all payments succeed or all fail
+        payments_completed = 0
+        payments_failed = 0
+        payment_results = []
+        
+        logger.info(f"Starting to process {len(investors)} investors (with transaction)")
+        
+        # Get MongoDB client for transaction
+        from db import get_client
+        client = get_client()
+        
+        try:
+            with client.start_session() as session:
+                with session.start_transaction():
+                    for investment in investors:
+                        try:
+                            user_id = investment.get("user_id")
+                            tokens_owned = investment.get("tokens_purchased", 0)
+                            
+                            logger.info(f"Processing investor: user_id={user_id}, tokens_purchased={tokens_owned}")
+                            
+                            if tokens_owned <= 0:
+                                logger.warning(f"User {user_id} has 0 tokens, skipping")
+                                payments_failed += 1
+                                payment_results.append({
+                                    "user_id": user_id,
+                                    "status": "failed",
+                                    "error": "No tokens owned"
+                                })
+                                continue
+                            
+                            # Calculate rent share
+                            rent_share = tokens_owned * rent_per_token
+                            logger.info(f"User {user_id}: {tokens_owned} tokens × {rent_per_token:.6f} = {rent_share:.2f} AED")
+                            
+                            # Credit wallet
+                            wallet = repo.get_wallet_by_user(self.db, user_id)
+                            if not wallet:
+                                logger.error(f"Wallet not found for user {user_id}")
+                                payments_failed += 1
+                                payment_results.append({
+                                    "user_id": user_id,
+                                    "status": "failed",
+                                    "error": "Wallet not found"
+                                })
+                                continue
+                            
+                            wallet_id = wallet["id"]
+                            
+                            # Update wallet balance (with session for transaction)
+                            updated_wallet = repo.update_wallet_balance(
+                                self.db, wallet_id, rent_share, operation="add", session=session
+                            )
+                            logger.info(f"Credited {rent_share:.2f} AED to wallet {wallet_id}, new balance: {updated_wallet.get('balance') if updated_wallet else 'unknown'}")
+                            
+                            # Create transaction record (with session)
+                            transaction = repo.create_transaction(
+                                db=self.db,
+                                user_id=user_id,
+                                wallet_id=wallet_id,
+                                tx_type="profit",  # Rent is a profit distribution
+                                amount=rent_share,
+                                property_id=property_id,
+                                status="completed",
+                                metadata={
+                                    "type": "rent_distribution",
+                                    "distribution_id": distribution_id,
+                                    "tokens_owned": tokens_owned,
+                                    "rent_per_token": rent_per_token,
+                                    "rent_period": f"{rent_period_start} to {rent_period_end}"
+                                },
+                                session=session
+                            )
+                            
+                            transaction_id = transaction["id"]
+                            logger.info(f"Created transaction {transaction_id} for rent payment")
+                            
+                            # Create rent payment record (with session)
+                            rent_payment = repo.create_rent_payment(
+                                db=self.db,
+                                distribution_id=distribution_id,
+                                user_id=user_id,
+                                property_id=property_id,
+                                tokens_owned=tokens_owned,
+                                rent_amount=rent_share,
+                                rent_period_start=rent_period_start,
+                                rent_period_end=rent_period_end,
+                                payment_status="completed",
+                                wallet_credited=True,
+                                transaction_id=transaction_id,
+                                session=session
+                            )
+                            
+                            payments_completed += 1
+                            logger.info(f"Successfully processed rent payment for user {user_id}")
+                            payment_results.append({
+                                "user_id": user_id,
+                                "tokens_owned": tokens_owned,
+                                "rent_amount": rent_share,
+                                "status": "success"
+                            })
+                            
+                        except Exception as e:
+                            logger.error(f"Failed to process rent payment for user {user_id}: {e}", exc_info=True)
+                            payments_failed += 1
+                            payment_results.append({
+                                "user_id": user_id if 'user_id' in locals() else "unknown",
+                                "status": "failed",
+                                "error": str(e)
+                            })
+                            # Re-raise to abort transaction if critical error
+                            if payments_completed > 0:
+                                # Some payments succeeded - abort transaction to ensure atomicity
+                                raise
+                    
+                    # If we reach here, all payments within transaction succeeded
+                    logger.info(f"Transaction completed: {payments_completed} payments processed")
+        
+        except Exception as tx_error:
+            # Transaction was aborted - all changes rolled back
+            logger.error(f"Transaction aborted, all changes rolled back: {tx_error}")
+            payments_failed = len(investors)
+            payments_completed = 0
+            payment_results = [{"user_id": inv.get("user_id"), "status": "failed", "error": "Transaction aborted"} for inv in investors]
+        
+        logger.info(f"Investor processing complete: {payments_completed} succeeded, {payments_failed} failed")
+        
+        # Step 7: Update distribution status to completed
+        final_status = "completed" if payments_failed == 0 else "completed_with_errors"
+        repo.update_rent_distribution_status(
+            db=self.db,
+            distribution_id=distribution_id,
+            status=final_status,
+            total_investors=len(investors),
+            payments_completed=payments_completed
+        )
+        
+        logger.info(f"Rent distribution completed: {payments_completed} succeeded, {payments_failed} failed")
+        
+        return {
+            "distribution_id": distribution_id,
+            "property_id": property_id,
+            "property_title": property_title,
+            "total_rent_amount": total_rent_amount,
+            "rent_per_token": rent_per_token,
+            "total_investors": len(investors),
+            "payments_completed": payments_completed,
+            "payments_failed": payments_failed,
+            "status": final_status,
+            "rent_period": f"{rent_period_start} to {rent_period_end}",
+            "payment_results": payment_results
+        }
+    
+    def get_distribution_details(self, distribution_id: str) -> Optional[Dict[str, Any]]:
+        """Get details of a rent distribution"""
+        distribution = repo.get_rent_distribution_by_id(self.db, distribution_id)
+        if not distribution:
+            return None
+        
+        # Enrich with property title
+        property_id = distribution.get("property_id")
+        if property_id:
+            property_data = repo.get_property_by_id(self.db, property_id)
+            if property_data:
+                distribution["property_title"] = property_data.get("title")
+        
+        return distribution

services/secondary_market.py

@@ -0,0 +1,354 @@
+"""
+Secondary Market Service - Token Trading on XRP DEX
+Allows users to buy/sell tokens from each other using XRP Ledger's built-in DEX
+"""
+
+from xrpl.clients import JsonRpcClient
+from xrpl.wallet import Wallet
+from xrpl.models.transactions import OfferCreate, OfferCancel
+from xrpl.models.requests import AccountOffers, BookOffers
+from xrpl.transaction import submit_and_wait, autofill_and_sign
+from xrpl.models.amounts import IssuedCurrencyAmount
+from xrpl.utils import xrp_to_drops, drops_to_xrp
+from typing import List, Dict, Optional
+from config import settings
+
+# Import blockchain utilities for retry and error handling
+from utils.blockchain_utils import (
+    retry_handler,
+    TransactionMonitor,
+    BlockchainError
+)
+
+class SecondaryMarket:
+    """Manages token trading on XRP Ledger DEX"""
+    
+    def __init__(self):
+        self.client = JsonRpcClient(settings.XRPL_RPC_URL)
+    
+    def create_sell_offer(
+        self,
+        seller_seed: str,
+        currency_code: str,
+        issuer_address: str,
+        token_amount: int,
+        price_per_token_xrp: float
+    ) -> Dict:
+        """
+        Create a sell offer for tokens - WITH RETRY
+        
+        Args:
+            seller_seed: Seller's wallet seed
+            currency_code: Property token currency code
+            issuer_address: Token issuer address
+            token_amount: Number of tokens to sell
+            price_per_token_xrp: Price per token in XRP
+        
+        Returns:
+            Offer details including offer sequence number
+        """
+        try:
+            seller = Wallet.from_seed(seller_seed)
+            total_xrp = token_amount * price_per_token_xrp
+            
+            # Create IOU amount (what seller is selling)
+            token_amount_obj = IssuedCurrencyAmount(
+                currency=currency_code,
+                issuer=issuer_address,
+                value=str(token_amount)
+            )
+            
+            def submit_sell_offer():
+                # Create offer: Sell tokens for XRP
+                offer_tx = OfferCreate(
+                    account=seller.classic_address,
+                    taker_gets=str(int(xrp_to_drops(total_xrp))),  # XRP (buyer pays)
+                    taker_pays=token_amount_obj,  # Tokens (seller gives)
+                )
+                
+                signed_tx = autofill_and_sign(offer_tx, self.client, seller)
+                result = submit_and_wait(signed_tx, self.client)
+                
+                if not result.is_successful():
+                    error = result.result.get('engine_result_message', 'Unknown error')
+                    raise Exception(error)
+                
+                return result
+            
+            result = retry_handler.execute_with_retry(
+                submit_sell_offer,
+                "Create Sell Offer"
+            )
+            
+            tx_hash = result.result.get('tx_json', {}).get('hash') or result.result.get('hash')
+            offer_sequence = result.result.get('tx_json', {}).get('Sequence')
+            
+            print(f"[MARKET] ✅ Sell offer created!")
+            print(f"[MARKET]   Seller: {seller.classic_address}")
+            print(f"[MARKET]   Selling: {token_amount} tokens")
+            print(f"[MARKET]   Price: {price_per_token_xrp} XRP per token")
+            print(f"[MARKET]   Total: {total_xrp} XRP")
+            print(f"[MARKET]   TX: {tx_hash}")
+            
+            return {
+                'success': True,
+                'offer_sequence': offer_sequence,
+                'tx_hash': tx_hash,
+                'seller': seller.classic_address,
+                'token_amount': token_amount,
+                'price_per_token_xrp': price_per_token_xrp,
+                'total_xrp': total_xrp
+            }
+                
+        except BlockchainError as e:
+            print(f"[MARKET] Sell offer failed: {e.technical_msg}")
+            return {'success': False, 'error': e.user_msg}
+        except Exception as e:
+            print(f"[MARKET] Error creating sell offer: {e}")
+            return {'success': False, 'error': 'Failed to create sell offer. Please try again.'}
+    
+    def create_buy_offer(
+        self,
+        buyer_seed: str,
+        currency_code: str,
+        issuer_address: str,
+        token_amount: int,
+        price_per_token_xrp: float
+    ) -> Dict:
+        """
+        Create a buy offer for tokens - WITH RETRY
+        
+        Args:
+            buyer_seed: Buyer's wallet seed
+            currency_code: Property token currency code
+            issuer_address: Token issuer address
+            token_amount: Number of tokens to buy
+            price_per_token_xrp: Price per token in XRP
+        
+        Returns:
+            Offer details
+        """
+        try:
+            buyer = Wallet.from_seed(buyer_seed)
+            total_xrp = token_amount * price_per_token_xrp
+            
+            # Create IOU amount (what buyer wants)
+            token_amount_obj = IssuedCurrencyAmount(
+                currency=currency_code,
+                issuer=issuer_address,
+                value=str(token_amount)
+            )
+            
+            def submit_buy_offer():
+                # Create offer: Buy tokens with XRP
+                offer_tx = OfferCreate(
+                    account=buyer.classic_address,
+                    taker_gets=token_amount_obj,  # Tokens (buyer wants)
+                    taker_pays=str(int(xrp_to_drops(total_xrp))),  # XRP (buyer pays)
+                )
+                
+                signed_tx = autofill_and_sign(offer_tx, self.client, buyer)
+                result = submit_and_wait(signed_tx, self.client)
+                
+                if not result.is_successful():
+                    error = result.result.get('engine_result_message', 'Unknown error')
+                    raise Exception(error)
+                
+                return result
+            
+            result = retry_handler.execute_with_retry(
+                submit_buy_offer,
+                "Create Buy Offer"
+            )
+            
+            tx_hash = result.result.get('tx_json', {}).get('hash') or result.result.get('hash')
+            offer_sequence = result.result.get('tx_json', {}).get('Sequence')
+            
+            print(f"[MARKET] ✅ Buy offer created!")
+            print(f"[MARKET]   Buyer: {buyer.classic_address}")
+            print(f"[MARKET]   Buying: {token_amount} tokens")
+            print(f"[MARKET]   Price: {price_per_token_xrp} XRP per token")
+            print(f"[MARKET]   Total: {total_xrp} XRP")
+            print(f"[MARKET]   TX: {tx_hash}")
+            
+            return {
+                'success': True,
+                'offer_sequence': offer_sequence,
+                'tx_hash': tx_hash,
+                'buyer': buyer.classic_address,
+                'token_amount': token_amount,
+                'price_per_token_xrp': price_per_token_xrp,
+                'total_xrp': total_xrp
+            }
+                
+        except BlockchainError as e:
+            print(f"[MARKET] Buy offer failed: {e.technical_msg}")
+            return {'success': False, 'error': e.user_msg}
+        except Exception as e:
+            print(f"[MARKET] Error creating buy offer: {e}")
+            return {'success': False, 'error': 'Failed to create buy offer. Please try again.'}
+    
+    def cancel_offer(self, wallet_seed: str, offer_sequence: int) -> Dict:
+        """Cancel an existing offer - WITH RETRY"""
+        try:
+            wallet = Wallet.from_seed(wallet_seed)
+            
+            def submit_cancel():
+                cancel_tx = OfferCancel(
+                    account=wallet.classic_address,
+                    offer_sequence=offer_sequence
+                )
+                
+                signed_tx = autofill_and_sign(cancel_tx, self.client, wallet)
+                result = submit_and_wait(signed_tx, self.client)
+                
+                if not result.is_successful():
+                    error = result.result.get('engine_result_message', 'Unknown error')
+                    raise Exception(error)
+                
+                return result
+            
+            result = retry_handler.execute_with_retry(
+                submit_cancel,
+                "Cancel Offer"
+            )
+            
+            tx_hash = result.result.get('tx_json', {}).get('hash') or result.result.get('hash')
+            print(f"[MARKET] ✅ Offer cancelled: {offer_sequence}")
+            
+            return {
+                'success': True,
+                'tx_hash': tx_hash,
+                'cancelled_sequence': offer_sequence
+            }
+                
+        except BlockchainError as e:
+            print(f"[MARKET] Cancel offer failed: {e.technical_msg}")
+            return {'success': False, 'error': e.user_msg}
+        except Exception as e:
+            print(f"[MARKET] Error cancelling offer: {e}")
+            return {'success': False, 'error': 'Failed to cancel offer. Please try again.'}
+    
+    def get_user_offers(self, wallet_address: str) -> List[Dict]:
+        """Get all active offers for a user"""
+        try:
+            request = AccountOffers(account=wallet_address)
+            response = self.client.request(request)
+            
+            if response.is_successful():
+                offers = response.result.get('offers', [])
+                
+                parsed_offers = []
+                for offer in offers:
+                    taker_gets = offer.get('taker_gets')
+                    taker_pays = offer.get('taker_pays')
+                    
+                    # Determine if it's a buy or sell offer
+                    if isinstance(taker_gets, str):
+                        # Getting XRP, paying tokens = SELL offer
+                        offer_type = 'sell'
+                        xrp_amount = float(taker_gets) / 1_000_000
+                        token_amount = float(taker_pays.get('value', 0))
+                    else:
+                        # Getting tokens, paying XRP = BUY offer
+                        offer_type = 'buy'
+                        xrp_amount = float(taker_pays) / 1_000_000 if isinstance(taker_pays, str) else 0
+                        token_amount = float(taker_gets.get('value', 0))
+                    
+                    parsed_offers.append({
+                        'sequence': offer.get('seq'),
+                        'type': offer_type,
+                        'token_amount': token_amount,
+                        'xrp_amount': xrp_amount,
+                        'price_per_token': xrp_amount / token_amount if token_amount > 0 else 0,
+                        'raw_offer': offer
+                    })
+                
+                return parsed_offers
+            
+            return []
+            
+        except Exception as e:
+            print(f"[MARKET] Error getting user offers: {e}")
+            return []
+    
+    def get_orderbook(
+        self,
+        currency_code: str,
+        issuer_address: str,
+        limit: int = 50
+    ) -> Dict:
+        """
+        Get orderbook for a token (buy and sell offers)
+        
+        Returns:
+            Dict with 'bids' (buy offers) and 'asks' (sell offers)
+        """
+        try:
+            # Get sell offers (asks)
+            asks_request = BookOffers(
+                taker_gets={'currency': 'XRP'},
+                taker_pays={
+                    'currency': currency_code,
+                    'issuer': issuer_address
+                },
+                limit=limit
+            )
+            
+            asks_response = self.client.request(asks_request)
+            asks = []
+            
+            if asks_response.is_successful():
+                for offer in asks_response.result.get('offers', []):
+                    taker_gets = float(offer.get('TakerGets', 0)) / 1_000_000  # XRP
+                    taker_pays = float(offer.get('TakerPays', {}).get('value', 0))  # Tokens
+                    
+                    if taker_pays > 0:
+                        asks.append({
+                            'price': taker_gets / taker_pays,
+                            'amount': taker_pays,
+                            'total': taker_gets,
+                            'account': offer.get('Account')
+                        })
+            
+            # Get buy offers (bids)
+            bids_request = BookOffers(
+                taker_gets={
+                    'currency': currency_code,
+                    'issuer': issuer_address
+                },
+                taker_pays={'currency': 'XRP'},
+                limit=limit
+            )
+            
+            bids_response = self.client.request(bids_request)
+            bids = []
+            
+            if bids_response.is_successful():
+                for offer in bids_response.result.get('offers', []):
+                    taker_gets = float(offer.get('TakerGets', {}).get('value', 0))  # Tokens
+                    taker_pays = float(offer.get('TakerPays', 0)) / 1_000_000  # XRP
+                    
+                    if taker_gets > 0:
+                        bids.append({
+                            'price': taker_pays / taker_gets,
+                            'amount': taker_gets,
+                            'total': taker_pays,
+                            'account': offer.get('Account')
+                        })
+            
+            return {
+                'success': True,
+                'bids': sorted(bids, key=lambda x: x['price'], reverse=True),
+                'asks': sorted(asks, key=lambda x: x['price']),
+                'best_bid': bids[0]['price'] if bids else None,
+                'best_ask': asks[0]['price'] if asks else None,
+                'spread': (asks[0]['price'] - bids[0]['price']) if bids and asks else None
+            }
+            
+        except Exception as e:
+            print(f"[MARKET] Error getting orderbook: {e}")
+            return {'success': False, 'error': str(e)}
+
+# Global instance
+secondary_market = SecondaryMarket()

services/xrp_service.py

@@ -0,0 +1,668 @@
+from typing import Optional, Tuple, Dict, Any, List
+from xrpl.clients import JsonRpcClient
+from xrpl.wallet import Wallet
+from xrpl.account import get_balance
+from xrpl.models.transactions import Payment, TrustSet, OfferCreate
+from xrpl.transaction import submit_and_wait, autofill_and_sign
+from xrpl.models.amounts import IssuedCurrencyAmount
+from xrpl.models.requests import Tx, AccountLines
+from xrpl.utils import xrp_to_drops, drops_to_xrp
+from config import settings
+import asyncio
+import time
+
+# Import blockchain utilities for retry and error handling
+from utils.blockchain_utils import (
+    retry_handler,
+    TransactionMonitor,
+    BlockchainError
+)
+
+# Import monitoring and logging
+from utils.logger import (
+    monitor_performance,
+    monitor_transaction,
+    get_logger,
+    log_info,
+    log_error,
+    log_warning
+)
+
+# Import price oracle for real-time rates
+try:
+    from services.price_oracle import price_oracle
+    USE_LIVE_RATES = True
+except ImportError:
+    USE_LIVE_RATES = False
+    print("[XRPL] Warning: Price oracle not available, using static rates")
+
+
+class XRPLService:
+    def __init__(self): 
+        self.client = JsonRpcClient(settings.XRPL_RPC_URL)
+
+    def generate_wallet(self) -> Tuple[str, str]:
+        # For demo: generate an in-memory wallet; in production use faucet for funding
+        wallet = Wallet.create()
+        # No auto-fund here; user should fund via faucet UI
+        return wallet.classic_address, wallet.seed
+
+    def get_issuer_wallet(self) -> Wallet:
+        """Get the issuer wallet from settings (DEPRECATED - use admin wallet instead)"""
+        if not settings.ISSUER_SEED:
+            raise ValueError("ISSUER_SEED not configured. Please use admin wallet for token issuance.")
+        return Wallet.from_seed(settings.ISSUER_SEED)
+
+    def generate_currency_code(self, property_id: str) -> str:
+        """Generate unique currency code for property in XRPL hex format"""
+        # Convert to 40-character hex format (XRPL standard for custom currencies)
+        # Use first 8 chars of property_id (MongoDB ObjectId) to ensure uniqueness
+        # Format: PROP{first_8_chars_of_id}
+        property_suffix = str(property_id)[:8].upper()  # e.g., 68E769F9
+        base_code = f"PROP{property_suffix}"  # e.g., PROP68E769F9
+        # Convert to hex and pad to 40 characters (20 bytes)
+        hex_code = base_code.encode('ascii').hex().upper()
+        # Pad with zeros to reach exactly 40 characters
+        return hex_code.ljust(40, '0')
+
+    @monitor_performance("get_xrp_balance")
+    def get_xrp_balance(self, address: str) -> float:
+        try:
+            from xrpl.models.requests import AccountInfo
+            account_info_request = AccountInfo(account=address)
+            response = self.client.request(account_info_request)
+            
+            if response.is_successful() and 'account_data' in response.result:
+                balance_drops = response.result['account_data'].get('Balance', '0')
+                print(f"Debug: Retrieved balance {balance_drops} drops for address {address}")
+                return float(balance_drops) / 1_000_000
+            else:
+                print(f"Debug: Account not found or inactive: {address}")
+                return 0.0
+        except Exception as e:
+            print(f"Error getting XRP balance for {address}: {e}")
+            return 0.0
+
+    def calculate_xrp_cost(self, token_amount: int, price_per_token_aed: int) -> float:
+        """Calculate XRP cost for token purchase using live exchange rates.
+        
+        This now uses a real-time price oracle to fetch current XRP/AED rates
+        from multiple exchanges (CoinGecko, CoinDCX, Binance).
+        
+        Falls back to configured rate if live feeds are unavailable.
+        """
+        aed_cost = token_amount * price_per_token_aed
+        
+        if USE_LIVE_RATES:
+            try:
+                xrp_cost = price_oracle.get_aed_to_xrp(aed_cost)
+                print(f"[XRPL] Using live rate: {aed_cost} AED = {xrp_cost:.6f} XRP")
+                return max(xrp_cost, 0.000001)  # Minimum 1 drop
+            except Exception as e:
+                print(f"[XRPL] Error fetching live rate: {e}, using fallback")
+        
+        # Fallback to static rate
+        rate = max(settings.XRPL_RATE_AED_TO_XRP, 0.0000001)
+        xrp_cost = aed_cost * rate
+        print(f"[XRPL] Using static rate: {aed_cost} AED = {xrp_cost:.6f} XRP")
+        return max(xrp_cost, 0.000001)
+
+    @monitor_transaction("property_token_creation")
+    @monitor_performance("create_property_token")
+    def create_property_token(self, property_id: str, total_tokens: int, issuer_seed: str = None) -> Dict[str, Any]:
+        """Create and issue tokens for a property on XRPL"""
+        try:
+            if not issuer_seed:
+                issuer_seed = settings.ISSUER_SEED
+            if not issuer_seed:
+                raise ValueError("No issuer seed provided")
+            
+            issuer = Wallet.from_seed(issuer_seed)
+            currency_code = self.generate_currency_code(property_id)
+            
+            # Create token metadata record
+            return {
+                'success': True,
+                'currency_code': currency_code,
+                'issuer_address': issuer.classic_address,
+                'total_supply': total_tokens,
+                'property_id': property_id
+            }
+        except Exception as e:
+            print(f"Error creating property token: {e}")
+            return {'success': False, 'error': str(e)}
+
+    @monitor_transaction("trustline_setup")
+    @monitor_performance("setup_user_trustline")
+    def setup_user_trustline(self, user_seed: str, currency: str, issuer: str) -> Dict[str, Any]:
+        """Setup trustline for user to receive tokens - WITH RETRY"""
+        try:
+            def create_trustline_with_retry():
+                result = self.create_trustline(user_seed, currency, issuer)
+                return result
+            
+            result = retry_handler.execute_with_retry(
+                create_trustline_with_retry,
+                "Trustline Setup"
+            )
+            
+            return {
+                'success': True,
+                'tx_hash': result.get('tx_json', {}).get('hash') or result.get('hash'),
+                'result': result
+            }
+        except BlockchainError as e:
+            print(f"Trustline setup failed: {e.technical_msg}")
+            return {'success': False, 'error': e.user_msg}
+        except Exception as e:
+            print(f"Error setting up trustline: {e}")
+            return {'success': False, 'error': 'Failed to set up token trust line. Please try again.'}
+
+    @monitor_transaction("token_transfer_to_issuer")
+    @monitor_performance("transfer_tokens_to_issuer")
+    def transfer_tokens_to_issuer(self, seller_seed: str, currency: str, issuer: str, token_amount: int, issuer_seed: str = None) -> Dict[str, Any]:
+        """Transfer tokens from user back to the issuer (for sell-back functionality).
+        
+        IMPORTANT: When you send IOU tokens back to the issuer, they are effectively "burned" or "redeemed".
+        The issuer's balance of their own currency doesn't increase - the tokens simply cease to exist.
+        This is the correct behavior for a sell-back/redemption scenario.
+        
+        Args:
+            seller_seed: Seller's wallet seed
+            currency: Property token currency code
+            issuer: Issuer wallet address
+            token_amount: Number of tokens to transfer back
+            issuer_seed: Property's dedicated issuer seed (optional)
+        
+        Returns:
+            Dict with success status, transaction hash, and details
+        """
+        try:
+            if settings.XRPL_TOKEN_MODEL.upper() != 'IOU':
+                return {
+                    'success': False,
+                    'error': 'Token transfer requires IOU token model'
+                }
+            
+            seller = Wallet.from_seed(seller_seed)
+            
+            print(f"[XRPL] Burning {token_amount} tokens by sending to issuer {issuer}")
+            print(f"  Seller: {seller.classic_address}")
+            print(f"  Currency: {currency}")
+            print(f"  Note: Tokens sent to issuer are automatically burned/redeemed")
+            
+            # Create payment to send tokens back to issuer (this burns them)
+            # The issuer doesn't need a trustline to receive their own tokens
+            payment = Payment(
+                account=seller.classic_address,
+                destination=issuer,
+                amount=IssuedCurrencyAmount(
+                    currency=currency,
+                    issuer=issuer,
+                    value=str(token_amount)
+                ),
+                # Add Flags to allow partial payments if needed
+                # But for burning, this should work directly
+            )
+            
+            # Sign and submit transaction with retry logic
+            try:
+                signed_tx = autofill_and_sign(payment, self.client, seller)
+                result = submit_and_wait(signed_tx, self.client)
+                
+                # Check if transaction was successful
+                # For IOU burns, we expect tesSUCCESS
+                result_code = result.result.get('meta', {}).get('TransactionResult', result.result.get('engine_result', 'UNKNOWN'))
+                
+                if result.is_successful() or result_code == 'tesSUCCESS':
+                    tx_hash = result.result.get('hash')
+                    print(f"[XRPL] ✅ Tokens burned successfully. TX: {tx_hash}")
+                    print(f"  Result code: {result_code}")
+                    return {
+                        'success': True,
+                        'tx_hash': tx_hash,
+                        'token_amount': token_amount,
+                        'seller_address': seller.classic_address,
+                        'issuer_address': issuer,
+                        'action': 'burned',
+                        'result': result.result
+                    }
+                else:
+                    error_code = result.result.get('engine_result', 'UNKNOWN')
+                    error_msg = result.result.get('engine_result_message', 'Transaction failed')
+                    print(f"[XRPL] ❌ Token burn failed: {error_code} - {error_msg}")
+                    
+                    # Provide more helpful error messages
+                    if error_code == 'tecPATH_PARTIAL':
+                        return {
+                            'success': False,
+                            'error': 'Insufficient token balance or trustline issue. Please verify your token balance.'
+                        }
+                    elif error_code == 'tecUNFUNDED_PAYMENT':
+                        return {
+                            'success': False,
+                            'error': 'Insufficient XRP for transaction fee. Please add XRP to your wallet.'
+                        }
+                    else:
+                        return {
+                            'success': False,
+                            'error': f'Transaction failed: {error_msg}'
+                        }
+            
+            except Exception as tx_error:
+                print(f"[XRPL] Transaction submission error: {tx_error}")
+                return {
+                    'success': False,
+                    'error': f'Failed to submit transaction: {str(tx_error)}'
+                }
+        
+        except Exception as e:
+            print(f"[XRPL] Error in transfer_tokens_to_issuer: {e}")
+            return {'success': False, 'error': str(e)}
+
+    @monitor_transaction("token_purchase")
+    @monitor_performance("purchase_tokens_with_xrp")
+    def purchase_tokens_with_xrp(self, buyer_seed: str, currency: str, issuer: str, token_amount: int, xrp_cost: float, issuer_seed: str = None) -> Dict[str, Any]:
+        """Execute IOU purchase (Payment + TrustSet + IOU issuance).
+
+        Args:
+            buyer_seed: Buyer's wallet seed
+            currency: Property token currency code
+            issuer: Issuer wallet address
+            token_amount: Number of tokens to purchase
+            xrp_cost: Cost in XRP
+            issuer_seed: Property's dedicated issuer seed (NEW - per-property wallet)
+        
+        Uses IOU tokens for fractional real estate ownership.
+        """
+        try:
+            if settings.XRPL_TOKEN_MODEL.upper() != 'IOU':
+                return {
+                    'success': False,
+                    'error': 'IOU purchase path disabled (XRPL_TOKEN_MODEL must be IOU)'
+                }
+            
+            # Use property-specific issuer seed if provided, otherwise fall back to master
+            effective_issuer_seed = issuer_seed or settings.ISSUER_SEED
+            if effective_issuer_seed:
+                issuer_wallet = Wallet.from_seed(effective_issuer_seed)
+                print(f"[XRPL] Using {'property-specific' if issuer_seed else 'master'} issuer wallet: {issuer_wallet.classic_address}")
+            else:
+                return {
+                    'success': False,
+                    'error': 'No issuer seed available; cannot issue IOU tokens'
+                }
+            
+            buyer = Wallet.from_seed(buyer_seed)
+            
+            # Note: In this system, the buyer pays with AED (fiat) in their platform wallet.
+            # The XRP transaction is just for blockchain record-keeping and IOU token issuance.
+            # The buyer needs minimal XRP only for transaction fees, not the full purchase amount.
+            # The property wallet (issuer) needs sufficient XRP reserves to issue IOU tokens.
+            
+            print(f"=== EXECUTING TOKEN PURCHASE ===")
+            print(f"Buyer: {buyer.classic_address}")
+            print(f"Issuer: {issuer_wallet.classic_address}")
+            print(f"Token amount: {token_amount}")
+            print(f"XRP cost: {xrp_cost}")
+
+            # Step 1: OPTIONAL XRP payment to issuer (for blockchain record-keeping)
+            # Note: Users pay in AED via platform wallet. This XRP payment is optional
+            # and only executed if buyer has sufficient XRP balance.
+            payment_tx_hash = None
+            buyer_balance = self.get_xrp_balance(buyer.classic_address)
+            
+            if buyer_balance >= xrp_cost + 0.01:  # Has enough XRP for payment + fees
+                print(f"[OPTIONAL] Buyer has sufficient XRP ({buyer_balance} XRP), sending payment...")
+                def send_xrp_payment():
+                    from xrpl.transaction import sign_and_submit
+                    
+                    xrp_payment = Payment(
+                        account=buyer.classic_address,
+                        amount=str(int(xrp_to_drops(xrp_cost))),  # Convert to string drops
+                        destination=issuer_wallet.classic_address
+                    )
+                    
+                    # Use sign_and_submit method
+                    payment_result = sign_and_submit(xrp_payment, self.client, buyer)
+                    
+                    if payment_result.result.get('engine_result') != 'tesSUCCESS':
+                        raise Exception(f'XRP payment failed: {payment_result.result.get("engine_result_message", "Unknown error")}')
+                    
+                    return payment_result
+                
+                try:
+                    payment_result = retry_handler.execute_with_retry(
+                        send_xrp_payment,
+                        "XRP Payment to Issuer"
+                    )
+                    payment_tx_hash = payment_result.result.get('tx_json', {}).get('hash')
+                    print(f"✅ XRP payment successful: {payment_tx_hash}")
+                except BlockchainError as e:
+                    print(f"[WARNING] XRP payment failed (non-critical): {e.user_msg}")
+                    # Continue anyway - payment is optional
+            else:
+                print(f"[SKIP] Buyer has insufficient XRP ({buyer_balance} XRP < {xrp_cost + 0.01} XRP required)")
+                print(f"[INFO] Skipping XRP payment - user paid in AED via platform wallet")
+                print(f"[INFO] Will issue IOU tokens directly")
+
+            # Step 2: Setup trustline (only if not already present)
+            if not self._has_trustline(buyer.classic_address, currency, issuer):
+                trustline_result = self.setup_user_trustline(buyer_seed, currency, issuer)
+                if not trustline_result['success']:
+                    print(f"Trustline setup issue (continuing): {trustline_result}")
+            else:
+                print("Skipping trustline creation – already exists.")
+
+            # Step 3: Issuer sends tokens to buyer - WITH RETRY
+            def send_token_transfer():
+                result = self.issue_tokens(
+                    issuer_seed=effective_issuer_seed,
+                    destination=buyer.classic_address,
+                    currency=currency,
+                    amount=str(token_amount)
+                )
+                
+                if 'error' in result:
+                    raise Exception(f'Token issuance failed: {result["error"]}')
+                
+                return result
+            
+            try:
+                token_transfer = retry_handler.execute_with_retry(
+                    send_token_transfer,
+                    "Token Transfer to Buyer"
+                )
+            except BlockchainError as e:
+                return {
+                    'success': False,
+                    'error': e.user_msg
+                }
+            
+            token_tx_hash = token_transfer.get('tx_json', {}).get('hash') or token_transfer.get('hash')
+            print(f"✅ Token transfer successful: {token_tx_hash}")
+            
+            return {
+                'success': True,
+                'payment_tx_hash': payment_tx_hash,
+                'token_tx_hash': token_tx_hash,
+                'token_amount': token_amount,
+                'xrp_cost': xrp_cost,
+                'buyer_address': buyer.classic_address,
+                'issuer_address': issuer_wallet.classic_address
+            }
+            
+        except BlockchainError as e:
+            # Return user-friendly error message
+            return {'success': False, 'error': e.user_msg}
+        except Exception as e:
+            # Sanitize outward error while logging locally
+            print(f"Error in token purchase: {e}")
+            if settings.XRPL_NETWORK == 'testnet':
+                import traceback
+                traceback.print_exc()
+            return {'success': False, 'error': 'Transaction failed. Please try again or contact support.'}
+
+    @monitor_performance("get_user_token_balance")
+    def get_user_token_balance(self, address: str, currency: str, issuer: str) -> float:
+        """Get specific token balance for user"""
+        try:
+            token_balances = self.get_token_balances(address)
+            for token in token_balances:
+                if token['currency'] == currency and token['issuer'] == issuer:
+                    return float(token['balance'])
+            return 0.0
+        except Exception as e:
+            print(f"Error getting user token balance: {e}")
+            return 0.0
+
+    def verify_transaction_status(self, tx_hash: str) -> Dict[str, Any]:
+        """Verify if a transaction was successful"""
+        try:
+            tx_data = self.get_tx(tx_hash)
+            if 'TransactionResult' in tx_data:
+                success = tx_data['TransactionResult'] == 'tesSUCCESS'
+                return {
+                    'success': success,
+                    'status': tx_data['TransactionResult'],
+                    'tx_data': tx_data
+                }
+            return {'success': False, 'error': 'Transaction not found'}
+        except Exception as e:
+            return {'success': False, 'error': str(e)}
+
+    # Duplicate methods removed - using the ones defined below
+
+    @monitor_transaction("trustline_creation")
+    @monitor_performance("create_trustline")
+    def create_trustline(self, holder_seed: str, currency: str, issuer: str, limit_amount: str = "1000000000") -> Dict[str, Any]:
+        try:
+            from xrpl.transaction import sign_and_submit
+            holder = Wallet.from_seed(holder_seed)
+            trust_set_tx = TrustSet(
+                account=holder.classic_address,
+                limit_amount=IssuedCurrencyAmount(currency=currency, issuer=issuer, value=limit_amount),
+            )
+            result = sign_and_submit(trust_set_tx, self.client, holder)
+            return result.result
+        except Exception as e:
+            print(f"Error in create_trustline: {e}")
+            return {'error': str(e)}
+
+    def _has_trustline(self, address: str, currency: str, issuer: str) -> bool:
+        """Check if an account already has a trustline for the given currency/issuer."""
+        try:
+            from xrpl.models.requests import AccountLines
+            resp = self.client.request(AccountLines(account=address))
+            if not resp.is_successful():
+                return False
+            for line in resp.result.get('lines', []):
+                if line.get('currency') == currency and line.get('account') == issuer:
+                    return True
+            return False
+        except Exception:
+            return False
+
+    @monitor_transaction("token_issuance")
+    @monitor_performance("issue_tokens")
+    def issue_tokens(self, issuer_seed: str, destination: str, currency: str, amount: str) -> Dict[str, Any]:
+        try:
+            from xrpl.transaction import sign_and_submit
+            issuer = Wallet.from_seed(issuer_seed)
+            # Create IOU amount for the token
+            token_amount = IssuedCurrencyAmount(currency=currency, issuer=issuer.classic_address, value=amount)
+            payment = Payment(
+                account=issuer.classic_address,
+                amount=token_amount,
+                destination=destination,
+                send_max=token_amount,  # Required for currency conversion/token issuance
+            )
+            result = sign_and_submit(payment, self.client, issuer)
+            return result.result
+        except Exception as e:
+            print(f"Error in issue_tokens: {e}")
+            return {'error': str(e)}
+
+    # Note: Explicit on-ledger OfferCreate helper was removed as unused in app flows
+
+    @monitor_performance("get_token_balances")
+    def get_token_balances(self, address: str) -> List[Dict[str, Any]]:
+        """Get IOU token balances for an address"""
+        try:
+            account_lines_request = AccountLines(account=address)
+            response = self.client.request(account_lines_request)
+            
+            if response.is_successful() and 'lines' in response.result:
+                tokens = []
+                for line in response.result['lines']:
+                    tokens.append({
+                        'currency': line.get('currency', ''),
+                        'issuer': line.get('account', ''),
+                        'balance': float(line.get('balance', '0')),
+                        'limit': line.get('limit', '0')
+                    })
+                print(f"Debug: Found {len(tokens)} token balances for {address}")
+                return tokens
+            else:
+                print(f"Debug: No token lines found for {address}")
+                return []
+        except Exception as e:
+            print(f"Error getting token balances for {address}: {e}")
+            return []
+
+    def get_tx(self, tx_hash: str) -> Dict[str, Any]:
+        req = Tx(transaction=tx_hash)
+        resp = self.client.request(req)
+        return resp.result
+
+    @monitor_transaction("kyc_blockchain_write")
+    @monitor_performance("write_kyc_to_blockchain")
+    async def write_kyc_to_blockchain(self, kyc_data: Dict[str, Any], issuer_seed: str = None) -> Dict[str, Any]:
+        """
+        Write KYC approval data to XRP Ledger as permanent proof (ASYNC)
+        Stores user data + IPFS document hash in transaction memo field
+        
+        Args:
+            kyc_data: {
+                'user_id': str,
+                'name': str,
+                'email': str,
+                'phone': str,
+                'address': str,
+                'ipfs_hash': str,  # IPFS CID of KYC document
+                'approved_by': str,
+                'approved_at': str
+            }
+            issuer_seed: Admin/issuer wallet seed (defaults to settings.ISSUER_SEED)
+            
+        Returns:
+            {
+                'success': bool,
+                'tx_hash': str,  # XRP Ledger transaction hash
+                'explorer_url': str,  # Link to view on explorer
+                'memo_data': dict  # Data written to blockchain
+            }
+        """
+        try:
+            if not issuer_seed:
+                issuer_seed = settings.ISSUER_SEED
+            if not issuer_seed:
+                raise ValueError("No issuer seed provided for KYC blockchain write")
+            
+            issuer = Wallet.from_seed(issuer_seed)
+            
+            print(f"[XRPL-KYC] Writing KYC data to blockchain...")
+            print(f"[XRPL-KYC] User: {kyc_data.get('name')} ({kyc_data.get('email')})")
+            print(f"[XRPL-KYC] IPFS Hash: {kyc_data.get('ipfs_hash')}")
+            
+            # Prepare memo data (max 1KB for XRP Ledger)
+            memo_data = {
+                "type": "KYC_APPROVAL",
+                "user_id": kyc_data.get('user_id'),
+                "name": kyc_data.get('name'),
+                "email": kyc_data.get('email'),
+                "phone": kyc_data.get('phone'),
+                "address": kyc_data.get('address'),
+                "ipfs_doc": kyc_data.get('ipfs_hash'),
+                "approved_at": kyc_data.get('approved_at'),
+                "approved_by": kyc_data.get('approved_by')
+            }
+            
+            # Convert to JSON string and check size
+            import json
+            memo_json = json.dumps(memo_data, separators=(',', ':'))  # Compact JSON
+            memo_size = len(memo_json.encode('utf-8'))
+            
+            if memo_size > 1024:
+                print(f"[XRPL-KYC] [WARNING] Memo too large ({memo_size} bytes), truncating...")
+                # Remove address if too large
+                memo_data.pop('address', None)
+                memo_json = json.dumps(memo_data, separators=(',', ':'))
+            
+            print(f"[XRPL-KYC] Memo size: {len(memo_json.encode('utf-8'))} bytes")
+            
+            # Create AccountSet transaction with memo (no destination needed, just stores data on ledger)
+            from xrpl.models.transactions import Memo, AccountSet
+            from xrpl.transaction import sign_and_submit
+            
+            # Convert memo to hex (required by XRPL)
+            memo_hex = memo_json.encode('utf-8').hex().upper()
+            
+            # Use AccountSet transaction to write data to blockchain without sending XRP
+            account_set_tx = AccountSet(
+                account=issuer.classic_address,
+                memos=[
+                    Memo(
+                        memo_data=memo_hex,
+                        memo_type="4B59435F415050524F56414C".upper(),  # "KYC_APPROVAL" in hex
+                        memo_format="6A736F6E".upper()  # "json" in hex
+                    )
+                ]
+            )
+            
+            # Run blockchain submission in thread pool to avoid blocking event loop
+            # This allows async function to work with sync blockchain library
+            import asyncio
+            from concurrent.futures import ThreadPoolExecutor
+            
+            def _submit_transaction_sync():
+                """Synchronous transaction submission - runs in thread pool"""
+                from xrpl.transaction import submit_and_wait
+                
+                try:
+                    # Use submit_and_wait which handles signing automatically
+                    response = submit_and_wait(
+                        transaction=account_set_tx,
+                        client=self.client,
+                        wallet=issuer
+                    )
+                    return response
+                    
+                except Exception as submit_error:
+                    print(f"[XRPL-KYC] ERROR: Transaction submission failed: {submit_error}")
+                    raise Exception(f'Transaction signing failed: {str(submit_error)}')
+            
+            # Execute sync function in thread pool and await result
+            loop = asyncio.get_event_loop()
+            try:
+                result = await loop.run_in_executor(None, _submit_transaction_sync)
+            except Exception as exec_error:
+                return {
+                    'success': False,
+                    'error': f'Transaction execution failed: {str(exec_error)}'
+                }
+            
+            # submit_and_wait returns the full response with metadata
+            # Check if transaction was successful
+            if result.result.get('meta', {}).get('TransactionResult') == 'tesSUCCESS':
+                tx_hash = result.result.get('hash')
+                explorer_url = f"{settings.XRPL_EXPLORER_BASE}{tx_hash}"
+                
+                print(f"[XRPL-KYC] SUCCESS: KYC data written to blockchain!")
+                print(f"[XRPL-KYC] TX Hash: {tx_hash}")
+                print(f"[XRPL-KYC] Explorer: {explorer_url}")
+                
+                return {
+                    'success': True,
+                    'tx_hash': tx_hash,
+                    'explorer_url': explorer_url,
+                    'memo_data': memo_data,
+                    'ipfs_hash': kyc_data.get('ipfs_hash')
+                }
+            else:
+                error_code = result.result.get('meta', {}).get('TransactionResult', 'Unknown')
+                error_msg = result.result.get('engine_result_message', error_code)
+                print(f"[XRPL-KYC] ERROR: Transaction failed: {error_msg}")
+                return {
+                    'success': False,
+                    'error': f'Blockchain write failed: {error_msg}'
+                }
+                
+        except Exception as e:
+            print(f"[XRPL-KYC] ERROR: Error writing KYC to blockchain: {e}")
+            return {
+                'success': False,
+                'error': str(e)
+            }
+
+xrpl_service = XRPLService()

utils/blockchain_utils.py

@@ -0,0 +1,316 @@
+"""
+Blockchain Utilities
+====================
+Retry logic, error handling, and transaction monitoring for XRP Ledger operations.
+"""
+
+import time
+from typing import Dict, Any, Optional, Callable
+from xrpl.clients import JsonRpcClient
+from xrpl.models import Response
+from xrpl.wallet import Wallet
+from xrpl.transaction import submit_and_wait
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class BlockchainError(Exception):
+    """Custom exception for blockchain-related errors with user-friendly messages"""
+    def __init__(self, technical_msg: str, user_msg: str, retryable: bool = False):
+        self.technical_msg = technical_msg
+        self.user_msg = user_msg
+        self.retryable = retryable
+        super().__init__(technical_msg)
+
+
+class BlockchainRetryHandler:
+    """
+    Handles retry logic for blockchain transactions with exponential backoff.
+    """
+    
+    def __init__(
+        self,
+        max_retries: int = 3,
+        base_delay: float = 1.0,
+        max_delay: float = 10.0,
+        exponential_base: float = 2.0
+    ):
+        """
+        Initialize retry handler.
+        
+        Args:
+            max_retries: Maximum number of retry attempts
+            base_delay: Initial delay in seconds
+            max_delay: Maximum delay between retries
+            exponential_base: Base for exponential backoff calculation
+        """
+        self.max_retries = max_retries
+        self.base_delay = base_delay
+        self.max_delay = max_delay
+        self.exponential_base = exponential_base
+    
+    def _calculate_delay(self, attempt: int) -> float:
+        """Calculate delay with exponential backoff"""
+        delay = self.base_delay * (self.exponential_base ** attempt)
+        return min(delay, self.max_delay)
+    
+    def execute_with_retry(
+        self,
+        operation: Callable,
+        operation_name: str,
+        *args,
+        **kwargs
+    ) -> Any:
+        """
+        Execute a blockchain operation with retry logic.
+        
+        Args:
+            operation: Function to execute
+            operation_name: Human-readable name for logging
+            *args, **kwargs: Arguments to pass to operation
+            
+        Returns:
+            Result from the operation
+            
+        Raises:
+            BlockchainError: If all retries fail
+        """
+        last_exception = None
+        
+        for attempt in range(self.max_retries + 1):
+            try:
+                logger.info(f"[BLOCKCHAIN] Attempting {operation_name} (attempt {attempt + 1}/{self.max_retries + 1})")
+                result = operation(*args, **kwargs)
+                
+                if attempt > 0:
+                    logger.info(f"[BLOCKCHAIN] ✅ {operation_name} succeeded after {attempt} retries")
+                
+                return result
+                
+            except Exception as e:
+                last_exception = e
+                error_msg = str(e)
+                
+                # Check if error is retryable
+                is_retryable = self._is_retryable_error(error_msg)
+                
+                if not is_retryable or attempt >= self.max_retries:
+                    logger.error(f"[BLOCKCHAIN] [ERROR] {operation_name} failed permanently: {error_msg}")
+                    raise self._convert_to_user_friendly_error(e, operation_name)
+                
+                # Calculate delay and retry
+                delay = self._calculate_delay(attempt)
+                logger.warning(
+                    f"[BLOCKCHAIN] [WARNING] {operation_name} failed (attempt {attempt + 1}): {error_msg}. "
+                    f"Retrying in {delay:.1f}s..."
+                )
+                time.sleep(delay)
+        
+        # Should never reach here, but just in case
+        raise self._convert_to_user_friendly_error(
+            last_exception or Exception("Unknown error"),
+            operation_name
+        )
+    
+    def _is_retryable_error(self, error_msg: str) -> bool:
+        """
+        Determine if an error is retryable based on error message.
+        
+        Retryable errors include:
+        - Network issues
+        - Temporary server errors
+        - Sequence number mismatches
+        - Insufficient XRP (user might fund wallet)
+        
+        Non-retryable errors include:
+        - Invalid signatures
+        - Malformed transactions
+        - Insufficient token balance (not XRP)
+        """
+        error_lower = error_msg.lower()
+        
+        # Retryable errors
+        retryable_keywords = [
+            "timeout",
+            "connection",
+            "network",
+            "sequence",
+            "telINSUF_FEE_P",  # Fee too low (can retry with higher fee)
+            "tefPAST_SEQ",     # Sequence already used
+            "terQUEUED",       # Transaction queued
+        ]
+        
+        for keyword in retryable_keywords:
+            if keyword in error_lower:
+                return True
+        
+        # Non-retryable errors
+        non_retryable_keywords = [
+            "signature",
+            "malformed",
+            "tecUNFUNDED_PAYMENT",  # Insufficient token balance
+            "tecNO_DST",            # Destination doesn't exist
+            "tecNO_PERMISSION",     # Unauthorized
+            "temBAD_FEE",           # Invalid fee
+        ]
+        
+        for keyword in non_retryable_keywords:
+            if keyword in error_lower:
+                return False
+        
+        # Default: retry on unknown errors (conservative approach)
+        return True
+    
+    def _convert_to_user_friendly_error(
+        self,
+        exception: Exception,
+        operation_name: str
+    ) -> BlockchainError:
+        """
+        Convert technical blockchain errors to user-friendly messages.
+        """
+        error_msg = str(exception).lower()
+        
+        # Map technical errors to user messages
+        if "insuf" in error_msg and "fee" in error_msg:
+            return BlockchainError(
+                technical_msg=str(exception),
+                user_msg="Transaction fee too low. Please try again.",
+                retryable=True
+            )
+        
+        if "tecUNFUNDED_PAYMENT" in error_msg or "insufficient" in error_msg:
+            return BlockchainError(
+                technical_msg=str(exception),
+                user_msg="Insufficient balance to complete this transaction.",
+                retryable=False
+            )
+        
+        if "sequence" in error_msg:
+            return BlockchainError(
+                technical_msg=str(exception),
+                user_msg="Transaction ordering issue. Please try again.",
+                retryable=True
+            )
+        
+        if "timeout" in error_msg or "connection" in error_msg:
+            return BlockchainError(
+                technical_msg=str(exception),
+                user_msg="Network connection issue. Please check your internet and try again.",
+                retryable=True
+            )
+        
+        if "signature" in error_msg or "unauthorized" in error_msg:
+            return BlockchainError(
+                technical_msg=str(exception),
+                user_msg="Authentication failed. Please contact support.",
+                retryable=False
+            )
+        
+        if "tecNO_DST" in error_msg:
+            return BlockchainError(
+                technical_msg=str(exception),
+                user_msg="Recipient wallet not activated. Please ensure the wallet is funded with XRP.",
+                retryable=False
+            )
+        
+        # Default user-friendly message
+        return BlockchainError(
+            technical_msg=str(exception),
+            user_msg=f"Transaction failed: {operation_name}. Please try again or contact support if the issue persists.",
+            retryable=True
+        )
+
+
+class TransactionMonitor:
+    """
+    Monitor blockchain transaction status and provide detailed feedback.
+    """
+    
+    @staticmethod
+    def submit_and_monitor(
+        client: JsonRpcClient,
+        transaction: Any,
+        wallet: Wallet,
+        operation_name: str = "Transaction"
+    ) -> Response:
+        """
+        Submit a transaction and monitor its status with detailed logging.
+        
+        Args:
+            client: XRP Ledger client
+            transaction: Transaction to submit
+            wallet: Wallet to sign with
+            operation_name: Human-readable operation name
+            
+        Returns:
+            Transaction response
+            
+        Raises:
+            BlockchainError: If transaction fails
+        """
+        logger.info(f"[TX_MONITOR] 📤 Submitting {operation_name}...")
+        logger.debug(f"[TX_MONITOR] Transaction details: {transaction.to_dict()}")
+        
+        try:
+            # Submit and wait for validation
+            response = submit_and_wait(transaction, client, wallet)
+            
+            # Check result
+            result = response.result
+            metadata = result.get("meta", {})
+            tx_result = metadata.get("TransactionResult", "unknown")
+            
+            logger.info(f"[TX_MONITOR] Transaction hash: {result.get('hash', 'N/A')}")
+            logger.info(f"[TX_MONITOR] Result code: {tx_result}")
+            
+            # Success codes start with "tes" (tesSUCCESS)
+            if tx_result.startswith("tes"):
+                logger.info(f"[TX_MONITOR] ✅ {operation_name} succeeded")
+                return response
+            
+            # Error codes
+            error_msg = f"{operation_name} failed with code: {tx_result}"
+            logger.error(f"[TX_MONITOR] [ERROR] {error_msg}")
+            
+            raise BlockchainError(
+                technical_msg=error_msg,
+                user_msg=TransactionMonitor._get_user_message_for_code(tx_result),
+                retryable=tx_result.startswith("ter")  # "ter" = retry, "tec" = claimed fee, "tem"/"tef" = malformed
+            )
+            
+        except BlockchainError:
+            raise
+        except Exception as e:
+            logger.error(f"[TX_MONITOR] [ERROR] {operation_name} exception: {str(e)}")
+            raise BlockchainError(
+                technical_msg=str(e),
+                user_msg=f"{operation_name} failed. Please try again.",
+                retryable=True
+            )
+    
+    @staticmethod
+    def _get_user_message_for_code(result_code: str) -> str:
+        """Map XRP Ledger result codes to user-friendly messages"""
+        
+        code_map = {
+            "tecUNFUNDED_PAYMENT": "Insufficient balance to complete this transaction.",
+            "tecNO_DST": "Destination wallet not found or not activated.",
+            "tecNO_LINE": "Trust line not established. Please enable the token first.",
+            "tecNO_PERMISSION": "You don't have permission to perform this action.",
+            "tecINSUFFICIENT_RESERVE": "Insufficient XRP reserve. You need at least 10 XRP in your wallet.",
+            "tecPATH_DRY": "No available path for this transaction.",
+            "terQUEUED": "Transaction queued. Please wait a moment and try again.",
+            "tefPAST_SEQ": "Transaction already processed. Please refresh and check your balance.",
+        }
+        
+        return code_map.get(result_code, f"Transaction failed with code {result_code}. Please contact support.")
+
+
+# Global retry handler instance
+retry_handler = BlockchainRetryHandler(
+    max_retries=3,
+    base_delay=1.0,
+    max_delay=10.0
+)

utils/cache.py

@@ -0,0 +1,231 @@
+"""
+Redis Caching Utility
+Provides caching decorator and Redis connection management
+"""
+import json
+import hashlib
+from functools import wraps
+from typing import Optional, Any
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Redis client (lazy initialization)
+_redis_client: Optional[Any] = None
+
+
+def get_redis_client():
+    """Get Redis client instance (singleton with graceful fallback)"""
+    global _redis_client
+    
+    if _redis_client is None:
+        try:
+            from redis import Redis
+            _redis_client = Redis(
+                host='localhost',
+                port=6379,
+                db=0,
+                decode_responses=True,
+                socket_connect_timeout=2,
+                socket_timeout=2
+            )
+            # Test connection
+            _redis_client.ping()
+            logger.info("[CACHE] [SUCCESS] Redis connection established")
+        except Exception as e:
+            logger.warning(f"[CACHE] Redis not available: {e}. Caching disabled.")
+            _redis_client = False  # Mark as unavailable to avoid retries
+    
+    return _redis_client if _redis_client is not False else None
+
+
+def generate_cache_key(func_name: str, args: tuple, kwargs: dict) -> str:
+    """Generate a unique cache key from function name and arguments"""
+    # Convert args and kwargs to a stable string representation
+    args_str = str(args)
+    kwargs_str = str(sorted(kwargs.items()))
+    combined = f"{func_name}:{args_str}:{kwargs_str}"
+    
+    # Hash for shorter keys (avoid Redis key length limits)
+    key_hash = hashlib.md5(combined.encode()).hexdigest()
+    return f"cache:{func_name}:{key_hash}"
+
+
+def cache(ttl: int = 300):
+    """
+    Caching decorator with Redis backend
+    
+    Args:
+        ttl: Time to live in seconds (default 5 minutes)
+    
+    Usage:
+        @cache(ttl=60)
+        def expensive_function(arg1, arg2):
+            # ... expensive operation
+            return result
+    """
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            redis_client = get_redis_client()
+            
+            # If Redis is not available, execute function normally
+            if redis_client is None:
+                return func(*args, **kwargs)
+            
+            try:
+                # Generate cache key
+                cache_key = generate_cache_key(func.__name__, args, kwargs)
+                
+                # Try to get from cache
+                cached_value = redis_client.get(cache_key)
+                
+                if cached_value is not None:
+                    logger.debug(f"[CACHE] HIT: {func.__name__}")
+                    return json.loads(cached_value)
+                
+                # Cache miss - execute function
+                logger.debug(f"[CACHE] MISS: {func.__name__}")
+                result = func(*args, **kwargs)
+                
+                # Store in cache
+                try:
+                    serialized = json.dumps(result, default=str)
+                    redis_client.setex(cache_key, ttl, serialized)
+                except (TypeError, ValueError) as e:
+                    logger.warning(f"[CACHE] Failed to serialize result for {func.__name__}: {e}")
+                
+                return result
+                
+            except Exception as e:
+                # If caching fails, log and execute function normally
+                logger.warning(f"[CACHE] Error in cache decorator for {func.__name__}: {e}")
+                return func(*args, **kwargs)
+        
+        return wrapper
+    return decorator
+
+
+def invalidate_cache(pattern: str = None):
+    """
+    Invalidate cache entries matching pattern
+    
+    Args:
+        pattern: Redis key pattern (e.g., "cache:list_properties:*")
+                If None, clears all cache entries
+    """
+    redis_client = get_redis_client()
+    
+    if redis_client is None:
+        return
+    
+    try:
+        if pattern:
+            keys = redis_client.keys(pattern)
+            if keys:
+                redis_client.delete(*keys)
+                logger.info(f"[CACHE] Invalidated {len(keys)} keys matching '{pattern}'")
+        else:
+            redis_client.flushdb()
+            logger.info("[CACHE] Cleared all cache entries")
+    except Exception as e:
+        logger.error(f"[CACHE] Error invalidating cache: {e}")
+
+
+def cache_property_data(property_id: str, data: dict, ttl: int = 300):
+    """Cache property data manually (for fine-grained control)"""
+    redis_client = get_redis_client()
+    
+    if redis_client is None:
+        return
+    
+    try:
+        cache_key = f"cache:property:{property_id}"
+        redis_client.setex(cache_key, ttl, json.dumps(data, default=str))
+        logger.debug(f"[CACHE] Cached property data: {property_id}")
+    except Exception as e:
+        logger.warning(f"[CACHE] Failed to cache property data: {e}")
+
+
+def get_cached_property(property_id: str) -> Optional[dict]:
+    """Get cached property data"""
+    redis_client = get_redis_client()
+    
+    if redis_client is None:
+        return None
+    
+    try:
+        cache_key = f"cache:property:{property_id}"
+        cached = redis_client.get(cache_key)
+        if cached:
+            return json.loads(cached)
+    except Exception as e:
+        logger.warning(f"[CACHE] Failed to get cached property: {e}")
+    
+    return None
+
+
+def cache_xrp_balance(address: str, balance: float, ttl: int = 300):
+    """Cache XRP balance for an address"""
+    redis_client = get_redis_client()
+    
+    if redis_client is None:
+        return
+    
+    try:
+        cache_key = f"cache:xrp_balance:{address}"
+        redis_client.setex(cache_key, ttl, str(balance))
+        logger.debug(f"[CACHE] Cached XRP balance for {address}: {balance}")
+    except Exception as e:
+        logger.warning(f"[CACHE] Failed to cache XRP balance: {e}")
+
+
+def get_cached_xrp_balance(address: str) -> Optional[float]:
+    """Get cached XRP balance"""
+    redis_client = get_redis_client()
+    
+    if redis_client is None:
+        return None
+    
+    try:
+        cache_key = f"cache:xrp_balance:{address}"
+        cached = redis_client.get(cache_key)
+        if cached:
+            return float(cached)
+    except Exception as e:
+        logger.warning(f"[CACHE] Failed to get cached XRP balance: {e}")
+    
+    return None
+
+
+def cache_token_balance(xrp_address: str, currency_code: str, issuer_address: str, balance: float, ttl: int = 300):
+    """Cache IOU token balance for an address"""
+    redis_client = get_redis_client()
+    
+    if redis_client is None:
+        return
+    
+    try:
+        cache_key = f"cache:token_balance:{xrp_address}:{currency_code}:{issuer_address}"
+        redis_client.setex(cache_key, ttl, str(balance))
+        logger.debug(f"[CACHE] Cached token balance for {xrp_address}: {balance} {currency_code}")
+    except Exception as e:
+        logger.warning(f"[CACHE] Failed to cache token balance: {e}")
+
+
+def get_cached_token_balance(xrp_address: str, currency_code: str, issuer_address: str) -> Optional[float]:
+    """Get cached IOU token balance"""
+    redis_client = get_redis_client()
+    
+    if redis_client is None:
+        return None
+    
+    try:
+        cache_key = f"cache:token_balance:{xrp_address}:{currency_code}:{issuer_address}"
+        cached = redis_client.get(cache_key)
+        if cached:
+            return float(cached)
+    except Exception as e:
+        logger.warning(f"[CACHE] Failed to get cached token balance: {e}")
+    
+    return None

utils/country_codes.py

@@ -0,0 +1,81 @@
+"""
+Country codes data and utility functions for international phone numbers
+"""
+
+# List of countries with their codes and ISO codes
+COUNTRIES = [
+    {"name": "United States", "code": "+1", "iso": "US", "flag": "🇺🇸"},
+    {"name": "United Kingdom", "code": "+44", "iso": "GB", "flag": "🇬🇧"},
+    {"name": "India", "code": "+91", "iso": "IN", "flag": "🇮🇳"},
+    {"name": "United Arab Emirates", "code": "+971", "iso": "AE", "flag": "🇦🇪"},
+    {"name": "Canada", "code": "+1", "iso": "CA", "flag": "🇨🇦"},
+    {"name": "Australia", "code": "+61", "iso": "AU", "flag": "🇦🇺"},
+    {"name": "Germany", "code": "+49", "iso": "DE", "flag": "🇩🇪"},
+    {"name": "France", "code": "+33", "iso": "FR", "flag": "🇫🇷"},
+    {"name": "Spain", "code": "+34", "iso": "ES", "flag": "🇪🇸"},
+    {"name": "Italy", "code": "+39", "iso": "IT", "flag": "🇮🇹"},
+    {"name": "China", "code": "+86", "iso": "CN", "flag": "🇨🇳"},
+    {"name": "Japan", "code": "+81", "iso": "JP", "flag": "🇯🇵"},
+    {"name": "South Korea", "code": "+82", "iso": "KR", "flag": "🇰🇷"},
+    {"name": "Singapore", "code": "+65", "iso": "SG", "flag": "🇸🇬"},
+    {"name": "Hong Kong", "code": "+852", "iso": "HK", "flag": "🇭🇰"},
+    {"name": "Saudi Arabia", "code": "+966", "iso": "SA", "flag": "🇸🇦"},
+    {"name": "Brazil", "code": "+55", "iso": "BR", "flag": "🇧🇷"},
+    {"name": "Mexico", "code": "+52", "iso": "MX", "flag": "🇲🇽"},
+    {"name": "South Africa", "code": "+27", "iso": "ZA", "flag": "🇿🇦"},
+    {"name": "Nigeria", "code": "+234", "iso": "NG", "flag": "🇳🇬"},
+    {"name": "Egypt", "code": "+20", "iso": "EG", "flag": "🇪🇬"},
+    {"name": "Pakistan", "code": "+92", "iso": "PK", "flag": "🇵🇰"},
+    {"name": "Bangladesh", "code": "+880", "iso": "BD", "flag": "🇧🇩"},
+    {"name": "Indonesia", "code": "+62", "iso": "ID", "flag": "🇮🇩"},
+    {"name": "Malaysia", "code": "+60", "iso": "MY", "flag": "🇲🇾"},
+    {"name": "Philippines", "code": "+63", "iso": "PH", "flag": "🇵🇭"},
+    {"name": "Thailand", "code": "+66", "iso": "TH", "flag": "🇹🇭"},
+    {"name": "Vietnam", "code": "+84", "iso": "VN", "flag": "🇻🇳"},
+    {"name": "Turkey", "code": "+90", "iso": "TR", "flag": "🇹🇷"},
+    {"name": "Russia", "code": "+7", "iso": "RU", "flag": "🇷🇺"},
+    {"name": "Poland", "code": "+48", "iso": "PL", "flag": "🇵🇱"},
+    {"name": "Netherlands", "code": "+31", "iso": "NL", "flag": "🇳🇱"},
+    {"name": "Belgium", "code": "+32", "iso": "BE", "flag": "🇧🇪"},
+    {"name": "Sweden", "code": "+46", "iso": "SE", "flag": "🇸🇪"},
+    {"name": "Norway", "code": "+47", "iso": "NO", "flag": "🇳🇴"},
+    {"name": "Denmark", "code": "+45", "iso": "DK", "flag": "🇩🇰"},
+    {"name": "Switzerland", "code": "+41", "iso": "CH", "flag": "🇨🇭"},
+    {"name": "Austria", "code": "+43", "iso": "AT", "flag": "🇦🇹"},
+    {"name": "Ireland", "code": "+353", "iso": "IE", "flag": "🇮🇪"},
+    {"name": "New Zealand", "code": "+64", "iso": "NZ", "flag": "🇳🇿"},
+]
+
+
+def get_country_by_code(code: str):
+    """Get country data by phone code"""
+    for country in COUNTRIES:
+        if country["code"] == code:
+            return country
+    return None
+
+
+def get_country_by_iso(iso: str):
+    """Get country data by ISO code"""
+    for country in COUNTRIES:
+        if country["iso"] == iso:
+            return country
+    return None
+
+
+def get_country_by_name(name: str):
+    """Get country data by country name"""
+    for country in COUNTRIES:
+        if country["name"].lower() == name.lower():
+            return country
+    return None
+
+
+def validate_country_code(code: str) -> bool:
+    """Validate if the country code exists"""
+    return any(country["code"] == code for country in COUNTRIES)
+
+
+def get_all_countries():
+    """Return all countries"""
+    return COUNTRIES

utils/crypto_utils.py

@@ -0,0 +1,98 @@
+"""Cryptographic utilities for secret encryption/decryption.
+
+Provides Fernet symmetric authenticated encryption over wallet seeds.
+Secrets are stored with a sentinel prefix:
+  ENC::<base64token>
+If a value does not start with ENC:: it is treated as legacy (plain/base64) and
+should be migrated by the caller.
+"""
+from __future__ import annotations
+import base64
+import os
+from typing import Optional
+from cryptography.fernet import Fernet, InvalidToken
+
+_FERNET: Optional[Fernet] = None
+_PREFIX = "ENC::"
+
+
+def _derive_or_load_key(raw: Optional[str]) -> Optional[bytes]:
+    """Return a 32-byte urlsafe base64-encoded key for Fernet or None.
+
+    Accepts either:
+      * Already a 44 char Fernet key (base64 urlsafe) -> used directly
+      * 32 raw bytes in base64 (decode then re-encode to urlsafe) (len 43/44)
+      * Hex string of length 64 -> interpreted as 32 bytes then base64 encoded
+    """
+    if not raw:
+        return None
+    raw = raw.strip()
+    # Direct Fernet key
+    if len(raw) in (43, 44) and all(c.isalnum() or c in ("-", "_") for c in raw.rstrip("=")):
+        try:
+            base64.urlsafe_b64decode(raw + ("=" * (-len(raw) % 4)))
+            return raw.encode()
+        except Exception:
+            pass
+    # Hex 64 -> bytes
+    if len(raw) == 64:
+        try:
+            b = bytes.fromhex(raw)
+            return base64.urlsafe_b64encode(b)
+        except ValueError:
+            pass
+    # Fallback: if it decodes from base64 to 32 bytes use it
+    try:
+        b = base64.b64decode(raw + ("=" * (-len(raw) % 4)))
+        if len(b) == 32:
+            return base64.urlsafe_b64encode(b)
+    except Exception:
+        pass
+    raise ValueError("ENCRYPTION_KEY provided is not a valid 32-byte or Fernet key material")
+
+
+def get_fernet(encryption_key: Optional[str]) -> Optional[Fernet]:
+    global _FERNET
+    if _FERNET is not None:
+        return _FERNET
+    key_bytes = _derive_or_load_key(encryption_key)
+    if not key_bytes:
+        return None
+    _FERNET = Fernet(key_bytes)
+    return _FERNET
+
+
+def encrypt_secret(plaintext: str, encryption_key: Optional[str]) -> str:
+    """Encrypt a secret; returns ENC::<token>. If key missing returns original (no prefix)."""
+    if not plaintext:
+        return plaintext
+    f = get_fernet(encryption_key)
+    if not f:
+        return plaintext  # no encryption key configured
+    token = f.encrypt(plaintext.encode()).decode()
+    return f"{_PREFIX}{token}"
+
+
+def is_encrypted(value: str) -> bool:
+    return isinstance(value, str) and value.startswith(_PREFIX)
+
+
+def decrypt_secret(value: Optional[str], encryption_key: Optional[str]) -> Optional[str]:
+    if not value:
+        return value
+    if not is_encrypted(value):
+        # Legacy base64 encoded value - decode it
+        try:
+            return base64.b64decode(value).decode()
+        except Exception:
+            # If decode fails, return as-is (might be plain text)
+            return value
+    token = value[len(_PREFIX):]
+    f = get_fernet(encryption_key)
+    if not f:
+        return value  # cannot decrypt without key
+    try:
+        return f.decrypt(token.encode()).decode()
+    except InvalidToken:
+        # Return sentinel text to signal decryption issue without raising
+        return None

utils/email_service.py

@@ -0,0 +1,186 @@
+"""
+Email Service for OTP Verification
+Sends OTP emails using SMTP (Gmail)
+"""
+import smtplib
+import random
+import string
+from email.mime.text import MIMEText
+from email.mime.multipart import MIMEMultipart
+from datetime import datetime, timedelta
+from typing import Optional
+import logging
+
+logger = logging.getLogger(__name__)
+
+# SMTP Configuration
+SMTP_SERVER = "smtp.gmail.com"
+SMTP_PORT = 587
+SMTP_EMAIL = "jigneshprajapati.igenerate@gmail.com"
+SMTP_PASSWORD = "vtvgwntllsfjqykx"  # NOTE: For Gmail, you MUST use an App Password!
+# To generate an App Password:
+# 1. Go to Google Account settings
+# 2. Security > 2-Step Verification (enable if not already)
+# 3. App passwords > Select app: Mail, Select device: Other (Custom name)
+# 4. Generate and use that 16-character password here
+
+def generate_otp(length: int = 6) -> str:
+    """Generate a random 6-digit OTP"""
+    return ''.join(random.choices(string.digits, k=length))
+
+
+def send_otp_email(to_email: str, otp: str, purpose: str = "login") -> bool:
+    """
+    Send OTP via email
+    
+    Args:
+        to_email: Recipient email address
+        otp: 6-digit OTP code
+        purpose: 'login' or 'registration'
+    
+    Returns:
+        bool: True if email sent successfully, False otherwise
+    """
+    try:
+        # Create message
+        msg = MIMEMultipart('alternative')
+        msg['From'] = SMTP_EMAIL
+        msg['To'] = to_email
+        msg['Subject'] = f"Your OTP for {purpose.capitalize()} - Real Estate Platform"
+        
+        # HTML email body with AtriumChain brand theme - Clean, Professional Design
+        html_body = f"""
+        <!DOCTYPE html>
+        <html>
+        <head>
+            <meta charset="UTF-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1.0">
+            <style>
+                body {{ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Inter', Arial, sans-serif; background-color: #F5F6F8; margin: 0; padding: 0; }}
+                .wrapper {{ max-width: 600px; margin: 40px auto; }}
+                .container {{ background: #FFFFFF; border-radius: 24px; overflow: hidden; box-shadow: 0 4px 24px rgba(15, 16, 19, 0.08); border: 1px solid #E5E7EB; }}
+                .header {{ background: #0F1013; padding: 48px 40px; text-align: center; }}
+                .logo {{ font-size: 28px; font-weight: 800; color: #FFFFFF; letter-spacing: -0.5px; margin: 0; }}
+                .logo span {{ color: #BBD2FB; }}
+                .tagline {{ color: rgba(255,255,255,0.7); font-size: 14px; margin: 8px 0 0 0; font-weight: 400; }}
+                .content {{ padding: 48px 40px; }}
+                .greeting {{ color: #0F1013; font-size: 20px; font-weight: 600; margin: 0 0 16px 0; }}
+                .message {{ color: #6B7280; font-size: 15px; line-height: 1.7; margin: 0 0 32px 0; }}
+                .otp-container {{ background: #F5F6F8; border: 2px solid #E5E7EB; border-radius: 16px; padding: 32px; text-align: center; margin: 32px 0; }}
+                .otp-label {{ margin: 0 0 12px 0; color: #6B7280; font-size: 12px; text-transform: uppercase; letter-spacing: 1.5px; font-weight: 600; }}
+                .otp-code {{ font-size: 44px; font-weight: 800; color: #0F1013; letter-spacing: 8px; margin: 0; font-family: 'SF Mono', 'Roboto Mono', monospace; }}
+                .otp-validity {{ margin: 16px 0 0 0; color: #6B7280; font-size: 13px; display: flex; align-items: center; justify-content: center; gap: 6px; }}
+                .otp-validity svg {{ width: 14px; height: 14px; }}
+                .security-box {{ background: #FEF3C7; border-left: 4px solid #F59E0B; border-radius: 0 12px 12px 0; padding: 20px 24px; margin: 32px 0; }}
+                .security-title {{ color: #92400E; font-weight: 700; font-size: 14px; margin: 0 0 12px 0; display: flex; align-items: center; gap: 8px; }}
+                .security-title svg {{ width: 16px; height: 16px; }}
+                .security-list {{ color: #78350F; font-size: 13px; line-height: 1.8; margin: 0; padding-left: 20px; }}
+                .security-list li {{ margin: 4px 0; }}
+                .divider {{ height: 1px; background: #E5E7EB; margin: 32px 0; }}
+                .footer-text {{ color: #6B7280; font-size: 14px; line-height: 1.6; margin: 0; }}
+                .signature {{ color: #0F1013; font-weight: 600; margin: 16px 0 0 0; }}
+                .footer {{ background: #F9FAFB; padding: 32px 40px; text-align: center; border-top: 1px solid #E5E7EB; }}
+                .footer p {{ color: #9CA3AF; font-size: 12px; margin: 4px 0; line-height: 1.5; }}
+                .footer-links {{ margin-top: 16px; }}
+                .footer-link {{ color: #0F1013; text-decoration: none; font-size: 12px; font-weight: 500; }}
+                .footer-link:hover {{ text-decoration: underline; }}
+                .brand-badge {{ display: inline-flex; align-items: center; gap: 8px; background: #0F1013; color: #FFFFFF; padding: 8px 16px; border-radius: 100px; font-size: 12px; font-weight: 600; margin-top: 20px; }}
+                .brand-badge svg {{ width: 16px; height: 16px; }}
+            </style>
+        </head>
+        <body>
+            <div class="wrapper">
+                <div class="container">
+                    <div class="header">
+                        <h1 class="logo">Atrium<span>Chain</span></h1>
+                        <p class="tagline">Blockchain-Powered Real Estate Investment</p>
+                    </div>
+                    <div class="content">
+                        <p class="greeting">Hello there!</p>
+                        <p class="message">You've requested to <strong style="color: #0F1013;">{purpose}</strong> to your AtriumChain account. Use the verification code below to complete your authentication:</p>
+                        
+                        <div class="otp-container">
+                            <p class="otp-label">Your Verification Code</p>
+                            <p class="otp-code">{otp}</p>
+                            <p class="otp-validity">
+                                <svg fill="none" viewBox="0 0 24 24" stroke="#6B7280"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 8v4l3 3m6-3a9 9 0 11-18 0 9 9 0 0118 0z"/></svg>
+                                Valid for 10 minutes
+                            </p>
+                        </div>
+                        
+                        <div class="security-box">
+                            <div class="security-title">
+                                <svg fill="none" viewBox="0 0 24 24" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"/></svg>
+                                Security Notice
+                            </div>
+                            <ul class="security-list">
+                                <li>This code expires in <strong>10 minutes</strong></li>
+                                <li>Never share this code with anyone</li>
+                                <li>AtriumChain will never ask for your OTP</li>
+                                <li>If you didn't request this, ignore this email</li>
+                            </ul>
+                        </div>
+                        
+                        <div class="divider"></div>
+                        
+                        <p class="footer-text">Need help? Contact our support team anytime. We're here to assist you with your property investment journey.</p>
+                        <p class="signature">The AtriumChain Team</p>
+                        
+                        <div style="text-align: center;">
+                            <div class="brand-badge">
+                                <svg fill="none" viewBox="0 0 24 24" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 12l2 2 4-4m5.618-4.016A11.955 11.955 0 0112 2.944a11.955 11.955 0 01-8.618 3.04A12.02 12.02 0 003 9c0 5.591 3.824 10.29 9 11.622 5.176-1.332 9-6.03 9-11.622 0-1.042-.133-2.052-.382-3.016z"/></svg>
+                                Secured by XRP Blockchain
+                            </div>
+                        </div>
+                    </div>
+                    <div class="footer">
+                        <p>This is an automated message from AtriumChain.</p>
+                        <p>© 2024 AtriumChain. All rights reserved.</p>
+                        <div class="footer-links">
+                            <a href="#" class="footer-link">Privacy Policy</a> &nbsp;•&nbsp;
+                            <a href="#" class="footer-link">Terms of Service</a> &nbsp;•&nbsp;
+                            <a href="#" class="footer-link">Help Center</a>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </body>
+        </html>
+        """
+        
+        # Attach HTML body
+        msg.attach(MIMEText(html_body, 'html'))
+        
+        # Connect to SMTP server and send email
+        logger.info(f"[EMAIL] Connecting to SMTP server: {SMTP_SERVER}:{SMTP_PORT}")
+        with smtplib.SMTP(SMTP_SERVER, SMTP_PORT) as server:
+            server.starttls()  # Secure the connection
+            logger.info(f"[EMAIL] Logging in as: {SMTP_EMAIL}")
+            server.login(SMTP_EMAIL, SMTP_PASSWORD)
+            logger.info(f"[EMAIL] Sending OTP to: {to_email}")
+            server.send_message(msg)
+        
+        logger.info(f"[EMAIL] [SUCCESS] OTP email sent successfully to {to_email}")
+        return True
+        
+    except smtplib.SMTPAuthenticationError as e:
+        logger.error(f"[EMAIL] [ERROR] SMTP Authentication failed: {e}")
+        logger.error("[EMAIL] [WARNING] IMPORTANT: For Gmail, you MUST use an App Password!")
+        logger.error("[EMAIL] Steps to generate App Password:")
+        logger.error("[EMAIL] 1. Go to https://myaccount.google.com/security")
+        logger.error("[EMAIL] 2. Enable 2-Step Verification if not already enabled")
+        logger.error("[EMAIL] 3. Go to App passwords section")
+        logger.error("[EMAIL] 4. Generate a new app password for 'Mail' application")
+        logger.error("[EMAIL] 5. Use that 16-character password in email_service.py")
+        return False
+    except smtplib.SMTPException as e:
+        logger.error(f"[EMAIL] [ERROR] SMTP error: {e}")
+        return False
+    except Exception as e:
+        logger.error(f"[EMAIL] [ERROR] Failed to send OTP email: {e}")
+        return False
+
+
+def get_otp_expiry() -> datetime:
+    """Get OTP expiry time (10 minutes from now)"""
+    return datetime.utcnow() + timedelta(minutes=10)

utils/fingerprint.py

@@ -0,0 +1,50 @@
+"""
+Device Fingerprinting Utilities
+Generates unique device fingerprints from request headers for session management
+"""
+import hashlib
+from fastapi import Request
+from typing import Optional
+
+
+def generate_device_fingerprint(request: Request, custom_fingerprint: Optional[str] = None) -> str:
+    """
+    Generate a unique device fingerprint from request headers
+    
+    Args:
+        request: FastAPI Request object
+        custom_fingerprint: Optional custom fingerprint from frontend (more reliable)
+    
+    Returns:
+        SHA256 hash of device characteristics
+    """
+    if custom_fingerprint:
+        # Use frontend-generated fingerprint if available (more accurate)
+        return hashlib.sha256(custom_fingerprint.encode()).hexdigest()
+    
+    # Fallback: Generate from server-side headers
+    user_agent = request.headers.get("user-agent", "unknown")
+    accept_language = request.headers.get("accept-language", "unknown")
+    accept_encoding = request.headers.get("accept-encoding", "unknown")
+    
+    # Combine characteristics
+    fingerprint_data = f"{user_agent}|{accept_language}|{accept_encoding}"
+    
+    # Return SHA256 hash
+    return hashlib.sha256(fingerprint_data.encode()).hexdigest()
+
+
+def generate_session_id(user_id: str, token: str, fingerprint: str) -> str:
+    """
+    Generate a unique session ID
+    
+    Args:
+        user_id: User's unique identifier
+        token: JWT token
+        fingerprint: Device fingerprint
+    
+    Returns:
+        SHA256 hash of combined data
+    """
+    session_data = f"{user_id}|{token}|{fingerprint}"
+    return hashlib.sha256(session_data.encode()).hexdigest()

utils/logger.py

@@ -0,0 +1,349 @@
+"""
+Enhanced logging system for real estate tokenization platform
+Provides structured logging with performance monitoring and transaction tracking
+"""
+
+import logging
+import logging.handlers
+import time
+import functools
+from typing import Any, Dict, Optional
+from pathlib import Path
+from datetime import datetime
+import json
+
+from config import settings
+
+
+class PerformanceLogger:
+    """Performance monitoring logger for slow operations"""
+    
+    @staticmethod
+    def log_slow_operation(operation_name: str, duration: float, details: Dict[str, Any] = None):
+        """Log operations that exceed the threshold"""
+        if duration > settings.SLOW_QUERY_THRESHOLD:
+            logger = logging.getLogger("performance")
+            logger.warning(
+                f"SLOW_OPERATION: {operation_name} took {duration:.3f}s",
+                extra={
+                    "operation": operation_name,
+                    "duration": duration,
+                    "threshold": settings.SLOW_QUERY_THRESHOLD,
+                    "details": details or {}
+                }
+            )
+
+
+class TransactionLogger:
+    """Blockchain transaction monitoring and logging"""
+    
+    @staticmethod
+    def log_transaction_start(tx_type: str, user_id: str, property_id: str = None, amount: float = None):
+        """Log the start of a blockchain transaction"""
+        logger = logging.getLogger("transactions")
+        logger.info(
+            f"TRANSACTION_START: {tx_type}",
+            extra={
+                "event": "transaction_start",
+                "tx_type": tx_type,
+                "user_id": user_id,
+                "property_id": property_id,
+                "amount": amount,
+                "timestamp": datetime.utcnow().isoformat()
+            }
+        )
+    
+    @staticmethod
+    def log_transaction_success(tx_type: str, tx_hash: str, user_id: str, duration: float, details: Dict[str, Any] = None):
+        """Log successful blockchain transaction"""
+        logger = logging.getLogger("transactions")
+        logger.info(
+            f"TRANSACTION_SUCCESS: {tx_type} completed in {duration:.3f}s",
+            extra={
+                "event": "transaction_success",
+                "tx_type": tx_type,
+                "tx_hash": tx_hash,
+                "user_id": user_id,
+                "duration": duration,
+                "details": details or {},
+                "timestamp": datetime.utcnow().isoformat()
+            }
+        )
+    
+    @staticmethod
+    def log_transaction_failure(tx_type: str, error: str, user_id: str, duration: float, details: Dict[str, Any] = None):
+        """Log failed blockchain transaction"""
+        logger = logging.getLogger("transactions")
+        logger.error(
+            f"TRANSACTION_FAILURE: {tx_type} failed after {duration:.3f}s - {error}",
+            extra={
+                "event": "transaction_failure",
+                "tx_type": tx_type,
+                "error": error,
+                "user_id": user_id,
+                "duration": duration,
+                "details": details or {},
+                "timestamp": datetime.utcnow().isoformat()
+            }
+        )
+
+
+class CustomFormatter(logging.Formatter):
+    """Custom formatter for structured logging"""
+    
+    def format(self, record):
+        # Add timestamp and environment info
+        record.environment = settings.ENVIRONMENT
+        record.service = "real-estate-tokenization"
+        
+        # Format the base message
+        formatted = super().format(record)
+        
+        # Add structured data if present
+        if hasattr(record, 'event'):
+            structured_data = {
+                "timestamp": record.created,
+                "level": record.levelname,
+                "environment": record.environment,
+                "service": record.service,
+                "event": record.event,
+                "message": record.getMessage()
+            }
+            
+            # Add extra fields
+            for key, value in record.__dict__.items():
+                if key not in ['name', 'msg', 'args', 'levelname', 'levelno', 'pathname', 
+                              'filename', 'module', 'lineno', 'funcName', 'created', 
+                              'msecs', 'relativeCreated', 'thread', 'threadName', 
+                              'processName', 'process', 'getMessage', 'exc_info', 
+                              'exc_text', 'stack_info', 'environment', 'service', 'message']:
+                    structured_data[key] = value
+            
+            # Return JSON for structured logs
+            return json.dumps(structured_data, default=str)
+        
+        return formatted
+
+
+def setup_logging():
+    """Setup comprehensive logging configuration"""
+    
+    # Create logs directory if it doesn't exist
+    if settings.LOG_FILE_ENABLED:
+        log_path = Path(settings.LOG_FILE_PATH)
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    # Configure root logger
+    logging.basicConfig(
+        level=getattr(logging, settings.LOG_LEVEL),
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+        datefmt='%Y-%m-%d %H:%M:%S'
+    )
+    
+    # Configure application logger
+    app_logger = logging.getLogger("app")
+    app_logger.setLevel(getattr(logging, settings.LOG_LEVEL))
+    
+    # Configure performance logger
+    perf_logger = logging.getLogger("performance")
+    perf_logger.setLevel(logging.WARNING)
+    
+    # Configure transaction logger
+    tx_logger = logging.getLogger("transactions")
+    tx_logger.setLevel(logging.INFO)
+    
+    # Add file handlers if enabled
+    if settings.LOG_FILE_ENABLED:
+        # Rotating file handler for general logs
+        file_handler = logging.handlers.RotatingFileHandler(
+            settings.LOG_FILE_PATH,
+            maxBytes=settings.LOG_FILE_MAX_SIZE,
+            backupCount=settings.LOG_FILE_BACKUP_COUNT
+        )
+        file_handler.setFormatter(CustomFormatter(
+            '%(asctime)s - %(environment)s - %(name)s - %(levelname)s - %(message)s'
+        ))
+        
+        # Add to all loggers
+        app_logger.addHandler(file_handler)
+        perf_logger.addHandler(file_handler)
+        tx_logger.addHandler(file_handler)
+    
+    # Console handler for development
+    if settings.is_development():
+        console_handler = logging.StreamHandler()
+        console_handler.setFormatter(logging.Formatter(
+            '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+        ))
+        
+        app_logger.addHandler(console_handler)
+        perf_logger.addHandler(console_handler)
+        tx_logger.addHandler(console_handler)
+    
+    return app_logger
+
+
+def monitor_performance(operation_name: str):
+    """Decorator to monitor function performance"""
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            if not settings.ENABLE_PERFORMANCE_MONITORING:
+                return func(*args, **kwargs)
+            
+            start_time = time.time()
+            try:
+                result = func(*args, **kwargs)
+                duration = time.time() - start_time
+                PerformanceLogger.log_slow_operation(operation_name, duration)
+                return result
+            except Exception as e:
+                duration = time.time() - start_time
+                PerformanceLogger.log_slow_operation(
+                    f"{operation_name}_FAILED", 
+                    duration, 
+                    {"error": str(e)}
+                )
+                raise
+        return wrapper
+    return decorator
+
+
+def monitor_transaction(tx_type: str):
+    """Decorator to monitor blockchain transactions"""
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            if not settings.ENABLE_TRANSACTION_MONITORING:
+                return func(*args, **kwargs)
+            
+            # Extract user_id from kwargs or args
+            user_id = kwargs.get('user_id') or getattr(args[0] if args else None, 'id', 'unknown')
+            property_id = kwargs.get('property_id')
+            amount = kwargs.get('amount')
+            
+            TransactionLogger.log_transaction_start(tx_type, user_id, property_id, amount)
+            
+            start_time = time.time()
+            try:
+                result = func(*args, **kwargs)
+                duration = time.time() - start_time
+                
+                # Extract transaction hash from result if available
+                tx_hash = None
+                if isinstance(result, dict):
+                    tx_hash = result.get('blockchain_tx_hash') or result.get('tx_hash')
+                
+                TransactionLogger.log_transaction_success(tx_type, tx_hash or 'N/A', user_id, duration)
+                return result
+            except Exception as e:
+                duration = time.time() - start_time
+                TransactionLogger.log_transaction_failure(tx_type, str(e), user_id, duration)
+                raise
+        return wrapper
+    return decorator
+
+
+# Initialize logging on import
+app_logger = setup_logging()
+
+# Export commonly used loggers
+def get_logger(name: str = "app") -> logging.Logger:
+    """Get a logger instance"""
+    return logging.getLogger(name)
+
+
+def setup_logger(
+    name: str,
+    level: int = logging.INFO,
+    log_to_file: bool = True,
+    log_to_console: bool = True
+) -> logging.Logger:
+    """
+    Setup and return a configured logger (compatible with app_logger.py)
+    
+    Args:
+        name: Logger name (typically __name__ from the calling module)
+        level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        log_to_file: Whether to write logs to file
+        log_to_console: Whether to write logs to console
+    
+    Returns:
+        Configured logger instance
+    """
+    # Create logger
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+    
+    # Avoid duplicate handlers if logger already configured
+    if logger.handlers:
+        return logger
+    
+    # Create logs directory if it doesn't exist
+    if log_to_file and settings.LOG_FILE_ENABLED:
+        log_path = Path(settings.LOG_FILE_PATH)
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+    
+    # Create formatters
+    detailed_formatter = logging.Formatter(
+        '%(asctime)s - %(name)s - %(levelname)s - %(funcName)s:%(lineno)d - %(message)s',
+        datefmt='%Y-%m-%d %H:%M:%S'
+    )
+    
+    simple_formatter = logging.Formatter(
+        '%(asctime)s - %(levelname)s - %(message)s',
+        datefmt='%H:%M:%S'
+    )
+    
+    # Console handler
+    if log_to_console:
+        console_handler = logging.StreamHandler()
+        console_handler.setLevel(level)
+        console_handler.setFormatter(simple_formatter)
+        logger.addHandler(console_handler)
+    
+    # File handler
+    if log_to_file and settings.LOG_FILE_ENABLED:
+        file_handler = logging.handlers.RotatingFileHandler(
+            settings.LOG_FILE_PATH,
+            maxBytes=settings.LOG_FILE_MAX_SIZE,
+            backupCount=settings.LOG_FILE_BACKUP_COUNT
+        )
+        file_handler.setFormatter(detailed_formatter)
+        logger.addHandler(file_handler)
+    
+    return logger
+
+
+# Pre-configured loggers for common modules (from app_logger.py)
+repo_logger = setup_logger("repo", level=logging.INFO)
+service_logger = setup_logger("services", level=logging.INFO)
+route_logger = setup_logger("routes", level=logging.INFO)
+utils_logger = setup_logger("utils", level=logging.DEBUG)
+
+
+# Convenience functions
+def log_info(message: str, **kwargs):
+    """Log info message with structured data"""
+    logger = get_logger()
+    logger.info(message, extra=kwargs)
+
+
+def log_warning(message: str, **kwargs):
+    """Log warning message with structured data"""
+    logger = get_logger()
+    logger.warning(message, extra=kwargs)
+
+
+def log_error(message: str, **kwargs):
+    """Log error message with structured data"""
+    logger = get_logger()
+    logger.error(message, extra=kwargs)
+
+
+def log_debug(message: str, **kwargs):
+    """Log debug message with structured data"""
+    logger = get_logger()
+    logger.debug(message, extra=kwargs)
+
+

utils/security_logger.py

@@ -0,0 +1,157 @@
+"""
+Security Event Logging
+Logs all security-related events for audit and monitoring
+"""
+import logging
+from datetime import datetime
+from typing import Optional, Dict, Any
+import json
+import os
+
+# Ensure logs directory exists
+os.makedirs('logs', exist_ok=True)
+
+# Configure security logger
+security_logger = logging.getLogger('security')
+security_logger.setLevel(logging.INFO)
+
+# Create file handler for security events
+security_handler = logging.FileHandler('logs/security.log')
+security_handler.setLevel(logging.INFO)
+
+# Create formatter
+formatter = logging.Formatter(
+    '%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+    datefmt='%Y-%m-%d %H:%M:%S'
+)
+security_handler.setFormatter(formatter)
+security_logger.addHandler(security_handler)
+
+
+def log_login_attempt(email: str, ip: str, success: bool, reason: Optional[str] = None):
+    """Log login attempt"""
+    event = {
+        'event_type': 'login_attempt',
+        'email': email,
+        'ip_address': ip,
+        'success': success,
+        'timestamp': datetime.utcnow().isoformat(),
+        'reason': reason
+    }
+    
+    if success:
+        security_logger.info(f"Successful login: {json.dumps(event)}")
+    else:
+        security_logger.warning(f"Failed login attempt: {json.dumps(event)}")
+
+
+def log_registration(email: str, ip: str, success: bool, reason: Optional[str] = None):
+    """Log registration attempt"""
+    event = {
+        'event_type': 'registration',
+        'email': email,
+        'ip_address': ip,
+        'success': success,
+        'timestamp': datetime.utcnow().isoformat(),
+        'reason': reason
+    }
+    
+    if success:
+        security_logger.info(f"New user registration: {json.dumps(event)}")
+    else:
+        security_logger.warning(f"Failed registration: {json.dumps(event)}")
+
+
+def log_rate_limit_exceeded(endpoint: str, ip: str):
+    """Log rate limit exceeded"""
+    event = {
+        'event_type': 'rate_limit_exceeded',
+        'endpoint': endpoint,
+        'ip_address': ip,
+        'timestamp': datetime.utcnow().isoformat()
+    }
+    
+    security_logger.warning(f"Rate limit exceeded: {json.dumps(event)}")
+
+
+def log_account_lockout(email: str, ip: str, duration_minutes: int):
+    """Log account lockout"""
+    event = {
+        'event_type': 'account_lockout',
+        'email': email,
+        'ip_address': ip,
+        'duration_minutes': duration_minutes,
+        'timestamp': datetime.utcnow().isoformat()
+    }
+    
+    security_logger.warning(f"Account locked: {json.dumps(event)}")
+
+
+def log_unauthorized_access(endpoint: str, ip: str, user_id: Optional[str] = None):
+    """Log unauthorized access attempt"""
+    event = {
+        'event_type': 'unauthorized_access',
+        'endpoint': endpoint,
+        'ip_address': ip,
+        'user_id': user_id,
+        'timestamp': datetime.utcnow().isoformat()
+    }
+    
+    security_logger.warning(f"Unauthorized access attempt: {json.dumps(event)}")
+
+
+def log_suspicious_activity(activity_type: str, details: Dict[str, Any], ip: str, user_id: Optional[str] = None):
+    """Log suspicious activity"""
+    event = {
+        'event_type': 'suspicious_activity',
+        'activity_type': activity_type,
+        'details': details,
+        'ip_address': ip,
+        'user_id': user_id,
+        'timestamp': datetime.utcnow().isoformat()
+    }
+    
+    security_logger.warning(f"Suspicious activity detected: {json.dumps(event)}")
+
+
+def log_data_access(user_id: str, data_type: str, action: str, ip: str):
+    """Log sensitive data access"""
+    event = {
+        'event_type': 'data_access',
+        'user_id': user_id,
+        'data_type': data_type,
+        'action': action,
+        'ip_address': ip,
+        'timestamp': datetime.utcnow().isoformat()
+    }
+    
+    security_logger.info(f"Data access: {json.dumps(event)}")
+
+
+def log_kyc_event(user_id: str, event_type: str, status: str, ip: str):
+    """Log KYC related events"""
+    event = {
+        'event_type': 'kyc_event',
+        'user_id': user_id,
+        'kyc_event_type': event_type,
+        'status': status,
+        'ip_address': ip,
+        'timestamp': datetime.utcnow().isoformat()
+    }
+    
+    security_logger.info(f"KYC event: {json.dumps(event)}")
+
+
+def log_transaction_event(user_id: str, transaction_type: str, amount: float, property_id: Optional[str], ip: str):
+    """Log transaction events"""
+    event = {
+        'event_type': 'transaction',
+        'user_id': user_id,
+        'transaction_type': transaction_type,
+        'amount': amount,
+        'property_id': property_id,
+        'ip_address': ip,
+        'timestamp': datetime.utcnow().isoformat()
+    }
+    
+    security_logger.info(f"Transaction event: {json.dumps(event)}")

utils/validators.py

@@ -0,0 +1,230 @@
+"""
+Validation Utilities
+Common validation functions to reduce duplicate code across routes
+"""
+from fastapi import HTTPException, status
+from typing import Dict, Any
+import repo
+
+
+def validate_property_exists(db, property_id: str) -> Dict[str, Any]:
+    """
+    Validate that a property exists and return it
+    
+    Args:
+        db: Database connection
+        property_id: Property ID to validate
+    
+    Returns:
+        Property dict if found
+    
+    Raises:
+        HTTPException: 404 if property not found
+    
+    Usage:
+        property_obj = validate_property_exists(db, property_id)
+    """
+    property_obj = repo.get_property_by_id(db, property_id)
+    if not property_obj:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Property not found"
+        )
+    return property_obj
+
+
+def validate_wallet_exists(db, user_id: str) -> Dict[str, Any]:
+    """
+    Validate that a user's wallet exists and return it
+    
+    Args:
+        db: Database connection
+        user_id: User ID to get wallet for
+    
+    Returns:
+        Wallet dict if found
+    
+    Raises:
+        HTTPException: 404 if wallet not found
+    
+    Usage:
+        wallet = validate_wallet_exists(db, current_user['id'])
+    """
+    wallet = repo.get_wallet_by_user(db, user_id)
+    if not wallet:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Wallet not found"
+        )
+    return wallet
+
+
+def validate_user_exists(db, user_id: str) -> Dict[str, Any]:
+    """
+    Validate that a user exists and return them
+    
+    Args:
+        db: Database connection
+        user_id: User ID to validate
+    
+    Returns:
+        User dict if found
+    
+    Raises:
+        HTTPException: 404 if user not found
+    
+    Usage:
+        user = validate_user_exists(db, user_id)
+    """
+    user = repo.get_user_by_id(db, user_id)
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found"
+        )
+    return user
+
+
+def validate_property_active(property_obj: Dict[str, Any]) -> None:
+    """
+    Validate that a property is active
+    
+    Args:
+        property_obj: Property dict to validate
+    
+    Raises:
+        HTTPException: 400 if property not active
+    
+    Usage:
+        validate_property_active(property_obj)
+    """
+    if not property_obj.get('is_active', False):
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Property is not active"
+        )
+
+
+def validate_property_funded(property_obj: Dict[str, Any]) -> None:
+    """
+    Validate that a property is funded
+    
+    Args:
+        property_obj: Property dict to validate
+    
+    Raises:
+        HTTPException: 400 if property not funded
+    
+    Usage:
+        validate_property_funded(property_obj)
+    """
+    if property_obj.get('status') != 'funded':
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Property is not funded. Current status: {property_obj.get('status', 'unknown')}"
+        )
+
+
+def validate_tokens_available(property_obj: Dict[str, Any], requested_tokens: int) -> None:
+    """
+    Validate that enough tokens are available for purchase
+    
+    Args:
+        property_obj: Property dict to check
+        requested_tokens: Number of tokens requested
+    
+    Raises:
+        HTTPException: 400 if insufficient tokens available
+    
+    Usage:
+        validate_tokens_available(property_obj, buy_request.amount_tokens)
+    """
+    available_tokens = property_obj.get('available_tokens', 0)
+    if available_tokens < requested_tokens:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Insufficient tokens available. Requested: {requested_tokens}, Available: {available_tokens}"
+        )
+
+
+def validate_wallet_balance(wallet: Dict[str, Any], required_amount: float) -> None:
+    """
+    Validate that wallet has sufficient balance
+    
+    Args:
+        wallet: Wallet dict to check
+        required_amount: Amount required
+    
+    Raises:
+        HTTPException: 400 if insufficient balance
+    
+    Usage:
+        validate_wallet_balance(wallet, total_cost)
+    """
+    current_balance = wallet.get('balance', 0.0)
+    if current_balance < required_amount:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Insufficient wallet balance. Required: {required_amount:.2f} {wallet.get('currency', 'AED')}, Available: {current_balance:.2f}"
+        )
+
+
+def validate_kyc_approved(user: Dict[str, Any]) -> None:
+    """
+    Validate that user's KYC is approved
+    
+    Args:
+        user: User dict to check
+    
+    Raises:
+        HTTPException: 403 if KYC not approved
+    
+    Usage:
+        validate_kyc_approved(current_user)
+    """
+    kyc_status = user.get('kyc_status', 'pending')
+    if kyc_status != 'approved':
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=f"KYC verification required. Your current status: {kyc_status}. Please complete KYC verification."
+        )
+
+
+def validate_admin_role(user: Dict[str, Any]) -> None:
+    """
+    Validate that user has admin role
+    
+    Args:
+        user: User dict to check
+    
+    Raises:
+        HTTPException: 403 if not admin
+    
+    Usage:
+        validate_admin_role(current_user)
+    """
+    if user.get('role') != 'admin':
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Admin access required"
+        )
+
+
+def validate_super_admin_role(user: Dict[str, Any]) -> None:
+    """
+    Validate that user has super_admin role
+    
+    Args:
+        user: User dict to check
+    
+    Raises:
+        HTTPException: 403 if not super admin
+    
+    Usage:
+        validate_super_admin_role(current_user)
+    """
+    if user.get('role') != 'super_admin':
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Super admin access required"
+        )