hummingbot · fengtality · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -21,7 +21,14 @@ module.exports = {
   rules: {
     'no-console': 'off',
     '@typescript-eslint/no-explicit-any': 'off',
-    '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+    // `ignoreRestSiblings` allows the idiomatic way to drop a key —
+    // `const { poolType, ...rest } = obj` — which is not dead code; the named sibling is
+    // how the rest is defined. `varsIgnorePattern` keeps a deliberately-unread binding
+    // legible as deliberate.
+    '@typescript-eslint/no-unused-vars': [
+      'warn',
+      { argsIgnorePattern: '^_', varsIgnorePattern: '^_', ignoreRestSiblings: true },
+    ],
     semi: [2, 'always'],
     'prettier/prettier': 'error',
     '@typescript-eslint/no-var-requires': 'off',

diff --git a/.github/workflows/workflow.yml b/.github/workflows/workflow.yml
@@ -80,6 +80,21 @@ jobs:
           # Copy template configurations
           cp -rf src/templates/* conf/
 
+      # The committed spec is what consumers generate their clients from, and the tests
+      # that check it read the committed copy — so a route change with no regeneration
+      # leaves them passing against a stale document. Only regenerating and comparing
+      # catches that. The generator writes the template port and placeholder wallets, so
+      # this produces the same bytes here as on any developer's machine.
+      - name: Check openapi.json is regenerated
+        shell: bash
+        run: |
+          pnpm generate:openapi
+          if ! git diff --quiet -- openapi.json; then
+            echo "::error::openapi.json does not match the routes. Run 'pnpm generate:openapi' and commit the result."
+            git --no-pager diff -- openapi.json
+            exit 1
+          fi
+
       - name: Run unit test coverage
         if: github.event_name == 'pull_request'
         shell: bash

diff --git a/.prettierignore b/.prettierignore
@@ -3,4 +3,5 @@ certs
 *.yml
 coverage
 dist
-vendor
+vendor
+openapi.json
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -251,28 +251,14 @@ Gateway implements RPC provider abstraction for optimized blockchain connectivit
   - Regional optimization (slc, ewr, lon, fra, ams, sg, tyo)
   - Connection warming for reduced latency
 
-### Testing RPC Providers
-Live integration tests in `scripts/`:
-- `test-infura-live.js`: Test Infura integration with real API key
-- `test-helius-live.js`: Test Helius integration with real API key
-- `test-provider-switching.js`: Test provider switching functionality
-
-Run tests:
-```bash
-# Requires configured API keys in conf/rpc/*.yml
-node scripts/test-infura-live.js
-node scripts/test-helius-live.js
-```
-
 ### Adding New RPC Provider
 1. Create config template: `src/templates/rpc/{provider}.yml`
 2. Create JSON schema: `src/templates/namespace/{provider}-schema.json`
 3. Register in `src/templates/root.yml`
 4. Implement service class: `src/chains/{chain}/{provider}-service.ts`
 5. Update chain connector to support provider selection
 6. Add `rpcProvider` enum to network schema
-7. Create live integration test script
-8. Document configuration and usage
+7. Document configuration and usage
 
 ## Hummingbot Gateway Endpoint Standardization
 - This repo standardized DEX and chain endpoints that are used by Hummingbot strategies. See this branch for the matching code, especially the Gateway connector classes https://github.com/hummingbot/hummingbot/tree/development

diff --git a/README.md b/README.md
@@ -112,29 +112,37 @@ Gateway uses [Swagger](https://swagger.io/) for API documentation. When running
 - `POST /chains/{chain}/approve` - Approve token spending
 - `POST /chains/{chain}/wrap` - Wrap/unwrap native tokens
 
-#### Connector Routes (`/connectors/{dex}/{type}/*`)
-
-**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
+#### Trading Routes (`/trading/{type}/*`)
+
+The trading type is a path segment and the connector is a `connector` parameter, so
+one set of routes covers every DEX.
+
+**Router** (`/trading/router/*`) — aggregators that route across pools (Jupiter, 0x, dflow, okx, titan, Uniswap, PancakeSwap):
+- `GET /trading/router/quote-swap` - Quote a swap (returns a `quoteId`)
+- `POST /trading/router/execute-quote` - Execute a previously fetched quote by id
+- `POST /trading/router/execute-swap` - Quote and execute in one call
+
+**AMM** (`/trading/amm/*`) — constant-product pools (Uniswap V2, PancakeSwap V2, Raydium CPMM, Meteora DAMM v2):
+- `GET /trading/amm/quote-swap` / `POST /trading/amm/execute-swap` - Swap against a single pool
+- `GET /trading/amm/pool-info` - Pool reserves, price, fee
+- `GET /trading/amm/position-info` - Wallet's liquidity in a pool
+- `GET /trading/amm/positions-owned` - All of a wallet's positions
+- `GET /trading/amm/quote-liquidity` - Two-sided deposit quote
+- `POST /trading/amm/open` / `close` - Open or close a position (fungible-LP AMMs deposit/withdraw in full)
+- `POST /trading/amm/add` / `remove` - Change a position's liquidity
+- `POST /trading/amm/create-pool`
+
+**CLMM** (`/trading/clmm/*`) — concentrated liquidity (Uniswap V3, PancakeSwap V3, Raydium, Meteora DLMM, Orca):
+- `GET /trading/clmm/quote-swap` / `POST /trading/clmm/execute-swap` - Swap against a single pool
+- `GET /trading/clmm/pool-info` - Pool info (optionally with bin/tick liquidity)
+- `GET /trading/clmm/position-info` - Position details
+- `GET /trading/clmm/positions-owned` - All of a wallet's positions
+- `GET /trading/clmm/quote-liquidity` - Deposit split for a candidate range
+- `GET /trading/clmm/fetch-pools` - Pool discovery from the DEX's own listing API
+- `POST /trading/clmm/open` / `close` - Open or close a position
+- `POST /trading/clmm/add` / `remove` - Change a position's liquidity
+- `POST /trading/clmm/collect-fees` - Collect earned fees
+- `POST /trading/clmm/create-pool`
 
 #### Wallet Routes (`/wallet/*`)
 - `GET /wallet` - List all wallets
@@ -405,43 +413,25 @@ docker compose up -d --build
 - `DELETE /wallet/remove` - Remove wallet
 - `POST /wallet/sign` - Sign message
 
-### Chain Operations
+### Chain Operations (`/chains/{chain}/*`)
 
-#### Ethereum/EVM (`/chains/ethereum`)
-- `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
+One parameterized set of routes serves every chain, so a new chain needs no new paths:
+- `GET /chains/{chain}/status` - Chain connection status and block height
+- `GET /chains/{chain}/estimate-gas` - Current transaction fee estimate
+- `POST /chains/{chain}/balances` - Wallet token balances
+- `POST /chains/{chain}/poll` - Poll a transaction by signature/hash
+- `POST /chains/{chain}/wrap` / `unwrap` - Wrap or unwrap the native token
 
-#### Solana (`/chains/solana`)
-- `GET /status` - Chain connection status
-- `GET /tokens` - Get token information
-- `GET /balances` - Get wallet balances
-- `GET /poll` - Poll transaction status
+EVM-only operations keep chain-specific paths, since they have no meaning elsewhere:
+- `POST /chains/ethereum/allowances` - Check token allowances
+- `POST /chains/ethereum/approve` - Approve token spending
 
 ### DEX Trading Endpoints
 
-#### Router Operations (DEX Aggregators)
-- `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)
-
-#### AMM Operations (Uniswap V2, PancakeSwap V2, Raydium)
-- `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
-
-#### CLMM Operations (Uniswap V3, PancakeSwap V3, Raydium, Meteora)
-- `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
+See [Trading Routes](#trading-routes-tradingtype) above. Every trading route takes
+`chainNetwork` (e.g. `solana-mainnet-beta`) and `connector` (e.g. `jupiter`), and the
+full request/response schemas are in the OpenAPI document at `/docs` (or `openapi.json`,
+regenerated with `pnpm generate:openapi`).
 
 ## Contribution
 
@@ -626,64 +616,22 @@ 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
-    /pancakeswap/             # PancakeSwap (EVM) connector tests
-    /pancakeswap-sol/         # PancakeSwap Solana 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
-
-/scripts                      # Live testing and utility scripts
-  test-helius-live.js        # Helius RPC provider integration tests
-  test-infura-live.js        # Infura RPC provider integration tests
-  test-provider-switching.js  # RPC provider switching tests
+  /chains/                    # Chain route tests (ethereum, solana)
+  /connectors/                # Connector tests, one directory per connector
+  /trading/                   # The unified /trading/* route tests
+  /mocks/                     # Shared mock modules (TypeScript)
+  /helpers/ /utils/           # Test helpers and fastifyWithTypeProvider
+  /services/ /wallet/ /config/ /pools/ /tokens/ /rpc/
+  jest-setup.js               # Test environment configuration
+
+/scripts                      # Utility scripts
+  generate-openapi.ts        # Write openapi.json from the live route table
+  create-wallet.ts           # Wallet creation helper
+  add-bsc-tokens.ts          # Token list maintenance
+  add-pancakeswap-pools.ts   # Pool list maintenance
+  migrate-pool-templates.ts  # Pool template migration
 ```
 
-#### RPC Provider Testing
-
-Gateway includes comprehensive testing for RPC provider integrations:
-
-**Live Integration Tests** (`scripts/test-*-live.js`):
-- Test real API connectivity with configured keys
-- Verify WebSocket connections and features
-- Measure performance improvements vs standard RPC
-- Validate network-specific endpoint mappings
-
-**Running RPC Provider Tests**:
-```bash
-# Test Infura integration (requires API key in conf/rpc/infura.yml)
-node scripts/test-infura-live.js
-
-# Test Helius integration (requires API key in conf/rpc/helius.yml)
-node scripts/test-helius-live.js
-
-# Test provider switching functionality
-node scripts/test-provider-switching.js
-```
-
-**Test Coverage Areas**:
-- Provider initialization and configuration loading
-- Automatic fallback to standard RPC on failures
-- Network-specific endpoint resolution
-- WebSocket connection establishment
-- Performance benchmarking and health checks
-
 For more details on the test setup and structure, see [Test README](./test/README.md).
 
 ## Development Guide
@@ -1010,12 +958,18 @@ testProviderIntegration();
 
 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)
+4. **Export plain operation functions** — not routes — following the pattern:
+   - Router operations in `router-routes/` (for DEX aggregators): `quoteSwap`, `executeSwap`, `executeQuote`
+   - AMM operations in `amm-routes/` (for V2-style pools)
+   - CLMM operations in `clmm-routes/` (for concentrated liquidity)
+
+   Each takes plain arguments and returns the shared response shape. Connectors no
+   longer register HTTP routes of their own; the unified `/trading/*` routes are the
+   only surface.
 
-5. **Add configuration and register** in `src/connectors/connector.routes.ts`
+5. **Add one entry per trading type** to `src/trading/connector-registry.ts`, which is
+   what wires the functions into the unified routes and into the `connector` enums the
+   schemas (and the OpenAPI document) advertise.
 
 ### Testing Requirements
 

diff --git a/docs/connectors/meteora-damm-v2.md b/docs/connectors/meteora-damm-v2.md
@@ -4,20 +4,22 @@ DAMM v2 is Meteora's constant-product AMM, implemented by the on-chain **cp-amm*
 (`cpamdpZCGKUy5JxQXB4dcpGPiikHawvSWAd6mEn1sGG`) and driven by the
 [`@meteora-ag/cp-amm-sdk`](https://docs.meteora.ag/developer-guides/damm-v2/typescript-sdk/getting-started).
 
-Gateway exposes it under the standard AMM interface at `/connectors/meteora/amm/*`, mirroring
-the Raydium AMM connector:
+Gateway exposes it through the unified AMM interface at `/trading/amm/*` with
+`connector=meteora`, the same routes that serve every other AMM connector:
 
 | Endpoint | Method | Notes |
 |---|---|---|
-| `/connectors/meteora/amm/pool-info` | GET | Pool reserves, price, base (cliff) fee % |
-| `/connectors/meteora/amm/position-info` | GET | Wallet's aggregate liquidity in a pool + per-position `positions[]` breakdown |
-| `/connectors/meteora/amm/positions-owned` | GET | All of the wallet's DAMM v2 positions across pools |
-| `/connectors/meteora/amm/quote-swap` | GET | Exact-in (SELL) / exact-out (BUY) quote |
-| `/connectors/meteora/amm/execute-swap` | POST | Swap |
-| `/connectors/meteora/amm/quote-liquidity` | GET | Two-sided deposit quote |
-| `/connectors/meteora/amm/add-liquidity` | POST | Add to a specific position (`positionAddress`) or open a new one |
-| `/connectors/meteora/amm/remove-liquidity` | POST | Remove a % from a specific position (`positionAddress` **required**) |
-| `/connectors/meteora/amm/create-pool` | POST | Create + seed a new pool |
+| `/trading/amm/pool-info` | GET | Pool reserves, price, base (cliff) fee % |
+| `/trading/amm/position-info` | GET | Wallet's aggregate liquidity in a pool + per-position `positions[]` breakdown |
+| `/trading/amm/positions-owned` | GET | All of the wallet's DAMM v2 positions across pools |
+| `/trading/amm/quote-swap` | GET | Exact-in (SELL) / exact-out (BUY) quote |
+| `/trading/amm/execute-swap` | POST | Swap |
+| `/trading/amm/quote-liquidity` | GET | Two-sided deposit quote |
+| `/trading/amm/open` | POST | Open a new position (NFT) and seed it with liquidity |
+| `/trading/amm/add` | POST | Add to a specific position (`positionAddress`) or open a new one |
+| `/trading/amm/remove` | POST | Remove a % from a specific position (`positionAddress` **required**) |
+| `/trading/amm/close` | POST | Withdraw everything and close the position NFT, refunding its rent (`positionAddress` **required**) |
+| `/trading/amm/create-pool` | POST | Create + seed a new pool |
 
 The implementation deliberately keeps to "the basics" so it fits the shared AMM schema. This
 document records where DAMM v2 differs from a classic fungible-LP AMM (e.g. Raydium AMM/CPMM),
@@ -91,7 +93,7 @@ resolves the seed price in this priority order:
 1. **`initialPrice`** (quote per base) if provided — `quoteTokenAmount = baseTokenAmount × initialPrice`.
 2. **`quoteTokenAmount`** if provided — the `baseTokenAmount : quoteTokenAmount` ratio sets the price.
 3. **Otherwise, the current market price is fetched** from the unified swap router
-   (`/trading/swap/quote`, i.e. the network's configured `swapProvider` — Jupiter on Solana, which
+   (`/trading/router/quote-swap`, i.e. the network's configured `swapProvider` — Jupiter on Solana, which
    aggregates existing venues) via a SELL quote of a small probe (1% of `baseTokenAmount`), and the
    pool is seeded there. The probe is kept small so the quote approximates the marginal market
    price; quoting the full seed amount would bake its own price impact into the seed price and
-Original file line number
+Diff line change
@@ Expand Up / @@ -3,4 +3,5 @@ certs @@
     *.yml
     coverage
     dist
-    vendor
+    vendor
+    openapi.json