Hyperion DEX CLI Tool

A comprehensive command-line interface for interacting with Hyperion DEX on Aptos blockchain. This tool allows you to create pools, swap tokens, check pool information, and more.

Table of Contents

• Installation
• Configuration
• Multi-Wallet Support
• CLI Commands
  • Get All Pools
  • Check Pool Existed
  • Swap Tokens
• Swap Path (Multi-hop)
• Multi-DEX Commands
• Create Pool
• Token Configuration
• Fee Tiers
• Examples
• Troubleshooting

Installation

# Install dependencies
pnpm install

# Or using npm
npm install

Configuration

Create a .env file in the project root:

# Network: TESTNET or MAINNET
NETWORK=TESTNET

# Aptos RPC URL (optional, uses default if not provided)
APTOS_RPC_URL=https://api.testnet.aptoslabs.com

# Aptos API Key (optional, for Hyperion SDK)
APTOS_API_KEY=your_api_key_here

# Private Key for signing transactions (required for swap/create-pool)
# Format: ed25519-priv-0x... or 0x...
APTOS_PRIVATE_KEY=ed25519-priv-0x...

Multi-Wallet Support

The project supports multiple wallets through JsonKeystoreWalletProvider, which allows you to load multiple wallets from a JSON file.

Wallet File Format

Create a wallets.json file in the project root:

[
  {
    "address": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "privateKeyHex": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
  },
  {
    "address": "0xfedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321",
    "privateKeyHex": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
  }
]

Note:

• Each wallet entry must have address and privateKeyHex fields
• privateKeyHex can be in formats: 0x..., ed25519-priv-0x..., or raw hex
• The address will be validated against the private key

Usage Example

import { JsonKeystoreWalletProvider } from "./services/wallet";
import { TradeExecutor } from "./services/trade-executor";
import { DexAdapterFactory } from "./services/dex-adaptor";

// Load wallets from file
const walletProvider = JsonKeystoreWalletProvider.fromFile("./wallets.json");

// Or load from array programmatically
const walletProvider2 = new JsonKeystoreWalletProvider([
  { 
    address: "0x...", 
    privateKeyHex: "0x..." 
  }
]);

// List all wallet addresses
const addresses = walletProvider.listWalletAddresses();
console.log("Loaded wallets:", addresses);
// Output: ["0x123...", "0xfed..."]

// Get wallet count
console.log("Total wallets:", walletProvider.getWalletCount());
// Output: 2

// Create adapter and executor
const adapter = DexAdapterFactory.create("hyperion");
const executor = new TradeExecutor(walletProvider, adapter);

// Execute swap with specific wallet
const result = await executor.executeSwapPath({
  walletAddress: "0x123...", // Use first wallet
  tokenIn: "0x...",
  tokenOut: "0x...",
  amountIn: BigInt(1000000),
  poolPaths: ["0xpool1", "0xpool2"],
  slippageBps: 50, // 0.5%
});

// Execute swap with different wallet
const result2 = await executor.executeSwapPath({
  walletAddress: "0xfed...", // Use second wallet
  tokenIn: "0x...",
  tokenOut: "0x...",
  amountIn: BigInt(2000000),
  poolPaths: ["0xpool1"],
  slippageBps: 50,
});

Features

• Multiple Wallets: Load and manage multiple wallets from a single JSON file
• Address Validation: Automatically validates that each address matches its private key
• Flexible Key Format: Supports multiple private key formats (0x..., ed25519-priv-0x..., or raw hex)
• Case-Insensitive: Address matching is case-insensitive
• Error Handling: Clear error messages for missing wallets or invalid formats

Security Notes

⚠️ Important:

• Never commit wallets.json to version control
• Add wallets.json to .gitignore
• Keep private keys secure and encrypted in production
• Use environment variables or secure key management systems for production

CLI Commands

Get All Pools

Fetch and display all available pools on Hyperion DEX.

pnpm cli get-all-pools

Output includes:

• Pool ID and sender address
• Fee tier and rate
• Current tick and sqrt price
• Token 1 and Token 2 information (symbol, name, address, decimals)
• Pool reserves (token balances)
• Stats (TVL, Volume 24h, Fees 24h if available)

