╔██████╗  █████╗ ████████╗███████╗██╗    ██╗ █████╗ ██╗   ██╗
██╔════╝ ██╔══██╗╚══██╔══╝██╔════╝██║    ██║██╔══██╗╚██╗ ██╔╝
██║  ███╗███████║   ██║   █████╗  ██║ █╗ ██║███████║ ╚████╔╝
██║   ██║██╔══██║   ██║   ██╔══╝  ██║███╗██║██╔══██║  ╚██╔╝
╚██████╔╝██║  ██║   ██║   ███████╗╚███╔███╔╝██║  ██║   ██║
 ╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚══════╝ ╚══╝╚══╝ ╚═╝  ╚═╝   ╚═╝

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:

• REST API: Direct HTTP/HTTPS endpoints for programmatic access
• Hummingbot Client: For automated trading strategies, use the Hummingbot repository

• Standardized REST API: Consistent endpoints for interacting with blockchains (Ethereum, Solana) and DEXs (Uniswap, Jupiter, Raydium, Meteora, 0x)
• Three Trading Types: Router (DEX aggregators), AMM (V2-style pools), and CLMM (V3-style concentrated liquidity)
• Modular Architecture: Clear separation of concerns with distinct modules for chains, connectors, configuration, and wallet management
• TypeScript-based: Leverages the TypeScript ecosystem and popular libraries like Fastify, Ethers.js, and Solana/web3.js
• Security: Built-in rate limiting (100 requests/minute) to prevent DoS attacks
• Extensible: Easily extended with new chains and connectors

• Backend: Node.js, TypeScript, Fastify
• Blockchain Interaction: Ethers.js (Ethereum), @solana/web3.js (Solana)
• Package Manager: pnpm
• Testing: Jest
• Linting/Formatting: ESLint, Prettier
• API Documentation: Swagger/OpenAPI

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.

• Ethereum Mainnet
• Arbitrum
• Avalanche
• Base
• BSC (Binance Smart Chain)
• Celo
• Optimism
• Polygon
• Sepolia (testnet)

• Solana Mainnet-Beta
• Solana Devnet

• Router: DEX aggregators that find optimal swap routes across multiple liquidity sources
• AMM (Automated Market Maker): Traditional V2-style constant product pools (x*y=k)
• CLMM (Concentrated Liquidity Market Maker): V3-style pools with capital efficiency through concentrated liquidity positions

Gateway uses Swagger for API documentation. When running Gateway, access the interactive API documentation at:

• Development mode: http://localhost:15888/docs
• Production mode: https://localhost:15888/docs

• GET /config/namespaces - List all configuration namespaces
• GET /config/chains - Get available chains and networks
• GET /config/connectors - List available DEX connectors
• GET /config - Get configuration for a namespace
• PUT /config - Update configuration values

• GET /chains/{chain}/status - Get chain status and block height
• GET /chains/{chain}/tokens - List supported tokens
• POST /chains/{chain}/balances - Get wallet token balances
• POST /chains/{chain}/allowances - Check token allowances
• POST /chains/{chain}/approve - Approve token spending
• POST /chains/{chain}/wrap - Wrap/unwrap native tokens

