trading-futures

What this skill does

# Perpetual Futures Trading - Complete API Reference

Trade leveraged perpetual futures across 4 exchanges with database tracking, custom strategies, and A/B testing.

**200+ methods across 4 exchanges. This is the complete reference.**

## Supported Exchanges

| Exchange | Type | Max Leverage | KYC | API Methods |
|----------|------|--------------|-----|-------------|
| Binance Futures | CEX | 125x | Yes | 55+ |
| Bybit | CEX | 100x | Yes | 50+ |
| MEXC | CEX | 200x | No (small) | 35+ |
| Hyperliquid | DEX | 50x | No | 60+ |

## Required Environment Variables

```bash
# Binance Futures
BINANCE_API_KEY=your_api_key
BINANCE_API_SECRET=your_api_secret

# Bybit
BYBIT_API_KEY=your_api_key
BYBIT_API_SECRET=your_api_secret

# MEXC (No KYC for small amounts)
MEXC_API_KEY=your_api_key
MEXC_API_SECRET=your_api_secret

# Hyperliquid (Fully decentralized, No KYC)
HYPERLIQUID_PRIVATE_KEY=your_private_key
HYPERLIQUID_WALLET_ADDRESS=0x...

# Optional: Database for trade tracking
DATABASE_URL=postgres://user:pass@localhost:5432/clodds
```

---

## Chat Commands

### Account & Balance

```
/futures balance [exchange]        # Check margin balance (all or specific)
/futures positions                 # View all open positions
/futures positions <exchange>      # View positions on specific exchange
```

### Opening Positions

```
/futures long <symbol> <size> [leverage]x    # Open long position
/futures short <symbol> <size> [leverage]x   # Open short position

# Examples:
/futures long BTCUSDT 0.1 10x      # Open 0.1 BTC long at 10x
/futures short ETHUSDT 1 20x       # Open 1 ETH short at 20x
/futures long BTCUSDT 0.01         # Use default leverage
```

### Take-Profit & Stop-Loss

```
/futures tp <symbol> <price>       # Set take-profit
/futures sl <symbol> <price>       # Set stop-loss
/futures tpsl <symbol> <tp> <sl>   # Set both at once

# Examples:
/futures tp BTCUSDT 105000         # Take profit at $105k
/futures sl BTCUSDT 95000          # Stop loss at $95k
/futures tpsl BTCUSDT 105000 95000 # Both
```

### Closing Positions

```
/futures close <symbol>            # Close specific position
/futures close-all                 # Close ALL positions (all exchanges)
/futures close-all <exchange>      # Close all on specific exchange
```

### Market Data

```
/futures markets [exchange]        # List available markets
/futures price <symbol>            # Get current price
/futures funding <symbol>          # Check funding rate
/futures orderbook <symbol>        # View orderbook depth
```

### Account Info

```
/futures stats                     # Trade statistics from database
/futures history [symbol]          # Trade history
/futures pnl [period]              # P&L summary (day/week/month)
```

### Leverage & Margin

```
/futures leverage <symbol> <value> # Set leverage
/futures margin <symbol> <mode>    # Set margin mode (cross/isolated)
```

---

## TypeScript API Reference

### Quick Setup

```typescript
import { setupFromEnv } from 'clodds/trading/futures';

// Auto-configure from environment variables
const { clients, database, strategyEngine } = await setupFromEnv();

// Access individual clients
const binance = clients.binance;
const bybit = clients.bybit;
const mexc = clients.mexc;
const hyperliquid = clients.hyperliquid;
```

### Manual Client Setup

```typescript
import {
  BinanceFuturesClient,
  BybitFuturesClient,
  MexcFuturesClient,
  HyperliquidClient,
  FuturesDatabase,
  StrategyEngine,
} from 'clodds/trading/futures';

// Binance
const binance = new BinanceFuturesClient({
  apiKey: process.env.BINANCE_API_KEY!,
  apiSecret: process.env.BINANCE_API_SECRET!,
  testnet: false,  // true for testnet
});

// Bybit
const bybit = new BybitFuturesClient({
  apiKey: process.env.BYBIT_API_KEY!,
  apiSecret: process.env.BYBIT_API_SECRET!,
  testnet: false,
});

// MEXC (No KYC)
const mexc = new MexcFuturesClient({
  apiKey: process.env.MEXC_API_KEY!,
  apiSecret: process.env.MEXC_API_SECRET!,
});

// Hyperliquid (Decentralized, No KYC)
const hyperliquid = new HyperliquidClient({
  privateKey: process.env.HYPERLIQUID_PRIVATE_KEY!,
  walletAddress: process.env.HYPERLIQUID_WALLET_ADDRESS!,
  testnet: false,
});
```

---

