Add custom trading controllersnew bots

[pierluigipanariello]

i've added this bots:
bots/controllers/generic/anti_folla_v1.py
bots/controllers/generic/delta_neutral_mm.py
bots/controllers/generic/funding_rate_arb.py
bots/controllers/generic/stat_arb_v2.py
bots/controllers/market_making/lm_multi_pair_dex.py

related to hummingbot/condor#46

[pierluigipanariello]

readme-new_bot.md

[pierluigipanariello]

Condor Strategies for Hummingbot

This repository contains a collection of custom controllers built on top of Hummingbot's strategy_v2 framework. Each controller implements a specific automated trading strategy — ranging from directional signal‑based trading to market making, arbitrage, and liquidity mining.

All controllers are designed to be used with Hummingbot (v2.0+) and can be deployed via the Condor / hummingbot-api environment.

---

Table of Contents

1. Anti‑Folla V1 (anti_folla_v1)
2. Funding Rate Arbitrage (funding_rate_arb)
3. Statistical Arbitrage V2 (stat_arb_v2)
4. Delta Neutral Market Making (delta_neutral_mm)
5. Multi‑Grid Strike (multi_grid_strike)
6. Liquidity Mining Multi‑Pair DEX (lm_multi_pair_dex)

---

Anti‑Folla V1 (anti_folla_v1)

Directional trading that goes against the crowd.
It calculates a composite score using a combination of technical indicators, order book imbalance (OBI), whale activity, and funding rates, then generates BUY/SELL signals when the score exceeds configurable thresholds.

Key features

• Contrarian logic: e.g., sells when funding rates are very positive (too many longs).
• Uses candlestick data (3m default) to compute VWAP, Donchian channels, OBV divergence, volume spikes, and trade flow.
• Optionally includes real‑time OBI from the order book.
• Configurable weights for each signal component.

Main configuration parameters

Parameter	Description
connector_name	Exchange (e.g., binance_perpetual)
trading_pair	Pair to trade (e.g., SOL-USDT)
total_amount_quote	Total capital in quote currency
stop_loss / take_profit	Risk limits (as decimals, e.g., 0.05)
score_buy_threshold / score_sell_threshold	Score thresholds for signals (default ±50)
weight_*	Weights for VWAP, Donchian, OBV, OBI, volume spike, trade flow, funding
enable_order_book_imbalance	Whether to use real‑time OBI

Signal logic

The controller computes a composite score (range -100 to +100) by weighting several signals:

• VWAP: price above/below rolling VWAP
• Donchian breakout: price breaks 20‑period high/low
• OBV divergence: bullish/bearish divergence
• OBI: bid/ask volume ratio
• Volume spike: last volume > 2.5× average
• Whale activity: last candle with large body and high volume
• Funding rate: contrarian (positive → short, negative → long)

A BUY signal is emitted when the score ≥ score_buy_threshold, SELL when ≤ score_sell_threshold.

---

Funding Rate Arbitrage (funding_rate_arb)

Multi‑exchange funding rate arbitrage — captures the difference in perpetual swap funding rates between two exchanges (or between spot and perpetual).

Modes

• Perp ↔ Perp : full delta‑neutral (short the high‑funding pair, long the low‑funding pair).
• Spot ↔ Perp : cash‑and‑carry (buy spot, sell perpetual with higher funding rate).

Key features

• Automatically detects if a connector is spot or perpetual.
• Dynamically retrieves the funding interval from each exchange (falls back to 8h / 1h for Hyperliquid).
• Computes hourly net funding rate and estimates the APY.
• Opens a pair of opposite positions when |net_rate| > entry_threshold and closes them when the rate drops below exit_threshold.
• Global stop‑loss / take‑profit on the combined PnL.

Main configuration parameters

Parameter	Description
connector_pair_a / connector_pair_b	Two (connector, trading pair) objects
entry_threshold	Minimum net hourly rate to open (e.g., 0.000025 = 0.0025%/h)
exit_threshold	Close when rate falls below this value
total_amount_quote	Total capital (split equally between the two legs)
leverage	Leverage for perpetual legs
funding_interval_a/b_hours	Optional manual override of funding intervals

Signal logic

The controller periodically fetches the latest funding rate from both exchanges, normalises them to an hourly rate, and calculates the net rate = rate_A – rate_B.