Example:

pnpm cli get-all-pools

Check Pool Existed

Check if a specific pool exists (hardcoded: USDC/USDT, fee tier 2).

pnpm cli check-pool-existed

Note: This command currently checks for USDC/USDT pool with fee tier 2. To check other pools, use get-all-pools and filter manually.

Swap Tokens

Swap tokens on Hyperion DEX. The command will fail if the pool doesn't exist.

pnpm cli swap <TOKEN_IN> <TOKEN_OUT> --amount <native_amount> [--fee-tier <TIER>] [--pool-id <POOL_ADDRESS>]

Parameters:

• TOKEN_IN: Input token symbol (e.g., USDC, USDT, ETH)
• TOKEN_OUT: Output token symbol (e.g., USDT, USDC, ETH)
• --amount: Amount in native units (with decimals), not human-readable
  • Example: For 0.1 USDC (8 decimals) = 10000000
  • Example: For 1 ETH (8 decimals) = 100000000
• --fee-tier (optional): Fee tier (0-5), default: 2 (0.3%)
• --pool-id (optional): Pool address. If provided, swaps directly in this pool without checking

Examples:

# Swap 0.1 USDC to USDT (default fee tier 2)
pnpm cli swap USDC USDT --amount 10000000

# Swap 1 ETH to USDT with fee tier 2
pnpm cli swap ETH USDT --amount 100000000 --fee-tier 2

# Swap using specific pool address
pnpm cli swap USDC USDT --amount 10000000 --pool-id 0xfef2c8bf84c2e8fc30f09226545984c16fb0a8133510751f9e0d6b670bee4b32

pnpm cli swap BTC  USDT  --amount 100000000 --fee-tier 2 
pnpm cli swap BUSD  USDT  --amount 100000000 --fee-tier 2 

Native Amount Calculation:

native_amount = human_amount × 10^decimals

Examples:
- 0.1 USDC (8 decimals) = 0.1 × 10^8 = 10000000
- 1 ETH (8 decimals) = 1 × 10^8 = 100000000
- 100 USDT (8 decimals) = 100 × 10^8 = 10000000000

Features:

