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

``bash


Install dependencies

pnpm install

Or using npm

npm install
`

Configuration

Create a .env file in the project root:

`env


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.

$3

Create a wallets.json file in the project root:

`json
[
{
"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

$3

`typescript
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,
});
`

$3

- 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

$3

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

$3

Fetch and display all available pools on Hyperion DEX.

`bash
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:
`bash
pnpm cli get-all-pools
`

---

$3

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

`bash
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.

---

$3

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

`bash
pnpm cli swap --amount [--fee-tier ] [--pool-id ]
`

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:
`bash


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)

---

$3

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

`bash
pnpm cli swap-path --amount --pool-id [ ...]
`

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:
`bash


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)

---

$3

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

`bash
pnpm cli multidex --swap-path --amount --pool-id [ ...] --dex
`

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:
`bash


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:
`bash


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

---

$3

Create a new liquidity pool for two tokens.

`bash
pnpm cli create-pool [--fee-tier ] [--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:
`bash


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

$3

`bash


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
`

$3

Swap stablecoins:
`bash
pnpm cli swap USDC USDT --amount 100000000 # 1 USDC
`

Create high-liquidity pool:
`bash
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:
`bash
pnpm cli swap USDC USDT --amount 100000000 --fee-tier 0
`

Swap via path (single-hop):
`bash
pnpm cli swap-path BTC USDT --amount 10000000 --pool-id 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb
`

Swap via path (multi-hop):
`bash
pnpm cli swap-path BTC BUSD --amount 10000000 --pool-id 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb 0x214794962c5f35f34094efa33595473088f9aa238d6470cfba9bcd017ae979df
`

Swap via Multi-DEX (single-hop):
`bash
pnpm cli multidex --dex hyperion --swap-path BTC USDT --amount 10000000 --pool-id 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb
`

Swap via Multi-DEX (multi-hop):
`bash
pnpm cli multidex --dex hyperion --swap-path BTC BUSD --amount 10000000 --pool-id 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb 0x214794962c5f35f34094efa33595473088f9aa238d6470cfba9bcd017ae979df
`

Swap via Multi-DEX (Tapp DEX - single-hop):
`bash
pnpm cli multidex --dex tapp --swap-path BTC USDC --amount 10000000 --pool-id 0x78ebd69e764c2a24ed21eab62fa2af283b0a366ebda191b296163698717b96bd
`
Swap via Multi-DEX (Tapp DEX - multi-hop):
`bash
pnpm cli multidex --dex tapp --swap-path BTC USDT --amount 10000000 --pool-id 0x78ebd69e764c2a24ed21eab62fa2af283b0a366ebda191b296163698717b96bd 0x4d22b2c8276f9d1e1565aabca678f09d9e31a687b12670634b70596ef27abc83
`

Get all pools from Multi-DEX:
`bash


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:
`bash
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

$3

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.

$3

- 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