Middleware that helps Hummingbot clients to connect to DEXs on various blockchain networks
50K+
╔██████╗ █████╗ ████████╗███████╗██╗ ██╗ █████╗ ██╗ ██╗
██╔════╝ ██╔══██╗╚══██╔══╝██╔════╝██║ ██║██╔══██╗╚██╗ ██╔╝
██║ ███╗███████║ ██║ █████╗ ██║ █╗ ██║███████║ ╚████╔╝
██║ ██║██╔══██║ ██║ ██╔══╝ ██║███╗██║██╔══██║ ╚██╔╝
╚██████╔╝██║ ██║ ██║ ███████╗╚███╔███╔╝██║ ██║ ██║
╚═════╝ ╚═╝ ╚═╝ ╚═╝ ╚══════╝ ╚══╝╚══╝ ╚═╝ ╚═╝ ╚═╝
Hummingbot Gateway is a versatile API server that standardizes interactions with blockchain networks and decentralized exchanges (DEXs). It acts as a middleware layer, providing a unified interface for performing actions like checking balances, executing trades, and managing wallets across different protocols.
Gateway can be accessed through:
Gateway abstracts the complexity of interacting with different blockchain protocols by providing standardized endpoints that work consistently across different chains and DEXs. Built with TypeScript to leverage native blockchain SDKs, it offers a language-agnostic API that can be integrated into any trading system.
Gateway may be used alongside the main Hummingbot client to enable trading and market making on DEXs, or as a standalone API server.
| Protocol | Chain | Router | AMM | CLMM | Description |
|---|---|---|---|---|---|
| Jupiter | Solana | ✅ | ❌ | ❌ | DEX aggregator finding optimal swap routes |
| Meteora | Solana | ❌ | ❌ | ✅ | Dynamic Liquidity Market Maker (DLMM) |
| Raydium | Solana | ❌ | ✅ | ✅ | Full-featured DEX with V2 AMM and V3 CLMM |
| Uniswap | Ethereum/EVM | ✅ | ✅ | ✅ | Complete V2 AMM, V3 CLMM, and Smart Order Router |
| 0x | Ethereum/EVM | ✅ | ❌ | ❌ | DEX aggregator with professional market making features |
Gateway uses Swagger for API documentation. When running Gateway, access the interactive API documentation at:
/config/*)GET /config/namespaces - List all configuration namespacesGET /config/chains - Get available chains and networksGET /config/connectors - List available DEX connectorsGET /config - Get configuration for a namespacePUT /config - Update configuration values/chains/{chain}/*)GET /chains/{chain}/status - Get chain status and block heightGET /chains/{chain}/tokens - List supported tokensPOST /chains/{chain}/balances - Get wallet token balancesPOST /chains/{chain}/allowances - Check token allowancesPOST /chains/{chain}/approve - Approve token spendingPOST /chains/{chain}/wrap - Wrap/unwrap native tokens/connectors/{dex}/{type}/*)Router Operations (e.g., /connectors/jupiter/router/*):
POST /quote - Get swap quote from aggregatorPOST /swap - Execute swap through aggregatorAMM Operations (e.g., /connectors/raydium/amm/*):
POST /poolInfo - Get pool detailsPOST /positionInfo - Get liquidity position infoPOST /quoteSwap - Get swap quotePOST /executeSwap - Execute swapPOST /quoteLiquidity - Quote add/remove liquidityPOST /addLiquidity - Add liquidity to poolPOST /removeLiquidity - Remove liquidity from poolCLMM Operations (e.g., /connectors/uniswap/clmm/*):
POST /poolInfo - Get concentrated liquidity pool infoPOST /openPosition - Open new positionPOST /closePosition - Close existing positionPOST /addLiquidity - Add liquidity to positionPOST /removeLiquidity - Remove liquidity from positionPOST /collectFees - Collect earned feesPOST /positionsOwned - List owned positions/wallet/*)GET /wallet - List all walletsPOST /wallet/add - Add new walletPOST /wallet/addHardware - Add hardware walletDELETE /wallet/remove - Remove walletPOST /wallet/setDefault - Set default wallet per chainmacOS:
# Install Xcode Command Line Tools (for C++ compiler)
xcode-select --install
# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Install Node.js 20+ and required libraries
brew install node@20 libusb python@3
Ubuntu/Debian:
# Update package list and install dependencies
sudo apt update
sudo apt install -y curl build-essential libusb-1.0-0-dev libudev-dev python3
# Add Node 20.x repository
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
# Install Node.js
sudo apt install -y nodejs
Windows:
npm install --global windows-build-tools
We recommend downloading the graphical installer from the NodeJS official site.
For terminal-based users who haven't installed Node.js using the platform-specific instructions above:
# Check Node.js version:
node --version
pnpm package managerpnpm is a faster and more space-efficient package manager than npm.
# Install PNPM globally
sudo npm install -g pnpm
# Check pnpm version
pnpm --version
# Clone Github repo
git clone https://github.com/hummingbot/gateway.git
# Go to newly created folder
cd gateway
# Switch to core-2.8 branch
git checkout core-2.8
# Install JS libraries (this will compile native dependencies)
pnpm install
# If you encounter USB HID errors during install, try:
# macOS/Linux:
pnpm install --force
# Windows (run as Administrator):
pnpm install --force
# Compile Typescript into JS
pnpm build
# Run Gateway setup script
# Option 1: Interactive setup (choose which configs to update)
pnpm run setup
# Option 2: Setup with all defaults (updates all configs automatically)
pnpm run setup:with-defaults
You can run Gateway in the Gateway server in unencrypted HTTP mode using the --dev flag. Note that a passphrase is still needed to encrypt and decrypt wallets used in executing transactions.
pnpm start --passphrase=<PASSPHRASE> --dev
To start the Gateway server in HTTPS mode, run the command without the --dev flag. Make sure to use the same passphrase that you used to generate certs in the Hummingbot client.
pnpm start --passphrase=<PASSPHRASE>
Option A: Pull from Docker Hub
# Note: This image will be available after the v2.8 release
docker pull hummingbot/gateway:latest
Option B: Build locally
# Simple build
docker build -t hummingbot/gateway:core-2.8 .
# Build with version tag and metadata
docker build \
--build-arg BRANCH=$(git rev-parse --abbrev-ref HEAD) \
--build-arg COMMIT=$(git rev-parse HEAD) \
--build-arg BUILD_DATE=$(date -u +"%Y-%m-%d") \
-t hummingbot/gateway:core-2.8 .
Development mode (Unencrypted HTTP endpoints, default):
docker run -p 15888:15888 \
-e GATEWAY_PASSPHRASE=admin \
-e GATEWAY_DEV=true \
-v $(pwd)/conf:/home/gateway/conf \
-v $(pwd)/logs:/home/gateway/logs \
hummingbot/gateway:core-2.8
Production mode (Encypted HTTPS endpoints, requires Hummingbot certs):
docker run -p 15888:15888 \
-e GATEWAY_PASSPHRASE=a \
-e GATEWAY_DEV=false \
-v $(pwd)/conf:/home/gateway/conf \
-v $(pwd)/logs:/home/gateway/logs \
-v $(pwd)/certs:/home/gateway/certs \
hummingbot/gateway:core-2.8
GET / - Health checkGET /chains - List supported blockchainsGET /connectors - List supported DEX connectorsGET /config - Get configurationPOST /config/update - Update configurationGET /wallet - List all walletsPOST /wallet/add - Add new walletDELETE /wallet/remove - Remove walletPOST /wallet/sign - Sign message/chains/ethereum)GET /status - Chain connection statusGET /tokens - Get token informationGET /balances - Get wallet balancesGET /allowances - Check token allowancesPOST /approve - Approve token spendingGET /poll - Poll transaction status/chains/solana)GET /status - Chain connection statusGET /tokens - Get token informationGET /balances - Get wallet balancesGET /poll - Poll transaction statusGET /connectors/{dex}/router/quote-swap - Get swap quotePOST /connectors/{dex}/router/execute-swap - Execute swap without quotePOST /connectors/{dex}/router/execute-quote - Execute pre-fetched quoteGET /connectors/0x/router/get-price - Get price estimate (0x only)GET /connectors/{dex}/amm/pool-info - Pool informationGET /connectors/{dex}/amm/position-info - LP position detailsPOST /connectors/{dex}/amm/add-liquidity - Add liquidityPOST /connectors/{dex}/amm/remove-liquidity - Remove liquidityGET /connectors/{dex}/clmm/pool-info - Pool informationGET /connectors/{dex}/clmm/positions-owned - List positionsPOST /connectors/{dex}/clmm/open-position - Open positionPOST /connectors/{dex}/clmm/add-liquidity - Add to positionPOST /connectors/{dex}/clmm/remove-liquidity - Remove from positionPOST /connectors/{dex}/clmm/collect-fees - Collect feesGateway is part of the open source Hummingbot project, which is powered by community contributions. Please see the Contributing guide in the Hummingbot docs for more information.
Here are some ways that you can contribute to Gateway:
To run in HTTP mode (for development), use pnpm start --dev. By default, Gateway runs in secure HTTPS mode.
If you want Gateway to log to standard out, set logToStdOut to true in conf/server.yml.
The format of configuration files are dictated by src/services/config-manager-v2.ts and the corresponding schema files in src/templates/namespace.
For each supported chain, token lists that translate address to symbols for each chain are stored in /conf/tokens. Use the /tokens API endpoints to manage tokens - changes require a Gateway restart to take effect.
Gateway follows a modular architecture with clear separation of concerns:
/src
├── chains/ # Blockchain-specific implementations
├── connectors/ # DEX-specific implementations
│ ├── {dex}/ # Each DEX connector directory
│ │ ├── router-routes/ # DEX aggregator operations
│ │ ├── amm-routes/ # AMM pool operations
│ │ └── clmm-routes/ # Concentrated liquidity operations
├── services/ # Core services (config, logging, tokens)
├── schemas/ # API request/response schemas (TypeBox)
│ ├── router-schema.ts # Router operation schemas
│ ├── amm-schema.ts # AMM operation schemas
│ └── clmm-schema.ts # CLMM operation schemas
├── config/ # Configuration routes and utilities
└── wallet/ # Wallet management
The src/chains directory contains blockchain network implementations. Each chain module includes:
getBalances, getTokensThe src/connectors directory houses DEX protocol implementations. Each connector provides:
Essential services in src/services include:
For a pull request merged into the codebase, it has to pass unit test coverage requirements. Take a look at Workflow for more details.
Run all unit tests.
pnpm test
Run an individual test folder or file
GATEWAY_TEST_MODE=dev jest --runInBand test/<folder>/<file>.test.ts
The test directory is organized as follows:
/test
/chains/ # Chain endpoint tests
chain.test.js # Chain routes test
ethereum.test.js # Ethereum chain tests
solana.test.js # Solana chain tests
/connectors/ # Connector endpoint tests by protocol
/jupiter/ # Jupiter connector tests
/uniswap/ # Uniswap connector tests
/raydium/ # Raydium connector tests
/meteora/ # Meteora connector tests
/mocks/ # Mock response data
/chains/ # Chain mock responses
chains.json # Chain routes mock response
/ethereum/ # Ethereum mock responses
/solana/ # Solana mock responses
/connectors/ # Connector mock responses
/services/ # Service tests
/data/ # Test data files
/wallet/ # Wallet tests
/config/ # Configuration tests
/jest-setup.js # Test environment configuration
For more details on the test setup and structure, see Test README.
Create chain implementation:
// src/chains/mychain/mychain.ts
export class MyChain extends ChainBase {
private static instances: Record<string, MyChain> = {};
public static getInstance(network: string): MyChain {
if (!MyChain.instances[network]) {
MyChain.instances[network] = new MyChain(network);
}
return MyChain.instances[network];
}
}
Implement required routes:
getWallet(address: string)getBalance(address: string)getTokens(tokenSymbols: string[])getPool(tradingPair: string)getStatus()Create route handlers in src/chains/mychain/routes/
Add configuration for each supported network:
src/templates/namespace/mychain-schema.jsonsrc/templates/namespace/mychain-network-schema.jsonsrc/templates/chains/mychain.yml chain default YAMLsrc/templates/chains/mychain/ foldernetwork-name.ymlRegister the chain in src/chains/chain.routes.ts
Choose the appropriate base class:
Create connector class:
// src/connectors/mydex/mydex.ts
export class MyDex {
private static instances: Record<string, MyDex> = {};
public static getInstance(chain: string, network: string): MyDex {
const key = `${chain}:${network}`;
if (!MyDex.instances[key]) {
MyDex.instances[key] = new MyDex(chain, network);
}
return MyDex.instances[key];
}
}
Implement trading methods based on supported operations
Create route files following the pattern:
router-routes/ (for DEX aggregators)amm-routes/ (for V2-style pools)clmm-routes/ (for concentrated liquidity)Add configuration and register in src/connectors/connector.routes.ts
test/mocks/This repo uses eslint and prettier for code quality and consistent formatting.
Run linting manually with:
pnpm lint
Format code with prettier:
pnpm format
If you see warnings like bigint: Failed to load bindings, pure JS will be used (try npm run rebuild?) when running Gateway, you can safely ignore them. The warnings are related to the bigint-buffer package, which falls back to pure JavaScript implementation when native bindings are not available. This doesn't affect Gateway's functionality.
If you want to attempt to fix these warnings, you can run:
pnpm rebuild-bigint
Note that this requires having the necessary C++ build tools installed on your system.
If you encounter errors when using hardware wallets (Ledger devices), here are common solutions:
If you see errors like Cannot find module '@ledgerhq/hw-transport-node-hid' or similar USB/HID-related errors:
Ensure prerequisites are installed (see Prerequisites section above)
Rebuild native dependencies:
# Clean and reinstall
pnpm clean
pnpm install --force
Platform-specific fixes:
Linux: Add udev rules for Ledger devices
wget -q -O - https://raw.githubusercontent.com/LedgerHQ/udev-rules/master/add_udev_rules.sh | sudo bash
macOS: Grant Terminal/IDE USB permissions in System Preferences > Security & Privacy
Windows: Run as Administrator and ensure drivers are installed from Ledger Live
plugdev group:
sudo usermod -a -G plugdev $USER
# Logout and login again for changes to take effect
Content type
Image
Digest
sha256:e64b8239b…
Size
404.2 MB
Last updated
8 days ago
docker pull hummingbot/gateway