• Signal = +1 (buy spread): net rate > entry_threshold → short exchange A, long exchange B (or spot+perp combination).
• Signal = -1 (sell spread): net rate < -entry_threshold → opposite.
• Signal = 0 : neutral zone, close any open positions.

The strategy automatically closes the positions when |net rate| < exit_threshold and re‑hedges when the delta exceeds the cooldown threshold.

---

Statistical Arbitrage V2 (stat_arb_v2)

Pairs trading on a single exchange. It trades the spread between two correlated assets (e.g., SOL‑USDT and XRP‑USDT) using a z‑score entry and a dynamic hedge ratio derived from OLS regression.

Key features

• Uses only one connector for both trading pairs (e.g., binance_perpetual).
• Calculates the cumulative return series of both pairs and runs a linear regression (dominant_cum ~ hedge_cum).
• Computes the spread, its z‑score, half‑life, R², and ADF p‑value to ensure stationarity.
• Filters out signals when R² is too low or the spread is not mean‑reverting (ADF p‑value too high).
• Dynamic hedge ratio: 1 / beta (capped by min/max_dynamic_hedge_ratio).
• Places limit orders on both legs according to the spread signal and manages the target allocation.

Main configuration parameters

Parameter	Description
connector_name	Exchange (e.g., binance_perpetual)
trading_pair_dominant / trading_pair_hedge	The two pairs
lookback_period	Number of candles for regression (e.g., 300)
entry_threshold	Z‑score level that triggers a trade (e.g., 2.0)
take_profit	Per‑executor take‑profit fraction (e.g., 0.0008 = 0.08%)
tp_global / sl_global	Global PnL% limits to close everything
min_r_squared / adf_pvalue_threshold	Statistical quality filters
use_dynamic_hedge_ratio	If True, uses OLS beta to size the hedge leg
max_orders_placed_per_side / max_orders_filled_per_side	Position scaling limits

Signal logic

1. Fetch lookback_period candles for both pairs.
2. Compute cumulative returns and run hedge_cum ~ dominant_cum.
3. Calculate the residual spread and its z‑score.
4. If R² >= min_r_squared and ADF p‑value <= threshold:
   • z > +entry_threshold → SELL dominant / BUY hedge (overvalued dominant)
   • z < -entry_threshold → BUY dominant / SELL hedge (undervalued dominant)
5. Otherwise signal = 0 (no trade).

The controller then places limit orders on both legs to approach the theoretical target quote amounts derived from the dynamic hedge ratio and total capital.

---

Delta Neutral Market Making (delta_neutral_mm)

Market making on a spot or perpetual exchange, hedged by an opposite position on a perpetual exchange. The maker side provides liquidity, while the hedge side adjusts to keep the overall delta close to zero.

Key features

• Maker exchange (can be spot or perpetual) – places multiple buy/sell limit orders with spreads derived from NATR and MACD.
• Hedge exchange (must be perpetual) – executes market orders when the net delta exceeds a threshold.
• The reference price for the maker orders is shifted using a normalised MACD signal.
• Spreads are dynamic: spread = base_spread × NATR_multiplier.
• Global stop‑loss / take‑profit on the combined PnL, plus a configurable hedge position timeout.
• Hedge orders can be placed as market orders to quickly rebalance delta.

Main configuration parameters

Parameter	Description
connector_pair_maker	(connector, pair) for providing liquidity
connector_pair_hedge	(perpetual connector, pair) for delta hedging
buy_spreads / sell_spreads	Comma‑separated base spread percentages (e.g., 1.0,2.0,3.0)
order_amount_quote	Quote amount per order level
hedge_threshold_quote	Delta (in USDT) that triggers a hedge
max_delta_quote	Emergency cap – hedge immediately when exceeded
macd_fast / macd_slow / macd_signal	MACD parameters for reference price shift
natr_length	NATR length for dynamic spread multiplier
maker_tp_multiplier	Multiplier for take‑profit (relative to spread)
hedge_position_timeout	Auto‑close hedge positions after this many seconds

Operational flow

• Reference price = last close × (1 + macd_normalised × natr/2).
• Spread multiplier = current NATR value.
• Maker orders are placed at ref_price × (1 ± spread_i × spread_mult) with a take‑profit set to spread_i × spread_mult × maker_tp_multiplier.
• Net delta = maker position (in quote) + hedge position (in quote).
• If |net delta| > hedge_threshold_quote, a hedge order (market) is sent on the perpetual exchange to reduce delta towards zero.
• If |net delta| > max_delta_quote, an immediate forced hedge is performed, overriding other logic.
• All stale maker orders are refreshed every order_refresh_time seconds.

