How to Configure Perpetual Futures Trading Across Binance, Bybit, and Hyperliquid with CloddsBot

CloddsBot enables perpetual futures trading across Binance, Bybit, and Hyperliquid through dedicated skill modules that route commands via /bf, /bb, and /hl prefixes while persisting all activity to an internal SQLite database.

The alsk1992/CloddsBot repository implements a modular architecture where each exchange operates as a self-contained skill within the src/skills/bundled/ directory. To configure perpetual futures trading, you must set exchange-specific environment variables and understand the unified command routing system that abstracts API complexity into natural language interactions.

Environment Configuration for Each Exchange

Each perpetual futures skill reads credentials from environment variables at runtime. The bot never logs these secrets; they are only used to initialize the low-level API wrappers in src/exchanges/.

Binance Futures Setup

The Binance skill in src/skills/bundled/binance-futures/index.ts expects the following variables, typically defined in a .env file placed in the project root:

BINANCE_API_KEY=xxxxxxxx
BINANCE_API_SECRET=xxxxxxxx
BINANCE_TESTNET=true
DRY_RUN=true

As implemented in lines 36-45 of the Binance skill module, BINANCE_TESTNET routes orders to the testnet environment, while DRY_RUN simulates execution without placing real orders【1†L36-L45】.

Bybit Futures Setup

The Bybit skill in src/skills/bundled/bybit-futures/index.ts follows an identical pattern with exchange-specific prefixes:

BYBIT_API_KEY=yyyyyyyy
BYBIT_API_SECRET=yyyyyyyy
BYBIT_TESTNET=true
DRY_RUN=true

Lines 36-45 of the Bybit implementation validate these credentials before initializing the REST client【2†L36-L45】.

Hyperliquid Wallet Configuration

Hyperliquid operates via wallet authentication rather than API keys. The skill in src/skills/bundled/hyperliquid/index.ts requires:

HYPERLIQUID_WALLET=0xabc123...
HYPERLIQUID_PRIVATE_KEY=0xdef456...
DRY_RUN=true

According to lines 32-43 of the Hyperliquid skill, the private key signs transactions locally before broadcasting to the Hyperliquid L1【3†L32-L43】.

Command Routing and Usage

Each skill exports a handler function that parses raw argument strings and routes them to specific sub-handlers. For example, the Binance skill maps /bf long BTCUSDT 0.01 10x to handleLong as shown in lines 79-89【1†L79-L89】.

Standard Command Prefixes

The bot registers three distinct command namespaces:

• /bf – Binance Futures (src/skills/bundled/binance-futures/)
• /bb – Bybit Futures (src/skills/bundled/bybit-futures/)
• /hl – Hyperliquid (src/skills/bundled/hyperliquid/)

Common commands available across all three exchanges include:

• Account: balance, positions, orders (Hyperliquid adds portfolio and fills)
• Trading: long, short, close, closeall, leverage (Hyperliquid adds margin and twap)
• Market Data: price, funding, markets (Hyperliquid adds book and candles)
• Database: trades, stats, dbfunding, dbpositions

Unified Trading Interface

The trading-futures aggregator in src/skills/bundled/trading-futures/ registers all three prefixes under a single skill entry point. This allows the bot to forward requests to the appropriate exchange wrapper based on the detected prefix, enabling simultaneous multi-exchange operation from one interface.

Database Logging and Analytics

Every executed order persists to the internal SQLite database via exchange-specific logging functions in src/db/index.ts.

Trade Persistence Layer

The database layer implements isolated tables for each exchange:

• Binance: logBinanceFuturesTrade writes to the binance_futures_trades table (implemented in src/skills/bundled/binance-futures/index.ts lines 77-95)【1†L77-L95】
• Bybit: logBybitFuturesTrade writes to bybit_futures_trades (lines 70-83)【2†L70-L83】
• Hyperliquid: logHyperliquidTrade writes to hyperliquid_trades (lines 50-57)【3†L50-L57】

Querying Historical Data

Users can query persisted data through database commands:

/bf trades 10

# Returns the last 10 Binance futures trades from the database

/hl dbstats ETH week  

# Returns weekly statistics for ETH from Hyperliquid logs

/bb dbpositions

# Lists all open Bybit positions stored in the database

The DB layer provides aggregation queries (get*Stats, get*FundingTotal) that surface analytics through the handleDbStats handlers in each skill module.

Extending the Architecture

To add a new perpetual futures exchange, implement three components mirroring the existing pattern:

1. API Wrapper: Create src/exchanges/<exchange>/ with methods matching getBalance, openLong, openShort, and closePosition signatures
2. Skill Module: Add src/skills/bundled/<exchange>/ that reads environment variables, implements command handlers for the standard command set, and calls the wrapper functions
3. Registration: Import the new skill into the trading-futures aggregator or expose a unique command prefix

This modular design maintains isolation between exchange implementations while presenting a consistent user experience across all perpetual futures markets.

Summary

• Environment Variables: Configure BINANCE_API_KEY/SECRET, BYBIT_API_KEY/SECRET, and HYPERLIQUID_WALLET/PRIVATE_KEY in your .env file, with optional DRY_RUN and testnet flags for safe testing.
• Command Prefixes: Use /bf for Binance, /bb for Bybit, and /hl for Hyperliquid to route orders through their respective skill modules in src/skills/bundled/.
• Data Persistence: All trades automatically log to SQLite via logBinanceFuturesTrade, logBybitFuturesTrade, and logHyperliquidTrade functions in src/db/index.ts.
• Unified Interface: The trading-futures aggregator enables simultaneous multi-exchange operation under a single command structure.
• Extensibility: New exchanges require only a wrapper in src/exchanges/ and a skill module in src/skills/bundled/ following the established architectural pattern.

Frequently Asked Questions

What environment variables are required to configure perpetual futures trading across Binance, Bybit, and Hyperliquid with CloddsBot?

Each exchange requires specific credentials: Binance needs BINANCE_API_KEY and BINANCE_API_SECRET; Bybit requires BYBIT_API_KEY and BYBIT_API_SECRET; Hyperliquid uses HYPERLIQUID_WALLET and HYPERLIQUID_PRIVATE_KEY for wallet-based authentication. All three support optional DRY_RUN and testnet flags for safe testing environments.

How does CloddsBot handle dry-run testing for perpetual futures trades?

When DRY_RUN=true is set in the environment, the exchange wrappers simulate order execution without transmitting real orders to the exchange APIs. This allows users to test command syntax and position calculations using live market data while risking no capital.

Can I trade on Binance, Bybit, and Hyperliquid simultaneously using CloddsBot?

Yes. The src/skills/bundled/trading-futures/ aggregator registers all three exchange skills simultaneously, enabling you to execute /bf long BTCUSDT 0.01 10x and /hl long BTC 0.5 5x in the same session. Each skill maintains independent API connections and database tables to prevent cross-exchange interference.

Where does CloddsBot store trade history and position data?

Trade history persists to an SQLite database via functions in src/db/index.ts. Binance trades log to binance_futures_trades, Bybit to bybit_futures_trades, and Hyperliquid to hyperliquid_trades. Users query this data through database commands like /bf trades or /hl dbstats without direct SQL interaction.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}