Router Operations (e.g., /connectors/jupiter/router/*):

• POST /quote - Get swap quote from aggregator
• POST /swap - Execute swap through aggregator

AMM Operations (e.g., /connectors/raydium/amm/*):

• POST /poolInfo - Get pool details
• POST /positionInfo - Get liquidity position info
• POST /quoteSwap - Get swap quote
• POST /executeSwap - Execute swap
• POST /quoteLiquidity - Quote add/remove liquidity
• POST /addLiquidity - Add liquidity to pool
• POST /removeLiquidity - Remove liquidity from pool

CLMM Operations (e.g., /connectors/uniswap/clmm/*):

• POST /poolInfo - Get concentrated liquidity pool info
• POST /openPosition - Open new position
• POST /closePosition - Close existing position
• POST /addLiquidity - Add liquidity to position
• POST /removeLiquidity - Remove liquidity from position
• POST /collectFees - Collect earned fees
• POST /positionsOwned - List owned positions

• GET /wallet - List all wallets
• POST /wallet/add - Add new wallet
• POST /wallet/addHardware - Add hardware wallet
• DELETE /wallet/remove - Remove wallet
• POST /wallet/setDefault - Set default wallet per chain

• NodeJS 20+ (required)
• Python 3 (required for node-gyp)
• C++ build tools (required for native dependencies)
• USB libraries (required for hardware wallet support)

macOS:

# 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:

1. Install Node.js 20+
2. Install Visual Studio Build Tools or Visual Studio Community with C++ workload
3. Install Python 3
4. Run PowerShell as Administrator and install windows-build-tools:

   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 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

• Development mode: http://localhost:15888
• Production mode: https://localhost:15888
• Swagger API docs: http://localhost:15888/docs (dev mode only)

• GET / - Health check
• GET /chains - List supported blockchains
• GET /connectors - List supported DEX connectors

• GET /config - Get configuration
• POST /config/update - Update configuration

• GET /wallet - List all wallets
• POST /wallet/add - Add new wallet
• DELETE /wallet/remove - Remove wallet
• POST /wallet/sign - Sign message

• GET /status - Chain connection status
• GET /tokens - Get token information
• GET /balances - Get wallet balances
• GET /allowances - Check token allowances
• POST /approve - Approve token spending
• GET /poll - Poll transaction status

• GET /status - Chain connection status
• GET /tokens - Get token information
• GET /balances - Get wallet balances
• GET /poll - Poll transaction status

• GET /connectors/{dex}/router/quote-swap - Get swap quote
• POST /connectors/{dex}/router/execute-swap - Execute swap without quote
• POST /connectors/{dex}/router/execute-quote - Execute pre-fetched quote
• GET /connectors/0x/router/get-price - Get price estimate (0x only)

• GET /connectors/{dex}/amm/pool-info - Pool information
• GET /connectors/{dex}/amm/position-info - LP position details
• POST /connectors/{dex}/amm/add-liquidity - Add liquidity
• POST /connectors/{dex}/amm/remove-liquidity - Remove liquidity

• GET /connectors/{dex}/clmm/pool-info - Pool information
• GET /connectors/{dex}/clmm/positions-owned - List positions
• POST /connectors/{dex}/clmm/open-position - Open position
• POST /connectors/{dex}/clmm/add-liquidity - Add to position
• POST /connectors/{dex}/clmm/remove-liquidity - Remove from position
• POST /connectors/{dex}/clmm/collect-fees - Collect fees

Gateway 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:

• File an issue at hummingbot issues
• Make a pull request
• Edit the docs
• Vote in quarterly polls to decide which DEXs Gateway should support

• 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:

• Core chain class implementing operations like getBalances, getTokens
• Chain-specific routes defining API endpoints
• Configuration management for the chain

The src/connectors directory houses DEX protocol implementations. Each connector provides:

• Router operations: DEX aggregator functionality (router-routes/)
  • Quote and execute swaps through aggregator protocols
  • Support for execute-quote pattern for better execution
• AMM operations: Automated Market Maker pools (amm-routes/)
  • Manage liquidity positions in V2-style pools
• CLMM operations: Concentrated Liquidity pools (clmm-routes/)
  • Manage positions with custom price ranges

Essential services in src/services include:

• config-manager-v2.ts: Robust configuration management with validation
• logger.ts: Flexible logging service
• token-service.ts: Token list management with security validation

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.

1. 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];
     }
   }

2. Implement required routes:

   • getWallet(address: string)
   • getBalance(address: string)
   • getTokens(tokenSymbols: string[])
   • getPool(tradingPair: string)
   • getStatus()

3. Create route handlers in src/chains/mychain/routes/

4. Add configuration for each supported network:

   • Add chain schema in src/templates/namespace/mychain-schema.json
   • Add network schema in src/templates/namespace/mychain-network-schema.json
   • Create src/templates/chains/mychain.yml chain default YAML
   • Create src/templates/chains/mychain/ folder
   • In this folder, create default YAML files for each support network titled network-name.yml

5. Register the chain in src/chains/chain.routes.ts

1. Choose the appropriate base class:

   • For AMM: Extend from AMM base functionality
   • For CLMM: Implement CLMM interface
   • For simple swaps: Implement basic swap methods

2. 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];
     }
   }

3. Implement trading methods based on supported operations

4. Create route files following the pattern:

   • Router routes in router-routes/ (for DEX aggregators)
   • AMM routes in amm-routes/ (for V2-style pools)
   • CLMM routes in clmm-routes/ (for concentrated liquidity)

5. Add configuration and register in src/connectors/connector.routes.ts

• Minimum 75% code coverage for new features
• Create mock responses in test/mocks/
• Write unit tests for all route handlers
• Test error cases and edge conditions

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:

1. Ensure prerequisites are installed (see Prerequisites section above)

2. Rebuild native dependencies:

   # Clean and reinstall
   pnpm clean
   pnpm install --force

3. 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

• Linux/macOS: Run Gateway with appropriate permissions or add your user to the plugdev group:

  sudo usermod -a -G plugdev $USER
  # Logout and login again for changes to take effect

• Ensure Ledger device is connected and unlocked
• Open the appropriate app (Ethereum or Solana) on the device
• Try different USB ports or cables
• Close Ledger Live if it's running (it may lock the device)