@megatao/sdk 1.1.0

package/docs/integration/INTEGRATION_GUIDE.md

@@ -0,0 +1,1679 @@
+# Alpha Futures SDK Integration Guide
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Basic Integration](#basic-integration)
+- [Authentication & Security](#authentication--security)
+- [Trading Bot Integration](#trading-bot-integration)
+- [Web Application Integration](#web-application-integration)
+- [API Server Integration](#api-server-integration)
+- [Mobile Integration](#mobile-integration)
+- [WebSocket & Real-time Data](#websocket--real-time-data)
+- [Error Handling & Recovery](#error-handling--recovery)
+- [Testing Your Integration](#testing-your-integration)
+- [Performance Optimization](#performance-optimization)
+- [Security Best Practices](#security-best-practices)
+
+## Overview
+
+This guide covers how to integrate the Alpha Futures SDK into various types of applications, from simple scripts to complex trading systems.
+
+## Installation
+
+### NPM/Yarn
+
+```bash
+# Using npm
+npm install @alpha-futures/sdk ethers
+
+# Using yarn
+yarn add @alpha-futures/sdk ethers
+
+# Using pnpm
+pnpm add @alpha-futures/sdk ethers
+```
+
+### TypeScript Configuration
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "node"
+  }
+}
+```
+
+## Basic Integration
+
+### Simple Script
+
+```typescript
+import { AlphaFuturesClient } from '@alpha-futures/sdk';
+import { ethers } from 'ethers';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+async function main() {
+  // Initialize client
+  const client = new AlphaFuturesClient({
+    rpcUrl: process.env.RPC_URL!,
+    privateKey: process.env.PRIVATE_KEY!,
+    network: 'mainnet'
+  });
+
+  // Get current price
+  const price = await client.priceOracle.getPrice('ALPHA');
+  console.log('ALPHA Price:', ethers.formatEther(price));
+
+  // Check account
+  const account = await client.marginAccount.getMarginAccount(
+    await client.signer.getAddress()
+  );
+  console.log('Available Margin:', ethers.formatEther(account.availableMargin));
+}
+
+main().catch(console.error);
+```
+
+### Environment Configuration
+
+`.env` file:
+```bash
+# Network Configuration
+RPC_URL=https://bittensor-evm.alchemyapi.io/v2/your-key
+NETWORK=mainnet
+
+# Account Configuration
+PRIVATE_KEY=0x...
+
+# Optional: Custom Contract Addresses
+MARGIN_ACCOUNT_ADDRESS=0x...
+POSITION_MANAGER_ADDRESS=0x...
+```
+
+### Configuration Management
+
+```typescript
+import { ClientConfig, NetworkConfig } from '@alpha-futures/sdk';
+
+class ConfigManager {
+  static getConfig(): ClientConfig {
+    const network = process.env.NETWORK || 'mainnet';
+    
+    // Custom network configuration
+    if (process.env.CUSTOM_NETWORK) {
+      const customNetwork: NetworkConfig = {
+        chainId: parseInt(process.env.CHAIN_ID!),
+        name: process.env.NETWORK_NAME!,
+        rpcUrl: process.env.RPC_URL!,
+        contracts: {
+          marginAccount: process.env.MARGIN_ACCOUNT_ADDRESS!,
+          positionManager: process.env.POSITION_MANAGER_ADDRESS!,
+          fundingRate: process.env.FUNDING_RATE_ADDRESS!,
+          liquidationEngine: process.env.LIQUIDATION_ENGINE_ADDRESS!,
+          protocolVault: process.env.PROTOCOL_VAULT_ADDRESS!,
+          priceOracle: process.env.PRICE_ORACLE_ADDRESS!,
+          taoToken: process.env.TAO_TOKEN_ADDRESS!
+        }
+      };
+      
+      return {
+        rpcUrl: process.env.RPC_URL!,
+        privateKey: process.env.PRIVATE_KEY!,
+        networkConfig: customNetwork
+      };
+    }
+    
+    // Standard network
+    return {
+      rpcUrl: process.env.RPC_URL!,
+      privateKey: process.env.PRIVATE_KEY!,
+      network
+    };
+  }
+}
+```
+
+## Authentication & Security
+
+### Secure Key Management
+
+```typescript
+import { Wallet } from 'ethers';
+import * as crypto from 'crypto';
+
+class SecureWalletManager {
+  private encryptedKey: string;
+  private salt: Buffer;
+  
+  constructor() {
+    this.salt = crypto.randomBytes(32);
+  }
+  
+  // Encrypt private key
+  encryptPrivateKey(privateKey: string, password: string): void {
+    const key = crypto.pbkdf2Sync(password, this.salt, 100000, 32, 'sha256');
+    const cipher = crypto.createCipheriv('aes-256-gcm', key, this.salt.slice(0, 16));
+    
+    let encrypted = cipher.update(privateKey, 'utf8', 'hex');
+    encrypted += cipher.final('hex');
+    
+    const authTag = cipher.getAuthTag();
+    this.encryptedKey = encrypted + authTag.toString('hex');
+  }
+  
+  // Decrypt and create wallet
+  createWallet(password: string, provider: any): Wallet {
+    const key = crypto.pbkdf2Sync(password, this.salt, 100000, 32, 'sha256');
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, this.salt.slice(0, 16));
+    
+    const encrypted = this.encryptedKey.slice(0, -32);
+    const authTag = Buffer.from(this.encryptedKey.slice(-32), 'hex');
+    decipher.setAuthTag(authTag);
+    
+    let decrypted = decipher.update(encrypted, 'hex', 'utf8');
+    decrypted += decipher.final('utf8');
+    
+    return new Wallet(decrypted, provider);
+  }
+}
+```
+
+### Multi-Signature Integration
+
+```typescript
+import { AlphaFuturesClient } from '@alpha-futures/sdk';
+
+class MultiSigIntegration {
+  private client: AlphaFuturesClient;
+  private signers: string[];
+  private threshold: number;
+  
+  constructor(client: AlphaFuturesClient, signers: string[], threshold: number) {
+    this.client = client;
+    this.signers = signers;
+    this.threshold = threshold;
+  }
+  
+  async proposeTransaction(
+    target: string,
+    data: string,
+    value: bigint
+  ): Promise<number> {
+    // Implementation depends on your multisig contract
+    // This is a conceptual example
+    const proposalId = await this.submitToMultisig(target, data, value);
+    return proposalId;
+  }
+  
+  async executeAfterApproval(proposalId: number): Promise<void> {
+    const approvals = await this.getApprovals(proposalId);
+    if (approvals >= this.threshold) {
+      await this.executeMultisigTransaction(proposalId);
+    }
+  }
+}
+```
+
+## Trading Bot Integration
+
+### Basic Trading Bot Structure
+
+```typescript
+import { AlphaFuturesClient } from '@alpha-futures/sdk';
+import { EventEmitter } from 'events';
+
+abstract class TradingBot extends EventEmitter {
+  protected client: AlphaFuturesClient;
+  protected isRunning: boolean = false;
+  protected config: BotConfig;
+  
+  constructor(client: AlphaFuturesClient, config: BotConfig) {
+    super();
+    this.client = client;
+    this.config = config;
+  }
+  
+  async start(): Promise<void> {
+    this.isRunning = true;
+    this.emit('started');
+    
+    while (this.isRunning) {
+      try {
+        await this.executeStrategy();
+        await this.sleep(this.config.interval);
+      } catch (error) {
+        this.emit('error', error);
+        await this.handleError(error);
+      }
+    }
+  }
+  
+  stop(): void {
+    this.isRunning = false;
+    this.emit('stopped');
+  }
+  
+  abstract executeStrategy(): Promise<void>;
+  abstract handleError(error: any): Promise<void>;
+  
+  protected sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+interface BotConfig {
+  interval: number;
+  maxPositions: number;
+  riskPerTrade: number;
+  stopLoss: number;
+  takeProfit: number;
+}
+```
+
+### Grid Trading Bot Example
+
+```typescript
+class GridTradingBot extends TradingBot {
+  private gridLevels: bigint[];
+  private positions: Map<string, GridPosition> = new Map();
+  
+  constructor(
+    client: AlphaFuturesClient,
+    config: GridBotConfig
+  ) {
+    super(client, config);
+    this.gridLevels = this.calculateGridLevels();
+  }
+  
+  private calculateGridLevels(): bigint[] {
+    const config = this.config as GridBotConfig;
+    const levels: bigint[] = [];
+    
+    for (let i = 0; i <= config.gridCount; i++) {
+      const price = config.lowerBound + 
+        (config.upperBound - config.lowerBound) * BigInt(i) / BigInt(config.gridCount);
+      levels.push(price);
+    }
+    
+    return levels;
+  }
+  
+  async executeStrategy(): Promise<void> {
+    const currentPrice = await this.client.priceOracle.getPrice('ALPHA');
+    
+    // Check each grid level
+    for (let i = 0; i < this.gridLevels.length - 1; i++) {
+      const lowerLevel = this.gridLevels[i];
+      const upperLevel = this.gridLevels[i + 1];
+      const levelKey = `${i}`;
+      
+      if (currentPrice >= lowerLevel && currentPrice <= upperLevel) {
+        if (!this.positions.has(levelKey)) {
+          // Open position at this level
+          await this.openGridPosition(levelKey, lowerLevel, upperLevel);
+        }
+      } else if (this.positions.has(levelKey)) {
+        // Close position if price moved out of range
+        await this.closeGridPosition(levelKey);
+      }
+    }
+  }
+  
+  private async openGridPosition(
+    key: string,
+    buyPrice: bigint,
+    sellPrice: bigint
+  ): Promise<void> {
+    const size = this.calculatePositionSize();
+    
+    const tx = await this.client.positionManager.openPosition({
+      asset: 'ALPHA',
+      size,
+      leverage: 2,
+      isLong: true
+    });
+    
+    await tx.wait();
+    
+    this.positions.set(key, {
+      positionId: await this.getPositionIdFromTx(tx),
+      buyPrice,
+      sellPrice,
+      size
+    });
+    
+    this.emit('positionOpened', key);
+  }
+  
+  private async closeGridPosition(key: string): Promise<void> {
+    const position = this.positions.get(key);
+    if (!position) return;
+    
+    await this.client.positionManager.closePosition(position.positionId);
+    this.positions.delete(key);
+    
+    this.emit('positionClosed', key);
+  }
+  
+  async handleError(error: any): Promise<void> {
+    console.error('Grid bot error:', error);
+    
+    // Retry logic
+    if (error.code === 'NETWORK_ERROR') {
+      await this.sleep(5000);
+      return;
+    }
+    
+    // Critical error - stop bot
+    if (error.code === 'INSUFFICIENT_FUNDS') {
+      this.stop();
+    }
+  }
+}
+
+interface GridBotConfig extends BotConfig {
+  gridCount: number;
+  lowerBound: bigint;
+  upperBound: bigint;
+  amountPerGrid: bigint;
+}
+
+interface GridPosition {
+  positionId: bigint;
+  buyPrice: bigint;
+  sellPrice: bigint;
+  size: bigint;
+}
+```
+
+## Web Application Integration
+
+### React Integration
+
+```typescript
+// hooks/useAlphaFutures.ts
+import { useState, useEffect, useCallback } from 'react';
+import { AlphaFuturesClient } from '@alpha-futures/sdk';
+import { ethers } from 'ethers';
+
+export function useAlphaFutures() {
+  const [client, setClient] = useState<AlphaFuturesClient | null>(null);
+  const [account, setAccount] = useState<string | null>(null);
+  const [isConnected, setIsConnected] = useState(false);
+  
+  const connect = useCallback(async () => {
+    if (typeof window.ethereum === 'undefined') {
+      throw new Error('MetaMask not installed');
+    }
+    
+    // Request account access
+    const accounts = await window.ethereum.request({ 
+      method: 'eth_requestAccounts' 
+    });
+    
+    // Create provider and signer
+    const provider = new ethers.BrowserProvider(window.ethereum);
+    const signer = await provider.getSigner();
+    
+    // Initialize client
+    const alphaClient = new AlphaFuturesClient({
+      provider,
+      signer,
+      network: 'mainnet'
+    });
+    
+    setClient(alphaClient);
+    setAccount(accounts[0]);
+    setIsConnected(true);
+  }, []);
+  
+  const disconnect = useCallback(() => {
+    setClient(null);
+    setAccount(null);
+    setIsConnected(false);
+  }, []);
+  
+  // Auto-connect if previously connected
+  useEffect(() => {
+    const checkConnection = async () => {
+      if (typeof window.ethereum !== 'undefined') {
+        const accounts = await window.ethereum.request({ 
+          method: 'eth_accounts' 
+        });
+        
+        if (accounts.length > 0) {
+          await connect();
+        }
+      }
+    };
+    
+    checkConnection();
+  }, [connect]);
+  
+  // Listen for account changes
+  useEffect(() => {
+    if (typeof window.ethereum !== 'undefined') {
+      window.ethereum.on('accountsChanged', (accounts: string[]) => {
+        if (accounts.length === 0) {
+          disconnect();
+        } else {
+          setAccount(accounts[0]);
+        }
+      });
+      
+      window.ethereum.on('chainChanged', () => {
+        window.location.reload();
+      });
+    }
+  }, [disconnect]);
+  
+  return {
+    client,
+    account,
+    isConnected,
+    connect,
+    disconnect
+  };
+}
+```
+
+### React Trading Component
+
+```tsx
+// components/TradingPanel.tsx
+import React, { useState, useEffect } from 'react';
+import { useAlphaFutures } from '../hooks/useAlphaFutures';
+import { ethers } from 'ethers';
+
+export function TradingPanel() {
+  const { client, account, isConnected } = useAlphaFutures();
+  const [loading, setLoading] = useState(false);
+  const [position, setPosition] = useState({
+    asset: 'ALPHA',
+    size: '1000',
+    leverage: 3,
+    isLong: true
+  });
+  const [accountInfo, setAccountInfo] = useState(null);
+  
+  useEffect(() => {
+    if (client && account) {
+      loadAccountInfo();
+    }
+  }, [client, account]);
+  
+  const loadAccountInfo = async () => {
+    try {
+      const info = await client.marginAccount.getMarginAccount(account);
+      setAccountInfo(info);
+    } catch (error) {
+      console.error('Failed to load account info:', error);
+    }
+  };
+  
+  const handleTrade = async () => {
+    if (!client) return;
+    
+    setLoading(true);
+    try {
+      const tx = await client.positionManager.openPosition({
+        asset: position.asset,
+        size: ethers.parseEther(position.size),
+        leverage: position.leverage,
+        isLong: position.isLong
+      });
+      
+      await tx.wait();
+      alert('Position opened successfully!');
+      await loadAccountInfo();
+    } catch (error) {
+      alert(`Error: ${error.message}`);
+    } finally {
+      setLoading(false);
+    }
+  };
+  
+  if (!isConnected) {
+    return <div>Please connect your wallet</div>;
+  }
+  
+  return (
+    <div className="trading-panel">
+      <h2>Open Position</h2>
+      
+      {accountInfo && (
+        <div className="account-info">
+          <p>Available Margin: {ethers.formatEther(accountInfo.availableMargin)} TAO</p>
+          <p>Used Margin: {ethers.formatEther(accountInfo.usedMargin)} TAO</p>
+        </div>
+      )}
+      
+      <div className="form-group">
+        <label>Asset</label>
+        <select 
+          value={position.asset}
+          onChange={(e) => setPosition({...position, asset: e.target.value})}
+        >
+          <option value="ALPHA">ALPHA</option>
+          <option value="BETA">BETA</option>
+        </select>
+      </div>
+      
+      <div className="form-group">
+        <label>Size (TAO)</label>
+        <input
+          type="number"
+          value={position.size}
+          onChange={(e) => setPosition({...position, size: e.target.value})}
+        />
+      </div>
+      
+      <div className="form-group">
+        <label>Leverage</label>
+        <input
+          type="range"
+          min="1"
+          max="10"
+          value={position.leverage}
+          onChange={(e) => setPosition({...position, leverage: parseInt(e.target.value)})}
+        />
+        <span>{position.leverage}x</span>
+      </div>
+      
+      <div className="form-group">
+        <label>Direction</label>
+        <button
+          className={position.isLong ? 'active' : ''}
+          onClick={() => setPosition({...position, isLong: true})}
+        >
+          Long
+        </button>
+        <button
+          className={!position.isLong ? 'active' : ''}
+          onClick={() => setPosition({...position, isLong: false})}
+        >
+          Short
+        </button>
+      </div>
+      
+      <button 
+        onClick={handleTrade}
+        disabled={loading}
+      >
+        {loading ? 'Opening Position...' : 'Open Position'}
+      </button>
+    </div>
+  );
+}
+```
+
+### Vue.js Integration
+
+```typescript
+// composables/useAlphaFutures.ts
+import { ref, computed, onMounted, onUnmounted } from 'vue';
+import { AlphaFuturesClient } from '@alpha-futures/sdk';
+import { ethers } from 'ethers';
+
+export function useAlphaFutures() {
+  const client = ref<AlphaFuturesClient | null>(null);
+  const account = ref<string | null>(null);
+  const isConnected = computed(() => !!client.value && !!account.value);
+  
+  const connect = async () => {
+    if (!window.ethereum) {
+      throw new Error('MetaMask not installed');
+    }
+    
+    const accounts = await window.ethereum.request({ 
+      method: 'eth_requestAccounts' 
+    });
+    
+    const provider = new ethers.BrowserProvider(window.ethereum);
+    const signer = await provider.getSigner();
+    
+    client.value = new AlphaFuturesClient({
+      provider,
+      signer,
+      network: 'mainnet'
+    });
+    
+    account.value = accounts[0];
+  };
+  
+  const disconnect = () => {
+    client.value = null;
+    account.value = null;
+  };
+  
+  onMounted(() => {
+    // Auto-connect logic
+    if (window.ethereum) {
+      window.ethereum.on('accountsChanged', handleAccountsChanged);
+      window.ethereum.on('chainChanged', handleChainChanged);
+    }
+  });
+  
+  onUnmounted(() => {
+    if (window.ethereum) {
+      window.ethereum.removeListener('accountsChanged', handleAccountsChanged);
+      window.ethereum.removeListener('chainChanged', handleChainChanged);
+    }
+  });
+  
+  return {
+    client: computed(() => client.value),
+    account: computed(() => account.value),
+    isConnected,
+    connect,
+    disconnect
+  };
+}
+```
+
+## API Server Integration
+
+### Express.js API Server
+
+```typescript
+// server.ts
+import express from 'express';
+import { AlphaFuturesClient } from '@alpha-futures/sdk';
+import { ethers } from 'ethers';
+import rateLimit from 'express-rate-limit';
+import helmet from 'helmet';
+
+const app = express();
+app.use(helmet());
+app.use(express.json());
+
+// Rate limiting
+const limiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100 // limit each IP to 100 requests per windowMs
+});
+app.use('/api/', limiter);
+
+// Initialize client
+const client = new AlphaFuturesClient({
+  rpcUrl: process.env.RPC_URL!,
+  privateKey: process.env.PRIVATE_KEY!,
+  network: 'mainnet'
+});
+
+// Middleware for API authentication
+const authenticateAPI = (req: Request, res: Response, next: NextFunction) => {
+  const apiKey = req.headers['x-api-key'];
+  
+  if (!apiKey || !isValidApiKey(apiKey)) {
+    return res.status(401).json({ error: 'Invalid API key' });
+  }
+  
+  next();
+};
+
+// Price endpoint
+app.get('/api/prices/:asset', authenticateAPI, async (req, res) => {
+  try {
+    const { asset } = req.params;
+    const price = await client.priceOracle.getPrice(asset);
+    
+    res.json({
+      asset,
+      price: ethers.formatEther(price),
+      timestamp: Date.now()
+    });
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+
+// Position endpoints
+app.post('/api/positions', authenticateAPI, async (req, res) => {
+  try {
+    const { asset, size, leverage, isLong, userAddress } = req.body;
+    
+    // Validate inputs
+    if (!asset || !size || !leverage || isLong === undefined || !userAddress) {
+      return res.status(400).json({ error: 'Missing required fields' });
+    }
+    
+    // Create position on behalf of user
+    // Note: This requires proper authorization setup
+    const tx = await client.positionManager.openPosition({
+      asset,
+      size: ethers.parseEther(size),
+      leverage,
+      isLong
+    });
+    
+    res.json({
+      txHash: tx.hash,
+      status: 'pending'
+    });
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+
+// WebSocket for real-time updates
+import { WebSocketServer } from 'ws';
+
+const wss = new WebSocketServer({ port: 8080 });
+
+wss.on('connection', (ws) => {
+  console.log('New WebSocket connection');
+  
+  // Subscribe to position events
+  client.positionManager.on('PositionOpened', (positionId, trader, asset) => {
+    ws.send(JSON.stringify({
+      type: 'positionOpened',
+      data: { positionId: positionId.toString(), trader, asset }
+    }));
+  });
+  
+  // Price updates
+  const priceInterval = setInterval(async () => {
+    try {
+      const prices = await client.priceOracle.getAllPrices();
+      ws.send(JSON.stringify({
+        type: 'priceUpdate',
+        data: prices.map(p => ({
+          asset: p.asset,
+          price: ethers.formatEther(p.price),
+          timestamp: p.timestamp
+        }))
+      }));
+    } catch (error) {
+      console.error('Price update error:', error);
+    }
+  }, 5000); // Every 5 seconds
+  
+  ws.on('close', () => {
+    clearInterval(priceInterval);
+  });
+});
+
+app.listen(3000, () => {
+  console.log('API server running on port 3000');
+});
+```
+
+### GraphQL Integration
+
+```typescript
+// graphql/schema.ts
+import { gql } from 'apollo-server-express';
+
+export const typeDefs = gql`
+  type Position {
+    id: String!
+    trader: String!
+    asset: String!
+    size: String!
+    isLong: Boolean!
+    leverage: Int!
+    entryPrice: String!
+    margin: String!
+    unrealizedPnL: String
+    marginRatio: String
+  }
+  
+  type MarginAccount {
+    user: String!
+    totalDeposited: String!
+    totalWithdrawn: String!
+    availableMargin: String!
+    usedMargin: String!
+    unrealizedPnL: String!
+    marginRatio: String!
+  }
+  
+  type Price {
+    asset: String!
+    price: String!
+    timestamp: Int!
+  }
+  
+  type FundingRate {
+    asset: String!
+    rate: String!
+    isPositive: Boolean!
+    nextUpdateTime: String!
+  }
+  
+  type Query {
+    position(id: String!): Position
+    positions(trader: String!): [Position!]!
+    marginAccount(address: String!): MarginAccount
+    price(asset: String!): Price
+    prices: [Price!]!
+    fundingRate(asset: String!): FundingRate
+    fundingRates: [FundingRate!]!
+  }
+  
+  type Mutation {
+    openPosition(
+      asset: String!
+      size: String!
+      leverage: Int!
+      isLong: Boolean!
+    ): TransactionResponse!
+    
+    closePosition(id: String!): TransactionResponse!
+    
+    deposit(amount: String!): TransactionResponse!
+    
+    withdraw(amount: String!): TransactionResponse!
+  }
+  
+  type TransactionResponse {
+    hash: String!
+    status: String!
+  }
+  
+  type Subscription {
+    priceUpdates(asset: String): Price!
+    positionUpdates(trader: String!): Position!
+    fundingRateUpdates(asset: String): FundingRate!
+  }
+`;
+
+// graphql/resolvers.ts
+export const resolvers = {
+  Query: {
+    position: async (_, { id }, { client }) => {
+      const position = await client.positionManager.getPosition(BigInt(id));
+      return formatPosition(position);
+    },
+    
+    positions: async (_, { trader }, { client }) => {
+      const positions = await client.positionManager.getAllPositions(trader);
+      return positions.map(formatPosition);
+    },
+    
+    marginAccount: async (_, { address }, { client }) => {
+      const account = await client.marginAccount.getMarginAccount(address);
+      return formatMarginAccount(account);
+    },
+    
+    price: async (_, { asset }, { client }) => {
+      const price = await client.priceOracle.getPrice(asset);
+      return {
+        asset,
+        price: ethers.formatEther(price),
+        timestamp: Date.now()
+      };
+    },
+    
+    prices: async (_, __, { client }) => {
+      const prices = await client.priceOracle.getAllPrices();
+      return prices.map(p => ({
+        asset: p.asset,
+        price: ethers.formatEther(p.price),
+        timestamp: p.timestamp
+      }));
+    }
+  },
+  
+  Mutation: {
+    openPosition: async (_, args, { client }) => {
+      const tx = await client.positionManager.openPosition({
+        asset: args.asset,
+        size: ethers.parseEther(args.size),
+        leverage: args.leverage,
+        isLong: args.isLong
+      });
+      
+      return {
+        hash: tx.hash,
+        status: 'pending'
+      };
+    },
+    
+    closePosition: async (_, { id }, { client }) => {
+      const tx = await client.positionManager.closePosition(BigInt(id));
+      return {
+        hash: tx.hash,
+        status: 'pending'
+      };
+    }
+  },
+  
+  Subscription: {
+    priceUpdates: {
+      subscribe: async function* (_, { asset }, { client }) {
+        while (true) {
+          const price = await client.priceOracle.getPrice(asset || 'ALPHA');
+          yield {
+            priceUpdates: {
+              asset: asset || 'ALPHA',
+              price: ethers.formatEther(price),
+              timestamp: Date.now()
+            }
+          };
+          await new Promise(resolve => setTimeout(resolve, 5000));
+        }
+      }
+    }
+  }
+};
+```
+
+## Mobile Integration
+
+### React Native Integration
+
+```typescript
+// services/AlphaFuturesService.ts
+import { AlphaFuturesClient } from '@alpha-futures/sdk';
+import { ethers } from 'ethers';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { WalletConnectProvider } from '@walletconnect/react-native';
+
+export class AlphaFuturesService {
+  private client: AlphaFuturesClient | null = null;
+  private walletConnector: WalletConnectProvider;
+  
+  constructor() {
+    this.walletConnector = new WalletConnectProvider({
+      infuraId: process.env.INFURA_ID,
+      bridge: 'https://bridge.walletconnect.org',
+    });
+  }
+  
+  async connect(): Promise<void> {
+    // Connect via WalletConnect
+    if (!this.walletConnector.connected) {
+      await this.walletConnector.createSession();
+    }
+    
+    // Create provider
+    const provider = new ethers.providers.Web3Provider(
+      this.walletConnector as any
+    );
+    
+    const signer = provider.getSigner();
+    
+    // Initialize client
+    this.client = new AlphaFuturesClient({
+      provider,
+      signer,
+      network: 'mainnet'
+    });
+    
+    // Save connection state
+    await AsyncStorage.setItem('walletConnected', 'true');
+  }
+  
+  async disconnect(): Promise<void> {
+    if (this.walletConnector.connected) {
+      await this.walletConnector.killSession();
+    }
+    
+    this.client = null;
+    await AsyncStorage.removeItem('walletConnected');
+  }
+  
+  getClient(): AlphaFuturesClient {
+    if (!this.client) {
+      throw new Error('Not connected');
+    }
+    return this.client;
+  }
+}
+
+// hooks/useAlphaFutures.ts (React Native)
+import { useState, useEffect } from 'react';
+import { AlphaFuturesService } from '../services/AlphaFuturesService';
+
+const service = new AlphaFuturesService();
+
+export function useAlphaFutures() {
+  const [isConnected, setIsConnected] = useState(false);
+  const [loading, setLoading] = useState(true);
+  
+  useEffect(() => {
+    checkConnection();
+  }, []);
+  
+  const checkConnection = async () => {
+    try {
+      const connected = await AsyncStorage.getItem('walletConnected');
+      if (connected === 'true') {
+        await service.connect();
+        setIsConnected(true);
+      }
+    } catch (error) {
+      console.error('Connection check failed:', error);
+    } finally {
+      setLoading(false);
+    }
+  };
+  
+  const connect = async () => {
+    try {
+      setLoading(true);
+      await service.connect();
+      setIsConnected(true);
+    } catch (error) {
+      throw error;
+    } finally {
+      setLoading(false);
+    }
+  };
+  
+  const disconnect = async () => {
+    try {
+      await service.disconnect();
+      setIsConnected(false);
+    } catch (error) {
+      console.error('Disconnect failed:', error);
+    }
+  };
+  
+  return {
+    client: isConnected ? service.getClient() : null,
+    isConnected,
+    loading,
+    connect,
+    disconnect
+  };
+}
+```
+
+## WebSocket & Real-time Data
+
+### Real-time Price Feed
+
+```typescript
+import { AlphaFuturesClient } from '@alpha-futures/sdk';
+import WebSocket from 'ws';
+
+class RealTimePriceFeed {
+  private client: AlphaFuturesClient;
+  private ws: WebSocket | null = null;
+  private subscribers: Map<string, Set<(price: bigint) => void>> = new Map();
+  
+  constructor(client: AlphaFuturesClient) {
+    this.client = client;
+  }
+  
+  connect(wsUrl: string): void {
+    this.ws = new WebSocket(wsUrl);
+    
+    this.ws.on('open', () => {
+      console.log('WebSocket connected');
+      this.subscribeToAllAssets();
+    });
+    
+    this.ws.on('message', (data: string) => {
+      const message = JSON.parse(data);
+      if (message.type === 'price') {
+        this.notifySubscribers(message.asset, BigInt(message.price));
+      }
+    });
+    
+    this.ws.on('error', (error) => {
+      console.error('WebSocket error:', error);
+      this.reconnect(wsUrl);
+    });
+    
+    this.ws.on('close', () => {
+      console.log('WebSocket closed');
+      this.reconnect(wsUrl);
+    });
+  }
+  
+  private reconnect(wsUrl: string): void {
+    setTimeout(() => {
+      console.log('Reconnecting...');
+      this.connect(wsUrl);
+    }, 5000);
+  }
+  
+  subscribeToPriceUpdates(
+    asset: string,
+    callback: (price: bigint) => void
+  ): () => void {
+    if (!this.subscribers.has(asset)) {
+      this.subscribers.set(asset, new Set());
+    }
+    
+    this.subscribers.get(asset)!.add(callback);
+    
+    // Return unsubscribe function
+    return () => {
+      this.subscribers.get(asset)?.delete(callback);
+    };
+  }
+  
+  private notifySubscribers(asset: string, price: bigint): void {
+    this.subscribers.get(asset)?.forEach(callback => {
+      callback(price);
+    });
+  }
+  
+  private subscribeToAllAssets(): void {
+    if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify({
+        type: 'subscribe',
+        assets: ['ALPHA', 'BETA', 'GAMMA']
+      }));
+    }
+  }
+}
+```
+
+### Event Streaming
+
+```typescript
+class EventStreamer {
+  private client: AlphaFuturesClient;
+  private eventHandlers: Map<string, Function[]> = new Map();
+  
+  constructor(client: AlphaFuturesClient) {
+    this.client = client;
+    this.setupEventListeners();
+  }
+  
+  private setupEventListeners(): void {
+    // Position events
+    this.client.positionManager.on('PositionOpened', (...args) => {
+      this.emit('positionOpened', ...args);
+    });
+    
+    this.client.positionManager.on('PositionClosed', (...args) => {
+      this.emit('positionClosed', ...args);
+    });
+    
+    // Liquidation events
+    this.client.liquidationEngine.on('PositionLiquidated', (...args) => {
+      this.emit('positionLiquidated', ...args);
+    });
+    
+    // Margin events
+    this.client.marginAccount.on('MarginDeposited', (...args) => {
+      this.emit('marginDeposited', ...args);
+    });
+    
+    this.client.marginAccount.on('MarginWithdrawn', (...args) => {
+      this.emit('marginWithdrawn', ...args);
+    });
+  }
+  
+  on(event: string, handler: Function): void {
+    if (!this.eventHandlers.has(event)) {
+      this.eventHandlers.set(event, []);
+    }
+    this.eventHandlers.get(event)!.push(handler);
+  }
+  
+  off(event: string, handler: Function): void {
+    const handlers = this.eventHandlers.get(event);
+    if (handlers) {
+      const index = handlers.indexOf(handler);
+      if (index > -1) {
+        handlers.splice(index, 1);
+      }
+    }
+  }
+  
+  private emit(event: string, ...args: any[]): void {
+    const handlers = this.eventHandlers.get(event);
+    if (handlers) {
+      handlers.forEach(handler => handler(...args));
+    }
+  }
+}
+```
+
+## Error Handling & Recovery
+
+### Comprehensive Error Handler
+
+```typescript
+import { ContractError, NetworkError, ValidationError } from '@alpha-futures/sdk';
+
+class ErrorHandler {
+  private retryAttempts: Map<string, number> = new Map();
+  private maxRetries: number = 3;
+  private retryDelay: number = 1000;
+  
+  async handleWithRetry<T>(
+    operation: () => Promise<T>,
+    context: string
+  ): Promise<T> {
+    const attempts = this.retryAttempts.get(context) || 0;
+    
+    try {
+      const result = await operation();
+      this.retryAttempts.delete(context);
+      return result;
+    } catch (error) {
+      return this.handleError(error, context, operation);
+    }
+  }
+  
+  private async handleError<T>(
+    error: any,
+    context: string,
+    operation: () => Promise<T>
+  ): Promise<T> {
+    const attempts = this.retryAttempts.get(context) || 0;
+    
+    // Categorize error
+    if (this.isRetryableError(error) && attempts < this.maxRetries) {
+      this.retryAttempts.set(context, attempts + 1);
+      
+      // Exponential backoff
+      const delay = this.retryDelay * Math.pow(2, attempts);
+      await this.sleep(delay);
+      
+      console.log(`Retrying ${context} (attempt ${attempts + 1}/${this.maxRetries})`);
+      return this.handleWithRetry(operation, context);
+    }
+    
+    // Non-retryable or max retries exceeded
+    this.retryAttempts.delete(context);
+    throw this.enhanceError(error, context);
+  }
+  
+  private isRetryableError(error: any): boolean {
+    // Network errors
+    if (error instanceof NetworkError) {
+      return true;
+    }
+    
+    // Specific error codes
+    const retryableCodes = [
+      'NETWORK_ERROR',
+      'TIMEOUT',
+      'SERVER_ERROR',
+      'ECONNRESET',
+      'ETIMEDOUT',
+      'ENOTFOUND'
+    ];
+    
+    return retryableCodes.includes(error.code);
+  }
+  
+  private enhanceError(error: any, context: string): Error {
+    if (error instanceof ValidationError) {
+      return new Error(`Validation failed in ${context}: ${error.message}`);
+    }
+    
+    if (error instanceof ContractError) {
+      return new Error(`Contract error in ${context}: ${error.reason || error.message}`);
+    }
+    
+    if (error instanceof NetworkError) {
+      return new Error(`Network error in ${context}: ${error.message}`);
+    }
+    
+    return new Error(`Unknown error in ${context}: ${error.message || error}`);
+  }
+  
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+// Usage
+const errorHandler = new ErrorHandler();
+
+async function safeOpenPosition(client: AlphaFuturesClient, params: any) {
+  return errorHandler.handleWithRetry(
+    () => client.positionManager.openPosition(params),
+    'openPosition'
+  );
+}
+```
+
+## Testing Your Integration
+
+### Unit Tests
+
+```typescript
+// __tests__/integration.test.ts
+import { AlphaFuturesClient } from '@alpha-futures/sdk';
+import { ethers } from 'ethers';
+
+jest.mock('@alpha-futures/sdk');
+
+describe('Alpha Futures Integration', () => {
+  let client: AlphaFuturesClient;
+  let mockProvider: any;
+  let mockSigner: any;
+  
+  beforeEach(() => {
+    mockProvider = {
+      getNetwork: jest.fn().mockResolvedValue({ chainId: 1 }),
+    };
+    
+    mockSigner = {
+      getAddress: jest.fn().mockResolvedValue('0x123...'),
+    };
+    
+    client = new AlphaFuturesClient({
+      provider: mockProvider,
+      signer: mockSigner,
+      network: 'mainnet'
+    });
+  });
+  
+  describe('Position Management', () => {
+    it('should open a position', async () => {
+      const mockTx = { hash: '0xabc...', wait: jest.fn() };
+      client.positionManager.openPosition = jest.fn().mockResolvedValue(mockTx);
+      
+      const params = {
+        asset: 'ALPHA',
+        size: ethers.parseEther('1000'),
+        leverage: 3,
+        isLong: true
+      };
+      
+      const tx = await client.positionManager.openPosition(params);
+      
+      expect(tx.hash).toBe('0xabc...');
+      expect(client.positionManager.openPosition).toHaveBeenCalledWith(params);
+    });
+  });
+});
+```
+
+### Integration Tests
+
+```typescript
+// __tests__/e2e.test.ts
+import { AlphaFuturesClient } from '@alpha-futures/sdk';
+import { ethers } from 'ethers';
+
+describe('E2E Integration Tests', () => {
+  let client: AlphaFuturesClient;
+  
+  beforeAll(async () => {
+    // Use test network
+    client = new AlphaFuturesClient({
+      rpcUrl: process.env.TEST_RPC_URL,
+      privateKey: process.env.TEST_PRIVATE_KEY,
+      network: 'testnet'
+    });
+  });
+  
+  it('should complete full trading flow', async () => {
+    // 1. Check initial balance
+    const initialAccount = await client.marginAccount.getMarginAccount(
+      await client.signer.getAddress()
+    );
+    
+    // 2. Deposit margin
+    const depositTx = await client.marginAccount.deposit(
+      ethers.parseEther('100')
+    );
+    await depositTx.wait();
+    
+    // 3. Open position
+    const openTx = await client.positionManager.openPosition({
+      asset: 'ALPHA',
+      size: ethers.parseEther('300'),
+      leverage: 3,
+      isLong: true
+    });
+    const receipt = await openTx.wait();
+    
+    // Extract position ID from events
+    const positionId = extractPositionId(receipt);
+    
+    // 4. Check position
+    const position = await client.positionManager.getPosition(positionId);
+    expect(position.size).toBe(ethers.parseEther('300'));
+    
+    // 5. Close position
+    const closeTx = await client.positionManager.closePosition(positionId);
+    await closeTx.wait();
+    
+    // 6. Verify final state
+    const finalAccount = await client.marginAccount.getMarginAccount(
+      await client.signer.getAddress()
+    );
+    
+    expect(finalAccount.usedMargin).toBe(0n);
+  }, 60000); // 60 second timeout
+});
+```
+
+## Performance Optimization
+
+### Caching Layer
+
+```typescript
+class CachedAlphaFuturesClient extends AlphaFuturesClient {
+  private cache: Map<string, { value: any; timestamp: number }> = new Map();
+  private cacheTTL: number = 5000; // 5 seconds
+  
+  async getPrice(asset: string): Promise<bigint> {
+    const cacheKey = `price:${asset}`;
+    const cached = this.getFromCache(cacheKey);
+    
+    if (cached) {
+      return cached;
+    }
+    
+    const price = await super.priceOracle.getPrice(asset);
+    this.setCache(cacheKey, price);
+    
+    return price;
+  }
+  
+  private getFromCache(key: string): any {
+    const item = this.cache.get(key);
+    if (!item) return null;
+    
+    if (Date.now() - item.timestamp > this.cacheTTL) {
+      this.cache.delete(key);
+      return null;
+    }
+    
+    return item.value;
+  }
+  
+  private setCache(key: string, value: any): void {
+    this.cache.set(key, {
+      value,
+      timestamp: Date.now()
+    });
+  }
+  
+  clearCache(): void {
+    this.cache.clear();
+  }
+}
+```
+
+### Batch Operations
+
+```typescript
+class BatchOperations {
+  private client: AlphaFuturesClient;
+  private queue: Array<{
+    operation: () => Promise<any>;
+    resolve: (value: any) => void;
+    reject: (error: any) => void;
+  }> = [];
+  private processing: boolean = false;
+  
+  constructor(client: AlphaFuturesClient) {
+    this.client = client;
+  }
+  
+  async addToQueue<T>(operation: () => Promise<T>): Promise<T> {
+    return new Promise((resolve, reject) => {
+      this.queue.push({ operation, resolve, reject });
+      this.processQueue();
+    });
+  }
+  
+  private async processQueue(): Promise<void> {
+    if (this.processing || this.queue.length === 0) {
+      return;
+    }
+    
+    this.processing = true;
+    
+    while (this.queue.length > 0) {
+      const batch = this.queue.splice(0, 10); // Process 10 at a time
+      
+      await Promise.all(
+        batch.map(async ({ operation, resolve, reject }) => {
+          try {
+            const result = await operation();
+            resolve(result);
+          } catch (error) {
+            reject(error);
+          }
+        })
+      );
+      
+      // Rate limiting
+      await this.sleep(100);
+    }
+    
+    this.processing = false;
+  }
+  
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+```
+
+## Security Best Practices
+
+### 1. Private Key Security
+
+- Never expose private keys in code
+- Use environment variables or secure key management systems
+- Implement key rotation policies
+
+### 2. Input Validation
+
+```typescript
+class SecureIntegration {
+  validatePositionParams(params: any): void {
+    // Asset validation
+    if (!this.isValidAsset(params.asset)) {
+      throw new ValidationError('Invalid asset', 'asset');
+    }
+    
+    // Size validation
+    const size = BigInt(params.size);
+    if (size < MIN_POSITION_SIZE) {
+      throw new ValidationError('Position size too small', 'size');
+    }
+    
+    // Leverage validation
+    if (params.leverage < 1 || params.leverage > 10) {
+      throw new ValidationError('Invalid leverage', 'leverage');
+    }
+  }
+  
+  private isValidAsset(asset: string): boolean {
+    const validAssets = ['ALPHA', 'BETA', 'GAMMA'];
+    return validAssets.includes(asset);
+  }
+}
+```
+
+### 3. Rate Limiting
+
+```typescript
+class RateLimiter {
+  private requests: Map<string, number[]> = new Map();
+  private limit: number;
+  private window: number;
+  
+  constructor(limit: number = 100, windowMs: number = 60000) {
+    this.limit = limit;
+    this.window = windowMs;
+  }
+  
+  isAllowed(identifier: string): boolean {
+    const now = Date.now();
+    const requests = this.requests.get(identifier) || [];
+    
+    // Remove old requests
+    const validRequests = requests.filter(time => now - time < this.window);
+    
+    if (validRequests.length >= this.limit) {
+      return false;
+    }
+    
+    validRequests.push(now);
+    this.requests.set(identifier, validRequests);
+    
+    return true;
+  }
+}
+```
+
+### 4. Transaction Security
+
+```typescript
+class SecureTransactionManager {
+  async sendTransaction(
+    client: AlphaFuturesClient,
+    operation: () => Promise<any>,
+    options: {
+      maxGasPrice?: bigint;
+      requireConfirmations?: number;
+    } = {}
+  ): Promise<any> {
+    // Check gas price
+    if (options.maxGasPrice) {
+      const gasPrice = await client.provider.getGasPrice();
+      if (gasPrice > options.maxGasPrice) {
+        throw new Error('Gas price too high');
+      }
+    }
+    
+    // Execute transaction
+    const tx = await operation();
+    
+    // Wait for confirmations
+    const receipt = await tx.wait(options.requireConfirmations || 1);
+    
+    // Verify success
+    if (receipt.status !== 1) {
+      throw new Error('Transaction failed');
+    }
+    
+    return receipt;
+  }
+}
+```
+
+## Conclusion
+
+Integrating the Alpha Futures SDK provides powerful capabilities for building trading applications. Key considerations:
+
+1. **Security First**: Always prioritize security in your implementation
+2. **Error Handling**: Implement robust error handling and recovery
+3. **Performance**: Use caching and batching for optimal performance
+4. **Testing**: Thoroughly test all integration points
+5. **Monitoring**: Implement logging and monitoring for production
+
+For additional support and examples, visit the [GitHub repository](https://github.com/alpha-futures/sdk) or join our [Discord community](https://discord.gg/alphafutures).