This is a python bot designed with a simple core architecture. I have set up the basic trading logic for four perpetual trading DEX's, Hyperliquid, Aster, Lighter and Paradex by implementing specific subclasses that inherit from a BaseConnector class. You can intialize a specific connector class and use the same named functions for the logic. These connectors can be found in the /utils directory. Utlimately, this allows for a higher level script to import and utilize these connectors as necessary. Each strategy is it's own self-contained set of logic simply utilizing the connectors I've built already, how it is built depends on who builds it. The application in the root directory itself is a TUI or textual-user-interface that operates in root and has its own utilities and logic, but is ultimately intended to manage various strategys, their logs and processes.
Note: The TUI was intended to be strategy agnostic but pushing to get the best UX the fastest meant there has been a lot of shortcuts taken and there is a lot of interdependency. Now, I can only guarantee it functions for the current strategy. One example of this interdependency is how the TUI has options to configure, manage and add strategy configuration files for the funding rate arbitrage. Another example is how the financial analysis script used by the TUI is designed only to interpret the funding arbitrage strategy logs.
The current strategy is funding rate arbitrage and currently it can be found at /strategies/basic_funding_arbitrage. I built this strategy to take a set of configuration parameters and then conduct a basic funding rate arbitrage action based on them. Note that a strategy configuration is a standardized yml file which the specific strategy script is built around understanding, they can be found at /strategies/basic_funding_arbitrage/configs.
The simplest way to explain the current funding rate arbitrage strategy is to walk through the configuration file:
basic_config:
funding_rate_check_interval:
leverage: 1
long_exchange: paradex
long_symbol: AAVE-USD-PERP
run_tests_before_trade: false
short_exchange: lighter
short_symbol: AAVE
meta-data:
description: testing lighter and paradex
file_name: test_three
strategy_config:
ee_step_delay: 0.05
min_funding_rate_diff: -1.0
position_ee_steps: 2
position_size_base_asset: 0.5
step_order_slippage: 0.01
time_below_min_rate_diff: 45
Upon running a new strategy, the bot opens a new long and short position for the specified asset on the specified exchanges. The long_exchange is the exchange that the bot opens a long position and the short_exchange is the exchange that the bot opens a short on. The short_symbol and long_symbol values exist because different exchanges denoate the same asset with different formats, if you choose two different assets you will no longer be arbitraging funding rates.
The bot opens positions of a specified base asset size (position_size_base_asset) and it will make a given number of entry or exit steps to reach that position size on both DEXs (position_ee_steps). The more entry/exit or 'ee' steps you take, the more individual orders are made to reach the full position size. Therefore each order is of size (in base assets) of position_size_base_asset / position_ee_steps. The value ee_step_delay is the time (in seconds) that the bot waits between placing order pairings, a minimal value is recommended to give APIs a breather and avoid rate-limiting. The leverage value set will set the leverage configuration on the chosen exchanges to match, so orders made will be put on that leverage. The position_size_base_asset will still be the position size obtained, increasing the leverage will simply reduce the margin required to open the position (and increase the liquidation risk).
Please note some limitations: Dex's have minimum order sizes which can and will differ from one another. Dex's also have specificity limits and will not accept numbers with too many decimal places. This is important to note because when you select a position_size_base_asset and a position_ee_steps value, you want to ensure they divide evenly with relatively few decimal places, if it is a big asset like BTC or ETH, ensure you dont have too many values past the most significant digit. The level of leverage offered may also differ between DEX's and you will need to select a value that both DEX's support. You can find more information on each dex's quirks in my various notes and markdown files. I recommend you task an LLM agent to go digging for the information. THis is bad development practice to not centralize this information but this readme is not a full documentation redo.
For funding rate arbitrage high leverage is not necessarily recommended. Your positions may be delta-neutral but often times the more profitable an arbitrage position, the less correlated the price action of that asset is between the two dexs. This could lead to an uncomfortable price swing into a liquidation or ADL on one dex and not the other, leaving you with directional risk.
Orders are placed simultaneously but the bot waits to place the next set of orders until both orders are resolved. Once both orders are resolved, the bot waits the ee_step_delay and then places the next set of orders. You can view the diagram below for a more intuitive view on how the bot enters and exits positions with multiple steps.
The reason for this multi-step logic is pretty straightforward. You may have already noticed that this functionality is essentially that of a TWAP order but it is being done through the bot rather than attempting to reconcile the many different API calls and resolution mechanics that different DEX's use. Making two separate TWAP orders on two exchanges that are guaranteed to start and end at the same time would be very messy. Ultimately the goal is to ensure as close to a delta-neutral position as possible when conducting funding rate arbitrage, these values give a basic but extensive amount of customization for determining how you want to enter and exit your arbitrage positions.
Additionally the value step_order_slippage is the configuration slippage value that is passed to each order when entering and exiting a position. Almost all DEXs have slippage values specified on an order-by-order basis, so this value is passed to each order made during an entry or exit procedure. You can assume that the slippage taken will roughly average to this value and you are guaranteed that your slippage will not exceed this value because orders will fail otherwise.
In the more liquid order books on these dex's I have come extremely close to true delta-neutral positions, even with a limited position step size of 3-4, with positions on dexs opened within 0.5-1 basis point of each other in price. Less entry/exit steps and weaker books so seen closer to 30-40 basis point spreads, and I've encountered everything inbetween. As with everything you will need to tweak things using various rules of thumb/heuristics: ie. the weaker the book the more steps dispersed over more time will give more opportunity for liquidity at the top of the book to refill, though prices may shift if you spend too much time.
The configuration value of run_tests_before_trade is simply a check that determines whether the bot runs a variety of tests of the connectors utilized in a particular configuration. I.e. if configured to use Hyperliquid and Aster, setting this value to true would run the connector tests for Hyperliquid and Aster. This will add significant time to starting a strategy but any issues with the connectors will be identified and cause the process to fail or halt before positions can be opened with failing connectors.
The final and most key parameter to understanding the funding rate arbitrage strategy is min_funding_rate_diff. For a given interval, which is determined by the funding_rate_check_interval parameter, we check this differential. The calculation is short_exchange_funding_rate - long_exchange_funding_rate, if the value is positive then the bot is earning a profit from funding. The value you configure is meant to match that seen on the exchange UI, your input decimal value is the percentage itself . So 0.003 = 0.003% (as seen on DEX Ui's), NOT 0.003 = 0.3%
You might notice the configurations I have include -1, this is because during testing I wanted the bot to run perpetually, and this guaranteed there was no case of the bot closing out positions..
If the differential between the two funding rates goes below the minimum allowed and stays there for a specified period of time aka. the time_below_min_rate_diff value, then the bot automatically begins an exit of the current position and the strategy resolves, you are done earning. This period of time is just meant to minimize rate noise possible causing a premature exit, I would be careful setting it above one or eight hours, the two most common intervals seen when describing and calculating funding.
Alternatives: CCXT - CCXT isn't a bot but a set of connectors for various CEXs and trading platforms Hummingbot - a bot that uses connectors from a variety of sources including most of those found on CCXT. The edge that this has over Hummingbot is simplified connectors that can be built quickly to support really long-tail decentralized exchanges where the more profitable funding arbitrage opportunities will likely be located. Most CEX perps are already arbed using Hummingbot. Hummingbot is larger and less quickly able to support new CEXs, and DEX's are a weird bunch, with inconsistent development styles. Most CEX's use proper REST API's, a lot of DEX's are complicated and make REST APIs but with weird caveats and sometimes just provide SDKs that do things for you, where going under the hood is difficult. Additionally the connectors used here are bog standard simple, hummingbot connectors need to be as comprehensive as possible to support the various bot and strategies offered. I guess the edge is that here, if you're reading this, you know the maintainer and can request more connectors.
Extra discussion: docker - not right now. Crashed position recovery, cloud server, processes, VM, all that schtuff
This directory contains comprehensive documentation for the funding rate arbitrage bot, organized into focused topics for easier access and maintenance.
- PROJECT_OVERVIEW.md - Project description, goals, and high-level architecture
- ARCHITECTURE.md - Detailed system architecture, design patterns, and core philosophy
- STRATEGY_SYSTEM.md - Strategy implementation patterns and configuration management
- DEX_CONNECTORS.md - Exchange connector implementations, authentication patterns, and supported DEXes
- CONFIGURATION.md - Environment variables, YAML configs, and setup requirements
- DEVELOPMENT.md - Development guidelines, dependencies, and code organization
- TUI_SYSTEM.md - Terminal UI management system and operational capabilities
- FINANCIAL_ANALYSIS.md - Financial analysis tools and performance metrics
- POSITION_RECOVERY.md - Automated position recovery system (already exists)
- CHANGELOG.md - Recent fixes, enhancements, and development updates
- VALIDATION_RESULTS.md - Live trading validation results and connector testing
- Review PROJECT_OVERVIEW.md for basic understanding
- Check CONFIGURATION.md for setup requirements
⚠️ IMPORTANT: Review DEX_CONNECTORS.md for platform compatibility requirements- See TUI_SYSTEM.md for operational instructions
- Review POSITION_RECOVERY.md for safety mechanisms
- Docker Platform: Use
docker-compose up --build(platform automatically configured) - Lighter Connector: ✅ RESOLVED - Platform architecture issue fixed
- Deployment: Ready for production with proper x86_64 platform specification
- Start with ARCHITECTURE.md and DEVELOPMENT.md
- Review DEX_CONNECTORS.md for exchange integration details
- Check CHANGELOG.md for recent changes and known issues