@megatao/sdk 1.1.0

package/docs/guides/GETTING_STARTED.md

@@ -0,0 +1,316 @@
+# Getting Started with Alpha Futures SDK
+
+This guide will help you get up and running with the Alpha Futures SDK and CLI in just a few minutes.
+
+## Prerequisites
+
+- Node.js 16.0.0 or higher
+- npm or yarn package manager
+- An Ethereum wallet with TAO tokens for trading
+- Access to an Ethereum RPC endpoint
+
+## Installation
+
+### Option 1: Global Installation (Recommended for CLI usage)
+
+```bash
+npm install -g @alpha-futures/sdk
+```
+
+### Option 2: Project Installation
+
+```bash
+npm install @alpha-futures/sdk
+```
+
+### Option 3: Run without Installation
+
+```bash
+npx @alpha-futures/sdk --help
+```
+
+## Initial Setup
+
+### 1. Create Configuration File
+
+Copy the example configuration file:
+
+```bash
+cp config.example.json config.json
+```
+
+Edit `config.json` with your settings:
+
+```json
+{
+  "network": "mainnet",
+  "rpcUrl": "https://your-rpc-url.com"
+}
+```
+
+### 2. Set Up Environment Variables
+
+Copy the example environment file:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your private key:
+
+```env
+PRIVATE_KEY=your_private_key_here
+NETWORK=mainnet
+RPC_URL=https://your-rpc-url.com
+```
+
+**Security Note**: Never commit `.env` files to version control!
+
+### 3. Test Your Setup
+
+Run the CLI to verify installation:
+
+```bash
+alpha-futures --version
+alpha-futures account info
+```
+
+## Your First Trade
+
+### Using the Interactive CLI
+
+1. Launch the interactive interface:
+
+```bash
+alpha-futures interactive
+```
+
+2. Select "Open Position" from the menu
+
+3. Follow the prompts to:
+   - Choose an asset (e.g., ALPHA)
+   - Enter position size
+   - Select leverage (1-10x)
+   - Choose direction (long/short)
+
+### Using Command Line
+
+Open a long position with 3x leverage:
+
+```bash
+alpha-futures position open --asset ALPHA --size 1000 --leverage 3 --long
+```
+
+### Using the SDK
+
+```typescript
+import { AlphaFuturesClient } from '@alpha-futures/sdk';
+
+async function openFirstPosition() {
+  // Initialize client
+  const client = new AlphaFuturesClient({
+    network: 'mainnet',
+    privateKey: process.env.PRIVATE_KEY
+  });
+
+  // Check account balance
+  const margin = await client.margin.getMarginAccount();
+  console.log('Available margin:', margin.availableMargin);
+
+  // Open a position
+  const position = await client.positions.openPosition({
+    asset: 'ALPHA',
+    size: 1000,
+    leverage: 3,
+    isLong: true
+  });
+
+  console.log('Position opened:', position.id);
+}
+
+openFirstPosition().catch(console.error);
+```
+
+## Common Operations
+
+### Check Your Positions
+
+```bash
+# List all positions
+alpha-futures position list
+
+# Get specific position details
+alpha-futures position info 0x00000000000000000000000000000001
+```
+
+### Monitor Market Data
+
+```bash
+# Check current prices
+alpha-futures market prices
+
+# View funding rates
+alpha-futures market funding-rates
+
+# See market statistics
+alpha-futures market stats
+```
+
+### Manage Your Account
+
+```bash
+# Check balance
+alpha-futures account balance
+
+# Deposit more margin
+alpha-futures account deposit --amount 500
+
+# Withdraw profits
+alpha-futures account withdraw --amount 200
+```
+
+## Best Practices
+
+### 1. Start Small
+
+- Begin with small position sizes to understand the platform
+- Use lower leverage (2-3x) initially
+- Monitor funding rates before opening positions
+
+### 2. Risk Management
+
+- Always maintain sufficient margin (>50% recommended)
+- Set stop-loss levels mentally or through monitoring
+- Diversify across multiple positions
+
+### 3. Monitor Positions
+
+- Check funding payments regularly
+- Watch for liquidation warnings
+- Keep track of unrealized P&L
+
+### 4. Use the Interactive CLI
+
+The interactive CLI provides:
+- Visual feedback and confirmations
+- Input validation
+- Real-time price updates
+- Transaction status tracking
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Insufficient margin" error**
+   - Check your account balance: `alpha-futures account balance`
+   - Deposit more TAO: `alpha-futures account deposit --amount 1000`
+
+2. **"Cannot connect to network"**
+   - Verify your RPC URL is correct
+   - Check your internet connection
+   - Try a different RPC endpoint
+
+3. **"Invalid private key"**
+   - Ensure your private key is correctly formatted
+   - Don't include '0x' prefix in .env file
+   - Check for extra spaces or newlines
+
+4. **"Gas estimation failed"**
+   - Increase gas limit in settings
+   - Check if you have enough ETH for gas
+   - Try again during lower network congestion
+
+### Debug Mode
+
+Enable debug logging for more information:
+
+```bash
+DEBUG=true alpha-futures position list
+```
+
+## Next Steps
+
+1. **Explore Advanced Features**
+   - Learn about limit orders
+   - Understand funding rate arbitrage
+   - Explore batch operations
+
+2. **Integrate the SDK**
+   - Build trading bots
+   - Create position monitors
+   - Develop custom strategies
+
+3. **Join the Community**
+   - Discord: [https://discord.gg/alphafutures](https://discord.gg/alphafutures)
+   - Follow updates on Twitter
+   - Contribute to the SDK on GitHub
+
+## Example Scripts
+
+### Position Monitor
+
+```typescript
+// monitor.ts
+import { AlphaFuturesClient } from '@alpha-futures/sdk';
+
+const client = new AlphaFuturesClient({
+  network: 'mainnet',
+  privateKey: process.env.PRIVATE_KEY
+});
+
+async function monitorPositions() {
+  const positions = await client.positions.getAllPositions();
+  
+  for (const position of positions) {
+    const pnl = await client.positions.getUnrealizedPnL(position.id);
+    const marginRatio = await client.positions.getMarginRatio(position.id);
+    
+    console.log(`Position ${position.id}:`);
+    console.log(`  P&L: ${pnl > 0 ? '+' : ''}${pnl.toFixed(2)} TAO`);
+    console.log(`  Margin Ratio: ${marginRatio.toFixed(2)}%`);
+    
+    if (marginRatio < 25) {
+      console.warn('  ⚠️  Low margin - consider adding margin!');
+    }
+  }
+}
+
+// Run every 60 seconds
+setInterval(monitorPositions, 60000);
+monitorPositions();
+```
+
+### Auto-Funding Collector
+
+```typescript
+// funding-collector.ts
+import { AlphaFuturesClient } from '@alpha-futures/sdk';
+
+const client = new AlphaFuturesClient({
+  network: 'mainnet',
+  privateKey: process.env.PRIVATE_KEY
+});
+
+async function collectFunding() {
+  const positions = await client.positions.getAllPositions();
+  
+  for (const position of positions) {
+    const funding = await client.funding.getAccruedFunding(position.id);
+    
+    if (funding > 0) {
+      await client.funding.collectFunding(position.id);
+      console.log(`Collected ${funding.toFixed(4)} TAO from position ${position.id}`);
+    }
+  }
+}
+
+// Run every 8 hours
+setInterval(collectFunding, 8 * 60 * 60 * 1000);
+```
+
+## Need Help?
+
+- Read the full documentation: [README.md](../README.md)
+- Check our FAQ: [https://docs.alphafutures.io/faq](https://docs.alphafutures.io/faq)
+- Ask in Discord: [https://discord.gg/alphafutures](https://discord.gg/alphafutures)
+- Report issues: [GitHub Issues](https://github.com/alpha-futures/sdk/issues)