@megatao/sdk 1.1.0

package/docs/guides/TRADING_GUIDE.md

@@ -0,0 +1,677 @@
+# Alpha Futures Trading Guide
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Understanding Perpetual Futures](#understanding-perpetual-futures)
+- [Getting Started](#getting-started)
+- [Trading Strategies](#trading-strategies)
+- [Risk Management](#risk-management)
+- [Funding Rates](#funding-rates)
+- [Liquidations](#liquidations)
+- [Advanced Strategies](#advanced-strategies)
+- [Common Pitfalls](#common-pitfalls)
+- [FAQ](#faq)
+
+## Introduction
+
+Alpha Futures is a decentralized perpetual futures protocol on Bittensor EVM that enables leveraged trading of Alpha tokens using TAO as collateral. This guide will help you understand how to trade effectively on the platform.
+
+### Key Features
+
+- **Synthetic Exposure**: Trade Alpha token price movements without holding actual tokens
+- **TAO Settlement**: All profits/losses are settled in TAO
+- **Up to 10x Leverage**: Amplify your trading positions
+- **No Expiry**: Perpetual contracts that never expire
+- **Funding Rates**: Mechanism to keep futures prices aligned with spot
+
+## Understanding Perpetual Futures
+
+### What are Perpetual Futures?
+
+Perpetual futures are derivative contracts that:
+- Track the price of an underlying asset (Alpha tokens)
+- Have no expiration date
+- Allow both long and short positions
+- Use funding rates to maintain price parity with spot markets
+
+### Key Concepts
+
+**Leverage**: Multiply your exposure to price movements
+- 2x leverage = $2,000 position with $1,000 margin
+- 10x leverage = $10,000 position with $1,000 margin
+
+**Margin**: Collateral required to open and maintain positions
+- Initial Margin: Required to open a position (33.33% for 3x leverage)
+- Maintenance Margin: Minimum required to keep position open (20%)
+
+**Funding Rate**: Periodic payments between longs and shorts
+- Positive rate: Longs pay shorts
+- Negative rate: Shorts pay longs
+
+## Getting Started
+
+### Step 1: Setup
+
+```typescript
+import { AlphaFuturesClient } from '@alpha-futures/sdk';
+import { ethers } from 'ethers';
+
+const client = new AlphaFuturesClient({
+  rpcUrl: 'https://your-rpc-url',
+  privateKey: 'your-private-key',
+  network: 'mainnet'
+});
+```
+
+### Step 2: Deposit Margin
+
+Before trading, deposit TAO as margin:
+
+```typescript
+// Deposit 1,000 TAO
+const depositAmount = ethers.parseEther('1000');
+const tx = await client.marginAccount.deposit(depositAmount);
+await tx.wait();
+
+// Check your account
+const account = await client.marginAccount.getMarginAccount(yourAddress);
+console.log('Available margin:', ethers.formatEther(account.availableMargin));
+```
+
+### Step 3: Check Market Conditions
+
+```typescript
+// Get current price
+const price = await client.priceOracle.getPrice('ALPHA');
+console.log('ALPHA price:', ethers.formatEther(price));
+
+// Check funding rate
+const funding = await client.fundingRate.getCurrentFundingRate('ALPHA');
+console.log('Funding rate:', funding.rate / 100n, '%');
+console.log('Longs pay shorts:', funding.isPositive);
+```
+
+### Step 4: Open Your First Position
+
+```typescript
+// Open a 3x leveraged long position
+const position = await client.positionManager.openPosition({
+  asset: 'ALPHA',
+  size: ethers.parseEther('3000'), // $3,000 position
+  leverage: 3,
+  isLong: true,
+  slippage: 50 // 0.5% max slippage
+});
+
+await position.wait();
+console.log('Position opened!');
+```
+
+## Trading Strategies
+
+### 1. Trend Following
+
+**Strategy**: Trade in the direction of the prevailing trend
+
+```typescript
+async function trendFollowingStrategy() {
+  // Get price history (example using external data)
+  const currentPrice = await client.priceOracle.getPrice('ALPHA');
+  
+  // Simple moving average calculation (pseudo-code)
+  const sma20 = calculateSMA(priceHistory, 20);
+  const sma50 = calculateSMA(priceHistory, 50);
+  
+  // Bullish signal: Price above both SMAs
+  if (currentPrice > sma20 && sma20 > sma50) {
+    await client.positionManager.openPosition({
+      asset: 'ALPHA',
+      size: ethers.parseEther('1000'),
+      leverage: 2,
+      isLong: true
+    });
+  }
+  
+  // Bearish signal: Price below both SMAs
+  if (currentPrice < sma20 && sma20 < sma50) {
+    await client.positionManager.openPosition({
+      asset: 'ALPHA',
+      size: ethers.parseEther('1000'),
+      leverage: 2,
+      isLong: false
+    });
+  }
+}
+```
+
+### 2. Range Trading
+
+**Strategy**: Buy at support, sell at resistance in ranging markets
+
+```typescript
+async function rangeTrading(support: bigint, resistance: bigint) {
+  const currentPrice = await client.priceOracle.getPrice('ALPHA');
+  const positions = await client.positionManager.getAllPositions(yourAddress);
+  
+  // Near support - open long
+  if (currentPrice <= support * 102n / 100n) { // Within 2% of support
+    if (!positions.some(p => p.isLong)) {
+      await client.positionManager.openPosition({
+        asset: 'ALPHA',
+        size: ethers.parseEther('2000'),
+        leverage: 3,
+        isLong: true
+      });
+    }
+  }
+  
+  // Near resistance - open short
+  if (currentPrice >= resistance * 98n / 100n) { // Within 2% of resistance
+    if (!positions.some(p => !p.isLong)) {
+      await client.positionManager.openPosition({
+        asset: 'ALPHA',
+        size: ethers.parseEther('2000'),
+        leverage: 3,
+        isLong: false
+      });
+    }
+  }
+}
+```
+
+### 3. Funding Rate Arbitrage
+
+**Strategy**: Capture funding payments when rates are extreme
+
+```typescript
+async function fundingArbitrage() {
+  const funding = await client.fundingRate.getCurrentFundingRate('ALPHA');
+  
+  // High positive funding rate - shorts earn
+  if (funding.isPositive && funding.rate > 30n) { // > 0.3%
+    await client.positionManager.openPosition({
+      asset: 'ALPHA',
+      size: ethers.parseEther('5000'),
+      leverage: 2,
+      isLong: false // Short to earn funding
+    });
+  }
+  
+  // High negative funding rate - longs earn
+  if (!funding.isPositive && funding.rate > 30n) { // < -0.3%
+    await client.positionManager.openPosition({
+      asset: 'ALPHA',
+      size: ethers.parseEther('5000'),
+      leverage: 2,
+      isLong: true // Long to earn funding
+    });
+  }
+}
+```
+
+### 4. Scalping
+
+**Strategy**: Quick trades on small price movements
+
+```typescript
+async function scalpingStrategy() {
+  const entryPrice = await client.priceOracle.getPrice('ALPHA');
+  
+  // Open position
+  const tx = await client.positionManager.openPosition({
+    asset: 'ALPHA',
+    size: ethers.parseEther('10000'),
+    leverage: 5,
+    isLong: true
+  });
+  
+  const receipt = await tx.wait();
+  const positionId = extractPositionId(receipt);
+  
+  // Monitor price
+  const checkPrice = setInterval(async () => {
+    const currentPrice = await client.priceOracle.getPrice('ALPHA');
+    const priceChange = (currentPrice - entryPrice) * 100n / entryPrice;
+    
+    // Take profit at 0.5% gain or stop loss at 0.3% loss
+    if (priceChange >= 50n || priceChange <= -30n) {
+      await client.positionManager.closePosition(positionId);
+      clearInterval(checkPrice);
+    }
+  }, 5000); // Check every 5 seconds
+}
+```
+
+## Risk Management
+
+### Position Sizing
+
+Never risk more than you can afford to lose. Use proper position sizing:
+
+```typescript
+function calculatePositionSize(
+  accountBalance: bigint,
+  riskPercentage: number,
+  stopLossPercentage: number
+): bigint {
+  // Risk 2% of account per trade with 5% stop loss
+  const riskAmount = accountBalance * BigInt(riskPercentage) / 100n;
+  const positionSize = riskAmount * 100n / BigInt(stopLossPercentage);
+  return positionSize;
+}
+
+// Example: $10,000 account, 2% risk, 5% stop loss
+const accountBalance = ethers.parseEther('10000');
+const positionSize = calculatePositionSize(accountBalance, 2, 5);
+// Result: $4,000 position size
+```
+
+### Stop Losses
+
+Always use stop losses to limit downside:
+
+```typescript
+async function monitorStopLoss(
+  positionId: bigint,
+  stopLossPrice: bigint,
+  isLong: boolean
+) {
+  const checkPrice = setInterval(async () => {
+    const currentPrice = await client.priceOracle.getPrice('ALPHA');
+    
+    const shouldStop = isLong 
+      ? currentPrice <= stopLossPrice
+      : currentPrice >= stopLossPrice;
+    
+    if (shouldStop) {
+      await client.positionManager.closePosition(positionId);
+      clearInterval(checkPrice);
+      console.log('Stop loss triggered');
+    }
+  }, 10000); // Check every 10 seconds
+}
+```
+
+### Leverage Guidelines
+
+- **Beginners**: Start with 1-2x leverage
+- **Intermediate**: 2-5x leverage with strict risk management
+- **Advanced**: Up to 10x only for short-term trades with tight stops
+
+### Diversification
+
+Don't put all margin into one position:
+
+```typescript
+async function diversifiedPortfolio() {
+  const account = await client.marginAccount.getMarginAccount(yourAddress);
+  const availableMargin = account.availableMargin;
+  
+  // Allocate margin across multiple positions
+  const positions = [
+    { asset: 'ALPHA', allocation: 40, leverage: 2, isLong: true },
+    { asset: 'BETA', allocation: 30, leverage: 3, isLong: false },
+    { asset: 'GAMMA', allocation: 30, leverage: 2, isLong: true }
+  ];
+  
+  for (const pos of positions) {
+    const margin = availableMargin * BigInt(pos.allocation) / 100n;
+    const size = margin * BigInt(pos.leverage);
+    
+    await client.positionManager.openPosition({
+      asset: pos.asset,
+      size,
+      leverage: pos.leverage,
+      isLong: pos.isLong
+    });
+  }
+}
+```
+
+## Funding Rates
+
+### Understanding Funding
+
+Funding rates balance long and short demand:
+
+```typescript
+async function analyzeFunding() {
+  const funding = await client.fundingRate.getCurrentFundingRate('ALPHA');
+  
+  console.log('Current funding rate:', funding.rate / 100n, '%');
+  console.log('Annualized:', funding.rate * 3n * 365n / 100n, '%'); // 3 times daily
+  
+  // Calculate daily funding cost/income
+  const positionSize = ethers.parseEther('10000');
+  const dailyFunding = positionSize * funding.rate * 3n / 10000n;
+  
+  if (funding.isPositive) {
+    console.log('Longs pay:', ethers.formatEther(dailyFunding), 'TAO daily');
+    console.log('Shorts earn:', ethers.formatEther(dailyFunding), 'TAO daily');
+  } else {
+    console.log('Shorts pay:', ethers.formatEther(dailyFunding), 'TAO daily');
+    console.log('Longs earn:', ethers.formatEther(dailyFunding), 'TAO daily');
+  }
+}
+```
+
+### Funding Strategy
+
+Use funding rates to enhance returns:
+
+```typescript
+async function fundingStrategy() {
+  const funding = await client.fundingRate.getCurrentFundingRate('ALPHA');
+  const price = await client.priceOracle.getPrice('ALPHA');
+  
+  // Only take positions when funding is favorable
+  if (bullishOnAlpha && (!funding.isPositive || funding.rate < 10n)) {
+    // Open long when funding is negative or low positive
+    await openLongPosition();
+  }
+  
+  if (bearishOnAlpha && (funding.isPositive && funding.rate > 20n)) {
+    // Open short when funding is high positive
+    await openShortPosition();
+  }
+}
+```
+
+## Liquidations
+
+### Avoiding Liquidation
+
+Monitor your margin ratio:
+
+```typescript
+async function monitorLiquidationRisk() {
+  const positions = await client.positionManager.getAllPositions(yourAddress);
+  
+  for (const position of positions) {
+    const status = await client.liquidationEngine.checkLiquidationStatus(position.id);
+    
+    console.log(`Position ${position.id}:`);
+    console.log(`Margin ratio: ${status.marginRatio / 100n}%`);
+    console.log(`Liquidation price: ${ethers.formatEther(status.liquidationPrice)}`);
+    
+    // Warning if close to liquidation
+    if (status.marginRatio < 2500n) { // Below 25%
+      console.warn('⚠️  Position at risk! Consider adding margin or closing.');
+      
+      // Add margin to avoid liquidation
+      if (status.marginRatio < 2200n) { // Below 22%
+        const additionalMargin = ethers.parseEther('500');
+        await client.positionManager.modifyPosition(
+          position.id,
+          additionalMargin,
+          true // add margin
+        );
+      }
+    }
+  }
+}
+```
+
+### Liquidation Hunting
+
+Advanced traders can profit from liquidating underwater positions:
+
+```typescript
+async function liquidationHunter() {
+  // Get at-risk positions
+  const atRisk = await client.liquidationEngine.getAtRiskPositions(2100n); // 21% margin
+  
+  for (const position of atRisk) {
+    console.log(`Found at-risk position: ${position.positionId}`);
+    console.log(`Margin ratio: ${position.marginRatio / 100n}%`);
+    
+    // Check if profitable to liquidate
+    const gasEstimate = await client.liquidationEngine.estimateGas
+      .liquidatePosition(position.positionId);
+    
+    const gasCost = gasEstimate * (await provider.getFeeData()).gasPrice;
+    const expectedBonus = position.remainingMargin * 5n / 100n; // 5% bonus
+    
+    if (expectedBonus > gasCost * 2n) { // 2x gas cost for profit
+      const tx = await client.liquidationEngine.liquidatePosition(position.positionId);
+      await tx.wait();
+      console.log('Position liquidated! Bonus earned:', ethers.formatEther(expectedBonus));
+    }
+  }
+}
+```
+
+## Advanced Strategies
+
+### Market Making
+
+Provide liquidity by maintaining balanced positions:
+
+```typescript
+class MarketMaker {
+  private client: AlphaFuturesClient;
+  private spread: bigint = 50n; // 0.5% spread
+  
+  async maintainQuotes() {
+    const midPrice = await this.client.priceOracle.getPrice('ALPHA');
+    const positions = await this.client.positionManager.getAllPositions(this.address);
+    
+    // Calculate current exposure
+    let netExposure = 0n;
+    for (const pos of positions) {
+      netExposure += pos.isLong ? pos.size : -pos.size;
+    }
+    
+    // Rebalance if needed
+    if (netExposure > ethers.parseEther('1000')) {
+      // Too long - open short to balance
+      await this.client.positionManager.openPosition({
+        asset: 'ALPHA',
+        size: netExposure,
+        leverage: 2,
+        isLong: false
+      });
+    } else if (netExposure < ethers.parseEther('-1000')) {
+      // Too short - open long to balance
+      await this.client.positionManager.openPosition({
+        asset: 'ALPHA',
+        size: -netExposure,
+        leverage: 2,
+        isLong: true
+      });
+    }
+  }
+}
+```
+
+### Delta Neutral Strategies
+
+Profit from funding while minimizing directional risk:
+
+```typescript
+async function deltaNeutralFunding() {
+  const funding = await client.fundingRate.getCurrentFundingRate('ALPHA');
+  
+  // Only enter if funding is significant
+  if (funding.rate < 20n) return; // Less than 0.2%
+  
+  const size = ethers.parseEther('10000');
+  
+  if (funding.isPositive) {
+    // Open short on futures (earn funding)
+    await client.positionManager.openPosition({
+      asset: 'ALPHA',
+      size,
+      leverage: 1,
+      isLong: false
+    });
+    
+    // Buy spot ALPHA to hedge (example - would need spot exchange integration)
+    // await spotExchange.buy('ALPHA', size);
+  }
+  
+  // Monitor and close when funding normalizes
+}
+```
+
+### Statistical Arbitrage
+
+Trade mean reversion between correlated assets:
+
+```typescript
+async function statArb(asset1: string, asset2: string) {
+  const price1 = await client.priceOracle.getPrice(asset1);
+  const price2 = await client.priceOracle.getPrice(asset2);
+  
+  // Calculate price ratio
+  const ratio = price1 * PRECISION / price2;
+  const historicalMean = calculateHistoricalMean(asset1, asset2);
+  const stdDev = calculateStdDev(asset1, asset2);
+  
+  // Trade when ratio deviates significantly
+  const zScore = (ratio - historicalMean) / stdDev;
+  
+  if (zScore > 2n) {
+    // Ratio too high - short asset1, long asset2
+    await client.positionManager.openPosition({
+      asset: asset1,
+      size: ethers.parseEther('5000'),
+      leverage: 3,
+      isLong: false
+    });
+    
+    await client.positionManager.openPosition({
+      asset: asset2,
+      size: ethers.parseEther('5000'),
+      leverage: 3,
+      isLong: true
+    });
+  }
+}
+```
+
+## Common Pitfalls
+
+### 1. Over-leveraging
+
+**Problem**: Using maximum leverage on every trade
+**Solution**: Start small and increase leverage gradually
+
+### 2. Ignoring Funding Rates
+
+**Problem**: Not accounting for funding costs
+**Solution**: Factor funding into your P&L calculations
+
+### 3. No Stop Losses
+
+**Problem**: Letting losses run hoping for reversal
+**Solution**: Always set stop losses before entering
+
+### 4. Revenge Trading
+
+**Problem**: Increasing position size after losses
+**Solution**: Stick to your position sizing rules
+
+### 5. FOMO Trading
+
+**Problem**: Entering positions due to fear of missing out
+**Solution**: Wait for your setup and trade your plan
+
+## FAQ
+
+### Q: What happens if I get liquidated?
+
+When liquidated:
+- Your position is closed at market price
+- Remaining margin (if any) is returned minus liquidation penalty
+- A 5% liquidation bonus goes to the liquidator
+- The rest goes to the insurance fund
+
+### Q: How often are funding rates charged?
+
+Funding rates are typically charged every 8 hours at:
+- 00:00 UTC
+- 08:00 UTC  
+- 16:00 UTC
+
+### Q: Can I trade with less than the minimum position size?
+
+No, positions must meet the minimum size requirement (usually 100 TAO worth).
+
+### Q: What's the maximum position size?
+
+Position size is limited by:
+- Your available margin
+- Protocol's risk limits
+- Available liquidity in the vault
+
+### Q: How do I calculate my break-even price?
+
+```typescript
+function calculateBreakeven(
+  entryPrice: bigint,
+  isLong: boolean,
+  tradingFee: bigint,
+  expectedFunding: bigint,
+  positionSize: bigint
+): bigint {
+  const totalCosts = tradingFee + expectedFunding;
+  const costPercentage = totalCosts * 10000n / positionSize;
+  
+  if (isLong) {
+    return entryPrice * (10000n + costPercentage) / 10000n;
+  } else {
+    return entryPrice * (10000n - costPercentage) / 10000n;
+  }
+}
+```
+
+### Q: What's the best time to trade?
+
+- **High volatility**: More opportunities but higher risk
+- **Low funding rates**: Reduced carrying costs
+- **Good liquidity**: Tighter spreads and less slippage
+
+### Q: How do I track my performance?
+
+```typescript
+async function trackPerformance(startDate: number, endDate: number) {
+  const account = await client.marginAccount.getMarginAccount(yourAddress);
+  
+  // Get all closed positions in date range
+  const events = await client.positionManager.queryFilter(
+    client.positionManager.filters.PositionClosed(null, yourAddress),
+    startDate,
+    endDate
+  );
+  
+  let totalPnL = 0n;
+  let winCount = 0;
+  let lossCount = 0;
+  
+  for (const event of events) {
+    const pnl = event.args.realizedPnL;
+    totalPnL += pnl;
+    
+    if (pnl > 0n) winCount++;
+    else lossCount++;
+  }
+  
+  console.log('Total P&L:', ethers.formatEther(totalPnL));
+  console.log('Win rate:', (winCount / (winCount + lossCount) * 100).toFixed(2), '%');
+  console.log('Total trades:', winCount + lossCount);
+}
+```
+
+## Conclusion
+
+Successful trading on Alpha Futures requires:
+- Understanding of perpetual futures mechanics
+- Solid risk management
+- Disciplined execution
+- Continuous learning and adaptation
+
+Start small, manage risk carefully, and always trade within your means. The protocol provides powerful tools for both speculation and hedging - use them wisely.
+
+Remember: Past performance doesn't guarantee future results. Always do your own research and never trade with funds you cannot afford to lose.