Multi-DEX SDK for Aptos blockchain - Supports Hyperion, Tapp, and more
npm install multidex-sdkA 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.
- 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
``bashInstall dependencies
pnpm install
Configuration
Create a
.env file in the project root:`env
Network: TESTNET or MAINNET
NETWORK=TESTNETAptos RPC URL (optional, uses default if not provided)
APTOS_RPC_URL=https://api.testnet.aptoslabs.comAptos API Key (optional, for Hyperion SDK)
APTOS_API_KEY=your_api_key_herePrivate 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 productionCLI 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 checkingExamples:
`bash
Swap 0.1 USDC to USDT (default fee tier 2)
pnpm cli swap USDC USDT --amount 10000000Swap 1 ETH to USDT with fee tier 2
pnpm cli swap ETH USDT --amount 100000000 --fee-tier 2Swap using specific pool address
pnpm cli swap USDC USDT --amount 10000000 --pool-id 0xfef2c8bf84c2e8fc30f09226545984c16fb0a8133510751f9e0d6b670bee4b32pnpm 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^decimalsExamples:
- 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 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddbMulti-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 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddbMulti-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 0x214794962c5f35f34094efa33595473088f9aa238d6470cfba9bcd017ae979dfSingle-hop: BTC -> USDC using Tapp DEX
pnpm cli multidex --dex tapp --swap-path BTC USDC --amount 10000000 --pool-id 0x78ebd69e764c2a24ed21eab62fa2af283b0a366ebda191b296163698717b96bdMulti-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-poolsGet 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 protocolNote: 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 100Create 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 lowWhat 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-pools2. Create a new pool (ETH/USDT)
pnpm cli create-pool ETH USDT 1 100 --fee-tier 23. Swap tokens (0.1 ETH to USDT)
pnpm cli swap ETH USDT --amount 10000000 --fee-tier 24. 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 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb6. Swap via path (multi-hop: BTC -> USDT -> BUSD)
pnpm cli swap-path BTC BUSD --amount 10000000 --pool-id 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb 0x214794962c5f35f34094efa33595473088f9aa238d6470cfba9bcd017ae979df7. Swap via Multi-DEX (single-hop: BTC -> USDT using Hyperion)
pnpm cli multidex --dex hyperion --swap-path BTC USDT --amount 10000000 --pool-id 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb8. Swap via Multi-DEX (multi-hop: BTC -> BUSD using Hyperion)
pnpm cli multidex --dex hyperion --swap-path BTC BUSD --amount 10000000 --pool-id 0xb6b933ef12a16010a826f26d4f3549495569f29f6b281c61222f7594032ffddb 0x214794962c5f35f34094efa33595473088f9aa238d6470cfba9bcd017ae979df9. 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 0x4d22b2c8276f9d1e1565aabca678f09d9e31a687b12670634b70596ef27abc8311. Get all pools from Hyperion DEX
pnpm cli multidex --dex hyperion --get-all-pools12. Get all pools from Tapp DEX
pnpm cli multidex --dex tapp --get-all-poolspnpm 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-poolsGet 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
``---
MIT