/trading-futures

name: trading-futures
description: "Trade perpetual futures on Binance, Bybit, Hyperliquid, MEXC with up to 200x leverage"
emoji: "📈"
gates:
  envs:
    anyOf:
      - BINANCE_API_KEY
      - BYBIT_API_KEY
      - HYPERLIQUID_PRIVATE_KEY
      - MEXC_API_KEY

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

# 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

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

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

// 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

// 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: 'LIM