• Checks if pool exists (fails if pool doesn't exist)
• Gets quote from pool before swapping
• Uses correct sqrt_price_limit (MAX/MIN) based on token direction
• Handles slippage protection (5% default)

Swap Path (Multi-hop)

Swap tokens via specified pool path (single-hop or multi-hop routing).

pnpm cli swap-path <TOKEN_IN> <TOKEN_OUT> --amount <native_amount> --pool-id <POOL_ADDRESS> [<POOL_ADDRESS> ...]

Parameters:

• TOKEN_IN: Input token symbol (e.g., BTC, USDC, ETH)
• TOKEN_OUT: Output token symbol (e.g., BUSD, USDT, ETH)
• --amount: Amount in native units (with decimals), not human-readable
• --pool-id: Pool address(es) for routing. Can specify multiple pools for multi-hop swaps
  • Single-hop: --pool-id 0xpool1
  • Multi-hop: --pool-id 0xpool1 0xpool2 (all addresses after first --pool-id)

Examples:

# Single-hop: BTC -> USDT (direct swap via one pool)
pnpm cli swap-path BTC USDT --amount 10000000 --pool-id 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb

# Multi-hop: BTC -> BUSD (via BTC/USDT pool then USDT/BUSD pool)
pnpm cli swap-path BTC BUSD --amount 10000000 --pool-id 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb 0x214794962c5f35f34094efa33595473088f9aa238d6470cfba9bcd017ae979df

Features:

• Validates pool path before swapping (checks if pools connect correctly)
• Supports single-hop and multi-hop routing
• Gets quote from batch path before swapping (if available)
• Handles slippage protection (5% default)
• Shows detailed pool path information for debugging

Pool Path Requirements:

• First pool must contain TOKEN_IN
• Intermediate pools must connect (output of pool N = input of pool N+1)
• Last pool must output TOKEN_OUT
• Example: BTC → USDT → BUSD requires:
  • Pool 1: BTC/USDT (BTC → USDT)
  • Pool 2: USDT/BUSD (USDT → BUSD)

Multi-DEX Commands

Swap tokens using multiple DEX protocols via adapter pattern. This allows you to use different DEX protocols (Hyperion, Tapp, etc.) with a unified interface.

pnpm cli multidex --swap-path <TOKEN_IN> <TOKEN_OUT> --amount <native_amount> --pool-id <POOL_ADDRESS> [<POOL_ADDRESS> ...] --dex <DEX_NAME>

Parameters:

• --swap-path: Swap path command
• TOKEN_IN: Input token symbol (e.g., BTC, USDC, ETH)
• TOKEN_OUT: Output token symbol (e.g., USDT, BUSD, ETH)
• --amount: Amount in native units (with decimals), not human-readable
• --pool-id: Pool address(es) for routing. Can specify multiple pools for multi-hop swaps
• --dex: DEX protocol name (e.g., hyperion, tapp)

Supported DEX Protocols:

• hyperion: Hyperion DEX
• tapp: Tapp DEX (coming soon)

Examples:

# Single-hop: BTC -> USDT using Hyperion DEX
pnpm cli multidex --dex hyperion --swap-path BTC USDT --amount 10000000 --pool-id 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb

# Multi-hop: BTC -> BUSD using Hyperion DEX (via BTC/USDT then USDT/BUSD)
pnpm cli multidex --dex hyperion --swap-path BTC BUSD --amount 10000000 --pool-id 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb 0x214794962c5f35f34094efa33595473088f9aa238d6470cfba9bcd017ae979df

# Single-hop: BTC -> USDC using Tapp DEX
pnpm cli multidex --dex tapp --swap-path BTC USDC --amount 10000000 --pool-id 0x78ebd69e764c2a24ed21eab62fa2af283b0a366ebda191b296163698717b96bd

# Multi-hop: BTC -> USDC using Tapp DEX
pnpm cli multidex --dex tapp --swap-path BTC USDT --amount 10000000 --pool-id 0x78ebd69e764c2a24ed21eab62fa2af283b0a366ebda191b296163698717b96bd 0x84f54cfaa33fc0b8b5de585179677f6bc6f9ed7246e3b2ec578328c053a05be

Get All Pools:

# Get all pools from Hyperion DEX
pnpm cli multidex --dex hyperion --get-all-pools

# Get all pools from Tapp DEX
pnpm cli multidex --dex tapp --get-all-pools

Features:

• Unified interface for multiple DEX protocols
• Same validation and features as swap-path command
• Easy to switch between different DEX protocols
• Supports single-hop and multi-hop routing
• Get all pools from any supported DEX protocol

Note: The multidex command uses the adapter pattern to support multiple DEX protocols. Currently supported: hyperion (fully implemented) and tapp (single-hop AMM pools supported).

Create Pool

Create a new liquidity pool for two tokens.

pnpm cli create-pool <TOKEN_A> <TOKEN_B> <AMOUNT_A> <AMOUNT_B> [--fee-tier <TIER>] [--slippage <SLIPPAGE>]

Parameters:

• TOKEN_A: Token A symbol (e.g., ETH, USDC, USDT)
• TOKEN_B: Token B symbol (e.g., USDT, USDC, ETH)
• AMOUNT_A: Human-readable amount for Token A (e.g., 1, 50, 100)
• AMOUNT_B: Human-readable amount for Token B (e.g., 100, 2000, 5000)
• --fee-tier (optional): Fee tier (0-5), default: 2 (0.3%)
• --slippage (optional): Slippage tolerance (0.0-1.0), default: 0.1 (10%)

Examples:

# Create ETH/USDT pool with 1 ETH and 100 USDT (default fee tier 2, 10% slippage)
pnpm cli create-pool ETH USDT 1 100

# Create ETH/USDT pool with custom fee tier and slippage
pnpm cli create-pool ETH USDT 1 100 --fee-tier 2 --slippage 0.05
pnpm cli create-pool BTC  USDT 10 500 --fee-tier 2 --slippage 0.05 

# Create USDC/USDT pool with 50 tokens each
pnpm cli create-pool USDC USDT 50 50

Important Notes:

• 💡 Recommended: Use --fee-tier 2 (0.3%) for best compatibility. Lower fee tiers (0, 1) may cause EXECUTION_LIMIT_REACHED errors during swaps due to smaller tick spacing.
• Amounts are in human-readable format (not native units)
• SDK will automatically estimate and adjust AMOUNT_B if needed to avoid EAMOUNT_B_TOO_LESS error
• Pool creation requires sufficient token balances in your wallet
• After creation, the tool verifies pool reserves and warns if they're too low

What happens:

1. Calculates initial price from AMOUNT_B / AMOUNT_A
2. Determines tick range (±2% from current price)
3. Estimates optimal AMOUNT_B using SDK (if needed)
4. Creates transaction payload
5. Signs and submits transaction (if APTOS_PRIVATE_KEY is set)
6. Verifies pool reserves after creation

Token Configuration

Supported tokens are defined in src/config/tokens.ts. Currently supported:

• USDC: 0x8c58fb7fd3ccb2d7bc079dcbf924567fccd385b24b0f8afbfdebf87dc671ba07 (8 decimals)
• USDT: 0x7538e517af47371976af23a1052bc64172cc65a029d1ef75b453a33d520f0b7f (8 decimals)
• ETH: 0xb61f9f829842869968edba4b88f0cf785ac6729fd664f50c7be8c630fd2daebc (8 decimals)

To add more tokens, edit src/config/tokens.ts.

Fee Tiers

| Fee Tier | Fee Rate | Tick Spacing | Use Case | |----------|----------|--------------|----------| | 0 | 0.01% | 1 | Very stable pairs | | 1 | 0.05% | 10 | Stable pairs | | 2 | 0.3% | 60 | Standard pairs (default) | | 3 | 1% | 200 | Volatile pairs | | 4 | 0.1% | 20 | Medium volatility | | 5 | 0.25% | 50 | Medium-high volatility |

⚠️ Recommendation: Use Fee Tier 2 (0.3%) when creating pools for best compatibility and to avoid EXECUTION_LIMIT_REACHED errors. Lower fee tiers (0, 1) have smaller tick spacing, which can cause computation issues during swaps.

Examples

Complete Workflow

# 1. Check all available pools
pnpm cli get-all-pools

# 2. Create a new pool (ETH/USDT)
pnpm cli create-pool ETH USDT 1 100 --fee-tier 2

# 3. Swap tokens (0.1 ETH to USDT)
pnpm cli swap ETH USDT --amount 10000000 --fee-tier 2

# 4. Swap using specific pool
pnpm cli swap USDC USDT --amount 10000000 --pool-id 0x...

# 5. Swap via path (single-hop)
pnpm cli swap-path BTC USDT --amount 10000000 --pool-id 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb

# 6. Swap via path (multi-hop: BTC -> USDT -> BUSD)
pnpm cli swap-path BTC BUSD --amount 10000000 --pool-id 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb 0x214794962c5f35f34094efa33595473088f9aa238d6470cfba9bcd017ae979df

# 7. Swap via Multi-DEX (single-hop: BTC -> USDT using Hyperion)
pnpm cli multidex --dex hyperion --swap-path BTC USDT --amount 10000000 --pool-id 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb

# 8. Swap via Multi-DEX (multi-hop: BTC -> BUSD using Hyperion)
pnpm cli multidex --dex hyperion --swap-path BTC BUSD --amount 10000000 --pool-id 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb 0x214794962c5f35f34094efa33595473088f9aa238d6470cfba9bcd017ae979df

# 9. Swap via Multi-DEX (single-hop: BTC -> USDC using Tapp)
pnpm cli multidex --dex tapp --swap-path BTC USDC --amount 10000000 --pool-id 0x78ebd69e764c2a24ed21eab62fa2af283b0a366ebda191b296163698717b96bd 

# 10. Swap via Multi-DEX (multi-hop: BTC -> USDT using Tapp)
pnpm cli multidex --dex tapp --swap-path BTC USDT --amount 1000000 --pool-id 0x78ebd69e764c2a24ed21eab62fa2af283b0a366ebda191b296163698717b96bd 0x4d22b2c8276f9d1e1565aabca678f09d9e31a687b12670634b70596ef27abc83

# 11. Get all pools from Hyperion DEX
pnpm cli multidex --dex hyperion --get-all-pools

# 12. Get all pools from Tapp DEX
pnpm cli multidex --dex tapp --get-all-pools

pnpm cli swap USDT USDC  --amount 100000000
pnpm cli swap USDC USDT  --amount 100000000

Common Use Cases

Swap stablecoins:

pnpm cli swap USDC USDT --amount 100000000  # 1 USDC

Create high-liquidity pool:

pnpm cli create-pool USDC USDT 1000 1000 --fee-tier 2 --slippage 0.01
pnpm cli create-pool BUSD USDT 50 1000 --fee-tier 2 --slippage 0.01 
pnpm cli create-pool BTC  USDT 10 1000 --fee-tier 2 --slippage 0.01

Swap with low fee tier:

pnpm cli swap USDC USDT --amount 100000000 --fee-tier 0

Swap via path (single-hop):

pnpm cli swap-path BTC USDT --amount 10000000 --pool-id 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb

Swap via path (multi-hop):

pnpm cli swap-path BTC BUSD --amount 10000000 --pool-id 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb 0x214794962c5f35f34094efa33595473088f9aa238d6470cfba9bcd017ae979df

Swap via Multi-DEX (single-hop):

pnpm cli multidex --dex hyperion --swap-path BTC USDT --amount 10000000 --pool-id 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb

Swap via Multi-DEX (multi-hop):

pnpm cli multidex --dex hyperion --swap-path BTC BUSD --amount 10000000 --pool-id 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb 0x214794962c5f35f34094efa33595473088f9aa238d6470cfba9bcd017ae979df

Swap via Multi-DEX (Tapp DEX - single-hop):

pnpm cli multidex --dex tapp --swap-path BTC USDC --amount 10000000 --pool-id 0x78ebd69e764c2a24ed21eab62fa2af283b0a366ebda191b296163698717b96bd

Swap via Multi-DEX (Tapp DEX - multi-hop):

pnpm cli multidex --dex tapp --swap-path BTC USDT --amount 10000000 --pool-id 0x78ebd69e764c2a24ed21eab62fa2af283b0a366ebda191b296163698717b96bd 0x4d22b2c8276f9d1e1565aabca678f09d9e31a687b12670634b70596ef27abc83

Get all pools from Multi-DEX:

# Get all pools from Hyperion DEX
pnpm cli multidex --dex hyperion --get-all-pools

# Get all pools from Tapp DEX
pnpm cli multidex --dex tapp --get-all-pools

Get help for a command:

pnpm cli swap --help
pnpm cli swap-path --help
pnpm cli multidex --help
pnpm cli multidex --get-all-pools --help
pnpm cli create-pool --help
pnpm cli get-all-pools --help

Troubleshooting

Common Errors

1. ESQRT_PRICE_LIMIT_UNAVAILABLE

• Cause: Wrong sqrt_price_limit direction (MAX vs MIN)
• Solution: The tool automatically determines the correct direction based on pool token order. If error persists, check pool token order.

2. EAMOUNT_B_TOO_LESS

• Cause: Insufficient AMOUNT_B for the chosen tick range
• Solution: SDK automatically estimates and uses higher amount if needed. Increase AMOUNT_B manually if issue persists.

3. EINSUFFICIENT_BALANCE

• Cause: Not enough tokens in wallet
• Solution: Ensure you have sufficient balance for both tokens before creating pool or swapping.

4. Pool reserves are very low after creation

• Cause: Insufficient balance or transaction issues
• Solution: Check your token balances and transaction details on explorer.

Getting Help

• Check transaction details on Aptos Explorer
• Review error messages in terminal output
• Verify token balances before operations
• Ensure .env file is configured correctly

Project Structure

quick-test/
├── src/
│   ├── cli.ts              # CLI interface
│   ├── swap.ts             # Swap functionality
│   ├── create-pool.ts     # Pool creation
│   ├── get-all-pools.ts    # Fetch all pools
│   ├── check-pool-existed.ts
│   ├── config/
│   │   ├── tokens.ts       # Token configuration
│   │   └── index.ts        # Main config
│   └── ...
├── notes/                   # Documentation notes
├── .env.example            # Environment variables template
└── README.md              # This file

License

MIT