## Binance Futures API (55+ Methods)

### Market Data

```typescript
// Prices & Tickers
await binance.getMarkPrice('BTCUSDT');
await binance.getTicker24h('BTCUSDT');
await binance.getAllTickers();
await binance.getBookTicker('BTCUSDT');

// Orderbook & Trades
await binance.getOrderBook('BTCUSDT', 100);
await binance.getRecentTrades('BTCUSDT', 500);
await binance.getHistoricalTrades('BTCUSDT', 500);
await binance.getAggTrades('BTCUSDT');

// Klines (Candlesticks)
await binance.getKlines('BTCUSDT', '1h', 100);
await binance.getContinuousKlines('BTCUSDT', '1h', 'PERPETUAL');
await binance.getIndexPriceKlines('BTCUSDT', '1h');
await binance.getMarkPriceKlines('BTCUSDT', '1h');
await binance.getPremiumIndexKlines('BTCUSDT', '1h');

// Funding Rates
await binance.getFundingRate('BTCUSDT');
await binance.getFundingRateHistory('BTCUSDT', 100);

// Market Info
await binance.getExchangeInfo();
await binance.getOpenInterest('BTCUSDT');
await binance.getOpenInterestHistory('BTCUSDT', '1h');
```

### Trading

```typescript
// Place Orders
await binance.placeOrder({
  symbol: 'BTCUSDT',
  side: 'BUY',
  type: 'MARKET',
  quantity: 0.01,
});

await binance.placeOrder({
  symbol: 'BTCUSDT',
  side: 'BUY',
  type: 'LIMIT',
  quantity: 0.01,
  price: 95000,
  timeInForce: 'GTC',
});

// With TP/SL
await binance.placeOrder({
  symbol: 'BTCUSDT',
  side: 'BUY',
  type: 'MARKET',
  quantity: 0.01,
  takeProfit: 105000,
  stopLoss: 95000,
});

// Batch Orders
await binance.placeBatchOrders([
  { symbol: 'BTCUSDT', side: 'BUY', type: 'LIMIT', quantity: 0.01, price: 94000 },
  { symbol: 'BTCUSDT', side: 'BUY', type: 'LIMIT', quantity: 0.01, price: 93000 },
]);

// Modify & Cancel
await binance.modifyOrder('BTCUSDT', orderId, { quantity: 0.02 });
await binance.cancelOrder('BTCUSDT', orderId);
await binance.cancelAllOrders('BTCUSDT');
await binance.cancelBatchOrders('BTCUSDT', [orderId1, orderId2]);

// Auto-cancel
await binance.setAutoCancel(60000);  // Cancel all after 60s
await binance.cancelAutoCancel();
```

### Account & Positions

```typescript
// Account Info
await binance.getAccountInfo();
await binance.getBalance();
await binance.getPositions();
await binance.getPositionRisk();

// Orders & History
await binance.getOpenOrders();
await binance.getOpenOrders('BTCUSDT');
await binance.getAllOrders('BTCUSDT');
await binance.getOrder('BTCUSDT', orderId);
await binance.getTradeHistory('BTCUSDT');
await binance.getIncomeHistory();
await binance.getIncomeHistory('BTCUSDT', 'REALIZED_PNL');

// Commission
await binance.getCommissionRate('BTCUSDT');
```

### Risk Management

```typescript
// Leverage
await binance.setLeverage('BTCUSDT', 10);
await binance.getLeverageBrackets();
await binance.getLeverageBrackets('BTCUSDT');

// Margin Mode
await binance.setMarginType('BTCUSDT', 'ISOLATED');
await binance.modifyIsolatedMargin('BTCUSDT', 100, 'ADD');
await binance.modifyIsolatedMargin('BTCUSDT', 50, 'REDUCE');

// Position Mode
await binance.getPositionMode();
await binance.setPositionMode(true);  // Hedge mode
await binance.setPositionMode(false); // One-way mode

// Multi-Asset Mode
await binance.getMultiAssetMode();
await binance.setMultiAssetMode(true);
```

### Analytics

```typescript
// Market Analytics
await binance.getLongShortRatio('BTCUSDT', '1h');
await binance.getTopTraderLongShortRatio('BTCUSDT', '1h');
await binance.getTopTraderPositions('BTCUSDT', '1h');
await binance.getGlobalLongShortRatio('BTCUSDT', '1h');
await binance.getTakerBuySellVolume('BTCUSDT', '1h');
```

### Staking & Earn

```typescript
// Staking
await binance.getStakingProducts();
await binance.stake('BNB', 10);
await binance.unstake('BNB', 5);
await binance.getStakingHistory();
await binance.getStakingPositions();
```

### Convert

```typescript
// Convert between assets
await binance.