---

Multi‑Grid Strike (multi_grid_strike)

Multiple independent grids on the same trading pair. Each grid is defined by its own price range, side (BUY or SELL), and percentage of total capital. This allows a single strategy instance to run, for example, a buy grid in a low range and a sell grid in a high range simultaneously.

Key features

• Each grid uses a GridExecutorConfig internally.
• Grids can be enabled/disabled dynamically (the controller monitors configuration changes and stops/creates executors accordingly).
• Capital is allocated per grid as a percentage of total_amount_quote.
• Supports common grid parameters: spread between orders, min order size, max open orders, order frequency.
• Active grids show their level distribution (pending, filled, completed) and performance metrics in the status display.

Main configuration parameters

Parameter	Description
connector_name / trading_pair	Exchange and pair for all grids
total_amount_quote	Total capital to be split among grids
grids	List of GridConfig objects, each with: grid_id, start_price, end_price, limit_price, side, amount_quote_pct, enabled
min_spread_between_orders	Minimum price gap between consecutive grid levels
min_order_amount_quote	Minimum notional per order
max_open_orders	Max orders the grid executor can have open at once
order_frequency	Seconds between order placement batches
keep_position	Whether the grid executor should keep its position when stopped

Behaviour

• For each enabled grid, the controller checks whether the current mid price lies inside the grid’s [start_price, end_price] bounds.
• If the price is inside and no GridExecutor exists for that grid_id, it creates one.
• If a grid is disabled or removed from the configuration, the corresponding executor is stopped.
• The to_format_status method displays a detailed table of each grid’s current stats (levels by state, order counts, PnL, etc.).

---

Liquidity Mining Multi‑Pair DEX (lm_multi_pair_dex)

Automated liquidity provision on decentralised exchanges that support limit orders (e.g., XRPL DEX, Hyperliquid spot). The strategy places multiple buy and sell limit orders across several trading pairs, using dynamic skew based on current inventory.

Key features

• Auto‑optimisation for the specific DEX:
  • XRPL → wider spreads, slower refresh, higher tolerance (due to 3‑5s latency, very low fees).
  • Hyperliquid → tighter spreads, faster refresh, lower tolerance (due to sub‑millisecond latency and maker rebate).
• Each trading pair receives an equal share of the allocated capital.
• Order amounts are skewed according to the current base asset percentage: if too much base is held, sell orders are favoured (and vice‑versa).
• Order prices are refreshed when they become too far from the theoretical price (tolerance parameter).
• Optional dynamic spreads based on ATR (configurable).
• Cooldown period after a fill to avoid immediate replacement.

Main configuration parameters

Parameter	Description
connector_name	Exchange connector (xrpl or hyperliquid)
markets	List of trading pairs (e.g., ["XRP-RLUSD", "BTC-XRP"])
token	Unified token for fee/balance checks (e.g., XRP for XRPL, USDC for Hyperliquid)
portfolio_allocation	Fraction of total_amount_quote to use (rest stays idle)
buy_spreads / sell_spreads	List of spread percentages for each order level
order_refresh_time	Seconds after which an unfilled order is refreshed
cooldown_time	Seconds to wait after a fill before placing new orders
order_refresh_tolerance_pct	Maximum allowed deviation from theoretical price before refreshing
target_base_pct / min_base_pct / max_base_pct / max_skew	Inventory skew parameters
use_dynamic_spreads	If True, spreads are multiplied by an ATR factor
atr_length / atr_multiplier_min/max	ATR settings for dynamic spreads

Operational flow

1. For each trading pair, compute the reference price (mid price) and the current base asset percentage.
2. Calculate buy/sell skew factors based on how far base_pct is from the target range.
3. Determine which order levels are missing (compared to active executors).
4. Create new PositionExecutor orders with:
   • Price = reference price × (1 ± spread_i)
   • Amount = (allocation per pair / number of levels) × skew factor
5. Refresh stale orders (age > order_refresh_time) that have drifted beyond the tolerance.
6. During cooldown after a fill, no new orders are placed for that pair.