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

> Configure perpetual futures trading on Binance, Bybit, and Hyperliquid using CloddsBot. Learn to route commands and persist activity with this powerful tool.

- Repository: [AL/CloddsBot](https://github.com/alsk1992/CloddsBot)
- Tags: how-to-guide
- Published: 2026-09-11

---

**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`](https://github.com/alsk1992/CloddsBot/blob/main/src/skills/bundled/binance-futures/index.ts) expects the following variables, typically defined in a `.env` file placed in the project root:

```ini
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`](https://github.com/alsk1992/CloddsBot/blob/main/src/skills/bundled/bybit-futures/index.ts) follows an identical pattern with exchange-specific prefixes:

```ini
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`](https://github.com/alsk1992/CloddsBot/blob/main/src/skills/bundled/hyperliquid/index.ts) requires:

```ini
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`](https://github.com/alsk1992/CloddsBot/blob/main/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`](https://github.com/alsk1992/CloddsBot/blob/main/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:

```text
/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`](https://github.com/alsk1992/CloddsBot/blob/main/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`](https://github.com/alsk1992/CloddsBot/blob/main/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.